{ "components": { "schemas": { "AIEmployeePatch": { "properties": { "avatar_treatment": { "anyOf": [ { "maxLength": 80, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Avatar Treatment" }, "default_playback_speed": { "anyOf": [ { "maximum": 2.0, "minimum": 0.5, "type": "number" }, { "type": "null" } ], "title": "Default Playback Speed" }, "default_voice_id": { "anyOf": [ { "maxLength": 120, "type": "string" }, { "type": "null" } ], "title": "Default Voice Id" }, "display_name": { "anyOf": [ { "maxLength": 120, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Display Name" }, "enabled": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Enabled" }, "manners_markdown": { "anyOf": [ { "maxLength": 20000, "type": "string" }, { "type": "null" } ], "title": "Manners Markdown" }, "mention_handle": { "anyOf": [ { "maxLength": 80, "minLength": 2, "type": "string" }, { "type": "null" } ], "title": "Mention Handle" }, "model_tier": { "anyOf": [ { "pattern": "^(low|medium|high)$", "type": "string" }, { "type": "null" } ], "title": "Model Tier" }, "soul_markdown": { "anyOf": [ { "maxLength": 20000, "type": "string" }, { "type": "null" } ], "title": "Soul Markdown" }, "system_prompt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "System Prompt" }, "voice_engine": { "anyOf": [ { "pattern": "^(gemini-realtime|self-hosted|openai-realtime)$", "type": "string" }, { "type": "null" } ], "title": "Voice Engine" } }, "title": "AIEmployeePatch", "type": "object" }, "AIEmployeeRequest": { "properties": { "avatar_treatment": { "default": "sparkle", "maxLength": 80, "minLength": 1, "title": "Avatar Treatment", "type": "string" }, "default_playback_speed": { "default": 1.0, "maximum": 2.0, "minimum": 0.5, "title": "Default Playback Speed", "type": "number" }, "default_voice_id": { "anyOf": [ { "maxLength": 120, "type": "string" }, { "type": "null" } ], "title": "Default Voice Id" }, "display_name": { "maxLength": 120, "minLength": 1, "title": "Display Name", "type": "string" }, "enabled": { "default": true, "title": "Enabled", "type": "boolean" }, "hire": { "anyOf": [ { "$ref": "#/components/schemas/HostedHireContext" }, { "type": "null" } ] }, "manners_markdown": { "default": "# TIDY MANNERS\n\nYou are connected to Tidy as a virtual employee.\n\nWhen you are in a group chat, you can read the conversation for context, but you should not reply to every message. Speak up when someone addresses you by name, asks you a question, delegates a task to you, replies to your current work, or you need to report meaningful progress, a blocker, or completion. Answer once, in the thread you were reached in. Never reply only to agree, thank or acknowledge, and never repeat what someone else already said.\n\nDo not assume every group message is for you. If the conversation is between other people or other employees, follow along silently. If you are unsure whether you are being asked to act, ask one short clarifying question or wait.\n\nDo not take action on private data or delegated work unless Tidy grants you the needed tool access.\n\n## Work skill-first\n\nBefore starting any multi-step task, list your installed skills and read the one that matches the task: its SKILL.md first, then only the reference file it points you to for this task, not every file. It carries the commands, paths, credentials, and failure remedies you would otherwise rediscover by trial and error. Follow the matching skill's steps instead of probing with ad-hoc terminal commands. Improvise only when no installed skill matches the task.\n\n## Colleagues and your inbox\n\nYou may work alongside other virtual employees. To tell, ask, or update a colleague, call `message_employee` with their name, and pass the item's `item_ref` when the message is about one. On shared work, a comment on the task that @mentions their handle reaches them too. `send_to_assistant` reaches Tidy's built-in assistant, never a colleague, and its reply is not theirs.\n\nMessages colleagues send you and @mentions waiting on you are in your inbox. Check it with `agent_inbox` when you start work, and before you tell anyone whether a message arrived. Answer a comment mention with `comment_reply` in its thread; reply to a colleague with `message_employee`.\n\nTidy also keeps a home room for you, where it posts system alerts. It is not a chat and no one waits in it to talk; every mention and colleague message it alerts you to is also in `agent_inbox`.\n\n## Shared knowledge framing\n\nTidy's memory holds facts from ALL of the user's assistants and from their notes, email, calendar and contacts, and recalls the ones relevant to a message for you under \"Personal Context\". Present a shared fact that did not come from your own conversation with this user as Tidy's record (\"our records show the launch moved to March\"), NEVER as your own history with them (\"as we discussed\", \"you told me\"): that fabricates a history and breaks their trust.\n\n## Recording and correcting memory\n\nWrite to memory only deliberately, never every turn. The tidy-mcp skill says when to correct a fact in the user's shared memory, when to keep a note of your own, and how to check what you remember.", "maxLength": 20000, "title": "Manners Markdown", "type": "string" }, "mention_handle": { "maxLength": 80, "minLength": 2, "title": "Mention Handle", "type": "string" }, "model_tier": { "default": "medium", "pattern": "^(low|medium|high)$", "title": "Model Tier", "type": "string" }, "role_title": { "anyOf": [ { "maxLength": 160, "type": "string" }, { "type": "null" } ], "title": "Role Title" }, "skills": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Skills" }, "soul_markdown": { "default": "", "maxLength": 20000, "title": "Soul Markdown", "type": "string" }, "system_prompt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "System Prompt" }, "voice_engine": { "default": "gemini-realtime", "pattern": "^(gemini-realtime|self-hosted|openai-realtime)$", "title": "Voice Engine", "type": "string" } }, "required": [ "display_name", "mention_handle" ], "title": "AIEmployeeRequest", "type": "object" }, "AIEmployeeResponse": { "properties": { "agent_account_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "default": null, "title": "Agent Account Id" }, "avatar_treatment": { "title": "Avatar Treatment", "type": "string" }, "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "default_playback_speed": { "default": 1.0, "title": "Default Playback Speed", "type": "number" }, "default_voice_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Default Voice Id" }, "display_name": { "title": "Display Name", "type": "string" }, "enabled": { "title": "Enabled", "type": "boolean" }, "hire_note": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Hire Note" }, "hired_skills": { "items": { "type": "string" }, "title": "Hired Skills", "type": "array" }, "id": { "format": "uuid", "title": "Id", "type": "string" }, "manners_markdown": { "default": "# TIDY MANNERS\n\nYou are connected to Tidy as a virtual employee.\n\nWhen you are in a group chat, you can read the conversation for context, but you should not reply to every message. Speak up when someone addresses you by name, asks you a question, delegates a task to you, replies to your current work, or you need to report meaningful progress, a blocker, or completion. Answer once, in the thread you were reached in. Never reply only to agree, thank or acknowledge, and never repeat what someone else already said.\n\nDo not assume every group message is for you. If the conversation is between other people or other employees, follow along silently. If you are unsure whether you are being asked to act, ask one short clarifying question or wait.\n\nDo not take action on private data or delegated work unless Tidy grants you the needed tool access.\n\n## Work skill-first\n\nBefore starting any multi-step task, list your installed skills and read the one that matches the task: its SKILL.md first, then only the reference file it points you to for this task, not every file. It carries the commands, paths, credentials, and failure remedies you would otherwise rediscover by trial and error. Follow the matching skill's steps instead of probing with ad-hoc terminal commands. Improvise only when no installed skill matches the task.\n\n## Colleagues and your inbox\n\nYou may work alongside other virtual employees. To tell, ask, or update a colleague, call `message_employee` with their name, and pass the item's `item_ref` when the message is about one. On shared work, a comment on the task that @mentions their handle reaches them too. `send_to_assistant` reaches Tidy's built-in assistant, never a colleague, and its reply is not theirs.\n\nMessages colleagues send you and @mentions waiting on you are in your inbox. Check it with `agent_inbox` when you start work, and before you tell anyone whether a message arrived. Answer a comment mention with `comment_reply` in its thread; reply to a colleague with `message_employee`.\n\nTidy also keeps a home room for you, where it posts system alerts. It is not a chat and no one waits in it to talk; every mention and colleague message it alerts you to is also in `agent_inbox`.\n\n## Shared knowledge framing\n\nTidy's memory holds facts from ALL of the user's assistants and from their notes, email, calendar and contacts, and recalls the ones relevant to a message for you under \"Personal Context\". Present a shared fact that did not come from your own conversation with this user as Tidy's record (\"our records show the launch moved to March\"), NEVER as your own history with them (\"as we discussed\", \"you told me\"): that fabricates a history and breaks their trust.\n\n## Recording and correcting memory\n\nWrite to memory only deliberately, never every turn. The tidy-mcp skill says when to correct a fact in the user's shared memory, when to keep a note of your own, and how to check what you remember.", "title": "Manners Markdown", "type": "string" }, "matrix_user_id": { "title": "Matrix User Id", "type": "string" }, "mention_handle": { "title": "Mention Handle", "type": "string" }, "model_tier": { "title": "Model Tier", "type": "string" }, "role_title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Role Title" }, "service_account_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Service Account Id" }, "soul_markdown": { "default": "", "title": "Soul Markdown", "type": "string" }, "system_prompt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "System Prompt" }, "tenant_id": { "format": "uuid", "title": "Tenant Id", "type": "string" }, "updated_at": { "format": "date-time", "title": "Updated At", "type": "string" }, "voice_engine": { "default": "gemini-realtime", "title": "Voice Engine", "type": "string" } }, "required": [ "id", "tenant_id", "display_name", "mention_handle", "matrix_user_id", "service_account_id", "system_prompt", "model_tier", "avatar_treatment", "enabled", "created_at", "updated_at" ], "title": "AIEmployeeResponse", "type": "object" }, "AIEmployeeSkill": { "properties": { "id": { "format": "uuid", "title": "Id", "type": "string" }, "name": { "title": "Name", "type": "string" } }, "required": [ "id", "name" ], "title": "AIEmployeeSkill", "type": "object" }, "AIEmployeeSkillsResponse": { "properties": { "ai_employee_id": { "format": "uuid", "title": "Ai Employee Id", "type": "string" }, "skills": { "items": { "$ref": "#/components/schemas/AIEmployeeSkill" }, "title": "Skills", "type": "array" } }, "required": [ "ai_employee_id" ], "title": "AIEmployeeSkillsResponse", "type": "object" }, "AIEmployeeSkillsUpdate": { "description": "Reconcile an employee's assigned skills to exactly this set (R9).", "properties": { "skill_ids": { "items": { "format": "uuid", "type": "string" }, "title": "Skill Ids", "type": "array" } }, "title": "AIEmployeeSkillsUpdate", "type": "object" }, "AcceptBatchRequest": { "properties": { "batch_id": { "format": "uuid", "title": "Batch Id", "type": "string" } }, "required": [ "batch_id" ], "title": "AcceptBatchRequest", "type": "object" }, "AcceptBatchResponse": { "properties": { "accepted": { "title": "Accepted", "type": "integer" }, "rule_ids": { "items": { "type": "string" }, "title": "Rule Ids", "type": "array" } }, "required": [ "accepted", "rule_ids" ], "title": "AcceptBatchResponse", "type": "object" }, "AcceptPortraitResponse": { "properties": { "evicted_ids": { "description": "Portraits removed by the last-5 retention bound, if any.", "items": { "type": "string" }, "title": "Evicted Ids", "type": "array" }, "portrait": { "$ref": "#/components/schemas/PortraitModel" } }, "required": [ "portrait", "evicted_ids" ], "title": "AcceptPortraitResponse", "type": "object" }, "AcceptProposalResponse": { "description": "Response model after accepting a time proposal.", "example": { "accepted": true, "event_id": "550e8400-e29b-41d4-a716-446655440000", "ics_uid": "abc123@google.com", "new_end": "2024-01-15T15:00:00Z", "new_start": "2024-01-15T14:00:00Z", "proposed_by": "sarah@example.com" }, "properties": { "accepted": { "default": true, "description": "Whether the proposal was accepted", "title": "Accepted", "type": "boolean" }, "event_id": { "description": "Calendar event UUID", "title": "Event Id", "type": "string" }, "ics_uid": { "description": "ICS UID of the event", "title": "Ics Uid", "type": "string" }, "new_end": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "New event end time (ISO format)", "title": "New End" }, "new_start": { "description": "New event start time (ISO format)", "title": "New Start", "type": "string" }, "proposed_by": { "description": "Email of person who proposed the change", "title": "Proposed By", "type": "string" } }, "required": [ "event_id", "ics_uid", "new_start", "proposed_by" ], "title": "AcceptProposalResponse", "type": "object" }, "AcceptResponse": { "properties": { "rule_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Rule Id" }, "status": { "title": "Status", "type": "string" } }, "required": [ "status", "rule_id" ], "title": "AcceptResponse", "type": "object" }, "AcceptSuggestionResponse": { "properties": { "display_subject": { "title": "Display Subject", "type": "string" }, "email_id": { "format": "uuid", "title": "Email Id", "type": "string" } }, "required": [ "email_id", "display_subject" ], "title": "AcceptSuggestionResponse", "type": "object" }, "AcceptanceMetricPeriod": { "description": "One acceptance cohort (TIDY-15442).\n\nA cohort is a UTC day, a proposal source, the evidence class that carried\nthe proposal, and the confidence-model version that scored it. It carries no\nmember identifier, address, domain or message content — an acceptance\naggregate is a tenant fact, not a record of who wrote to whom.", "properties": { "acceptance_rate": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Acceptance Rate" }, "approved_count": { "title": "Approved Count", "type": "integer" }, "confidence_model_version": { "title": "Confidence Model Version", "type": "integer" }, "decided_count": { "title": "Decided Count", "type": "integer" }, "expired_count": { "title": "Expired Count", "type": "integer" }, "max_decision_seconds": { "title": "Max Decision Seconds", "type": "integer" }, "mean_decision_seconds": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Mean Decision Seconds" }, "merged_count": { "title": "Merged Count", "type": "integer" }, "muted_count": { "title": "Muted Count", "type": "integer" }, "pending_count": { "title": "Pending Count", "type": "integer" }, "period_start": { "format": "date", "title": "Period Start", "type": "string" }, "proposed_count": { "title": "Proposed Count", "type": "integer" }, "raise_reason": { "title": "Raise Reason", "type": "string" }, "rejected_count": { "title": "Rejected Count", "type": "integer" }, "rolled_up_at": { "format": "date-time", "title": "Rolled Up At", "type": "string" }, "source_kind": { "title": "Source Kind", "type": "string" } }, "required": [ "period_start", "source_kind", "raise_reason", "confidence_model_version", "proposed_count", "pending_count", "approved_count", "rejected_count", "muted_count", "expired_count", "merged_count", "decided_count", "acceptance_rate", "mean_decision_seconds", "max_decision_seconds", "rolled_up_at" ], "title": "AcceptanceMetricPeriod", "type": "object" }, "AcceptanceMetricsResponse": { "properties": { "automation_promotion": { "$ref": "#/components/schemas/AutomationPromotionStatus" }, "periods": { "items": { "$ref": "#/components/schemas/AcceptanceMetricPeriod" }, "title": "Periods", "type": "array" }, "total": { "title": "Total", "type": "integer" } }, "required": [ "periods", "total", "automation_promotion" ], "title": "AcceptanceMetricsResponse", "type": "object" }, "AccessAttemptRequest": { "description": "The portal whose edge gate produced this attempt.", "properties": { "portal_id": { "maxLength": 64, "minLength": 1, "title": "Portal Id", "type": "string" } }, "required": [ "portal_id" ], "title": "AccessAttemptRequest", "type": "object" }, "AccessAttemptResponse": { "properties": { "outcome": { "enum": [ "success", "denied" ], "title": "Outcome", "type": "string" }, "portal_id": { "title": "Portal Id", "type": "string" }, "recorded": { "title": "Recorded", "type": "boolean" } }, "required": [ "portal_id", "outcome", "recorded" ], "title": "AccessAttemptResponse", "type": "object" }, "AccessHistoryEntry": { "description": "Audit log entry for security access history.", "properties": { "action": { "title": "Action", "type": "string" }, "actor_account_id": { "title": "Actor Account Id", "type": "string" }, "actor_email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Actor Email" }, "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "details": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "title": "Details" }, "id": { "title": "Id", "type": "string" }, "ip_address": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Ip Address" }, "resource_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Resource Id" }, "resource_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Resource Type" } }, "required": [ "id", "action", "actor_account_id", "created_at" ], "title": "AccessHistoryEntry", "type": "object" }, "AccessHistoryResponse": { "description": "Response for access history.", "properties": { "entries": { "items": { "$ref": "#/components/schemas/AccessHistoryEntry" }, "title": "Entries", "type": "array" }, "total": { "title": "Total", "type": "integer" } }, "required": [ "entries", "total" ], "title": "AccessHistoryResponse", "type": "object" }, "AccessKeyIssuanceRecord": { "properties": { "code": { "title": "Code", "type": "string" }, "discord_handle": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Discord Handle" }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Email" }, "issued_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Issued At" } }, "required": [ "code", "discord_handle", "email", "issued_at" ], "title": "AccessKeyIssuanceRecord", "type": "object" }, "AccessKeyIssueRequest": { "properties": { "discord_handle": { "description": "The member's Discord username — the issuance key. Normalized (lowercased, leading '@' stripped), so one person cannot collect a key per spelling.", "maxLength": 64, "minLength": 1, "title": "Discord Handle", "type": "string" }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The address the member self-reported, recorded against the handle on the pool row. Capturing the person as a LEAD (and mirroring the key onto it) is the caller's follow-up through the capture door with the tenant's own lead facet.", "title": "Email" }, "prefix": { "default": "DISCORD", "description": "Invite-code pool to claim from. The community pool by default — never a campaign's pool.", "maxLength": 32, "minLength": 1, "title": "Prefix", "type": "string" } }, "required": [ "discord_handle" ], "title": "AccessKeyIssueRequest", "type": "object" }, "AccessKeyIssueResponse": { "properties": { "available": { "description": "Claimable codes left in the pool.", "title": "Available", "type": "integer" }, "code": { "description": "The key to DM the member.", "title": "Code", "type": "string" }, "discord_handle": { "title": "Discord Handle", "type": "string" }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Email" }, "issued_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Issued At" }, "low_stock": { "description": "Below the escalation threshold — tell the Manager to mint more.", "title": "Low Stock", "type": "boolean" }, "outcome": { "description": "'issued' for a fresh claim, 'existing' when the member already held a key — a re-ask returns the same key (R17).", "title": "Outcome", "type": "string" } }, "required": [ "code", "outcome", "discord_handle", "email", "issued_at", "available", "low_stock" ], "title": "AccessKeyIssueResponse", "type": "object" }, "AccessKeyStockResponse": { "properties": { "available": { "title": "Available", "type": "integer" }, "issued": { "title": "Issued", "type": "integer" }, "issued_to_handles": { "description": "Codes issued to a Discord member specifically.", "title": "Issued To Handles", "type": "integer" }, "low_stock": { "title": "Low Stock", "type": "boolean" }, "low_stock_threshold": { "title": "Low Stock Threshold", "type": "integer" }, "prefix": { "title": "Prefix", "type": "string" }, "redeemed": { "title": "Redeemed", "type": "integer" } }, "required": [ "prefix", "available", "issued", "redeemed", "issued_to_handles", "low_stock_threshold", "low_stock" ], "title": "AccessKeyStockResponse", "type": "object" }, "AccessKeyUnredeemedResponse": { "properties": { "issuances": { "items": { "$ref": "#/components/schemas/AccessKeyIssuanceRecord" }, "title": "Issuances", "type": "array" }, "older_than_days": { "title": "Older Than Days", "type": "integer" }, "prefix": { "title": "Prefix", "type": "string" } }, "required": [ "prefix", "older_than_days", "issuances" ], "title": "AccessKeyUnredeemedResponse", "type": "object" }, "AccountChip": { "additionalProperties": false, "properties": { "hue": { "exclusiveMaximum": 360.0, "minimum": 0.0, "title": "Hue", "type": "integer" }, "initials": { "maxLength": 2, "minLength": 1, "title": "Initials", "type": "string" } }, "required": [ "initials", "hue" ], "title": "AccountChip", "type": "object" }, "AccountCredits": { "properties": { "billing_period_start": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Billing Period Start" }, "per_user": { "default": [], "items": { "$ref": "#/components/schemas/UserCreditRollup" }, "title": "Per User", "type": "array" }, "period_inflow": { "default": 0.0, "title": "Period Inflow", "type": "number" }, "pool_balance": { "default": 0.0, "title": "Pool Balance", "type": "number" }, "recent_ledger": { "default": [], "items": { "$ref": "#/components/schemas/CreditLedgerEntry" }, "title": "Recent Ledger", "type": "array" } }, "title": "AccountCredits", "type": "object" }, "AccountDetailResponse": { "properties": { "audit_trail": { "items": { "$ref": "#/components/schemas/AuditTrailEntry" }, "title": "Audit Trail", "type": "array" }, "credits": { "$ref": "#/components/schemas/AccountCredits" }, "entitlements": { "$ref": "#/components/schemas/AccountEntitlements" }, "inboxes": { "$ref": "#/components/schemas/AccountInboxes" }, "overrides": { "items": { "$ref": "#/components/schemas/AccountOverride" }, "title": "Overrides", "type": "array" }, "overview": { "$ref": "#/components/schemas/AccountOverview" }, "pipeline": { "$ref": "#/components/schemas/AccountPipeline" }, "subscription": { "$ref": "#/components/schemas/AccountSubscription" } }, "required": [ "overview", "subscription", "entitlements", "overrides", "credits", "inboxes", "pipeline", "audit_trail" ], "title": "AccountDetailResponse", "type": "object" }, "AccountDiscountsResponse": { "properties": { "coupons": { "default": [], "items": { "$ref": "#/components/schemas/AdminStripeCoupon" }, "title": "Coupons", "type": "array" }, "dashboard_url": { "title": "Dashboard Url", "type": "string" }, "discounts": { "default": [], "items": { "$ref": "#/components/schemas/AdminSubscriptionDiscount" }, "title": "Discounts", "type": "array" }, "livemode": { "title": "Livemode", "type": "boolean" }, "stripe_subscription_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Stripe Subscription Id" }, "tenant_id": { "title": "Tenant Id", "type": "string" } }, "required": [ "tenant_id", "livemode", "dashboard_url" ], "title": "AccountDiscountsResponse", "type": "object" }, "AccountEntitlements": { "properties": { "allotments": { "additionalProperties": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "default": {}, "title": "Allotments", "type": "object" }, "billing_exempt": { "default": false, "title": "Billing Exempt", "type": "boolean" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Error" }, "features": { "additionalProperties": { "type": "boolean" }, "default": {}, "title": "Features", "type": "object" }, "tier_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Tier Id" } }, "title": "AccountEntitlements", "type": "object" }, "AccountIdentity": { "additionalProperties": false, "properties": { "account_generation": { "format": "uuid", "title": "Account Generation", "type": "string" }, "chip": { "$ref": "#/components/schemas/AccountChip" }, "label": { "maxLength": 260, "minLength": 1, "title": "Label", "type": "string" }, "plan": { "anyOf": [ { "maxLength": 64, "pattern": "^[a-zA-Z0-9 _-]+$", "type": "string" }, { "type": "null" } ], "title": "Plan" } }, "required": [ "label", "account_generation", "chip" ], "title": "AccountIdentity", "type": "object" }, "AccountInboxes": { "properties": { "addon_inboxes": { "default": 0, "title": "Addon Inboxes", "type": "integer" }, "addon_inboxes_via": { "default": "override", "enum": [ "stripe", "override" ], "title": "Addon Inboxes Via", "type": "string" }, "allowed": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Allowed" }, "connected": { "default": 0, "title": "Connected", "type": "integer" } }, "title": "AccountInboxes", "type": "object" }, "AccountMe": { "description": "Response body for ``GET /accounts/me`` and ``PATCH /accounts/me``.\n\nOnly exposes fields the caller needs — this is not a full accounts\ndump. ``datetime`` fields serialize via the canonical ISO UTC helper\n(millisecond precision, trailing ``Z``) per the Tidy Time Standard.", "properties": { "active_timezone": { "title": "Active Timezone", "type": "string" }, "billing_exempt": { "default": false, "title": "Billing Exempt", "type": "boolean" }, "deletion_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Deletion Status" }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Email" }, "has_pending_deletion": { "default": false, "title": "Has Pending Deletion", "type": "boolean" }, "home_timezone": { "title": "Home Timezone", "type": "string" }, "id": { "format": "uuid", "title": "Id", "type": "string" }, "is_admin": { "default": false, "title": "Is Admin", "type": "boolean" }, "plan_tier": { "default": "core", "title": "Plan Tier", "type": "string" }, "subscribe_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Subscribe Reason" }, "subscription_required": { "default": false, "title": "Subscription Required", "type": "boolean" }, "subscription_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Subscription Status" }, "timezone_auto_detected_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Timezone Auto Detected At" }, "trial_days": { "default": 0, "title": "Trial Days", "type": "integer" }, "trial_end": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Trial End" }, "trial_expired": { "default": false, "title": "Trial Expired", "type": "boolean" }, "trial_started_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Trial Started At" } }, "required": [ "id", "email", "home_timezone", "active_timezone", "timezone_auto_detected_at" ], "title": "AccountMe", "type": "object" }, "AccountMeUpdate": { "additionalProperties": false, "description": "Partial-update body for ``PATCH /accounts/me``.\n\nAll fields optional. Unknown fields rejected to keep the contract tight\n(we may expand over time; extra fields should fail loudly so the\nclient can fix the call site).\n\nTimezone validation happens in the endpoint body (not via a Pydantic\n``field_validator``) so that invalid zones return 400 per the Tidy\nTime Standard AC, rather than FastAPI's default 422. We keep the model\nitself format-permissive and rely on ``validate_iana_timezone`` at the\nroute boundary.", "properties": { "active_timezone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "IANA zone name the UI should display in. Travelers override this.", "title": "Active Timezone" }, "home_timezone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "IANA zone name for the caller's permanent home.", "title": "Home Timezone" } }, "title": "AccountMeUpdate", "type": "object" }, "AccountOverride": { "properties": { "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "created_by": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Created By" }, "dimension": { "title": "Dimension", "type": "string" }, "expires_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Expires At" }, "id": { "title": "Id", "type": "string" }, "reason": { "title": "Reason", "type": "string" }, "value_boolean": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "title": "Value Boolean" }, "value_numeric": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "title": "Value Numeric" } }, "required": [ "id", "dimension", "reason", "created_at" ], "title": "AccountOverride", "type": "object" }, "AccountOverrideCreate": { "properties": { "dimension": { "description": "A plan_tiers entitlement column name", "title": "Dimension", "type": "string" }, "expires_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Expires At" }, "reason": { "description": "Audit reason (required)", "title": "Reason", "type": "string" }, "value_boolean": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Value Boolean" }, "value_numeric": { "anyOf": [ { "type": "number" }, { "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$", "type": "string" }, { "type": "null" } ], "title": "Value Numeric" } }, "required": [ "dimension", "reason" ], "title": "AccountOverrideCreate", "type": "object" }, "AccountOverrideResponse": { "properties": { "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "created_by": { "format": "uuid", "title": "Created By", "type": "string" }, "dimension": { "title": "Dimension", "type": "string" }, "expires_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Expires At" }, "id": { "format": "uuid", "title": "Id", "type": "string" }, "reason": { "title": "Reason", "type": "string" }, "tenant_id": { "format": "uuid", "title": "Tenant Id", "type": "string" }, "value_boolean": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Value Boolean" }, "value_numeric": { "anyOf": [ { "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$", "type": "string" }, { "type": "null" } ], "title": "Value Numeric" } }, "required": [ "id", "tenant_id", "dimension", "reason", "created_by", "created_at" ], "title": "AccountOverrideResponse", "type": "object" }, "AccountOverview": { "properties": { "billing_exempt": { "default": false, "title": "Billing Exempt", "type": "boolean" }, "created_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Created At" }, "env": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Env" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Name" }, "owner_email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Owner Email" }, "status": { "title": "Status", "type": "string" }, "stripe_dashboard_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Stripe Dashboard Url" }, "stripe_livemode": { "default": false, "title": "Stripe Livemode", "type": "boolean" }, "tenant_id": { "title": "Tenant Id", "type": "string" } }, "required": [ "tenant_id", "status" ], "title": "AccountOverview", "type": "object" }, "AccountPipeline": { "properties": { "courtesy": { "default": false, "title": "Courtesy", "type": "boolean" }, "cycle_start": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Cycle Start" }, "emails_allotted": { "default": 0, "title": "Emails Allotted", "type": "integer" }, "emails_processed": { "default": 0, "title": "Emails Processed", "type": "integer" }, "reset_date": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Reset Date" }, "stage": { "default": "normal", "title": "Stage", "type": "string" }, "utilization": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "title": "Utilization" } }, "title": "AccountPipeline", "type": "object" }, "AccountPlanResponse": { "description": "Response model for account plan information.\n\nSourced from the entitlement resolver (F2). `plan_name` is the real\n`plan_tiers.tier_id` (core / plus / max) — never a legacy tier alias.", "properties": { "features": { "description": "List of enabled features", "items": { "type": "string" }, "title": "Features", "type": "array" }, "has_bulk_import": { "description": "Whether bulk import is enabled", "title": "Has Bulk Import", "type": "boolean" }, "max_files_per_import": { "description": "Import email allotment (0 = disabled/unlimited)", "title": "Max Files Per Import", "type": "integer" }, "plan_name": { "description": "Plan tier id: core, plus, max", "title": "Plan Name", "type": "string" } }, "required": [ "plan_name", "has_bulk_import", "max_files_per_import" ], "title": "AccountPlanResponse", "type": "object" }, "AccountSearchResult": { "properties": { "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Name" }, "owner_email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Owner Email" }, "status": { "title": "Status", "type": "string" }, "tenant_id": { "title": "Tenant Id", "type": "string" }, "tier": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Tier" } }, "required": [ "tenant_id", "status" ], "title": "AccountSearchResult", "type": "object" }, "AccountSearchStatus": { "properties": { "account_id": { "format": "uuid", "title": "Account Id", "type": "string" }, "account_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Account Name" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error" }, "latency_ms": { "title": "Latency Ms", "type": "number" }, "result_count": { "title": "Result Count", "type": "integer" }, "status": { "title": "Status", "type": "string" } }, "required": [ "account_id", "account_name", "result_count", "latency_ms", "status" ], "title": "AccountSearchStatus", "type": "object" }, "AccountSubscription": { "properties": { "cancel_at_period_end": { "default": false, "title": "Cancel At Period End", "type": "boolean" }, "current_period_end": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Current Period End" }, "current_period_start": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Current Period Start" }, "resolved_status": { "default": "none", "title": "Resolved Status", "type": "string" }, "seats": { "default": 0, "title": "Seats", "type": "integer" }, "stripe_customer_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Stripe Customer Id" }, "stripe_customer_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Stripe Customer Url" }, "stripe_price_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Stripe Price Id" }, "stripe_subscription_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Stripe Subscription Id" }, "stripe_subscription_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Stripe Subscription Url" }, "subscription_required": { "default": false, "title": "Subscription Required", "type": "boolean" }, "subscription_status": { "default": "none", "title": "Subscription Status", "type": "string" }, "tier": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Tier" }, "trial_end": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Trial End" } }, "title": "AccountSubscription", "type": "object" }, "AccountUsageByKindResponse": { "properties": { "by_kind": { "default": [], "items": { "$ref": "#/components/schemas/_AccountKindBreakdown" }, "title": "By Kind", "type": "array" }, "period_end": { "format": "date-time", "title": "Period End", "type": "string" }, "period_start": { "format": "date-time", "title": "Period Start", "type": "string" } }, "required": [ "period_start", "period_end" ], "title": "AccountUsageByKindResponse", "type": "object" }, "AcpAuthMethodReport": { "description": "TIDY-19931 (F7) — one sign-in method an ACP registry agent declared\n(`AcpAuthMethodWireV1` in `packages/matrix-message-schema`).", "properties": { "args": { "anyOf": [ { "items": { "maxLength": 512, "type": "string" }, "maxItems": 32, "type": "array" }, { "type": "null" } ], "title": "Args" }, "description": { "anyOf": [ { "maxLength": 1024, "type": "string" }, { "type": "null" } ], "title": "Description" }, "id": { "maxLength": 128, "minLength": 1, "title": "Id", "type": "string" }, "name": { "maxLength": 160, "minLength": 1, "title": "Name", "type": "string" }, "type": { "enum": [ "agent", "env_var", "terminal" ], "title": "Type", "type": "string" }, "vars": { "anyOf": [ { "items": { "type": "string" }, "maxItems": 16, "type": "array" }, { "type": "null" } ], "title": "Vars" } }, "required": [ "id", "name", "type" ], "title": "AcpAuthMethodReport", "type": "object" }, "ActionCapability": { "description": "A canonical authoring verb, the scope it needs, whether THIS caller's\ngrant covers it, and one worked example to correct against.", "properties": { "action": { "title": "Action", "type": "string" }, "endpoint": { "$ref": "#/components/schemas/ActionEndpoint" }, "example": { "additionalProperties": true, "title": "ActionCapabilityExample", "type": "object" }, "granted": { "title": "Granted", "type": "boolean" }, "mutates": { "title": "Mutates", "type": "boolean" }, "scope": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Scope" }, "summary": { "default": "", "title": "Summary", "type": "string" }, "tool": { "title": "Tool", "type": "string" } }, "required": [ "action", "tool", "endpoint", "mutates", "granted" ], "title": "ActionCapability", "type": "object" }, "ActionEndpoint": { "description": "The API call a verb makes. The scope beside it is read off THIS route.", "properties": { "method": { "title": "Method", "type": "string" }, "path": { "title": "Path", "type": "string" } }, "required": [ "method", "path" ], "title": "ActionEndpoint", "type": "object" }, "ActionItem": { "properties": { "assignee_matrix_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Assignee Matrix Id" }, "event_id": { "title": "Event Id", "type": "string" }, "text": { "title": "Text", "type": "string" } }, "required": [ "text", "event_id" ], "title": "ActionItem", "type": "object" }, "ActionParamSpec": { "description": "Resolution config for a single handler input (D9).\n\n``source`` selects the resolver branch:\n * ``system`` → ``value`` is a ``$``-var / ``{{ }}`` template (variable_engine)\n * ``property`` → ``value`` is a property key read from the subject row\n * ``formula`` → ``value`` is a formula expression (formula_engine)\n * ``prompt`` → ``value`` omitted; filled from ``prompt_values[key]``\n\nTIDY-18238 — ``placeholder`` and ``match_property`` are declared here even\nthough this service never resolves either (both are client-side prompt-modal\nconcerns). This model is one of the three canonical statements of the param\ncontract, alongside the web ``ActionParamSpec`` and the Kotlin one, and it is\nwhat a reader consults to learn which keys a stored param may carry.\n``placeholder`` (TIDY-14917) and ``match_property`` (this story) were both\nstamped onto live definitions by migrations while every server-side\ndeclaration of the contract still omitted them — the same divergence that,\non the web side, silently erased the whole owning action from every surface.\nDeclaring them keeps the enumeration honest and makes any future\n``model_dump`` round-trip carry them instead of quietly dropping them.", "properties": { "default": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Default" }, "key": { "description": "Handler input name", "title": "Key", "type": "string" }, "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Prompt-modal field label (prompt)", "title": "Label" }, "match_property": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Subject property whose value this prompt field must exactly equal before the modal will submit — the typed confirmation names the ROW, not the verb (TIDY-18238). Enforced client-side; the server keeps its own gate.", "title": "Match Property" }, "placeholder": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Prompt-modal field placeholder/hint (prompt) — TIDY-14917", "title": "Placeholder" }, "required": { "default": false, "description": "Whether the handler requires this input", "title": "Required", "type": "boolean" }, "source": { "description": "Resolution source", "enum": [ "system", "property", "formula", "prompt" ], "title": "Source", "type": "string" }, "type": { "anyOf": [ { "enum": [ "string", "number", "boolean", "date", "uuid", "email" ], "type": "string" }, { "type": "null" } ], "title": "Type" }, "value": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "$-var/{{ }} (system) | property key (property) | expression (formula)", "title": "Value" } }, "required": [ "key", "source" ], "title": "ActionParamSpec", "type": "object" }, "ActionableMention": { "description": "One un-acted actionable mention in a virtual employee's inbox (S3).\n\nCarries a resolver key + non-secret hint — never a secret/MXID. The\nruntime re-resolves the comment via ``tidy://comments/{comment_id}`` under\nthe mention grant (no parent-doc leak). Chat rows carry the room + event id\nso the runtime can reply in the originating room.\n\nFor comment rows it additionally carries the highlighted ``anchor_text``\n(the instruction the agent must act on) + ``anchor_block_id`` and the comment\n``comment_body`` (TIDY-11594). These are authorized by the SAME mention grant\nthat authorizes the comment thread + anchor (TIDY-11434/R6) — delivering them\nadds no new authorization surface and lets the agent act on the highlighted\ninstruction WITHOUT any parent-document read.", "properties": { "anchor_block_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Anchor Block Id" }, "anchor_text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Anchor Text" }, "body_snippet": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Body Snippet" }, "comment_body": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Comment Body" }, "comment_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Comment Id" }, "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "delivered_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Delivered At" }, "id": { "title": "Id", "type": "string" }, "matrix_event_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Matrix Event Id" }, "matrix_room_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Matrix Room Id" }, "source": { "enum": [ "comment", "chat" ], "title": "Source", "type": "string" } }, "required": [ "id", "source", "created_at" ], "title": "ActionableMention", "type": "object" }, "ActionableMentionAckRequest": { "properties": { "acted_via": { "anyOf": [ { "maxLength": 120, "type": "string" }, { "type": "null" } ], "title": "Acted Via" } }, "title": "ActionableMentionAckRequest", "type": "object" }, "ActionableMentionAckResponse": { "properties": { "acted": { "title": "Acted", "type": "boolean" }, "already_acted": { "default": false, "title": "Already Acted", "type": "boolean" }, "id": { "title": "Id", "type": "string" } }, "required": [ "id", "acted" ], "title": "ActionableMentionAckResponse", "type": "object" }, "ActionableMentionInboxResponse": { "properties": { "mentions": { "items": { "$ref": "#/components/schemas/ActionableMention" }, "title": "Mentions", "type": "array" } }, "title": "ActionableMentionInboxResponse", "type": "object" }, "ActivatedBundleResponse": { "description": "A bundle that just became THE active one for its owner.\n\n``archived_bundle_ids`` names the bundles archived to keep the invariant.\nThe client turns that into the \"you had another bundle open — keep it or\ndiscard it?\" prompt (R8): keeping it needs no call, discarding it is a\nDELETE. The server never discards on the user's behalf.", "properties": { "archived_bundle_ids": { "default": [], "items": { "type": "string" }, "title": "Archived Bundle Ids", "type": "array" }, "created_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Created At" }, "facet_slug": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Facet Slug" }, "id": { "title": "Id", "type": "string" }, "instructions": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Instructions" }, "item_count": { "title": "Item Count", "type": "integer" }, "items": { "default": [], "items": { "$ref": "#/components/schemas/BundleItemResponse" }, "title": "Items", "type": "array" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Name" }, "resolution": { "anyOf": [ { "$ref": "#/components/schemas/ResolutionResponse" }, { "type": "null" } ], "default": null }, "status": { "title": "Status", "type": "string" }, "token_estimate": { "title": "Token Estimate", "type": "integer" }, "updated_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Updated At" } }, "required": [ "id", "status", "item_count", "token_estimate" ], "title": "ActivatedBundleResponse", "type": "object" }, "ActivationResponse": { "properties": { "activated": { "title": "Activated", "type": "boolean" }, "path": { "title": "Path", "type": "string" }, "sha256": { "title": "Sha256", "type": "string" } }, "required": [ "path", "sha256", "activated" ], "title": "ActivationResponse", "type": "object" }, "ActiveBundleSummary": { "description": "Identity, revision, binding and size of an active bundle — and nothing\nelse. It is what a client needs to focus the row or re-ask with a fresh\nexpectation; it deliberately carries no item content.", "properties": { "facet_slug": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Facet Slug" }, "id": { "title": "Id", "type": "string" }, "item_count": { "title": "Item Count", "type": "integer" }, "updated_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Updated At" } }, "required": [ "id", "item_count" ], "title": "ActiveBundleSummary", "type": "object" }, "ActiveTimeLogResponse": { "description": "The caller's currently-active time log (stopped_at IS NULL), if any.", "properties": { "active_time_log": { "anyOf": [ { "$ref": "#/components/schemas/TimeLogResponse" }, { "type": "null" } ] } }, "title": "ActiveTimeLogResponse", "type": "object" }, "ActiveTimerResponse": { "description": "Response payload for active timer lookup.", "properties": { "active_timer": { "anyOf": [ { "$ref": "#/components/schemas/TimerSessionResponse" }, { "type": "null" } ], "default": null } }, "title": "ActiveTimerResponse", "type": "object" }, "ActivityActor": { "properties": { "account_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Account Id" }, "avatar_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Avatar Url" }, "display_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Display Name" } }, "title": "ActivityActor", "type": "object" }, "ActivityAiScheduleApplyRequest": { "description": "Request payload for applying accepted schedule blocks.", "properties": { "proposal_ids": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Proposal Ids" }, "proposal_set_id": { "title": "Proposal Set Id", "type": "string" } }, "required": [ "proposal_set_id" ], "title": "ActivityAiScheduleApplyRequest", "type": "object" }, "ActivityAiScheduleApplyResponse": { "description": "Response payload for applying schedule blocks.", "properties": { "applied_count": { "title": "Applied Count", "type": "integer" }, "proposal_set_id": { "title": "Proposal Set Id", "type": "string" }, "updated_activity_ids": { "items": { "type": "string" }, "title": "Updated Activity Ids", "type": "array" } }, "required": [ "proposal_set_id", "applied_count" ], "title": "ActivityAiScheduleApplyResponse", "type": "object" }, "ActivityAiScheduleBlock": { "description": "Scheduled activity block generated by AI planner.\n\n``proposal_id``/``proposal_set_id`` are internal identifiers (not\nprimitives). ``activity_id`` is rewritten to ``A-``.", "properties": { "activity_id": { "title": "Activity Id", "type": "string" }, "activity_title": { "title": "Activity Title", "type": "string" }, "blocked_dependency_count": { "default": 0, "title": "Blocked Dependency Count", "type": "integer" }, "blocking_count": { "default": 0, "title": "Blocking Count", "type": "integer" }, "end_time": { "format": "date-time", "title": "End Time", "type": "string" }, "proposal_id": { "title": "Proposal Id", "type": "string" }, "proposal_set_id": { "title": "Proposal Set Id", "type": "string" }, "reason": { "title": "Reason", "type": "string" }, "score": { "title": "Score", "type": "number" }, "start_time": { "format": "date-time", "title": "Start Time", "type": "string" } }, "required": [ "proposal_id", "proposal_set_id", "activity_id", "activity_title", "start_time", "end_time", "score", "reason" ], "title": "ActivityAiScheduleBlock", "type": "object" }, "ActivityAiScheduleRequest": { "description": "Request payload for AI schedule proposal generation.", "properties": { "default_block_minutes": { "default": 30, "maximum": 240.0, "minimum": 15.0, "title": "Default Block Minutes", "type": "integer" }, "max_activities": { "default": 20, "maximum": 100.0, "minimum": 1.0, "title": "Max Activities", "type": "integer" }, "scope": { "default": "day", "enum": [ "day", "week" ], "title": "Scope", "type": "string" }, "start_date": { "anyOf": [ { "format": "date", "type": "string" }, { "type": "null" } ], "title": "Start Date" }, "timezone": { "default": "UTC", "title": "Timezone", "type": "string" }, "workday_end_hour": { "default": 18, "maximum": 24.0, "minimum": 1.0, "title": "Workday End Hour", "type": "integer" }, "workday_start_hour": { "default": 8, "maximum": 23.0, "minimum": 0.0, "title": "Workday Start Hour", "type": "integer" } }, "title": "ActivityAiScheduleRequest", "type": "object" }, "ActivityAiScheduleResponse": { "description": "Response payload for AI schedule proposal generation.", "properties": { "generated_blocks": { "items": { "$ref": "#/components/schemas/ActivityAiScheduleBlock" }, "title": "Generated Blocks", "type": "array" }, "proposal_set_id": { "title": "Proposal Set Id", "type": "string" }, "scope": { "enum": [ "day", "week" ], "title": "Scope", "type": "string" }, "unscheduled_activity_ids": { "items": { "type": "string" }, "title": "Unscheduled Activity Ids", "type": "array" }, "window_end": { "format": "date-time", "title": "Window End", "type": "string" }, "window_start": { "format": "date-time", "title": "Window Start", "type": "string" } }, "required": [ "proposal_set_id", "scope", "window_start", "window_end" ], "title": "ActivityAiScheduleResponse", "type": "object" }, "ActivityArchiveBulkItem": { "description": "Per-id outcome — partial success is explicit, never silent.", "properties": { "archived_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Archived At" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Error" }, "id": { "title": "Id", "type": "string" }, "ok": { "title": "Ok", "type": "boolean" } }, "required": [ "id", "ok" ], "title": "ActivityArchiveBulkItem", "type": "object" }, "ActivityArchiveBulkRequest": { "description": "Bulk archive request — typed IDs (``A-``) or bare UUIDs.", "properties": { "ids": { "items": { "type": "string" }, "maxItems": 500, "minItems": 1, "title": "Ids", "type": "array" } }, "required": [ "ids" ], "title": "ActivityArchiveBulkRequest", "type": "object" }, "ActivityArchiveBulkResponse": { "properties": { "archived_count": { "title": "Archived Count", "type": "integer" }, "failed_count": { "title": "Failed Count", "type": "integer" }, "results": { "items": { "$ref": "#/components/schemas/ActivityArchiveBulkItem" }, "title": "Results", "type": "array" } }, "required": [ "results", "archived_count", "failed_count" ], "title": "ActivityArchiveBulkResponse", "type": "object" }, "ActivityArchiveResponse": { "description": "Archive state after an archive/unarchive transition.", "properties": { "archived_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Archived At" }, "archived_by": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Archived By" }, "changed": { "title": "Changed", "type": "boolean" }, "id": { "title": "Id", "type": "string" } }, "required": [ "id", "changed" ], "title": "ActivityArchiveResponse", "type": "object" }, "ActivityAttachmentResponse": { "description": "Attachment object returned by API.\n\n``id`` is the attachment row id (internal — not a public primitive)\nso it stays bare. ``activity_id`` and ``email_id`` are rewritten.", "properties": { "activity_id": { "title": "Activity Id", "type": "string" }, "attachment_type": { "title": "Attachment Type", "type": "string" }, "content": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Content" }, "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Description" }, "email_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Email Id" }, "id": { "title": "Id", "type": "string" }, "storage_path": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Storage Path" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Title" }, "updated_at": { "format": "date-time", "title": "Updated At", "type": "string" }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Url" } }, "required": [ "id", "activity_id", "attachment_type", "created_at", "updated_at" ], "title": "ActivityAttachmentResponse", "type": "object" }, "ActivityCreate": { "description": "Input model for POST /api/v1/activities.", "properties": { "assigned_by": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Assigned By" }, "assignee": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Assignee" }, "assignee_principal_key": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Assignment intent: account UUID or assistant for the built-in employee.", "title": "Assignee Principal Key" }, "category": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Category" }, "confidence_score": { "anyOf": [ { "maximum": 1.0, "minimum": 0.0, "type": "number" }, { "type": "null" } ], "title": "Confidence Score" }, "custom_properties": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Custom Properties" }, "due_date": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Due Date" }, "due_datetime": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Due Datetime" }, "end": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "End" }, "estimated_duration_minutes": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Estimated Duration Minutes" }, "facet_data": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Facet Data" }, "facets": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Facets" }, "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Id" }, "is_recurring": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is Recurring" }, "owner": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Owner" }, "parent_activity_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Parent Activity Id" }, "plain_text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Plain Text" }, "priority": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Priority" }, "project_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Project Id" }, "recurrence_day_of_month": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Recurrence Day Of Month" }, "recurrence_days_of_week": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Recurrence Days Of Week" }, "recurrence_end_date": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Recurrence End Date" }, "recurrence_interval": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Recurrence Interval" }, "recurrence_pattern": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Recurrence Pattern" }, "snoozed_until": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Snoozed Until" }, "source_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Source Id" }, "source_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": "manual", "title": "Source Type" }, "start": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Start" }, "start_date": { "anyOf": [ { "format": "date", "type": "string" }, { "type": "null" } ], "title": "Start Date" }, "status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Status" }, "tags": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Tags" }, "title": { "maxLength": 500, "minLength": 1, "title": "Title", "type": "string" }, "type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Type" }, "visibility": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": "private", "title": "Visibility" } }, "required": [ "title" ], "title": "ActivityCreate", "type": "object" }, "ActivityDelegationCancelRequest": { "properties": { "reason": { "anyOf": [ { "maxLength": 2000, "type": "string" }, { "type": "null" } ], "description": "Why, in a line: the assignee is told it.", "title": "Reason" } }, "title": "ActivityDelegationCancelRequest", "type": "object" }, "ActivityDelegationCancelResponse": { "properties": { "assignee_account_id": { "title": "Assignee Account Id", "type": "string" }, "assignee_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Assignee Name" }, "cancel_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Cancel Reason" }, "cancelled_by_account_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Cancelled By Account Id" }, "cancelled_delegation_ids": { "description": "It and every hand-off under it, deepest first.", "items": { "type": "string" }, "title": "Cancelled Delegation Ids", "type": "array" }, "changed_objects": { "description": "The Tidy objects its sessions created or changed since the hand-off.", "items": { "$ref": "#/components/schemas/ActivityDelegationChangedObject" }, "title": "Changed Objects", "type": "array" }, "child_activity_id": { "title": "Child Activity Id", "type": "string" }, "child_short_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Child Short Id" }, "child_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Child Status" }, "child_title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Child Title" }, "completion_report": { "anyOf": [ { "$ref": "#/components/schemas/ActivityDelegationCompletionReport" }, { "type": "null" } ], "default": null, "description": "The child's current handoff note, once its assignee wrote one." }, "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "delegation_id": { "title": "Delegation Id", "type": "string" }, "delegator_account_id": { "title": "Delegator Account Id", "type": "string" }, "delegator_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Delegator Name" }, "depth": { "title": "Depth", "type": "integer" }, "holds_line": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "What holds the child's work open right now, in words; null when nothing does.", "title": "Holds Line" }, "parent_activity_id": { "title": "Parent Activity Id", "type": "string" }, "settled_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Settled At" }, "state": { "enum": [ "open", "done", "cancelled" ], "title": "State", "type": "string" }, "stopped_conversation_ids": { "description": "Conversations still working a cancelled task, told to stop.", "items": { "type": "string" }, "title": "Stopped Conversation Ids", "type": "array" }, "work_summary": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "What its sessions did since the hand-off, as one counted sentence; null when nothing yet.", "title": "Work Summary" } }, "required": [ "delegation_id", "parent_activity_id", "child_activity_id", "delegator_account_id", "assignee_account_id", "depth", "state", "created_at", "cancelled_delegation_ids", "stopped_conversation_ids" ], "title": "ActivityDelegationCancelResponse", "type": "object" }, "ActivityDelegationChangedObject": { "properties": { "ids": { "description": "Their typed ids.", "items": { "type": "string" }, "title": "Ids", "type": "array" }, "noun": { "description": "What they are: task, note, contact, …", "title": "Noun", "type": "string" }, "verb": { "description": "What the child's work did to them: Created, Updated, …", "title": "Verb", "type": "string" } }, "required": [ "verb", "noun", "ids" ], "title": "ActivityDelegationChangedObject", "type": "object" }, "ActivityDelegationCompletionReport": { "properties": { "result": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Result" }, "summary": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Summary" } }, "title": "ActivityDelegationCompletionReport", "type": "object" }, "ActivityDelegationCreateRequest": { "properties": { "assignee": { "description": "The colleague to hand it to: an employee's name, slug, @handle or account id.", "maxLength": 200, "minLength": 1, "title": "Assignee", "type": "string" }, "brief": { "description": "What you need from them, standing on its own: the outcome, what you already know, and what to hand back. It becomes the child task's body.", "maxLength": 20000, "minLength": 1, "title": "Brief", "type": "string" }, "client_request_id": { "description": "Your own id for this hand-off. Retrying with the same id and arguments returns the same child task; the same id with other arguments is refused.", "maxLength": 128, "minLength": 1, "pattern": "^[\\x21-\\x7e]+$", "title": "Client Request Id", "type": "string" }, "harness": { "anyOf": [ { "maxLength": 80, "type": "string" }, { "type": "null" } ], "description": "A harness the colleague already has, to run it on.", "title": "Harness" }, "model": { "anyOf": [ { "maxLength": 200, "type": "string" }, { "type": "null" } ], "description": "A model the colleague's owner lets it use.", "title": "Model" }, "reasoning_level": { "anyOf": [ { "maxLength": 40, "type": "string" }, { "type": "null" } ], "title": "Reasoning Level" }, "title": { "description": "The child task's title.", "maxLength": 500, "minLength": 1, "title": "Title", "type": "string" } }, "required": [ "assignee", "title", "brief", "client_request_id" ], "title": "ActivityDelegationCreateRequest", "type": "object" }, "ActivityDelegationCreateResponse": { "properties": { "assignee_account_id": { "title": "Assignee Account Id", "type": "string" }, "assignee_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Assignee Name" }, "cancel_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Cancel Reason" }, "cancelled_by_account_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Cancelled By Account Id" }, "changed_objects": { "description": "The Tidy objects its sessions created or changed since the hand-off.", "items": { "$ref": "#/components/schemas/ActivityDelegationChangedObject" }, "title": "Changed Objects", "type": "array" }, "child_activity_id": { "title": "Child Activity Id", "type": "string" }, "child_short_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Child Short Id" }, "child_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Child Status" }, "child_title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Child Title" }, "completion_report": { "anyOf": [ { "$ref": "#/components/schemas/ActivityDelegationCompletionReport" }, { "type": "null" } ], "default": null, "description": "The child's current handoff note, once its assignee wrote one." }, "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "delegation_id": { "title": "Delegation Id", "type": "string" }, "delegator_account_id": { "title": "Delegator Account Id", "type": "string" }, "delegator_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Delegator Name" }, "depth": { "title": "Depth", "type": "integer" }, "holds_line": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "What holds the child's work open right now, in words; null when nothing does.", "title": "Holds Line" }, "parent_activity_id": { "title": "Parent Activity Id", "type": "string" }, "replayed": { "description": "True when this client_request_id had already handed this off.", "title": "Replayed", "type": "boolean" }, "settled_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Settled At" }, "state": { "enum": [ "open", "done", "cancelled" ], "title": "State", "type": "string" }, "work_summary": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "What its sessions did since the hand-off, as one counted sentence; null when nothing yet.", "title": "Work Summary" } }, "required": [ "delegation_id", "parent_activity_id", "child_activity_id", "delegator_account_id", "assignee_account_id", "depth", "state", "created_at", "replayed" ], "title": "ActivityDelegationCreateResponse", "type": "object" }, "ActivityDelegationResponse": { "properties": { "assignee_account_id": { "title": "Assignee Account Id", "type": "string" }, "assignee_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Assignee Name" }, "cancel_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Cancel Reason" }, "cancelled_by_account_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Cancelled By Account Id" }, "changed_objects": { "description": "The Tidy objects its sessions created or changed since the hand-off.", "items": { "$ref": "#/components/schemas/ActivityDelegationChangedObject" }, "title": "Changed Objects", "type": "array" }, "child_activity_id": { "title": "Child Activity Id", "type": "string" }, "child_short_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Child Short Id" }, "child_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Child Status" }, "child_title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Child Title" }, "completion_report": { "anyOf": [ { "$ref": "#/components/schemas/ActivityDelegationCompletionReport" }, { "type": "null" } ], "default": null, "description": "The child's current handoff note, once its assignee wrote one." }, "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "delegation_id": { "title": "Delegation Id", "type": "string" }, "delegator_account_id": { "title": "Delegator Account Id", "type": "string" }, "delegator_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Delegator Name" }, "depth": { "title": "Depth", "type": "integer" }, "holds_line": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "What holds the child's work open right now, in words; null when nothing does.", "title": "Holds Line" }, "parent_activity_id": { "title": "Parent Activity Id", "type": "string" }, "settled_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Settled At" }, "state": { "enum": [ "open", "done", "cancelled" ], "title": "State", "type": "string" }, "work_summary": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "What its sessions did since the hand-off, as one counted sentence; null when nothing yet.", "title": "Work Summary" } }, "required": [ "delegation_id", "parent_activity_id", "child_activity_id", "delegator_account_id", "assignee_account_id", "depth", "state", "created_at" ], "title": "ActivityDelegationResponse", "type": "object" }, "ActivityDelegationsResponse": { "properties": { "all_back": { "description": "Every hand-off is done or cancelled.", "title": "All Back", "type": "boolean" }, "delegations": { "items": { "$ref": "#/components/schemas/ActivityDelegationResponse" }, "title": "Delegations", "type": "array" }, "parent_activity_id": { "title": "Parent Activity Id", "type": "string" }, "wait_timed_out": { "description": "The wait ended on its clock with work still out. Nothing was cancelled.", "title": "Wait Timed Out", "type": "boolean" } }, "required": [ "parent_activity_id", "delegations", "all_back", "wait_timed_out" ], "title": "ActivityDelegationsResponse", "type": "object" }, "ActivityEditHistoryEntry": { "description": "Single activity field edit record.", "properties": { "activity_id": { "description": "Activity UUID", "title": "Activity Id", "type": "string" }, "change_set_id": { "description": "Edit batch UUID", "title": "Change Set Id", "type": "string" }, "changed_at": { "description": "ISO 8601 timestamp of the change", "format": "date-time", "title": "Changed At", "type": "string" }, "changed_by": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Account UUID that made the change", "title": "Changed By" }, "edit_source": { "description": "Source of the change", "title": "Edit Source", "type": "string" }, "field_name": { "description": "Changed field name", "title": "Field Name", "type": "string" }, "id": { "description": "Edit history UUID", "title": "Id", "type": "string" }, "new_value": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "New stored value", "title": "New Value" }, "old_value": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Previous stored value", "title": "Old Value" }, "source_context": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "description": "Captured source attribution for the change", "title": "Source Context" } }, "required": [ "id", "change_set_id", "activity_id", "field_name", "edit_source", "changed_at" ], "title": "ActivityEditHistoryEntry", "type": "object" }, "ActivityEditHistoryResponse": { "description": "Response payload for activity edit history queries.", "properties": { "entries": { "description": "Most recent edit history entries for the activity", "items": { "$ref": "#/components/schemas/ActivityEditHistoryEntry" }, "title": "Entries", "type": "array" } }, "title": "ActivityEditHistoryResponse", "type": "object" }, "ActivityFeedItem": { "properties": { "action_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Action Url" }, "actor": { "$ref": "#/components/schemas/ActivityActor" }, "id": { "format": "uuid", "title": "Id", "type": "string" }, "metadata": { "additionalProperties": true, "title": "Metadata", "type": "object" }, "occurred_at": { "format": "date-time", "title": "Occurred At", "type": "string" }, "read_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Read At" }, "room_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Room Name" }, "snippet": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Snippet" }, "source_event_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Source Event Id" }, "source_room_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Source Room Id" }, "title": { "title": "Title", "type": "string" }, "type": { "enum": [ "chat_mention", "chat_keyword", "chat_proactive", "chat_reminder" ], "title": "Type", "type": "string" } }, "required": [ "id", "type", "occurred_at", "title" ], "title": "ActivityFeedItem", "type": "object" }, "ActivityFeedResponse": { "properties": { "items": { "items": { "$ref": "#/components/schemas/ActivityFeedItem" }, "title": "Items", "type": "array" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Next Cursor" } }, "required": [ "items" ], "title": "ActivityFeedResponse", "type": "object" }, "ActivityId": { "description": "Typed primitive ID for activities (prefix 'A').", "examples": [ "A-550e8400-e29b-41d4-a716-446655440000" ], "pattern": "^A-[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "title": "ActivityId", "type": "string", "x-tidy-typed-id-prefix": "A", "x-tidy-typed-id-table": "activities" }, "ActivityInteractionRequest": { "description": "Payload for recording a user interaction with an activity.", "properties": { "event_type": { "enum": [ "open", "edit", "link" ], "title": "Event Type", "type": "string" } }, "required": [ "event_type" ], "title": "ActivityInteractionRequest", "type": "object" }, "ActivityInteractionResponse": { "description": "Response after recording an interaction.", "properties": { "last_interaction_at": { "format": "date-time", "title": "Last Interaction At", "type": "string" }, "status": { "default": "ok", "title": "Status", "type": "string" } }, "required": [ "last_interaction_at" ], "title": "ActivityInteractionResponse", "type": "object" }, "ActivityMarkAllReadResponse": { "properties": { "marked": { "title": "Marked", "type": "integer" } }, "required": [ "marked" ], "title": "ActivityMarkAllReadResponse", "type": "object" }, "ActivityReadRequest": { "properties": { "read": { "default": true, "title": "Read", "type": "boolean" } }, "title": "ActivityReadRequest", "type": "object" }, "ActivityReadResponse": { "properties": { "id": { "format": "uuid", "title": "Id", "type": "string" }, "read_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Read At" } }, "required": [ "id" ], "title": "ActivityReadResponse", "type": "object" }, "ActivityResponse": { "description": "Complete activity object returned by API endpoints.", "properties": { "agent_session_state": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "title": "Agent Session State" }, "applied_facet_versions": { "anyOf": [ { "additionalProperties": { "type": "integer" }, "type": "object" }, { "type": "null" } ], "default": null, "title": "Applied Facet Versions" }, "approval_status": { "default": "approved", "title": "Approval Status", "type": "string" }, "archived": { "default": false, "title": "Archived", "type": "boolean" }, "archived_ancestor": { "default": false, "title": "Archived Ancestor", "type": "boolean" }, "archived_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Archived At" }, "archived_by": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Archived By" }, "assigned_agent": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "title": "Assigned Agent" }, "assigned_by": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Assigned By" }, "assignee": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Assignee" }, "assignee_principal_key": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Assignee Principal Key" }, "assignee_principal_type": { "anyOf": [ { "enum": [ "account", "assistant" ], "type": "string" }, { "type": "null" } ], "default": null, "title": "Assignee Principal Type" }, "attachments": { "anyOf": [ { "items": { "$ref": "#/components/schemas/ActivityAttachmentResponse" }, "type": "array" }, { "type": "null" } ], "default": null, "title": "Attachments" }, "category": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Category" }, "comments": { "anyOf": [ { "items": { "$ref": "#/components/schemas/TaskCommentSummary" }, "type": "array" }, { "type": "null" } ], "default": null, "title": "Comments" }, "confidence_score": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "title": "Confidence Score" }, "container_seq": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Container Seq" }, "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "custom_properties": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "title": "Custom Properties" }, "deleted_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Deleted At" }, "due_date": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Due Date" }, "due_datetime": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Due Datetime" }, "end": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "End" }, "estimated_duration_minutes": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Estimated Duration Minutes" }, "facet_data": { "additionalProperties": true, "title": "Facet Data", "type": "object" }, "facets": { "items": { "type": "string" }, "title": "Facets", "type": "array" }, "historical_facet_values": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "title": "Historical Facet Values" }, "icon": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Icon" }, "id": { "title": "Id", "type": "string" }, "is_recurring": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "title": "Is Recurring" }, "normalized_title_hash": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Normalized Title Hash" }, "owner": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Owner" }, "parent_activity_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Parent Activity Id" }, "plain_text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Plain Text" }, "priority": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Priority" }, "project_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Project Id" }, "provenance": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "title": "Provenance" }, "recurrence_day_of_month": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Recurrence Day Of Month" }, "recurrence_days_of_week": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "default": null, "title": "Recurrence Days Of Week" }, "recurrence_end_date": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Recurrence End Date" }, "recurrence_interval": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Recurrence Interval" }, "recurrence_pattern": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Recurrence Pattern" }, "resolved_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Resolved At" }, "score": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "title": "Score" }, "score_override": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "title": "Score Override" }, "score_override_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Score Override At" }, "short_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Short Id" }, "snoozed_until": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Snoozed Until" }, "source_email_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Email this activity was extracted from, when the source is an email.", "title": "Source Email Id" }, "source_evidence": { "anyOf": [ { "items": { "$ref": "#/components/schemas/SourceEvidence" }, "type": "array" }, { "type": "null" } ], "default": null, "description": "Source records that produced this activity.", "title": "Source Evidence" }, "source_evidence_error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Set when the source-evidence sub-fetch failed.", "title": "Source Evidence Error" }, "source_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Source Id" }, "source_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Source Type" }, "start": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Start" }, "start_date": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Start Date" }, "status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Status" }, "stuck_work": { "anyOf": [ { "$ref": "#/components/schemas/StuckWorkNote" }, { "type": "null" } ], "default": null, "description": "Set when an employee's write left this item stuck: assigned to an employee whose Wakes for leaves its state out, so nothing will wake anyone for it." }, "tags": { "items": { "type": "string" }, "title": "Tags", "type": "array" }, "tenant_id": { "title": "Tenant Id", "type": "string" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Title" }, "title_plain": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Plain-text projection of the rich title (server-computed).", "title": "Title Plain" }, "tracked_time_seconds": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Tracked Time Seconds" }, "updated_at": { "format": "date-time", "title": "Updated At", "type": "string" }, "visibility": { "default": "private", "title": "Visibility", "type": "string" } }, "required": [ "id", "tenant_id", "created_at", "updated_at" ], "title": "ActivityResponse", "type": "object" }, "ActivityScoreRecalculateRequest": { "description": "Request payload for score recomputation.", "properties": { "activity_ids": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Activity Ids" }, "facet_slug": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Facet Slug" }, "force": { "default": false, "title": "Force", "type": "boolean" } }, "title": "ActivityScoreRecalculateRequest", "type": "object" }, "ActivityScoreRecalculateResponse": { "description": "Response payload for score recomputation.", "properties": { "processed": { "title": "Processed", "type": "integer" }, "skipped": { "title": "Skipped", "type": "integer" }, "updated": { "title": "Updated", "type": "integer" } }, "required": [ "processed", "updated", "skipped" ], "title": "ActivityScoreRecalculateResponse", "type": "object" }, "ActivityUnreadCountResponse": { "properties": { "count": { "title": "Count", "type": "integer" } }, "required": [ "count" ], "title": "ActivityUnreadCountResponse", "type": "object" }, "ActivityUpdate": { "description": "Input model for PATCH /api/v1/activities/{id}. All fields optional.", "properties": { "assigned_agent": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Assigned Agent" }, "assigned_by": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Assigned By" }, "assignee": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Assignee" }, "assignee_principal_key": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Account UUID or assistant; explicit null clears the assignment.", "title": "Assignee Principal Key" }, "backlog_rank": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "The item's place in its assignee's manual work order (lower is earlier; null clears it).", "title": "Backlog Rank" }, "base_values": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "Internal-only autosave base values for field conflict detection", "title": "Base Values" }, "category": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Category" }, "confirm_unready": { "anyOf": [ { "maxLength": 500, "type": "string" }, { "type": "null" } ], "description": "An employee starting work that waits on something not done: why it starts anyway (a person asked, or what it waits for already exists). Accepted only after the refusal that names the prerequisites; audited.", "title": "Confirm Unready" }, "container_seq": { "anyOf": [ { "minimum": 0.0, "type": "integer" }, { "type": "null" } ], "title": "Container Seq" }, "custom_properties": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Custom Properties" }, "due_date": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Due Date" }, "due_datetime": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Due Datetime" }, "end": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "End" }, "estimated_duration_minutes": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Estimated Duration Minutes" }, "facet_data": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Facet Data" }, "facets": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Facets" }, "icon": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Icon" }, "is_recurring": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is Recurring" }, "owner": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Owner" }, "parent_activity_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Parent Activity Id" }, "pin": { "anyOf": [ { "enum": [ "next", "last", "none" ], "type": "string" }, { "type": "null" } ], "description": "Reorder this item in its assignee's backlog: 'next' works it first, 'last' sinks it, 'none' clears the pin.", "title": "Pin" }, "plain_text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Plain Text" }, "priority": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Priority" }, "project_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Project Id" }, "recurrence_day_of_month": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Recurrence Day Of Month" }, "recurrence_days_of_week": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Recurrence Days Of Week" }, "recurrence_end_date": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Recurrence End Date" }, "recurrence_interval": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Recurrence Interval" }, "recurrence_pattern": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Recurrence Pattern" }, "score": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Score" }, "score_override": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Manual score override. Set a number to pin the score against recalculation; send null to delete the override and revert to the computed score.", "title": "Score Override" }, "snoozed_until": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Snoozed Until" }, "source_context": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "Internal-only audit/source attribution metadata", "title": "Source Context" }, "start": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Start" }, "start_date": { "anyOf": [ { "format": "date", "type": "string" }, { "type": "null" } ], "title": "Start Date" }, "status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Status" }, "tags": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Tags" }, "title": { "anyOf": [ { "maxLength": 500, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Title" }, "tracked_time_seconds": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Tracked Time Seconds" }, "type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Type" }, "visibility": { "anyOf": [ { "enum": [ "private", "shared", "tenant" ], "type": "string" }, { "type": "null" } ], "title": "Visibility" } }, "title": "ActivityUpdate", "type": "object" }, "AddAttendeeRequest": { "description": "Request body for creating an event attendee.", "properties": { "agent_account_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "TIDY-16410: invite a virtual employee by agent account. This is THE VE marker; identity is never inferred from the address.", "title": "Agent Account Id" }, "attendee_email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Attendee email address. Optional only when `agent_account_id` names a virtual employee, whose address comes from the registry.", "title": "Attendee Email" }, "attendee_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Attendee display name", "title": "Attendee Name" }, "role": { "default": "REQ-PARTICIPANT", "description": "iCalendar role: CHAIR, REQ-PARTICIPANT, OPT-PARTICIPANT, NON-PARTICIPANT. CHAIR designates the meeting owner — for a virtual employee that is who opens the meeting (TIDY-16410).", "title": "Role", "type": "string" } }, "title": "AddAttendeeRequest", "type": "object" }, "AddElementOp": { "additionalProperties": false, "description": "Insert ONE new element on top of the scene.\n\nThe engine validates it against the shape the editor's renderer needs and\nfills the canonical defaults for everything the caller did not name, so an\nagent does not have to know Excalidraw's full element schema to add a box.", "properties": { "element": { "additionalProperties": true, "minProperties": 1, "title": "Element", "type": "object" }, "op": { "const": "add_element", "title": "Op", "type": "string" } }, "required": [ "op", "element" ], "title": "AddElementOp", "type": "object" }, "AddHarnessAccountRequest": { "additionalProperties": false, "properties": { "job_id": { "format": "uuid", "title": "Job Id", "type": "string" }, "recipient_key": { "maxLength": 128, "minLength": 1, "title": "Recipient Key", "type": "string" }, "requesting_device": { "maxLength": 255, "minLength": 1, "title": "Requesting Device", "type": "string" }, "sealed_secret": { "anyOf": [ { "$ref": "#/components/schemas/SealedEnvelope" }, { "type": "null" } ] } }, "required": [ "job_id", "requesting_device", "recipient_key" ], "title": "AddHarnessAccountRequest", "type": "object" }, "AddItemRequest": { "description": "Add one source. The four source kinds are mutually exclusive shapes.\n\n``primitive`` / ``container`` carry ``typed_id`` (``N-``); a bare UUID\nis accepted during the typed-id deprecation window only when\n``primitive_type`` names the table, because a bare UUID alone is ambiguous\nacross 22 primitive tables.", "properties": { "client_item_id": { "anyOf": [ { "maxLength": 200, "type": "string" }, { "type": "null" } ], "description": "The client's own stable id for ONE capture, scoped to this bundle. Replaying it returns the existing item with duplicate=true, so an offline retry cannot add the same dictation twice. A replay whose content differs is a 409, not a pretend-duplicate.", "title": "Client Item Id" }, "context_role": { "default": "source", "description": "What this item contributes (TIDY-17832). 'source' is citeable evidence and the default — an older client that omits the field adds a source, exactly as it always has. 'instruction' is the user's own steering: it never enters the numbered source blocks and merges into this run's instruction layer instead. Only a capture or a file recording may be an instruction.", "enum": [ "source", "instruction" ], "title": "Context Role", "type": "string" }, "gesture": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Which affordance the user reached for — one of the shared gesture vocabulary (overflow, context_menu, long_press, bulk, drag). We ship four affordances and cannot otherwise tell which ones earn their keep.", "title": "Gesture" }, "instruction_reviewed": { "default": false, "description": "The member has read this instruction text back and confirms it is what they said. Only reviewed instructions steer a generation.", "title": "Instruction Reviewed", "type": "boolean" }, "primitive_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Primitive Type" }, "scope_note": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Scope Note" }, "source_kind": { "enum": [ "primitive", "container", "external", "capture" ], "title": "Source Kind", "type": "string" }, "source_surface": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Where the add came from (e.g. 'web:email-list', 'android:share-sheet').", "title": "Source Surface" }, "text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Text" }, "typed_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Typed Id" }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Url" } }, "required": [ "source_kind" ], "title": "AddItemRequest", "type": "object" }, "AddItemResponse": { "properties": { "bundle_id": { "title": "Bundle Id", "type": "string" }, "child_count": { "default": 0, "description": "For a container chip: how many direct children it resolved to, excluding deselected ones. Zero for every other item.", "title": "Child Count", "type": "integer" }, "client_item_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Client Item Id" }, "context_role": { "default": "source", "description": "'source' (citeable evidence) or 'instruction' (the user's own steering, which never enters the numbered source blocks).", "title": "Context Role", "type": "string" }, "created_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Created At" }, "duplicate": { "default": false, "description": "True when this primitive was already in the bundle and the add was a no-op — the client shows an 'already in bundle' toast, not an error.", "title": "Duplicate", "type": "boolean" }, "excluded": { "default": false, "title": "Excluded", "type": "boolean" }, "external_final_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Where the fetch actually landed, when a redirect took it somewhere other than the submitted URL. Null when it did not.", "title": "External Final Url" }, "external_kind": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "External Kind" }, "external_metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "description": "Provider-reported facts about an external source, shaped per external_kind. A YouTube source (external_kind 'youtube') carries video_id, channel, duration_seconds, published_at and transcript_source.", "title": "External Metadata" }, "external_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "External Url" }, "failure_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Failure Code" }, "id": { "title": "Id", "type": "string" }, "inline_text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Inline Text" }, "instruction_reviewed_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "When a member confirmed instruction_text. Null means a machine wrote it and nobody has read it back — which blocks generation.", "title": "Instruction Reviewed At" }, "instruction_text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "The member-owned, editable instruction text this run consumes.", "title": "Instruction Text" }, "parent_item_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Parent Item Id" }, "position": { "title": "Position", "type": "integer" }, "primitive_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Primitive Id" }, "primitive_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Primitive Type" }, "scope_note": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Scope Note" }, "source_kind": { "title": "Source Kind", "type": "string" }, "state": { "title": "State", "type": "string" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Title" }, "token_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Token Count" }, "typed_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Public typed id of the source primitive, when it has one.", "title": "Typed Id" }, "updated_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Updated At" } }, "required": [ "id", "bundle_id", "position", "source_kind", "state" ], "title": "AddItemResponse", "type": "object" }, "AddToFocusQueueRequest": { "properties": { "email_ids": { "items": { "type": "string" }, "maxItems": 100, "minItems": 1, "title": "Email Ids", "type": "array" } }, "required": [ "email_ids" ], "title": "AddToFocusQueueRequest", "type": "object" }, "AddToFocusQueueResponse": { "properties": { "answered": { "default": 0, "title": "Answered", "type": "integer" }, "draft_generation_started": { "default": false, "title": "Draft Generation Started", "type": "boolean" }, "queued": { "title": "Queued", "type": "integer" }, "queued_email_ids": { "items": { "format": "uuid", "type": "string" }, "title": "Queued Email Ids", "type": "array" } }, "required": [ "queued" ], "title": "AddToFocusQueueResponse", "type": "object" }, "AddonInboxesRequest": { "properties": { "quantity": { "minimum": 0.0, "title": "Quantity", "type": "integer" } }, "required": [ "quantity" ], "title": "AddonInboxesRequest", "type": "object" }, "AddressBookCreateRequest": { "properties": { "display_name": { "maxLength": 160, "minLength": 1, "title": "Display Name", "type": "string" }, "owner_type": { "default": "user", "enum": [ "user", "account" ], "title": "Owner Type", "type": "string" }, "slug": { "anyOf": [ { "maxLength": 96, "minLength": 1, "pattern": "^[a-z0-9][a-z0-9-]{0,95}$", "type": "string" }, { "type": "null" } ], "title": "Slug" }, "visibility": { "default": "private", "enum": [ "private", "shared", "global" ], "title": "Visibility", "type": "string" } }, "required": [ "display_name" ], "title": "AddressBookCreateRequest", "type": "object" }, "AddressBookMemberRequest": { "properties": { "primitive_id": { "format": "uuid", "title": "Primitive Id", "type": "string" }, "primitive_type": { "enum": [ "contact", "organization" ], "title": "Primitive Type", "type": "string" } }, "required": [ "primitive_type", "primitive_id" ], "title": "AddressBookMemberRequest", "type": "object" }, "AddressBookMemberResponse": { "properties": { "address_book_id": { "format": "uuid", "title": "Address Book Id", "type": "string" }, "changed": { "title": "Changed", "type": "boolean" }, "primitive_id": { "format": "uuid", "title": "Primitive Id", "type": "string" }, "primitive_type": { "enum": [ "contact", "organization" ], "title": "Primitive Type", "type": "string" } }, "required": [ "address_book_id", "primitive_type", "primitive_id", "changed" ], "title": "AddressBookMemberResponse", "type": "object" }, "AddressBookResponse": { "properties": { "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "display_name": { "title": "Display Name", "type": "string" }, "id": { "format": "uuid", "title": "Id", "type": "string" }, "member_count": { "default": 0, "title": "Member Count", "type": "integer" }, "owner_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Owner Id" }, "owner_type": { "enum": [ "user", "account" ], "title": "Owner Type", "type": "string" }, "slug": { "title": "Slug", "type": "string" }, "tenant_id": { "format": "uuid", "title": "Tenant Id", "type": "string" }, "updated_at": { "format": "date-time", "title": "Updated At", "type": "string" }, "visibility": { "enum": [ "private", "shared", "global" ], "title": "Visibility", "type": "string" } }, "required": [ "id", "tenant_id", "slug", "display_name", "visibility", "owner_id", "owner_type", "created_at", "updated_at" ], "title": "AddressBookResponse", "type": "object" }, "AddressBookShareAllResponse": { "properties": { "address_book_id": { "format": "uuid", "title": "Address Book Id", "type": "string" }, "contacts_updated": { "title": "Contacts Updated", "type": "integer" }, "organizations_updated": { "title": "Organizations Updated", "type": "integer" } }, "required": [ "address_book_id", "contacts_updated", "organizations_updated" ], "title": "AddressBookShareAllResponse", "type": "object" }, "AddressBookUpdateRequest": { "properties": { "display_name": { "anyOf": [ { "maxLength": 160, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Display Name" }, "visibility": { "anyOf": [ { "enum": [ "private", "shared", "global" ], "type": "string" }, { "type": "null" } ], "title": "Visibility" } }, "title": "AddressBookUpdateRequest", "type": "object" }, "AddressData": { "description": "Deprecated postal-address contract; retained until lagging clients update.", "properties": { "city": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "City name", "title": "City" }, "country": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": "USA", "description": "Country name or ISO code", "title": "Country" }, "line1": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Address line 1 (street, apartment)", "title": "Line1" }, "line2": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Address line 2 (suite, unit)", "title": "Line2" }, "postal_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ZIP or postal code", "title": "Postal Code" }, "state": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "State/province code or name", "title": "State" } }, "title": "AddressData", "type": "object" }, "AdminChannelResponse": { "properties": { "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "has_retention_override": { "default": false, "title": "Has Retention Override", "type": "boolean" }, "is_shared_channel": { "default": false, "title": "Is Shared Channel", "type": "boolean" }, "member_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Member Count" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Name" }, "room_id": { "title": "Room Id", "type": "string" }, "room_type": { "title": "Room Type", "type": "string" }, "visibility": { "title": "Visibility", "type": "string" } }, "required": [ "room_id", "room_type", "visibility", "created_at" ], "title": "AdminChannelResponse", "type": "object" }, "AdminChatCapabilityMatrixResponse": { "properties": { "entries": { "items": { "$ref": "#/components/schemas/CapabilityMatrixEntry" }, "title": "Entries", "type": "array" } }, "required": [ "entries" ], "title": "AdminChatCapabilityMatrixResponse", "type": "object" }, "AdminChatIndexResponse": { "properties": { "active_retention_policies_count": { "default": 0, "title": "Active Retention Policies Count", "type": "integer" }, "e2ee_dms_count": { "default": 0, "title": "E2Ee Dms Count", "type": "integer" }, "known_capabilities": { "items": { "type": "string" }, "title": "Known Capabilities", "type": "array" }, "last_audit_actor_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Last Audit Actor Id" }, "last_audit_entry_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Last Audit Entry At" }, "legal_holds_count": { "default": 0, "title": "Legal Holds Count", "type": "integer" }, "pending_export_jobs_count": { "default": 0, "title": "Pending Export Jobs Count", "type": "integer" } }, "required": [ "known_capabilities" ], "title": "AdminChatIndexResponse", "type": "object" }, "AdminChatSettingsResponse": { "properties": { "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "custom_emoji_enabled": { "title": "Custom Emoji Enabled", "type": "boolean" }, "edit_window_minutes": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Edit Window Minutes" }, "huddle_media_plane": { "default": "auto", "enum": [ "auto", "meet_first", "livekit_only" ], "title": "Huddle Media Plane", "type": "string" }, "pin_permission": { "enum": [ "anyone", "members", "admins" ], "title": "Pin Permission", "type": "string" }, "schedule_max_days": { "title": "Schedule Max Days", "type": "integer" }, "tenant_id": { "title": "Tenant Id", "type": "string" }, "updated_at": { "format": "date-time", "title": "Updated At", "type": "string" } }, "required": [ "tenant_id", "pin_permission", "schedule_max_days", "custom_emoji_enabled", "created_at", "updated_at" ], "title": "AdminChatSettingsResponse", "type": "object" }, "AdminChatUserResponse": { "properties": { "account_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Account Id" }, "deactivated_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Deactivated At" }, "display_name": { "title": "Display Name", "type": "string" }, "kind": { "title": "Kind", "type": "string" }, "matrix_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Matrix Id" }, "provisioned_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Provisioned At" }, "status": { "title": "Status", "type": "string" } }, "required": [ "kind", "display_name", "status" ], "title": "AdminChatUserResponse", "type": "object" }, "AdminCustomEmojiListResponse": { "properties": { "custom_emoji_enabled": { "title": "Custom Emoji Enabled", "type": "boolean" }, "items": { "items": { "$ref": "#/components/schemas/CustomEmojiResponse" }, "title": "Items", "type": "array" } }, "required": [ "items", "custom_emoji_enabled" ], "title": "AdminCustomEmojiListResponse", "type": "object" }, "AdminFeatureSwitchEntry": { "description": "One switch: the descriptor, its global default, and its counts.", "properties": { "added_at": { "title": "Added At", "type": "string" }, "beta_tenants": { "items": { "type": "string" }, "title": "Beta Tenants", "type": "array" }, "debt": { "title": "Debt", "type": "boolean" }, "description": { "title": "Description", "type": "string" }, "enablement": { "$ref": "#/components/schemas/SwitchEnablement" }, "global_default": { "enum": [ "on", "off", "unset" ], "title": "Global Default", "type": "string" }, "is_ops": { "title": "Is Ops", "type": "boolean" }, "key": { "title": "Key", "type": "string" }, "label": { "title": "Label", "type": "string" }, "lifecycle": { "enum": [ "beta", "ga" ], "title": "Lifecycle", "type": "string" }, "owner": { "title": "Owner", "type": "string" }, "pending_work_ref": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Pending Work Ref" }, "pending_work_summary": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Pending Work Summary" }, "pending_work_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Pending Work Url" }, "removal_due_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Removal Due At" }, "requires": { "items": { "type": "string" }, "title": "Requires", "type": "array" } }, "required": [ "key", "label", "description", "lifecycle", "owner", "added_at", "is_ops", "debt", "global_default", "enablement" ], "title": "AdminFeatureSwitchEntry", "type": "object" }, "AdminHuddleResponse": { "properties": { "ended_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Ended At" }, "id": { "title": "Id", "type": "string" }, "is_active": { "default": false, "title": "Is Active", "type": "boolean" }, "participant_count": { "default": 0, "title": "Participant Count", "type": "integer" }, "room_id": { "title": "Room Id", "type": "string" }, "room_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Room Name" }, "started_at": { "format": "date-time", "title": "Started At", "type": "string" }, "started_by": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Started By" } }, "required": [ "id", "room_id", "started_at" ], "title": "AdminHuddleResponse", "type": "object" }, "AdminPollResponse": { "properties": { "closed_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Closed At" }, "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "creator": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Creator" }, "id": { "title": "Id", "type": "string" }, "is_open": { "default": true, "title": "Is Open", "type": "boolean" }, "question": { "title": "Question", "type": "string" }, "room_id": { "title": "Room Id", "type": "string" }, "room_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Room Name" }, "vote_count": { "default": 0, "title": "Vote Count", "type": "integer" } }, "required": [ "id", "room_id", "question", "created_at" ], "title": "AdminPollResponse", "type": "object" }, "AdminSpendCapUpdate": { "properties": { "monthly_cap_usd": { "anyOf": [ { "exclusiveMinimum": 0.0, "type": "number" }, { "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$", "type": "string" } ], "title": "Monthly Cap Usd" } }, "required": [ "monthly_cap_usd" ], "title": "AdminSpendCapUpdate", "type": "object" }, "AdminSpendSummaryResponse": { "properties": { "by_feature": { "items": { "$ref": "#/components/schemas/FeatureSpend" }, "title": "By Feature", "type": "array" }, "by_model": { "items": { "$ref": "#/components/schemas/ModelSpend" }, "title": "By Model", "type": "array" }, "month_start": { "format": "date", "title": "Month Start", "type": "string" }, "mtd_total_usd": { "title": "Mtd Total Usd", "type": "number" }, "rollup_lag_days": { "default": 0, "title": "Rollup Lag Days", "type": "integer" }, "rollup_through_day": { "anyOf": [ { "format": "date", "type": "string" }, { "type": "null" } ], "default": null, "title": "Rollup Through Day" }, "top_tenants": { "items": { "$ref": "#/components/schemas/TenantSpend" }, "title": "Top Tenants", "type": "array" }, "unattributed_cost_usd": { "title": "Unattributed Cost Usd", "type": "number" }, "window": { "title": "Window", "type": "string" } }, "required": [ "window", "month_start", "mtd_total_usd", "by_model", "by_feature", "top_tenants", "unattributed_cost_usd" ], "title": "AdminSpendSummaryResponse", "type": "object" }, "AdminStatsResponse": { "description": "Admin dashboard statistics.", "properties": { "active_users": { "title": "Active Users", "type": "integer" }, "avg_pipeline_duration_minutes": { "default": 0.0, "title": "Avg Pipeline Duration Minutes", "type": "number" }, "calendar_sources": { "default": 0, "title": "Calendar Sources", "type": "integer" }, "contacts_low_confidence": { "default": 0, "title": "Contacts Low Confidence", "type": "integer" }, "email_sources": { "title": "Email Sources", "type": "integer" }, "events_approved": { "default": 0, "title": "Events Approved", "type": "integer" }, "events_pending_review": { "default": 0, "title": "Events Pending Review", "type": "integer" }, "events_rejected": { "default": 0, "title": "Events Rejected", "type": "integer" }, "failed_pipelines_today": { "default": 0, "title": "Failed Pipelines Today", "type": "integer" }, "litellm_total_calls_30d": { "default": 0, "title": "Litellm Total Calls 30D", "type": "integer" }, "litellm_total_spend_30d": { "default": 0.0, "title": "Litellm Total Spend 30D", "type": "number" }, "litellm_total_tokens_30d": { "default": 0, "title": "Litellm Total Tokens 30D", "type": "integer" }, "new_users_7d": { "default": 0, "title": "New Users 7D", "type": "integer" }, "news_summaries_by_type": { "additionalProperties": { "type": "integer" }, "default": {}, "title": "News Summaries By Type", "type": "object" }, "notes_approved": { "default": 0, "title": "Notes Approved", "type": "integer" }, "notes_pending_review": { "default": 0, "title": "Notes Pending Review", "type": "integer" }, "notes_rejected": { "default": 0, "title": "Notes Rejected", "type": "integer" }, "organizations_approved": { "default": 0, "title": "Organizations Approved", "type": "integer" }, "organizations_pending_review": { "default": 0, "title": "Organizations Pending Review", "type": "integer" }, "organizations_rejected": { "default": 0, "title": "Organizations Rejected", "type": "integer" }, "pending_onboarding": { "title": "Pending Onboarding", "type": "integer" }, "pipeline_runs_today": { "default": 0, "title": "Pipeline Runs Today", "type": "integer" }, "pipeline_success_rate": { "default": 0.0, "title": "Pipeline Success Rate", "type": "number" }, "pipelines_last_hour": { "default": 0, "title": "Pipelines Last Hour", "type": "integer" }, "tasks_approved": { "default": 0, "title": "Tasks Approved", "type": "integer" }, "tasks_pending_review": { "default": 0, "title": "Tasks Pending Review", "type": "integer" }, "tasks_rejected": { "default": 0, "title": "Tasks Rejected", "type": "integer" }, "total_api_calls_30d": { "default": 0, "title": "Total Api Calls 30D", "type": "integer" }, "total_contacts": { "default": 0, "title": "Total Contacts", "type": "integer" }, "total_cost_cents_30d": { "default": 0, "title": "Total Cost Cents 30D", "type": "integer" }, "total_emails_processed": { "default": 0, "title": "Total Emails Processed", "type": "integer" }, "total_events": { "default": 0, "title": "Total Events", "type": "integer" }, "total_news_summaries": { "default": 0, "title": "Total News Summaries", "type": "integer" }, "total_news_updates": { "default": 0, "title": "Total News Updates", "type": "integer" }, "total_notes": { "default": 0, "title": "Total Notes", "type": "integer" }, "total_organizations": { "default": 0, "title": "Total Organizations", "type": "integer" }, "total_reminders": { "default": 0, "title": "Total Reminders", "type": "integer" }, "total_tasks": { "default": 0, "title": "Total Tasks", "type": "integer" }, "total_tenants": { "title": "Total Tenants", "type": "integer" }, "total_tokens_30d": { "default": 0, "title": "Total Tokens 30D", "type": "integer" }, "unread_notifications": { "default": 0, "title": "Unread Notifications", "type": "integer" } }, "required": [ "total_tenants", "active_users", "pending_onboarding", "email_sources" ], "title": "AdminStatsResponse", "type": "object" }, "AdminStripeCoupon": { "properties": { "amount_off_cents": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Amount Off Cents" }, "currency": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Currency" }, "duration": { "title": "Duration", "type": "string" }, "duration_in_months": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Duration In Months" }, "id": { "title": "Id", "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Name" }, "percent_off": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "title": "Percent Off" }, "tidy_managed": { "default": false, "title": "Tidy Managed", "type": "boolean" }, "valid": { "default": true, "title": "Valid", "type": "boolean" } }, "required": [ "id", "duration" ], "title": "AdminStripeCoupon", "type": "object" }, "AdminSubscriptionDiscount": { "properties": { "coupon": { "$ref": "#/components/schemas/AdminStripeCoupon" }, "end": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "End" }, "id": { "title": "Id", "type": "string" }, "promotion_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Promotion Code" }, "start": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Start" } }, "required": [ "id", "coupon" ], "title": "AdminSubscriptionDiscount", "type": "object" }, "AdminUsageAccount": { "description": "One row of ``get_admin_usage_summary(30)``.", "properties": { "account_id": { "format": "uuid", "title": "Account Id", "type": "string" }, "by_feature": { "additionalProperties": true, "default": {}, "title": "By Feature", "type": "object" }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Email" }, "first_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "First Name" }, "last_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Last Name" }, "tenant_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "default": null, "title": "Tenant Id" }, "total_calls": { "default": 0, "title": "Total Calls", "type": "integer" }, "total_cost_cents": { "default": 0, "title": "Total Cost Cents", "type": "integer" }, "total_tokens": { "default": 0, "title": "Total Tokens", "type": "integer" } }, "required": [ "account_id" ], "title": "AdminUsageAccount", "type": "object" }, "AdminUsageByKindResponse": { "properties": { "by_kind": { "default": [], "items": { "$ref": "#/components/schemas/KindBreakdown" }, "title": "By Kind", "type": "array" }, "by_tenant": { "default": [], "items": { "$ref": "#/components/schemas/TenantKindBreakdown" }, "title": "By Tenant", "type": "array" }, "totals": { "additionalProperties": { "type": "number" }, "default": {}, "title": "Totals", "type": "object" } }, "title": "AdminUsageByKindResponse", "type": "object" }, "AdminUsageSummaryResponse": { "description": "The full admin/usage page data bundle.", "properties": { "accounts": { "items": { "$ref": "#/components/schemas/AdminUsageAccount" }, "title": "Accounts", "type": "array" }, "aiDraftCount": { "title": "Aidraftcount", "type": "integer" }, "aiDraftCount30d": { "title": "Aidraftcount30D", "type": "integer" }, "combinedCostCents30d": { "default": 0, "title": "Combinedcostcents30D", "type": "integer" }, "combinedCostCentsByKind30d": { "additionalProperties": { "type": "integer" }, "default": {}, "title": "Combinedcostcentsbykind30D", "type": "object" }, "feedbackSummary": { "items": { "$ref": "#/components/schemas/FeedbackSummaryRow" }, "title": "Feedbacksummary", "type": "array" }, "testimonialCandidates": { "items": { "$ref": "#/components/schemas/TestimonialCandidate" }, "title": "Testimonialcandidates", "type": "array" }, "totalCostCents": { "title": "Totalcostcents", "type": "integer" }, "totalTokens": { "title": "Totaltokens", "type": "integer" } }, "required": [ "accounts", "totalTokens", "totalCostCents", "feedbackSummary", "testimonialCandidates", "aiDraftCount", "aiDraftCount30d" ], "title": "AdminUsageSummaryResponse", "type": "object" }, "AdminUserSummary": { "properties": { "billing_tier_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "default": null, "title": "Billing Tier Id" }, "created_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Created At" }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Email" }, "id": { "format": "uuid", "title": "Id", "type": "string" }, "is_admin": { "default": false, "title": "Is Admin", "type": "boolean" }, "suspended_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Suspended At" } }, "required": [ "id" ], "title": "AdminUserSummary", "type": "object" }, "AdoptUnitRequest": { "properties": { "project_id": { "format": "uuid", "title": "Project Id", "type": "string" }, "superseded_dispositions": { "additionalProperties": { "type": "string" }, "title": "Superseded Dispositions", "type": "object" }, "unit_key": { "minLength": 1, "title": "Unit Key", "type": "string" } }, "required": [ "unit_key", "project_id" ], "title": "AdoptUnitRequest", "type": "object" }, "AdoptUnitResponse": { "properties": { "adopted_pack_version": { "title": "Adopted Pack Version", "type": "integer" }, "created": { "items": { "additionalProperties": true, "type": "object" }, "title": "Created", "type": "array" }, "install_id": { "format": "uuid", "title": "Install Id", "type": "string" }, "project_id": { "format": "uuid", "title": "Project Id", "type": "string" }, "skipped": { "items": { "additionalProperties": true, "type": "object" }, "title": "Skipped", "type": "array" }, "superseded_archived": { "items": { "type": "string" }, "title": "Superseded Archived", "type": "array" }, "superseded_kept": { "items": { "type": "string" }, "title": "Superseded Kept", "type": "array" }, "unit_key": { "title": "Unit Key", "type": "string" } }, "required": [ "install_id", "unit_key", "project_id", "adopted_pack_version" ], "title": "AdoptUnitResponse", "type": "object" }, "AdoptableUnitResponse": { "properties": { "adopted": { "default": false, "title": "Adopted", "type": "boolean" }, "adopted_pack_version": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Adopted Pack Version" }, "auto_on_new_project": { "default": false, "title": "Auto On New Project", "type": "boolean" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "key": { "title": "Key", "type": "string" }, "label": { "title": "Label", "type": "string" }, "per_project": { "default": false, "title": "Per Project", "type": "boolean" }, "preview": { "items": { "$ref": "#/components/schemas/UnitPreviewItem" }, "title": "Preview", "type": "array" }, "superseded": { "items": { "$ref": "#/components/schemas/UnitSupersededItem" }, "title": "Superseded", "type": "array" }, "update_available": { "default": false, "title": "Update Available", "type": "boolean" } }, "required": [ "key", "label" ], "title": "AdoptableUnitResponse", "type": "object" }, "AdoptableUnitsResponse": { "properties": { "install_id": { "format": "uuid", "title": "Install Id", "type": "string" }, "project_id": { "format": "uuid", "title": "Project Id", "type": "string" }, "recipes": { "items": { "$ref": "#/components/schemas/MigrationRecipeResponse" }, "title": "Recipes", "type": "array" }, "template_slug": { "title": "Template Slug", "type": "string" }, "template_version": { "title": "Template Version", "type": "integer" }, "units": { "items": { "$ref": "#/components/schemas/AdoptableUnitResponse" }, "title": "Units", "type": "array" } }, "required": [ "install_id", "template_slug", "template_version", "project_id" ], "title": "AdoptableUnitsResponse", "type": "object" }, "AdoptionResponse": { "properties": { "rows": { "items": { "$ref": "#/components/schemas/AdoptionRow" }, "title": "Rows", "type": "array" }, "window_days": { "title": "Window Days", "type": "integer" } }, "required": [ "window_days", "rows" ], "title": "AdoptionResponse", "type": "object" }, "AdoptionRow": { "description": "One event's adoption over the requested window.", "properties": { "active_tenants": { "title": "Active Tenants", "type": "integer" }, "adoption_pct": { "title": "Adoption Pct", "type": "number" }, "eligible_tenants": { "title": "Eligible Tenants", "type": "integer" }, "event_name": { "title": "Event Name", "type": "string" }, "trend": { "items": { "type": "integer" }, "title": "Trend", "type": "array" } }, "required": [ "event_name", "eligible_tenants", "active_tenants", "adoption_pct", "trend" ], "title": "AdoptionRow", "type": "object" }, "AdvanceRequest": { "description": "Request for /onboarding/advance — caller echoes the step they believe current.", "properties": { "from_step": { "description": "Step the caller believes is current", "title": "From Step", "type": "string" }, "workforce_path": { "anyOf": [ { "enum": [ "hosted", "workshop" ], "type": "string" }, { "type": "null" } ], "title": "Workforce Path" } }, "required": [ "from_step" ], "title": "AdvanceRequest", "type": "object" }, "AdvanceResponse": { "description": "Result of /onboarding/advance: next_step (None if terminal) + FE URL.", "properties": { "account_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Effective account_type used to compute next_step", "title": "Account Type" }, "from_step": { "description": "Step the caller advanced from", "title": "From Step", "type": "string" }, "next_step": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Next step or None if terminal", "title": "Next Step" }, "next_url": { "description": "URL FE should navigate to", "title": "Next Url", "type": "string" }, "onboarding_mode": { "default": "tenant", "description": "Progress owner advanced by this request.", "title": "Onboarding Mode", "type": "string" } }, "required": [ "from_step", "next_url" ], "title": "AdvanceResponse", "type": "object" }, "AdvancedAudioSessionRenewRequest": { "properties": { "credential": { "description": "The credential currently held by the client", "maxLength": 4096, "title": "Credential", "type": "string" }, "operation_id": { "maxLength": 128, "minLength": 8, "title": "Operation Id", "type": "string" } }, "required": [ "credential", "operation_id" ], "title": "AdvancedAudioSessionRenewRequest", "type": "object" }, "AdvancedAudioSessionRequest": { "properties": { "capability_version": { "description": "Capability contract version the client implements", "maxLength": 64, "title": "Capability Version", "type": "string" }, "operation_id": { "description": "Client-generated idempotency key; one mint per id per tenant", "maxLength": 128, "minLength": 8, "title": "Operation Id", "type": "string" } }, "required": [ "capability_version", "operation_id" ], "title": "AdvancedAudioSessionRequest", "type": "object" }, "AdvancedAudioSessionResponse": { "properties": { "capability_version": { "title": "Capability Version", "type": "string" }, "credential": { "title": "Credential", "type": "string" }, "expires_at": { "format": "date-time", "title": "Expires At", "type": "string" }, "provider": { "title": "Provider", "type": "string" } }, "required": [ "credential", "expires_at", "provider", "capability_version" ], "title": "AdvancedAudioSessionResponse", "type": "object" }, "AffectedRecords": { "description": "Counts of records updated during merge.\n\nTracks how many rows in each related table were updated\nto point to the primary contact.", "properties": { "calendar_attendees": { "default": 0, "description": "Calendar attendees updated", "title": "Calendar Attendees", "type": "integer" }, "contact_aliases": { "default": 0, "description": "Contact aliases transferred", "title": "Contact Aliases", "type": "integer" }, "contact_dismissal_memory": { "default": 0, "description": "Contact dismissal memory rows repointed", "title": "Contact Dismissal Memory", "type": "integer" }, "contact_edit_history": { "default": 0, "description": "Contact edit history rows transferred", "title": "Contact Edit History", "type": "integer" }, "contact_enrichment_queue": { "default": 0, "description": "Contact enrichment queue rows transferred", "title": "Contact Enrichment Queue", "type": "integer" }, "contact_face_profiles": { "default": 0, "description": "Contact face profiles repointed or folded (TIDY-15265)", "title": "Contact Face Profiles", "type": "integer" }, "contact_group_members": { "default": 0, "description": "Contact group memberships transferred", "title": "Contact Group Members", "type": "integer" }, "contact_interactions": { "default": 0, "description": "Contact interaction rows transferred", "title": "Contact Interactions", "type": "integer" }, "contact_merge_notes": { "default": 0, "description": "Deprecated (TIDY-12173): always 0 — merge no longer creates notes", "title": "Contact Merge Notes", "type": "integer" }, "contact_organizations": { "default": 0, "description": "Contact organization links transferred", "title": "Contact Organizations", "type": "integer" }, "contact_photos": { "default": 0, "description": "Contact photos transferred", "title": "Contact Photos", "type": "integer" }, "contact_promotion_scores": { "default": 0, "description": "Contact promotion score rows merged", "title": "Contact Promotion Scores", "type": "integer" }, "crm_proposals": { "default": 0, "description": "Auto-CRM proposals repointed at the survivor", "title": "Crm Proposals", "type": "integer" }, "entity_match_suggestions": { "default": 0, "description": "Entity match suggestions transferred", "title": "Entity Match Suggestions", "type": "integer" }, "external_contacts": { "default": 0, "description": "External-identity cache rows (device/Google/CardDAV/...) repointed", "title": "External Contacts", "type": "integer" }, "face_clusters": { "default": 0, "description": "Resolved face clusters repointed (TIDY-15265)", "title": "Face Clusters", "type": "integer" }, "family_members": { "default": 0, "description": "Family member rows transferred", "title": "Family Members", "type": "integer" }, "graph_edges": { "default": 0, "description": "Graph edges transferred", "title": "Graph Edges", "type": "integer" }, "notes": { "default": 0, "description": "Notes transferred", "title": "Notes", "type": "integer" }, "parental_consent": { "default": 0, "description": "Consent records updated", "title": "Parental Consent", "type": "integer" }, "photo_faces": { "default": 0, "description": "Photos v2 face tags repointed (TIDY-15265)", "title": "Photo Faces", "type": "integer" }, "primitive_links": { "default": 0, "description": "Primitive links updated", "title": "Primitive Links", "type": "integer" } }, "title": "AffectedRecords", "type": "object" }, "AfterSpanPlacement": { "additionalProperties": false, "description": "Immediately after the top-level block containing ``old``.", "properties": { "mode": { "const": "after_span", "title": "Mode", "type": "string" }, "old": { "description": "Text that occurs exactly ONCE in the body. Two matches is an ambiguous_span refusal, not a guess.", "maxLength": 10000, "minLength": 1, "title": "Old", "type": "string" } }, "required": [ "mode", "old" ], "title": "AfterSpanPlacement", "type": "object" }, "AgentApprovalRequest": { "properties": { "activity_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Bare activity uuid of the task this is about; set blocked if the card expires.", "title": "Activity Id" }, "input": { "additionalProperties": true, "description": "The tool's exact input. The approval covers this call and no other.", "title": "AgentApprovalToolInput", "type": "object" }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Why, shown to the owner.", "title": "Reason" }, "run_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Correlates the approval to the run.", "title": "Run Id" }, "tool_name": { "description": "The tool the employee wants to use.", "minLength": 1, "title": "Tool Name", "type": "string" } }, "required": [ "tool_name" ], "title": "AgentApprovalRequest", "type": "object" }, "AgentApprovalResponse": { "properties": { "conversation_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Conversation Id" }, "decision": { "description": "allow (the owner approved this exact call; spent now, once) | declined | pending (the card is open in the asking conversation; the decision arrives there as a steer)", "title": "Decision", "type": "string" }, "in_this_conversation": { "default": true, "description": "pending: whether the open card stands in the conversation this call was made in. False means another of the employee's conversations asked first, and the owner's decision arrives there (an approval covers the exact call from any of them, once).", "title": "In This Conversation", "type": "boolean" }, "opened": { "default": false, "description": "True when this call opened the card.", "title": "Opened", "type": "boolean" }, "prompt_id": { "title": "Prompt Id", "type": "string" } }, "required": [ "decision", "prompt_id" ], "title": "AgentApprovalResponse", "type": "object" }, "AgentArtifactOperationStatusResponse": { "description": "Status of one principal-owned agent artifact operation (TIDY-15409 D32).", "properties": { "artifact_kind": { "title": "Artifact Kind", "type": "string" }, "error_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Error Code" }, "operation_id": { "title": "Operation Id", "type": "string" }, "result": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "description": "The recorded result, present once the operation completed.", "title": "AgentArtifactOperationResult" }, "status": { "enum": [ "pending", "completed", "failed_retryable", "failed_terminal" ], "title": "Status", "type": "string" }, "target_artifact_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Target Artifact Id" }, "target_version": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Target Version" }, "updated_at": { "format": "date-time", "title": "Updated At", "type": "string" } }, "required": [ "operation_id", "artifact_kind", "status", "updated_at" ], "title": "AgentArtifactOperationStatusResponse", "type": "object" }, "AgentAutonomyListResponse": { "properties": { "agents": { "items": { "$ref": "#/components/schemas/AgentAutonomyRow" }, "title": "Agents", "type": "array" }, "stale_threshold_seconds": { "title": "Stale Threshold Seconds", "type": "integer" }, "window_hours": { "title": "Window Hours", "type": "integer" } }, "required": [ "window_hours", "stale_threshold_seconds" ], "title": "AgentAutonomyListResponse", "type": "object" }, "AgentAutonomyRow": { "description": "One virtual employee's autonomy telemetry — TIDY-16413 (A9).\n\n`autonomy_state` is DERIVED at read time from the columns below plus the\nliveness row; it is stored nowhere, so it cannot disagree with its own\ninputs. Web and Android both render this exact field rather than each\nprojecting the vocabulary themselves.\n\nEvery counter is trailing-24h. `tokens_24h` / `cost_24h_usd` are NULL — not\nzero — when no conversation reported telemetry in the window: the board\nrenders that as \"unavailable\", because a VE we cannot measure is not a VE\nthat spent nothing.", "properties": { "active_runs": { "default": 0, "title": "Active Runs", "type": "integer" }, "agent_account_id": { "title": "Agent Account Id", "type": "string" }, "autonomy_state": { "enum": [ "working", "stalled-awaiting-wake", "backoff", "degraded", "suspended", "offline" ], "title": "Autonomy State", "type": "string" }, "backoff_level": { "default": 0, "title": "Backoff Level", "type": "integer" }, "cost_24h_usd": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "title": "Cost 24H Usd" }, "current_context_limit_tokens": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Current Context Limit Tokens" }, "current_context_used_tokens": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Current Context Used Tokens" }, "current_conversation_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Current Conversation Id" }, "current_item_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Current Item Id" }, "current_item_title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Current Item Title" }, "daily_cost_cap_usd": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "title": "Daily Cost Cap Usd" }, "daily_token_cap": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Daily Token Cap" }, "daily_wake_cap": { "default": 48, "title": "Daily Wake Cap", "type": "integer" }, "display_name": { "title": "Display Name", "type": "string" }, "error_repeat_count": { "default": 0, "title": "Error Repeat Count", "type": "integer" }, "heartbeat_enabled": { "title": "Heartbeat Enabled", "type": "boolean" }, "last_decision": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Last Decision" }, "last_decision_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Last Decision At" }, "last_decision_class": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Last Decision Class" }, "last_decision_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Last Decision Id" }, "last_decision_source": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Last Decision Source" }, "last_error_class": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Last Error Class" }, "last_heartbeat_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Last Heartbeat At" }, "loop_suppressed_items": { "default": 0, "title": "Loop Suppressed Items", "type": "integer" }, "loop_suspect_threshold": { "title": "Loop Suspect Threshold", "type": "integer" }, "max_parallel_sessions": { "title": "Max Parallel Sessions", "type": "integer" }, "next_wake_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Next Wake At" }, "slug": { "title": "Slug", "type": "string" }, "status": { "title": "Status", "type": "string" }, "tenant_flag_enabled": { "title": "Tenant Flag Enabled", "type": "boolean" }, "tokens_24h": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Tokens 24H" }, "trip_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Trip Reason" }, "tripped_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Tripped At" }, "usage_available": { "default": true, "title": "Usage Available", "type": "boolean" }, "wake_completion_ratio": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "title": "Wake Completion Ratio" }, "wake_idle_minutes": { "title": "Wake Idle Minutes", "type": "integer" }, "wakes_24h": { "default": 0, "title": "Wakes 24H", "type": "integer" } }, "required": [ "agent_account_id", "slug", "display_name", "status", "autonomy_state", "heartbeat_enabled", "tenant_flag_enabled", "wake_idle_minutes", "max_parallel_sessions", "loop_suspect_threshold" ], "title": "AgentAutonomyRow", "type": "object" }, "AgentBudgetDefinition": { "description": "A live budget as state — membership, limit, metric, window — never its burn.", "properties": { "id": { "title": "Id", "type": "string" }, "limit": { "title": "Limit", "type": "number" }, "metric": { "enum": [ "cost_usd", "tokens" ], "title": "Metric", "type": "string" }, "period": { "enum": [ "day", "week", "month" ], "title": "Period", "type": "string" }, "period_start": { "format": "date-time", "title": "Period Start", "type": "string" }, "soft_threshold_pct": { "title": "Soft Threshold Pct", "type": "number" }, "title": { "title": "Title", "type": "string" } }, "required": [ "id", "title", "metric", "period", "limit", "soft_threshold_pct", "period_start" ], "title": "AgentBudgetDefinition", "type": "object" }, "AgentBudgetInput": { "additionalProperties": false, "description": "The connector's budget view, used only to make the server's decision stricter.", "properties": { "local_spend": { "$ref": "#/components/schemas/AgentBudgetLocalSpend" }, "snapshot": { "items": { "$ref": "#/components/schemas/AgentBudgetSnapshotEntry" }, "maxItems": 64, "title": "Snapshot", "type": "array" } }, "required": [ "local_spend" ], "title": "AgentBudgetInput", "type": "object" }, "AgentBudgetLocalSpend": { "additionalProperties": false, "description": "What the box spent since its renewal snapshot's epoch (``costGuardSpend``).", "properties": { "cost": { "maximum": 1000000000000.0, "minimum": 0.0, "title": "Cost", "type": "number" }, "tokens": { "maximum": 1000000000000000.0, "minimum": 0.0, "title": "Tokens", "type": "integer" } }, "required": [ "tokens", "cost" ], "title": "AgentBudgetLocalSpend", "type": "object" }, "AgentBudgetSnapshotEntry": { "additionalProperties": false, "description": "One budget's burn as the connector's current renewal snapshot reported it.\n\nEchoed only for a real measurement (never a ``refused`` sentinel). Compared\nonly with the same budget, metric, period and window (TIDY-19869 V6-M2).", "properties": { "budget_id": { "format": "uuid", "title": "Budget Id", "type": "string" }, "burn": { "maximum": 1000000000000000.0, "minimum": 0.0, "title": "Burn", "type": "number" }, "metric": { "enum": [ "cost_usd", "tokens" ], "title": "Metric", "type": "string" }, "period": { "enum": [ "day", "week", "month" ], "title": "Period", "type": "string" }, "period_start": { "format": "date-time", "title": "Period Start", "type": "string" } }, "required": [ "budget_id", "metric", "period", "period_start", "burn" ], "title": "AgentBudgetSnapshotEntry", "type": "object" }, "AgentClaimPreflightRequest": { "properties": { "claim_token": { "maxLength": 256, "minLength": 32, "title": "Claim Token", "type": "string" } }, "required": [ "claim_token" ], "title": "AgentClaimPreflightRequest", "type": "object" }, "AgentClaimPreflightResponse": { "properties": { "agent_account_id": { "format": "uuid", "title": "Agent Account Id", "type": "string" }, "portable_state": { "enum": [ "none", "dormant", "active" ], "title": "Portable State", "type": "string" } }, "required": [ "agent_account_id", "portable_state" ], "title": "AgentClaimPreflightResponse", "type": "object" }, "AgentClaimRequest": { "properties": { "claim_token": { "maxLength": 256, "minLength": 32, "title": "Claim Token", "type": "string" }, "runtime_kind": { "anyOf": [ { "maxLength": 80, "type": "string" }, { "type": "null" } ], "title": "Runtime Kind" } }, "required": [ "claim_token" ], "title": "AgentClaimRequest", "type": "object" }, "AgentClaimResponse": { "properties": { "account_id": { "title": "Account Id", "type": "string" }, "agent_member_id": { "title": "Agent Member Id", "type": "string" }, "bearer_token": { "title": "Bearer Token", "type": "string" }, "display_name": { "title": "Display Name", "type": "string" }, "employee_settings": { "$ref": "#/components/schemas/EmployeeAgentSettingsPayload" }, "homeserver_url": { "title": "Homeserver Url", "type": "string" }, "matrix_access_token": { "title": "Matrix Access Token", "type": "string" }, "matrix_allowed_users": { "items": { "type": "string" }, "title": "Matrix Allowed Users", "type": "array" }, "matrix_bootstrap_url": { "title": "Matrix Bootstrap Url", "type": "string" }, "matrix_device_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Matrix Device Id" }, "matrix_home_room_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Matrix Home Room Id" }, "matrix_home_room_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Matrix Home Room Name" }, "matrix_user_id": { "title": "Matrix User Id", "type": "string" }, "mcp_endpoint": { "title": "Mcp Endpoint", "type": "string" }, "runtime_kind": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Runtime Kind" }, "status": { "const": "active", "title": "Status", "type": "string" }, "tenant_id": { "title": "Tenant Id", "type": "string" } }, "required": [ "tenant_id", "account_id", "agent_member_id", "display_name", "matrix_user_id", "homeserver_url", "matrix_access_token", "mcp_endpoint", "bearer_token", "matrix_bootstrap_url", "status" ], "title": "AgentClaimResponse", "type": "object" }, "AgentClaimV2Request": { "properties": { "agent_account_id": { "format": "uuid", "title": "Agent Account Id", "type": "string" }, "claim_token": { "maxLength": 256, "minLength": 32, "title": "Claim Token", "type": "string" }, "idempotency_key": { "format": "uuid", "title": "Idempotency Key", "type": "string" }, "installation_id": { "format": "uuid", "title": "Installation Id", "type": "string" }, "machine_fingerprint": { "maxLength": 512, "minLength": 16, "title": "Machine Fingerprint", "type": "string" }, "runtime_kind": { "enum": [ "pi", "hermes", "openclaw", "claude-code", "codex", "opencode", "antigravity" ], "title": "Runtime Kind", "type": "string" }, "takeover_receipt_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Takeover Receipt Id" }, "workshop_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Workshop Id" }, "workshop_install_id": { "anyOf": [ { "pattern": "^[0-9a-f]{12}$", "type": "string" }, { "type": "null" } ], "title": "Workshop Install Id" } }, "required": [ "claim_token", "runtime_kind", "agent_account_id", "installation_id", "idempotency_key", "machine_fingerprint" ], "title": "AgentClaimV2Request", "type": "object" }, "AgentClaimV2Response": { "properties": { "connector_bundle_v2": { "$ref": "#/components/schemas/ConnectorBundleV2" }, "host_continuity_token": { "title": "Host Continuity Token", "type": "string" }, "host_instance_id": { "format": "uuid", "title": "Host Instance Id", "type": "string" }, "installation_id": { "format": "uuid", "title": "Installation Id", "type": "string" }, "recovered_existing": { "default": false, "title": "Recovered Existing", "type": "boolean" }, "replacement_not_before": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Replacement Not Before" }, "server_time": { "format": "date-time", "title": "Server Time", "type": "string" }, "workshop_hosting": { "anyOf": [ { "enum": [ "provisioned", "byo" ], "type": "string" }, { "type": "null" } ], "default": null, "title": "Workshop Hosting" } }, "required": [ "installation_id", "host_instance_id", "host_continuity_token", "connector_bundle_v2", "server_time" ], "title": "AgentClaimV2Response", "type": "object" }, "AgentColleagueTurnRequest": { "description": "A colleague's message the connector would answer (TIDY-19611).", "properties": { "event_id": { "description": "The colleague's message — or its edit — that @mentions this employee.", "maxLength": 512, "minLength": 1, "title": "Event Id", "type": "string" }, "room_id": { "maxLength": 512, "minLength": 1, "title": "Room Id", "type": "string" } }, "required": [ "room_id", "event_id" ], "title": "AgentColleagueTurnRequest", "type": "object" }, "AgentColleagueTurnResponse": { "properties": { "admitted": { "title": "Admitted", "type": "boolean" }, "reason": { "description": "`admitted`, or why not: not_a_colleague, colleague_not_in_room, room_not_admissible, already_answered, room_employee_run_capped, event_unverified, or a wake safeguard (daily_wake_cap_reached, autonomy_tripped, employee_paused, ...).", "title": "Reason", "type": "string" } }, "required": [ "admitted", "reason" ], "title": "AgentColleagueTurnResponse", "type": "object" }, "AgentControlCommand": { "properties": { "command_id": { "title": "Command Id", "type": "string" }, "issued_at": { "title": "Issued At", "type": "string" }, "issued_by": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Issued By" }, "kind": { "title": "Kind", "type": "string" }, "payload": { "additionalProperties": true, "title": "Payload", "type": "object" } }, "required": [ "command_id", "kind", "payload", "issued_at" ], "title": "AgentControlCommand", "type": "object" }, "AgentControlCommandResponse": { "properties": { "expires_at": { "title": "Expires At", "type": "string" }, "id": { "title": "Id", "type": "string" }, "issued_at": { "title": "Issued At", "type": "string" }, "issued_by": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Issued By" }, "kind": { "title": "Kind", "type": "string" }, "payload": { "additionalProperties": true, "title": "Payload", "type": "object" }, "scope": { "title": "Scope", "type": "string" }, "scope_ref": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Scope Ref" }, "targets": { "items": { "$ref": "#/components/schemas/AgentControlTarget" }, "title": "Targets", "type": "array" } }, "required": [ "id", "scope", "kind", "payload", "issued_at", "expires_at", "targets" ], "title": "AgentControlCommandResponse", "type": "object" }, "AgentControlCreateRequest": { "properties": { "kind": { "description": "steer | stop", "title": "Kind", "type": "string" }, "payload": { "additionalProperties": true, "description": "steer requires payload.message; stop takes optional reason.", "title": "Payload", "type": "object" }, "scope": { "description": "session | activity | project | all", "title": "Scope", "type": "string" }, "scope_ref": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "UUID of the session/activity/project (not for scope=all).", "title": "Scope Ref" } }, "required": [ "scope", "kind" ], "title": "AgentControlCreateRequest", "type": "object" }, "AgentControlListResponse": { "properties": { "commands": { "items": { "$ref": "#/components/schemas/AgentControlCommand" }, "title": "Commands", "type": "array" } }, "required": [ "commands" ], "title": "AgentControlListResponse", "type": "object" }, "AgentControlTarget": { "properties": { "ack_outcome": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Ack Outcome" }, "acked_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Acked At" }, "agent_name": { "title": "Agent Name", "type": "string" }, "session_id": { "title": "Session Id", "type": "string" }, "status": { "title": "Status", "type": "string" } }, "required": [ "session_id", "agent_name", "status" ], "title": "AgentControlTarget", "type": "object" }, "AgentConversationMoveRequest": { "description": "TIDY-20023: an employee asks to move the conversation it is in into a project.", "properties": { "project": { "description": "The project: its id (bare or P-) or its exact name, among those the conversation's person can see.", "maxLength": 300, "minLength": 1, "title": "Project", "type": "string" }, "reason": { "description": "Why, in a sentence the person reads on the card.", "maxLength": 4000, "minLength": 1, "title": "Reason", "type": "string" }, "run_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Correlates the request to the dispatched run.", "title": "Run Id" } }, "required": [ "project", "reason" ], "title": "AgentConversationMoveRequest", "type": "object" }, "AgentConversationMoveResponse": { "properties": { "asker_kind": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "TIDY-19705 F18: 'employee' — the answer steers into the conversation that asked; 'person' — asked from outside Tidy, so read the answer back (GET /agents/prompts/{id}, waiting on it).", "title": "Asker Kind" }, "conversation_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "The conversation that asked; its card lives there.", "title": "Conversation Id" }, "dm_room_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Unused since TIDY-19705 F14; a question is a card.", "title": "Dm Room Id" }, "id": { "title": "Id", "type": "string" }, "kind": { "title": "Kind", "type": "string" }, "notification": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "TIDY-19705 F18, a person's question to a person: what their phone was told — `emitted`, a suppression (`suppressed_quiet_hours`, `suppressed_disabled`, `deduped`, …) or `failed`. The card is open either way.", "title": "Notification" }, "project_id": { "description": "The project the conversation would move into.", "title": "Project Id", "type": "string" }, "project_name": { "title": "Project Name", "type": "string" }, "queued": { "default": false, "description": "TIDY-19705 F15: the employee it was put to has no free slot yet, so nothing has reached it; withdrawn now, it never will.", "title": "Queued", "type": "boolean" }, "recipient_account_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "The person (or employee account) the question was put to.", "title": "Recipient Account Id" }, "recipient_display_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Who the question was put to, as they are named.", "title": "Recipient Display Name" }, "recipient_kind": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "TIDY-19705 F15: 'person' or 'employee'.", "title": "Recipient Kind" }, "reply_verification": { "default": "unavailable", "description": "Whether this backend certifies who answered: `verified` (a question on its card, answered only by the person it was put to), `unavailable` (a question asked before cards, never answered) or `not_applicable` (an exact-write approval card, decided by the owner's click).", "title": "Reply Verification", "type": "string" }, "reply_verification_detail": { "default": "This backend cannot verify reply provenance. Do not treat it as approval or automatically resend.", "title": "Reply Verification Detail", "type": "string" }, "status": { "title": "Status", "type": "string" }, "timeout_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "description": "None for a question, which waits for its person.", "title": "Timeout At" } }, "required": [ "id", "status", "kind", "project_id", "project_name" ], "title": "AgentConversationMoveResponse", "type": "object" }, "AgentDelegationAccess": { "description": "One delegation resource at one access level (TIDY-19305).", "properties": { "action": { "enum": [ "read", "read_write" ], "title": "Action", "type": "string" }, "resource_type": { "title": "Resource Type", "type": "string" } }, "required": [ "resource_type", "action" ], "title": "AgentDelegationAccess", "type": "object" }, "AgentElevationRequest": { "description": "TIDY-16360 — set this employee's elevation intent. Explicit, never toggled.\n\nA body carrying the value rather than a bare toggle endpoint: two admins\nacting on a stale roster would otherwise flip each other's change, and the\nthing being flipped is whether an employee may become root on someone's\ncomputer.", "properties": { "elevated_privileges": { "title": "Elevated Privileges", "type": "boolean" } }, "required": [ "elevated_privileges" ], "title": "AgentElevationRequest", "type": "object" }, "AgentElevationResponse": { "properties": { "elevated_privileges": { "title": "Elevated Privileges", "type": "boolean" }, "elevated_privileges_applied": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "title": "Elevated Privileges Applied" }, "elevation_state": { "default": "idle", "enum": [ "idle", "pending", "applying", "failed" ], "title": "Elevation State", "type": "string" }, "pending_restart": { "default": false, "title": "Pending Restart", "type": "boolean" } }, "required": [ "elevated_privileges" ], "title": "AgentElevationResponse", "type": "object" }, "AgentEventLivenessResponse": { "properties": { "harnesses": { "items": { "additionalProperties": true, "type": "object" }, "title": "Harnesses", "type": "array" }, "status": { "default": "ok", "title": "Status", "type": "string" } }, "required": [ "harnesses" ], "title": "AgentEventLivenessResponse", "type": "object" }, "AgentGitHubAccessRequest": { "description": "TIDY-16314 — set this employee's GitHub consent on a LIVE employee.\n\nCarries the value rather than toggling, for the same reason as elevation\nnext door: what is being flipped is whether this employee may mint a token\nagainst the workspace's GitHub App installation, and two admins on a stale\nroster must not be able to flip each other's decision blind.", "properties": { "github_access": { "title": "Github Access", "type": "boolean" }, "scm_plugin_ids": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Scm Plugin Ids" } }, "required": [ "github_access" ], "title": "AgentGitHubAccessRequest", "type": "object" }, "AgentGitHubAccessResponse": { "properties": { "credential_helper_may_need_repair": { "default": false, "title": "Credential Helper May Need Repair", "type": "boolean" }, "github_access": { "title": "Github Access", "type": "boolean" }, "scm_access": { "anyOf": [ { "$ref": "#/components/schemas/AgentScmAccessResponse" }, { "type": "null" } ], "default": null }, "scm_grant_error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Scm Grant Error" }, "scm_grant_job_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Scm Grant Job Id" } }, "required": [ "github_access" ], "title": "AgentGitHubAccessResponse", "type": "object" }, "AgentGitIdentity": { "description": "TIDY-16314 — the RESOLVED commit identity a heartbeat hands the host.\n\nAlways the effective values, never the nullable overrides: the host's only\njob is to write these into the VE-scoped git config, and resolution lives\nserver-side so every connector version renders the same identity.", "properties": { "email": { "title": "Email", "type": "string" }, "model_trailer": { "default": false, "title": "Model Trailer", "type": "boolean" }, "name": { "title": "Name", "type": "string" } }, "required": [ "name", "email" ], "title": "AgentGitIdentity", "type": "object" }, "AgentGitIdentityRequest": { "description": "TIDY-16314 — set this employee's commit identity. Whole-value, never a\npatch: two admins acting on a stale roster must overwrite, not interleave.\n\n``None``/blank fields mean \"use the default\" (the VE's own name and\n``@ve.``) — resolved server-side so a VE provisioned\nbefore these fields existed still has a full identity. ``tidy[bot]`` is\ndeliberately never a default and never special-cased here.", "properties": { "git_author_email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Git Author Email" }, "git_author_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Git Author Name" }, "git_model_trailer": { "default": false, "title": "Git Model Trailer", "type": "boolean" } }, "title": "AgentGitIdentityRequest", "type": "object" }, "AgentGitIdentityResponse": { "properties": { "effective_email": { "title": "Effective Email", "type": "string" }, "effective_name": { "title": "Effective Name", "type": "string" }, "git_author_default_email": { "title": "Git Author Default Email", "type": "string" }, "git_author_default_name": { "title": "Git Author Default Name", "type": "string" }, "git_author_email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Git Author Email" }, "git_author_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Git Author Name" }, "git_model_trailer": { "default": false, "title": "Git Model Trailer", "type": "boolean" } }, "required": [ "effective_name", "effective_email", "git_author_default_name", "git_author_default_email" ], "title": "AgentGitIdentityResponse", "type": "object" }, "AgentHarnessProcesses": { "description": "TIDY-19933 (F9) — the harness processes one employee's connector keeps.\n\n`budget` is the owner's max_parallel_sessions; the rest count the\nconversations taking it now: running a turn, holding background work, and\nkeeping a harness process warm for a next turn. A person's turn always runs,\nso `running` and `holding` can pass `budget`; a warm one never does.", "properties": { "budget": { "maximum": 64.0, "minimum": 1.0, "title": "Budget", "type": "integer" }, "holding": { "maximum": 256.0, "minimum": 0.0, "title": "Holding", "type": "integer" }, "running": { "maximum": 256.0, "minimum": 0.0, "title": "Running", "type": "integer" }, "warm": { "maximum": 64.0, "minimum": 0.0, "title": "Warm", "type": "integer" } }, "required": [ "budget", "running", "holding", "warm" ], "title": "AgentHarnessProcesses", "type": "object" }, "AgentHarnessReport": { "description": "TIDY-16332 (S21) — one harness a VE host runs, as the connector sees it.\n\nFacts only. The connector does not judge its own currency — a stale\nconnector is exactly the one whose idea of \"supported\" is stale too — so\nthe comparison against the supported range happens on the server.", "properties": { "accounts": { "anyOf": [ { "items": { "$ref": "#/components/schemas/HarnessAccountReport" }, "maxItems": 32, "type": "array" }, { "type": "null" } ], "title": "Accounts" }, "active_account_absent": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Active Account Absent" }, "auth_state": { "anyOf": [ { "enum": [ "signed_in", "installed_not_signed_in" ], "type": "string" }, { "type": "null" } ], "title": "Auth State" }, "executable": { "anyOf": [ { "maxLength": 1024, "type": "string" }, { "type": "null" } ], "title": "Executable" }, "is_default": { "default": false, "title": "Is Default", "type": "boolean" }, "latest_version": { "anyOf": [ { "maxLength": 80, "type": "string" }, { "type": "null" } ], "title": "Latest Version" }, "model_catalog": { "anyOf": [ { "items": { "maxLength": 255, "minLength": 1, "type": "string" }, "maxItems": 256, "type": "array" }, { "type": "null" } ], "title": "Model Catalog" }, "model_catalog_entries": { "anyOf": [ { "items": { "$ref": "#/components/schemas/HarnessModelCatalogEntryReport" }, "maxItems": 256, "type": "array" }, { "type": "null" } ], "title": "Model Catalog Entries" }, "model_context_limit_tokens": { "anyOf": [ { "additionalProperties": { "minimum": 1.0, "type": "integer" }, "type": "object" }, { "type": "null" } ], "title": "Model Context Limit Tokens" }, "option_descriptors": { "anyOf": [ { "items": { "$ref": "#/components/schemas/HarnessModelOptionDescriptorsReport" }, "maxItems": 100, "type": "array" }, { "type": "null" } ], "title": "Option Descriptors" }, "own_sign_ins": { "anyOf": [ { "$ref": "#/components/schemas/HarnessOwnSignInsReport" }, { "type": "null" } ] }, "packages_update_failure": { "anyOf": [ { "maxLength": 800, "type": "string" }, { "type": "null" } ], "title": "Packages Update Failure" }, "packages_updated_at": { "anyOf": [ { "maxLength": 40, "type": "string" }, { "type": "null" } ], "title": "Packages Updated At" }, "runtime": { "maxLength": 64, "title": "Runtime", "type": "string" }, "sdk_version": { "anyOf": [ { "maxLength": 80, "type": "string" }, { "type": "null" } ], "title": "Sdk Version" }, "self_updating": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Self Updating" }, "sign_in_evidence": { "anyOf": [ { "additionalProperties": { "$ref": "#/components/schemas/HarnessSignInEvidenceReport" }, "maxProperties": 32, "type": "object" }, { "type": "null" } ], "title": "Sign In Evidence" }, "sign_in_store": { "anyOf": [ { "pattern": "^[0-9a-f]{64}$", "type": "string" }, { "type": "null" } ], "title": "Sign In Store" }, "unavailable_reason": { "anyOf": [ { "maxLength": 300, "type": "string" }, { "type": "null" } ], "title": "Unavailable Reason" }, "update_atomic": { "default": false, "title": "Update Atomic", "type": "boolean" }, "update_checked_at": { "anyOf": [ { "maxLength": 40, "type": "string" }, { "type": "null" } ], "title": "Update Checked At" }, "update_failure": { "anyOf": [ { "maxLength": 800, "type": "string" }, { "type": "null" } ], "title": "Update Failure" }, "usage": { "anyOf": [ { "$ref": "#/components/schemas/HarnessUsageSnapshotV1" }, { "type": "null" } ] }, "usage_by_profile": { "anyOf": [ { "additionalProperties": { "$ref": "#/components/schemas/HarnessUsageSnapshotV1" }, "type": "object" }, { "type": "null" } ], "title": "Usage By Profile" }, "usage_observation_seq": { "anyOf": [ { "minimum": 1.0, "type": "integer" }, { "type": "null" } ], "title": "Usage Observation Seq" }, "version": { "anyOf": [ { "maxLength": 80, "type": "string" }, { "type": "null" } ], "title": "Version" } }, "required": [ "runtime" ], "title": "AgentHarnessReport", "type": "object" }, "AgentHeartbeatRequest": { "properties": { "artifact_digest": { "anyOf": [ { "maxLength": 100, "type": "string" }, { "type": "null" } ], "title": "Artifact Digest" }, "artifact_version": { "anyOf": [ { "maxLength": 80, "type": "string" }, { "type": "null" } ], "title": "Artifact Version" }, "capabilities": { "anyOf": [ { "items": { "type": "string" }, "maxItems": 64, "type": "array" }, { "type": "null" } ], "title": "Capabilities" }, "elevated_privileges": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Elevated Privileges" }, "harness_processes": { "anyOf": [ { "$ref": "#/components/schemas/AgentHarnessProcesses" }, { "type": "null" } ] }, "harnesses": { "anyOf": [ { "items": { "$ref": "#/components/schemas/AgentHarnessReport" }, "maxItems": 6, "type": "array" }, { "type": "null" } ], "title": "Harnesses" }, "last_exit": { "anyOf": [ { "$ref": "#/components/schemas/AgentOutOfMemoryExit" }, { "type": "null" } ] }, "lifecycle_reports": { "anyOf": [ { "items": { "$ref": "#/components/schemas/AgentLifecyclePhaseReport" }, "maxItems": 8, "type": "array" }, { "type": "null" } ], "title": "Lifecycle Reports" }, "memory_enforcement": { "anyOf": [ { "$ref": "#/components/schemas/AgentMemoryEnforcement" }, { "type": "null" } ] }, "providers": { "anyOf": [ { "items": { "$ref": "#/components/schemas/AgentProviderReport" }, "maxItems": 8, "type": "array" }, { "type": "null" } ], "title": "Providers" }, "runtime_host": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "title": "Runtime Host" }, "runtime_kind": { "anyOf": [ { "maxLength": 80, "type": "string" }, { "type": "null" } ], "title": "Runtime Kind" }, "runtime_pid": { "anyOf": [ { "minimum": 0.0, "type": "integer" }, { "type": "null" } ], "title": "Runtime Pid" }, "session_contract_version": { "anyOf": [ { "maximum": 1000.0, "minimum": 0.0, "type": "integer" }, { "type": "null" } ], "title": "Session Contract Version" }, "turn_outcomes": { "anyOf": [ { "maxProperties": 32, "patternProperties": { "^[a-z0-9_]{1,64}$": { "maximum": 100000.0, "minimum": 0.0, "type": "integer" } }, "type": "object" }, { "type": "null" } ], "title": "Turn Outcomes" }, "update_report": { "anyOf": [ { "$ref": "#/components/schemas/AgentUpdatePhaseReport" }, { "type": "null" } ] }, "update_reports": { "anyOf": [ { "items": { "$ref": "#/components/schemas/AgentUpdatePhaseReport" }, "maxItems": 16, "type": "array" }, { "type": "null" } ], "title": "Update Reports" } }, "title": "AgentHeartbeatRequest", "type": "object" }, "AgentHeartbeatResponse": { "properties": { "git_identity": { "anyOf": [ { "$ref": "#/components/schemas/AgentGitIdentity" }, { "type": "null" } ], "default": null }, "harness_settings": { "additionalProperties": { "additionalProperties": { "type": "boolean" }, "type": "object" }, "title": "Harness Settings", "type": "object" }, "last_exit_recorded": { "default": false, "title": "Last Exit Recorded", "type": "boolean" }, "last_heartbeat_at": { "format": "date-time", "title": "Last Heartbeat At", "type": "string" }, "last_seen_at": { "format": "date-time", "title": "Last Seen At", "type": "string" }, "lifecycle": { "anyOf": [ { "$ref": "#/components/schemas/AgentLifecycleDirective" }, { "type": "null" } ], "default": null }, "max_parallel_sessions": { "anyOf": [ { "maximum": 50, "minimum": 1, "type": "integer" }, { "type": "null" } ], "default": null, "title": "Max Parallel Sessions" }, "memory_ceiling": { "anyOf": [ { "$ref": "#/components/schemas/AgentMemoryCeiling" }, { "type": "null" } ], "default": null }, "status": { "const": "active", "title": "Status", "type": "string" }, "update": { "anyOf": [ { "$ref": "#/components/schemas/AgentUpdateDirective" }, { "type": "null" } ], "default": null }, "usage_refresh": { "items": { "$ref": "#/components/schemas/HarnessUsageRefresh" }, "title": "Usage Refresh", "type": "array" } }, "required": [ "status", "last_seen_at", "last_heartbeat_at" ], "title": "AgentHeartbeatResponse", "type": "object" }, "AgentHeartbeatSettingsRequest": { "description": "TIDY-16406 — the owner's work-heartbeat settings for one employee.\n\nExplicit values, never toggles (same reasoning as elevation next door).\nAbsent fields keep their current value.", "properties": { "approvers": { "anyOf": [ { "items": { "type": "string" }, "maxItems": 20, "type": "array" }, { "type": "null" } ], "description": "Account ids that may be asked to approve for this employee when the ask is not about an owned work item. Empty = the owner alone.", "title": "Approvers" }, "browser_evidence_retention_days_override": { "anyOf": [ { "maximum": 365.0, "minimum": 1.0, "type": "integer" }, { "type": "null" } ], "title": "Browser Evidence Retention Days Override" }, "browser_evidence_video_override": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Browser Evidence Video Override" }, "charter": { "anyOf": [ { "maxLength": 20000, "type": "string" }, { "type": "null" } ], "title": "Charter" }, "colleague_messages_per_hour": { "anyOf": [ { "maximum": 100.0, "minimum": 0.0, "type": "integer" }, { "type": "null" } ], "title": "Colleague Messages Per Hour" }, "compaction_threshold_percent": { "anyOf": [ { "maximum": 95.0, "minimum": 50.0, "type": "integer" }, { "type": "null" } ], "title": "Compaction Threshold Percent" }, "daily_cost_cap_usd": { "anyOf": [ { "maximum": 999999.0, "minimum": 0.0, "type": "number" }, { "type": "null" } ], "title": "Daily Cost Cap Usd" }, "daily_token_cap": { "anyOf": [ { "minimum": 0.0, "type": "integer" }, { "type": "null" } ], "title": "Daily Token Cap" }, "daily_wake_cap": { "anyOf": [ { "maximum": 10000.0, "minimum": 0.0, "type": "integer" }, { "type": "null" } ], "title": "Daily Wake Cap" }, "delegation_max_depth": { "anyOf": [ { "maximum": 5.0, "minimum": 1.0, "type": "integer" }, { "type": "null" } ], "title": "Delegation Max Depth" }, "delegation_max_open": { "anyOf": [ { "maximum": 20.0, "minimum": 1.0, "type": "integer" }, { "type": "null" } ], "title": "Delegation Max Open" }, "delegation_scope": { "anyOf": [ { "enum": [ "nobody", "reports", "named", "anyone" ], "type": "string" }, { "type": "null" } ], "title": "Delegation Scope" }, "delegation_targets": { "anyOf": [ { "items": { "type": "string" }, "maxItems": 50, "type": "array" }, { "type": "null" } ], "title": "Delegation Targets" }, "heartbeat_enabled": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Heartbeat Enabled" }, "max_parallel_sessions": { "anyOf": [ { "maximum": 50.0, "minimum": 1.0, "type": "integer" }, { "type": "null" } ], "title": "Max Parallel Sessions" }, "memory_ceiling_bytes": { "anyOf": [ { "maximum": 1099511627776.0, "minimum": 1073741824.0, "type": "integer" }, { "type": "null" } ], "title": "Memory Ceiling Bytes" }, "plan_approval_expiry_minutes": { "anyOf": [ { "maximum": 10080.0, "minimum": 5.0, "type": "integer" }, { "type": "null" } ], "title": "Plan Approval Expiry Minutes" }, "plan_first_default": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Plan First Default" }, "reflection_cadence": { "anyOf": [ { "maxLength": 32, "pattern": "^P(?:\\d+D)?(?:T(?:\\d+H)?(?:\\d+M)?)?$", "type": "string" }, { "type": "null" } ], "title": "Reflection Cadence" }, "reflection_idle_days": { "anyOf": [ { "maximum": 365.0, "minimum": 0.0, "type": "integer" }, { "type": "null" } ], "title": "Reflection Idle Days" }, "reflection_max_proposals": { "anyOf": [ { "maximum": 50.0, "minimum": 1.0, "type": "integer" }, { "type": "null" } ], "title": "Reflection Max Proposals" }, "reflection_proposal_target": { "anyOf": [ { "maximum": 50.0, "minimum": 1.0, "type": "integer" }, { "type": "null" } ], "title": "Reflection Proposal Target" }, "wake_idle_minutes": { "anyOf": [ { "maximum": 1440.0, "minimum": 1.0, "type": "integer" }, { "type": "null" } ], "title": "Wake Idle Minutes" } }, "title": "AgentHeartbeatSettingsRequest", "type": "object" }, "AgentHeartbeatSettingsResponse": { "properties": { "allow_standing_grants": { "default": true, "title": "Allow Standing Grants", "type": "boolean" }, "approvers": { "items": { "type": "string" }, "title": "Approvers", "type": "array" }, "autonomy_ceiling": { "anyOf": [ { "enum": [ "supervised", "auto_accept_edits", "full_access" ], "type": "string" }, { "type": "null" } ], "default": null, "title": "Autonomy Ceiling" }, "autonomy_trip_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Autonomy Trip Reason" }, "autonomy_tripped_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Autonomy Tripped At" }, "browser_evidence_footprint_bytes": { "default": 0, "title": "Browser Evidence Footprint Bytes", "type": "integer" }, "browser_evidence_retention_days_override": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Browser Evidence Retention Days Override" }, "browser_evidence_video_override": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "title": "Browser Evidence Video Override" }, "charter": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Charter" }, "colleague_messages_per_hour": { "default": 5, "title": "Colleague Messages Per Hour", "type": "integer" }, "compaction_threshold_percent": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": 80, "title": "Compaction Threshold Percent" }, "daily_cost_cap_usd": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "title": "Daily Cost Cap Usd" }, "daily_token_cap": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Daily Token Cap" }, "daily_wake_cap": { "default": 48, "title": "Daily Wake Cap", "type": "integer" }, "delegation_max_depth": { "default": 2, "title": "Delegation Max Depth", "type": "integer" }, "delegation_max_open": { "default": 5, "title": "Delegation Max Open", "type": "integer" }, "delegation_scope": { "default": "nobody", "enum": [ "nobody", "reports", "named", "anyone" ], "title": "Delegation Scope", "type": "string" }, "delegation_targets": { "items": { "type": "string" }, "title": "Delegation Targets", "type": "array" }, "disengaged": { "default": false, "title": "Disengaged", "type": "boolean" }, "disengagement_days": { "default": 7, "title": "Disengagement Days", "type": "integer" }, "heartbeat_enabled": { "title": "Heartbeat Enabled", "type": "boolean" }, "last_engaged_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Last Engaged At" }, "local_day_start": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Local Day Start" }, "loop_suppressed_items": { "default": 0, "title": "Loop Suppressed Items", "type": "integer" }, "max_parallel_sessions": { "title": "Max Parallel Sessions", "type": "integer" }, "memory_ceiling_bytes": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Memory Ceiling Bytes" }, "memory_ceiling_unenforced_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Memory Ceiling Unenforced Reason" }, "plan_approval_expiry_minutes": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Plan Approval Expiry Minutes" }, "plan_first_default": { "default": false, "title": "Plan First Default", "type": "boolean" }, "reflection_cadence": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Reflection Cadence" }, "reflection_flag_enabled": { "default": false, "title": "Reflection Flag Enabled", "type": "boolean" }, "reflection_idle_days": { "default": 3, "title": "Reflection Idle Days", "type": "integer" }, "reflection_max_proposals": { "default": 5, "title": "Reflection Max Proposals", "type": "integer" }, "reflection_proposal_target": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Reflection Proposal Target" }, "spend_today_usd": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "title": "Spend Today Usd" }, "tenant_flag_enabled": { "title": "Tenant Flag Enabled", "type": "boolean" }, "time_zone": { "default": "UTC", "title": "Time Zone", "type": "string" }, "tokens_today": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Tokens Today" }, "usage_available": { "default": true, "title": "Usage Available", "type": "boolean" }, "usage_measurable": { "default": true, "title": "Usage Measurable", "type": "boolean" }, "usage_unmeasurable_reason": { "anyOf": [ { "enum": [ "hosted", "harness_reports_no_usage" ], "type": "string" }, { "type": "null" } ], "default": null, "title": "Usage Unmeasurable Reason" }, "wake_idle_minutes": { "title": "Wake Idle Minutes", "type": "integer" }, "wakes_today": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Wakes Today" } }, "required": [ "heartbeat_enabled", "wake_idle_minutes", "max_parallel_sessions", "tenant_flag_enabled" ], "title": "AgentHeartbeatSettingsResponse", "type": "object" }, "AgentHomeRoomLogEntry": { "description": "One back-channel event from the VE's home-room timeline (TIDY-16782).\n\nThe home room is the system back channel — no human is a member and it is\nplaintext by design (TIDY-16646) — so this server-side projection is how\nthe home-base Log tab makes wakes and system notices (upgrade notes, the\nhome-room turn refusal) inspectable, and the work orders and completion\nreports a room kept from before that rail retired (TIDY-19869).", "properties": { "body": { "default": "", "title": "Body", "type": "string" }, "event_id": { "title": "Event Id", "type": "string" }, "kind": { "title": "Kind", "type": "string" }, "notification_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Notification Type" }, "origin_server_ts": { "title": "Origin Server Ts", "type": "integer" }, "sender": { "title": "Sender", "type": "string" }, "wake_class": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Wake Class" } }, "required": [ "event_id", "sender", "origin_server_ts", "kind" ], "title": "AgentHomeRoomLogEntry", "type": "object" }, "AgentHomeRoomLogResponse": { "properties": { "entries": { "items": { "$ref": "#/components/schemas/AgentHomeRoomLogEntry" }, "title": "Entries", "type": "array" }, "unavailable_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Unavailable Reason" } }, "title": "AgentHomeRoomLogResponse", "type": "object" }, "AgentLedgerAnchorResolveResponse": { "description": "D10 anchor re-location outcome (content-hash first, nearest-ancestor\nfallback). An unresolvable anchor is a VALID EMPTY, not an error.", "properties": { "anchor": { "additionalProperties": true, "title": "Anchor", "type": "object" }, "captured_through": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Captured Through" }, "complete": { "default": true, "title": "Complete", "type": "boolean" }, "resolved": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "description": "{resolved_by: content_hash|nearest_ancestor, operation_id, event_id, occurred_at, file_path, content_hash, kind} or null.", "title": "Resolved" }, "stale_sources": { "items": { "type": "string" }, "title": "Stale Sources", "type": "array" }, "status": { "default": "ok", "title": "Status", "type": "string" } }, "required": [ "anchor" ], "title": "AgentLedgerAnchorResolveResponse", "type": "object" }, "AgentLedgerEventIn": { "additionalProperties": true, "description": "One captured operation — the canonical correlation envelope plus its\npayload. See docs/plans/evidence-architecture/article.md §2.", "properties": { "actor": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "{type,id}.", "title": "Actor" }, "actor_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Actor Id" }, "agent": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Agent" }, "agent_run_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "recipe-engine agent_runs.id (distinct from run_id).", "title": "Agent Run Id" }, "causation": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "{parent_operation_id?, cause?}.", "title": "Causation" }, "effects": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "description": "mutation ops only: [{primitive_type, primitive_id, mutation_ref}] references.", "title": "Effects" }, "emitted_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Forwarder send time.", "title": "Emitted At" }, "envelope_version": { "default": 1, "title": "Envelope Version", "type": "integer" }, "event_id": { "description": "Stable transport id (UUID).", "title": "Event Id", "type": "string" }, "fault_keys": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Fault Keys" }, "harness_runtime": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Harness Runtime" }, "host": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Host" }, "kind": { "description": "S10 vocabulary + F0 additive kinds.", "title": "Kind", "type": "string" }, "machine_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Machine Id" }, "occurred_at": { "description": "ISO 8601 UTC ms Z (event time).", "title": "Occurred At", "type": "string" }, "operation_id": { "description": "ULID grouping start/end events.", "title": "Operation Id", "type": "string" }, "payload": { "additionalProperties": true, "title": "Payload", "type": "object" }, "principal_member_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Principal Member Id" }, "run_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "17502 wake/harness-run id.", "title": "Run Id" }, "schema_version": { "default": 1, "title": "Schema Version", "type": "integer" }, "seq": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Per-run monotonic ordinal.", "title": "Seq" }, "session_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "agent_sessions.id ref.", "title": "Session Id" }, "session_ref": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Harness-native ref (TurnTelemetryV1.session_ref).", "title": "Session Ref" }, "span_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Span Id" }, "task_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Task Id" }, "trace_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Trace Id" }, "turn_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Deterministic turn:{session_ref}:{ordinal}; derived.", "title": "Turn Id" }, "turn_ordinal": { "anyOf": [ { "minimum": 1.0, "type": "integer" }, { "type": "null" } ], "title": "Turn Ordinal" }, "ve_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Ve Id" }, "work_item_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Work Item Id" }, "work_item_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Work Item Type" } }, "required": [ "event_id", "kind", "occurred_at", "operation_id" ], "title": "AgentLedgerEventIn", "type": "object" }, "AgentLedgerForkRequest": { "properties": { "cause": { "anyOf": [ { "maxLength": 200, "type": "string" }, { "type": "null" } ], "title": "Cause" }, "fork_session_ref": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional harness-native ref for the new lineage.", "title": "Fork Session Ref" }, "source_operation_id": { "description": "ULID of the chosen operation the lineage forks at.", "title": "Source Operation Id", "type": "string" }, "source_session_id": { "description": "Conversation stream to fork from.", "title": "Source Session Id", "type": "string" } }, "required": [ "source_session_id", "source_operation_id" ], "title": "AgentLedgerForkRequest", "type": "object" }, "AgentLedgerForkResponse": { "properties": { "captured_through": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Captured Through" }, "complete": { "default": true, "title": "Complete", "type": "boolean" }, "fork": { "additionalProperties": true, "description": "{session_id, operation_id, event_id, accepted}.", "title": "Fork", "type": "object" }, "parent": { "additionalProperties": true, "description": "{session_id, operation_id, occurred_at, kind}.", "title": "Parent", "type": "object" }, "stale_sources": { "items": { "type": "string" }, "title": "Stale Sources", "type": "array" }, "status": { "default": "ok", "title": "Status", "type": "string" } }, "required": [ "fork", "parent" ], "title": "AgentLedgerForkResponse", "type": "object" }, "AgentLedgerHotspotsResponse": { "description": "F3-S3 deterministic hotspot analysis — D6 envelope + versioned numbers.\n\n``analysis`` carries ``analysis_version`` (which algorithm produced these\nnumbers) and ``truncated``; ``complete:false`` means the analysis window\nmay be missing operations — consumers must render that WITH the counts.", "properties": { "analysis": { "additionalProperties": true, "description": "Versioned deterministic analysis (analysis_version ledger-hotspots-v1): churn, timing, failures, structure.", "title": "Analysis", "type": "object" }, "captured_through": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Captured Through" }, "complete": { "default": true, "description": "False ⇒ partial capture in scope: the numbers may be missing operations; see stale_sources and captured_through.", "title": "Complete", "type": "boolean" }, "session_id": { "title": "Session Id", "type": "string" }, "stale_sources": { "items": { "type": "string" }, "title": "Stale Sources", "type": "array" }, "status": { "default": "ok", "title": "Status", "type": "string" } }, "required": [ "session_id", "analysis" ], "title": "AgentLedgerHotspotsResponse", "type": "object" }, "AgentLedgerIngestRequest": { "properties": { "events": { "description": "Batched capture buffer.", "items": { "$ref": "#/components/schemas/AgentLedgerEventIn" }, "maxItems": 500, "minItems": 1, "title": "Events", "type": "array" } }, "required": [ "events" ], "title": "AgentLedgerIngestRequest", "type": "object" }, "AgentLedgerIngestResponse": { "properties": { "accepted": { "title": "Accepted", "type": "integer" }, "duplicates": { "title": "Duplicates", "type": "integer" }, "status": { "default": "ok", "title": "Status", "type": "string" } }, "required": [ "accepted", "duplicates" ], "title": "AgentLedgerIngestResponse", "type": "object" }, "AgentLedgerIntegrityResponse": { "properties": { "broken_at": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "title": "Broken At" }, "captured_through": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Captured Through" }, "complete": { "default": true, "title": "Complete", "type": "boolean" }, "entries_checked": { "title": "Entries Checked", "type": "integer" }, "status": { "default": "ok", "title": "Status", "type": "string" }, "verified": { "title": "Verified", "type": "boolean" } }, "required": [ "verified", "entries_checked" ], "title": "AgentLedgerIntegrityResponse", "type": "object" }, "AgentLedgerQueryResponse": { "description": "D6 outcome envelope — HTTP 200 with silent empties is forbidden.", "properties": { "captured_through": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Ingestion watermark for the queried scope.", "title": "Captured Through" }, "complete": { "default": true, "description": "False ⇒ partial window: a capture-gap marker exists in scope; see stale_sources and captured_through.", "title": "Complete", "type": "boolean" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Keyset cursor on (occurred_at, event_id); never OFFSET.", "title": "Next Cursor" }, "rows": { "items": { "additionalProperties": true, "type": "object" }, "title": "Rows", "type": "array" }, "stale_sources": { "description": "Sources with capture-gap markers in scope — absence without liveness is UNKNOWN, never healthy.", "items": { "type": "string" }, "title": "Stale Sources", "type": "array" }, "status": { "default": "ok", "title": "Status", "type": "string" } }, "required": [ "rows" ], "title": "AgentLedgerQueryResponse", "type": "object" }, "AgentLedgerTimelineResponse": { "description": "F3-S1 rewind/fast-forward window — D6 envelope + scrubber position.", "properties": { "captured_through": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Captured Through" }, "complete": { "default": true, "description": "False ⇒ partial capture for the conversation stream; see stale_sources and captured_through.", "title": "Complete", "type": "boolean" }, "direction": { "description": "rewind | fast_forward | head", "title": "Direction", "type": "string" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Next Cursor" }, "position": { "additionalProperties": true, "description": "{operation_id, occurred_at, resolved_from}.", "title": "Position", "type": "object" }, "rows": { "items": { "additionalProperties": true, "type": "object" }, "title": "Rows", "type": "array" }, "session_id": { "title": "Session Id", "type": "string" }, "stale_sources": { "items": { "type": "string" }, "title": "Stale Sources", "type": "array" }, "status": { "default": "ok", "title": "Status", "type": "string" } }, "required": [ "session_id", "direction", "position", "rows" ], "title": "AgentLedgerTimelineResponse", "type": "object" }, "AgentLifecycleDirective": { "description": "TIDY-16360 — reconfigure this host's lifecycle definition and restart it.\n\nCarried by the heartbeat response beside ``update`` and absent whenever\nthere is nothing to do, which is the overwhelmingly common answer. It names\na UNIT PROPERTY, which is why it cannot ride the per-session ``runtime_mode``\nchannel: honouring it means re-rendering the systemd unit and restarting the\nservice, not changing how the next turn is run.", "properties": { "directive_id": { "format": "uuid", "title": "Directive Id", "type": "string" }, "elevated_privileges": { "title": "Elevated Privileges", "type": "boolean" } }, "required": [ "directive_id", "elevated_privileges" ], "title": "AgentLifecycleDirective", "type": "object" }, "AgentLifecyclePhaseReport": { "description": "TIDY-16360 — one phase of a lifecycle reconfigure, reported on heartbeat.\n\nOnly two phases exist, and neither is success. ``accepted`` means the host\nhas spawned the reconfigure and is about to restart itself; ``failed`` means\nit could not. There is deliberately no ``applied``: the process that would\nreport it is the one being replaced, so it could only ever be a guess.\nSuccess is OBSERVED instead — the boot that comes back reports its own\nprivilege state and the server sees convergence.", "properties": { "detail": { "anyOf": [ { "maxLength": 500, "type": "string" }, { "type": "null" } ], "title": "Detail" }, "directive_id": { "format": "uuid", "title": "Directive Id", "type": "string" }, "phase": { "enum": [ "accepted", "failed" ], "title": "Phase", "type": "string" } }, "required": [ "directive_id", "phase" ], "title": "AgentLifecyclePhaseReport", "type": "object" }, "AgentLifecycleRequest": { "properties": { "reason": { "anyOf": [ { "maxLength": 500, "type": "string" }, { "type": "null" } ], "title": "Reason" } }, "title": "AgentLifecycleRequest", "type": "object" }, "AgentLifecycleResponse": { "properties": { "agent": { "anyOf": [ { "$ref": "#/components/schemas/AgentMemberPayload" }, { "type": "null" } ], "default": null }, "removed": { "default": false, "title": "Removed", "type": "boolean" } }, "title": "AgentLifecycleResponse", "type": "object" }, "AgentMemberPayload": { "properties": { "account_id": { "title": "Account Id", "type": "string" }, "autonomy_ceiling": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Autonomy Ceiling" }, "display_name": { "title": "Display Name", "type": "string" }, "elevated_privileges": { "default": false, "title": "Elevated Privileges", "type": "boolean" }, "elevated_privileges_applied": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "title": "Elevated Privileges Applied" }, "elevation_failure_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Elevation Failure Reason" }, "elevation_state": { "default": "idle", "enum": [ "idle", "pending", "applying", "failed" ], "title": "Elevation State", "type": "string" }, "execution_posture": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Execution Posture" }, "generation": { "default": 1, "title": "Generation", "type": "integer" }, "git_author_default_email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Git Author Default Email" }, "git_author_default_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Git Author Default Name" }, "git_author_email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Git Author Email" }, "git_author_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Git Author Name" }, "git_model_trailer": { "default": false, "title": "Git Model Trailer", "type": "boolean" }, "harness": { "title": "Harness", "type": "string" }, "host_deprovision": { "anyOf": [ { "$ref": "#/components/schemas/HostDeprovisionState" }, { "type": "null" } ], "default": null }, "last_github_mint_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Last Github Mint At" }, "last_gitlab_mint_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Last Gitlab Mint At" }, "last_heartbeat_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Last Heartbeat At" }, "last_seen_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Last Seen At" }, "lifecycle_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Lifecycle Reason" }, "machine_bound": { "default": true, "title": "Machine Bound", "type": "boolean" }, "matrix_home_room_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Matrix Home Room Id" }, "matrix_home_room_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Matrix Home Room Name" }, "matrix_user_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Matrix User Id" }, "mcp_endpoint": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Mcp Endpoint" }, "member_status": { "enum": [ "active", "suspended", "revoked" ], "title": "Member Status", "type": "string" }, "member_type": { "const": "virtual_employee", "title": "Member Type", "type": "string" }, "membership_id": { "title": "Membership Id", "type": "string" }, "mention_handle": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Mention Handle" }, "owner_account_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Owner Account Id" }, "person_id": { "title": "Person Id", "type": "string" }, "portable_target": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "title": "Portable Target" }, "refused_plugin": { "anyOf": [ { "$ref": "#/components/schemas/RefusedModelPlugin" }, { "type": "null" } ], "default": null }, "removed_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Removed At" }, "revoked_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Revoked At" }, "runtime_host": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Runtime Host" }, "runtime_kind": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Runtime Kind" }, "runtime_pid": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Runtime Pid" }, "sandbox_level": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Sandbox Level" }, "slug": { "title": "Slug", "type": "string" }, "status": { "enum": [ "provisioned", "claim_pending", "active", "disconnected", "offline", "suspended", "revoked", "removed", "degraded", "needs_reauth" ], "title": "Status", "type": "string" }, "suspended_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Suspended At" }, "tenant_id": { "title": "Tenant Id", "type": "string" } }, "required": [ "tenant_id", "account_id", "person_id", "membership_id", "slug", "display_name", "member_type", "member_status", "status", "harness" ], "title": "AgentMemberPayload", "type": "object" }, "AgentMemoryCeiling": { "description": "TIDY-19932 (F8) — the owner's memory ceiling for an employee on its own\ncomputer (a workshop's daemon gets its employees' on its own beat). `bytes`\nNone is the machine's default.", "properties": { "bytes": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Bytes" } }, "title": "AgentMemoryCeiling", "type": "object" }, "AgentMemoryEnforcement": { "description": "TIDY-19932 (F8, AC6) — whether an employee on its owner's own computer is\nheld to its memory ceiling, as its connector says on every beat. `reason`\nis the sentence its Autonomy field shows when it is not (\"Memory ceilings\nare not enforced on macOS.\").", "properties": { "reason": { "anyOf": [ { "maxLength": 300, "type": "string" }, { "type": "null" } ], "title": "Reason" }, "status": { "enum": [ "enforced", "unenforced" ], "title": "Status", "type": "string" } }, "required": [ "status" ], "title": "AgentMemoryEnforcement", "type": "object" }, "AgentMemoryEnrichRequest": { "description": "An agent asserts a durable fact derived from data it is authorized to see.\n\nThe fact joins the PRINCIPAL's substrate (owned by the principal, never the\nagent) through ``guard_substrate_write`` + ``assert_substrate_owner``. The\nwritten visibility may NOT exceed the ``source_visibility`` floor\n(read-private-write-shared is forbidden).\n\n``room_id`` + ``sender`` describe the TURN (TIDY-17352 / D21) and are what\nlet one employee serve several people: the sender is the principal the fact\nbelongs to, the room is the audience it may reach. Both are optional and both\nare VALIDATED server-side — the room decides the audience, and a sender who\nis not in that room is ignored rather than trusted. A request that names\nneither behaves exactly as it did before this story.", "properties": { "fact_text": { "maxLength": 8000, "minLength": 1, "title": "Fact Text", "type": "string" }, "principal_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Principal Id" }, "room_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Matrix room id of the turn — decides the fact's audience.", "title": "Room Id" }, "sender": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Matrix user id of the human whose turn this is. Resolved to the acting principal when they are a member of room_id.", "title": "Sender" }, "source_visibility": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Visibility floor of the source the fact was derived from. Omit to take the turn room's own visibility.", "title": "Source Visibility" }, "target_entity_id": { "description": "Entity the fact is about.", "title": "Target Entity Id", "type": "string" }, "target_visibility": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Desired visibility of the written fact (≤ source floor, and ≤ the turn room's visibility). Omit to write at the room's floor.", "title": "Target Visibility" } }, "required": [ "fact_text", "target_entity_id" ], "title": "AgentMemoryEnrichRequest", "type": "object" }, "AgentMemoryEnrichResponse": { "properties": { "id": { "title": "Id", "type": "string" }, "link_source": { "title": "Link Source", "type": "string" }, "owner_id": { "title": "Owner Id", "type": "string" }, "scope_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Scope Id" }, "scope_type": { "default": "principal", "title": "Scope Type", "type": "string" }, "stored": { "title": "Stored", "type": "boolean" }, "superseded_fact_text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Superseded Fact Text" }, "supersedes_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Supersedes Id" }, "visibility": { "default": "private", "title": "Visibility", "type": "string" } }, "required": [ "id", "owner_id", "link_source", "stored" ], "title": "AgentMemoryEnrichResponse", "type": "object" }, "AgentMemoryHit": { "description": "One remembered item. ``label`` (``kind:id``) is what a correction cites.", "properties": { "id": { "title": "Id", "type": "string" }, "kind": { "title": "Kind", "type": "string" }, "label": { "title": "Label", "type": "string" }, "level": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Level" }, "source_message_ids": { "items": { "type": "string" }, "title": "Source Message Ids", "type": "array" }, "text": { "title": "Text", "type": "string" }, "updated_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Updated At" } }, "required": [ "kind", "id", "label", "text" ], "title": "AgentMemoryHit", "type": "object" }, "AgentMemoryObservationsResponse": { "description": "The agent's own private episodic observations, newest first.", "properties": { "observations": { "items": { "$ref": "#/components/schemas/AgentMemoryHit" }, "title": "Observations", "type": "array" } }, "title": "AgentMemoryObservationsResponse", "type": "object" }, "AgentMemoryObserveRequest": { "description": "An agent records one of its own direct observations (episodic memory).\n\nEpisodic memory is PRIVATE to the acting agent — it never reaches the\nprincipal's substrate nor any other agent. The owner is the authenticated\nagent member; the observation text is stored as a private ``notes`` row\n(``note_kind='agent_episodic'``) through ``guard_episodic_write``.", "properties": { "container_ref": { "anyOf": [ { "maxLength": 64, "type": "string" }, { "type": "null" } ], "title": "Container Ref" }, "observation": { "maxLength": 8000, "minLength": 1, "title": "Observation", "type": "string" }, "source_message_ids": { "items": { "type": "string" }, "maxItems": 50, "title": "Source Message Ids", "type": "array" } }, "required": [ "observation" ], "title": "AgentMemoryObserveRequest", "type": "object" }, "AgentMemoryObserveResponse": { "properties": { "id": { "title": "Id", "type": "string" }, "note_kind": { "title": "Note Kind", "type": "string" }, "owner_id": { "title": "Owner Id", "type": "string" }, "stored": { "title": "Stored", "type": "boolean" }, "visibility": { "title": "Visibility", "type": "string" } }, "required": [ "id", "owner_id", "visibility", "note_kind", "stored" ], "title": "AgentMemoryObserveResponse", "type": "object" }, "AgentMemoryRecallRequest": { "properties": { "in_reply_to_sender": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Matrix user id of the sender of the message this turn replies to.", "title": "In Reply To Sender" }, "mentions": { "description": "Matrix user ids named in m.mentions for this message.", "items": { "type": "string" }, "title": "Mentions", "type": "array" }, "principal_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Principal Id" }, "principal_ids": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Principal Ids" }, "query": { "maxLength": 4000, "minLength": 1, "title": "Query", "type": "string" }, "recall_mode": { "default": "push", "enum": [ "push", "pull" ], "title": "Recall Mode", "type": "string" }, "room_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Matrix room id of the turn — drives DM-vs-group classification.", "title": "Room Id" }, "runtime": { "anyOf": [ { "enum": [ "hermes", "openclaw", "pi" ], "type": "string" }, { "type": "null" } ], "title": "Runtime" }, "sender": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Matrix user id of the human whose turn this is.", "title": "Sender" } }, "required": [ "query" ], "title": "AgentMemoryRecallRequest", "type": "object" }, "AgentMemoryRecallResponse": { "properties": { "context": { "default": "", "title": "Context", "type": "string" }, "grant_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Grant Id" }, "injected": { "title": "Injected", "type": "boolean" }, "principal_account_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Principal Account Id" }, "reason": { "title": "Reason", "type": "string" }, "runtime": { "anyOf": [ { "enum": [ "hermes", "openclaw", "pi" ], "type": "string" }, { "type": "null" } ], "default": null, "title": "Runtime" }, "source_ids": { "items": { "additionalProperties": true, "type": "object" }, "title": "Source Ids", "type": "array" } }, "required": [ "injected", "reason" ], "title": "AgentMemoryRecallResponse", "type": "object" }, "AgentMemorySearchRequest": { "description": "A virtual employee searches its own memory (TIDY-19329).\n\nTwo stores answer, each under its own owner: the agent's PRIVATE episodic\nobservations (always — they are the agent's own), and the principal's\nshared memory, read under that ONE principal's predicate and only while an\nactive ``notes`` delegation grant covers it. ``principal_id`` / ``room_id``\n/ ``sender`` resolve the principal exactly as recall and enrich do.", "properties": { "limit": { "default": 10, "maximum": 50.0, "minimum": 1.0, "title": "Limit", "type": "integer" }, "principal_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Principal Id" }, "query": { "maxLength": 4000, "minLength": 1, "title": "Query", "type": "string" }, "room_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Room Id" }, "sender": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Sender" } }, "required": [ "query" ], "title": "AgentMemorySearchRequest", "type": "object" }, "AgentMemorySearchResponse": { "properties": { "facts": { "items": { "$ref": "#/components/schemas/AgentMemoryHit" }, "title": "Facts", "type": "array" }, "observations": { "items": { "$ref": "#/components/schemas/AgentMemoryHit" }, "title": "Observations", "type": "array" }, "principal_account_id": { "title": "Principal Account Id", "type": "string" }, "substrate_reason": { "title": "Substrate Reason", "type": "string" } }, "required": [ "principal_account_id", "substrate_reason" ], "title": "AgentMemorySearchResponse", "type": "object" }, "AgentMountShare": { "description": "TIDYMAIN-ACTIVITY-40 — one live per-VE share of a workshop mount.\n\nThe box provisions the turn's sandbox from it at turn start: the mount\npoint is denied to the turn (any live share denies the mount, D3) and the\nshare's prefix is carved back at its role — read-only for `read`,\nwritable for `read_write` — so the VE's own tools open the shared folder\nwith no manual ACL and a read-only VE cannot write.", "properties": { "mount_id": { "description": "The box's stable id for the mount.", "title": "Mount Id", "type": "string" }, "mount_point": { "description": "The mount point on the box, as reported.", "title": "Mount Point", "type": "string" }, "path": { "description": "The canonical absolute prefix the grant reaches, inside the mount.", "title": "Path", "type": "string" }, "role": { "description": "The granted role: `read` is a scoped read, `read_write` a scoped read + write.", "enum": [ "read", "read_write" ], "title": "Role", "type": "string" } }, "required": [ "mount_id", "mount_point", "path", "role" ], "title": "AgentMountShare", "type": "object" }, "AgentOutOfMemoryExit": { "description": "Why an employee's previous process ended, in the kernel's words (TIDY-19932).", "properties": { "at": { "format": "date-time", "title": "At", "type": "string" }, "limit_bytes": { "minimum": 0.0, "title": "Limit Bytes", "type": "integer" }, "reason": { "const": "out_of_memory", "title": "Reason", "type": "string" }, "scope": { "enum": [ "employee", "workshop" ], "title": "Scope", "type": "string" } }, "required": [ "reason", "scope", "limit_bytes", "at" ], "title": "AgentOutOfMemoryExit", "type": "object" }, "AgentPluginAction": { "description": "A curated action the plugin ships (TIDY-19604 F8): a rule step that\ncalls it through the plugin's own connection — no URL, no secret.", "properties": { "description": { "title": "Description", "type": "string" }, "id": { "title": "Id", "type": "string" }, "inputs": { "items": { "$ref": "#/components/schemas/AgentPluginActionInput" }, "title": "Inputs", "type": "array" }, "label": { "title": "Label", "type": "string" }, "results": { "items": { "type": "string" }, "title": "Results", "type": "array" }, "step": { "$ref": "#/components/schemas/AgentPluginActionStep" } }, "required": [ "id", "label", "description", "inputs", "results", "step" ], "title": "AgentPluginAction", "type": "object" }, "AgentPluginActionInput": { "properties": { "key": { "title": "Key", "type": "string" }, "label": { "title": "Label", "type": "string" }, "placeholder": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Placeholder" }, "required": { "title": "Required", "type": "boolean" }, "type": { "title": "Type", "type": "string" } }, "required": [ "key", "label", "type", "required" ], "title": "AgentPluginActionInput", "type": "object" }, "AgentPluginActionStep": { "description": "The rule action that runs a curated action: ``call_endpoint`` with the\nplugin, the action and its inputs (each input's label where its value goes).", "properties": { "params": { "additionalProperties": true, "title": "Plugin Action Step Params", "type": "object" }, "verb": { "title": "Verb", "type": "string" } }, "required": [ "verb", "params" ], "title": "AgentPluginActionStep", "type": "object" }, "AgentPluginApiSetup": { "description": "Where the plugin's API lives and how a request is authorised.", "properties": { "api_flavor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Api Flavor" }, "auth_scheme": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Auth Scheme" }, "base_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Base Url" }, "scheme_config": { "additionalProperties": { "type": "string" }, "title": "Scheme Config", "type": "object" } }, "required": [ "scheme_config" ], "title": "AgentPluginApiSetup", "type": "object" }, "AgentPluginDelivery": { "description": "Where this plugin's shipment stands for the calling employee.\n\n``acknowledged_at`` is the WORKSHOP's receipt for the shipment\n(``acknowledgement_scope``): proof the box took it, never that this\ncredential, harness or turn holds a value. ``last_attempt`` is the latest\ndelivery attempt, reported beside that history — a later failed retry does\nnot erase an earlier receipt. Never a value, an error text or a token.", "properties": { "acknowledged_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Acknowledged At" }, "acknowledgement_scope": { "const": "workshop", "default": "workshop", "title": "Acknowledgement Scope", "type": "string" }, "last_attempt": { "anyOf": [ { "$ref": "#/components/schemas/AgentPluginDeliveryAttempt" }, { "type": "null" } ], "default": null }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Reason" }, "recovery": { "anyOf": [ { "$ref": "#/components/schemas/AgentPluginRecovery" }, { "type": "null" } ], "default": null }, "shipment_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Shipment Id" }, "state": { "enum": [ "acknowledged", "held", "pending_ack", "failed", "refused", "cancelled", "unconfirmed", "installation_unavailable", "connector_update_required", "other_workshop", "not_shipped", "ambiguous", "target_unverified" ], "title": "State", "type": "string" }, "target": { "enum": [ "caller_installation", "employee_placement", "none" ], "title": "Target", "type": "string" }, "workshop_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Workshop Id" } }, "required": [ "target", "state" ], "title": "AgentPluginDelivery", "type": "object" }, "AgentPluginDeliveryAttempt": { "description": "The latest delivery attempt (a ``keys.ship`` job) for the shipment.", "properties": { "at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "At" }, "job_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Job Id" }, "refusal_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Refusal Code" }, "state": { "title": "State", "type": "string" } }, "required": [ "state" ], "title": "AgentPluginDeliveryAttempt", "type": "object" }, "AgentPluginEnvSetup": { "description": "The env NAMES a shipped connection reaches the employee's turns under\n(TIDY-19802 F2): its secret, and its API's address when it has one.", "properties": { "base_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Base Url" }, "token": { "title": "Token", "type": "string" } }, "required": [ "token" ], "title": "AgentPluginEnvSetup", "type": "object" }, "AgentPluginEvent": { "description": "An event the plugin receives (TIDY-19604 F9/F10/F13): what a rule can\nbe triggered by, with the fields it carries.", "properties": { "fields": { "items": { "$ref": "#/components/schemas/AgentPluginEventField" }, "title": "Fields", "type": "array" }, "key": { "title": "Key", "type": "string" }, "label": { "title": "Label", "type": "string" }, "trigger": { "$ref": "#/components/schemas/AgentPluginEventTrigger" } }, "required": [ "key", "label", "fields", "trigger" ], "title": "AgentPluginEvent", "type": "object" }, "AgentPluginEventField": { "description": "One field of an event: a rule reads it as ``event.``.", "properties": { "max_size": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Max Size" }, "name": { "title": "Name", "type": "string" }, "required": { "title": "Required", "type": "boolean" }, "type": { "title": "Type", "type": "string" } }, "required": [ "name", "type", "required" ], "title": "AgentPluginEventField", "type": "object" }, "AgentPluginEventTrigger": { "description": "The rule trigger that fires on the event — ``plugin_event`` with the\nplugin and the event's key.", "properties": { "event": { "title": "Event", "type": "string" }, "kind": { "title": "Kind", "type": "string" }, "plugin_id": { "title": "Plugin Id", "type": "string" } }, "required": [ "kind", "plugin_id", "event" ], "title": "AgentPluginEventTrigger", "type": "object" }, "AgentPluginLend": { "description": "One live lend the calling employee holds on a plugin.", "properties": { "capability_scope": { "items": { "type": "string" }, "title": "Capability Scope", "type": "array" }, "conversation_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Conversation Id" }, "expires_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Expires At" }, "grant_id": { "title": "Grant Id", "type": "string" }, "scope": { "enum": [ "once", "session", "standing" ], "title": "Scope", "type": "string" } }, "required": [ "grant_id", "scope", "capability_scope" ], "title": "AgentPluginLend", "type": "object" }, "AgentPluginManifest": { "description": "Everything an employee needs to set a lent plugin up — never a secret.", "properties": { "actions": { "default": [], "items": { "$ref": "#/components/schemas/AgentPluginAction" }, "title": "Actions", "type": "array" }, "beyond_actions": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Beyond Actions" }, "category": { "title": "Category", "type": "string" }, "category_label": { "title": "Category Label", "type": "string" }, "connection_method": { "title": "Connection Method", "type": "string" }, "delivery": { "anyOf": [ { "$ref": "#/components/schemas/AgentPluginDelivery" }, { "type": "null" } ], "default": null }, "delivery_kind": { "anyOf": [ { "enum": [ "scoped_token", "env_key", "stdio_config", "env_binding" ], "type": "string" }, { "type": "null" } ], "default": null, "title": "Delivery Kind" }, "events": { "default": [], "items": { "$ref": "#/components/schemas/AgentPluginEvent" }, "title": "Events", "type": "array" }, "id": { "title": "Id", "type": "string" }, "kind": { "title": "Kind", "type": "string" }, "label": { "title": "Label", "type": "string" }, "lends": { "items": { "$ref": "#/components/schemas/AgentPluginLend" }, "title": "Lends", "type": "array" }, "next_step": { "title": "Next Step", "type": "string" }, "provider_name": { "title": "Provider Name", "type": "string" }, "setup": { "$ref": "#/components/schemas/AgentPluginSetup" }, "shipped_to_you": { "title": "Shipped To You", "type": "boolean" }, "status": { "title": "Status", "type": "string" }, "through_tidy": { "title": "Through Tidy", "type": "boolean" }, "token_route": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Token Route" }, "typed_id": { "title": "Typed Id", "type": "string" } }, "required": [ "id", "typed_id", "kind", "label", "category", "category_label", "provider_name", "connection_method", "status", "lends", "setup", "shipped_to_you", "through_tidy", "next_step" ], "title": "AgentPluginManifest", "type": "object" }, "AgentPluginMcpSetup": { "description": "How to run or reach the plugin's MCP server. ``env_refs`` maps an env\nname to a ``${TIDY_MCP_*}`` reference, never to a value.", "properties": { "args": { "items": { "type": "string" }, "title": "Args", "type": "array" }, "auth_method": { "title": "Auth Method", "type": "string" }, "command": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Command" }, "cwd": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Cwd" }, "env_refs": { "additionalProperties": { "type": "string" }, "title": "Env Refs", "type": "object" }, "transport": { "enum": [ "stdio", "http" ], "title": "Transport", "type": "string" }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Url" } }, "required": [ "transport", "args", "env_refs", "auth_method" ], "title": "AgentPluginMcpSetup", "type": "object" }, "AgentPluginRecovery": { "description": "The existing gesture that moves this delivery on, and whose it is.", "properties": { "action": { "enum": [ "lend", "ship", "ship_again", "approve", "update_connector" ], "title": "Action", "type": "string" }, "actor": { "enum": [ "plugin_owner", "workshop_approver" ], "title": "Actor", "type": "string" } }, "required": [ "action", "actor" ], "title": "AgentPluginRecovery", "type": "object" }, "AgentPluginSetup": { "properties": { "api": { "anyOf": [ { "$ref": "#/components/schemas/AgentPluginApiSetup" }, { "type": "null" } ], "default": null }, "credential_stored": { "title": "Credential Stored", "type": "boolean" }, "env": { "anyOf": [ { "$ref": "#/components/schemas/AgentPluginEnvSetup" }, { "type": "null" } ], "default": null }, "env_key": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Env Key" }, "mcp": { "anyOf": [ { "$ref": "#/components/schemas/AgentPluginMcpSetup" }, { "type": "null" } ], "default": null } }, "required": [ "credential_stored" ], "title": "AgentPluginSetup", "type": "object" }, "AgentPluginsResponse": { "properties": { "plugins": { "items": { "$ref": "#/components/schemas/AgentPluginManifest" }, "title": "Plugins", "type": "array" } }, "required": [ "plugins" ], "title": "AgentPluginsResponse", "type": "object" }, "AgentProjectRootEnsureRequest": { "properties": { "project_id": { "description": "The project to mint a workspace root for.", "title": "Project Id", "type": "string" } }, "required": [ "project_id" ], "title": "AgentProjectRootEnsureRequest", "type": "object" }, "AgentProjectRootEnsureResponse": { "description": "The ensured row plus everything the VE host needs to act on it.", "properties": { "agent_account_id": { "title": "Agent Account Id", "type": "string" }, "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "id": { "title": "Id", "type": "string" }, "last_error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Last Error" }, "project_id": { "title": "Project Id", "type": "string" }, "project_name": { "title": "Project Name", "type": "string" }, "repo": { "anyOf": [ { "$ref": "#/components/schemas/AgentProjectRootRepo" }, { "type": "null" } ], "default": null, "description": "The linked repo to clone, or null for a repo-less project." }, "repo_cloned": { "title": "Repo Cloned", "type": "boolean" }, "root_path": { "title": "Root Path", "type": "string" }, "setup_job_error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Why no host job could be submitted (e.g. the VE's machine is offline). The row stays pending until a later ensure succeeds.", "title": "Setup Job Error" }, "setup_job_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "The connector job now minting the root on the VE host.", "title": "Setup Job Id" }, "status": { "description": "pending | ready | error | detached", "title": "Status", "type": "string" }, "tenant_id": { "title": "Tenant Id", "type": "string" }, "updated_at": { "format": "date-time", "title": "Updated At", "type": "string" } }, "required": [ "id", "tenant_id", "agent_account_id", "project_id", "root_path", "status", "repo_cloned", "created_at", "updated_at", "project_name" ], "title": "AgentProjectRootEnsureResponse", "type": "object" }, "AgentProjectRootListResponse": { "properties": { "roots": { "items": { "$ref": "#/components/schemas/AgentProjectRootResponse" }, "title": "Roots", "type": "array" } }, "required": [ "roots" ], "title": "AgentProjectRootListResponse", "type": "object" }, "AgentProjectRootRepo": { "description": "The project's repo link, as the VE host needs it for the clone.", "properties": { "clone_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Clone Url" }, "default_branch": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Default Branch" }, "provider": { "title": "Provider", "type": "string" }, "repo_full_name": { "title": "Repo Full Name", "type": "string" } }, "required": [ "provider", "repo_full_name" ], "title": "AgentProjectRootRepo", "type": "object" }, "AgentProjectRootReportRequest": { "properties": { "last_error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Required context when status is 'error'.", "title": "Last Error" }, "repo_cloned": { "default": false, "title": "Repo Cloned", "type": "boolean" }, "status": { "description": "ready | error", "title": "Status", "type": "string" } }, "required": [ "status" ], "title": "AgentProjectRootReportRequest", "type": "object" }, "AgentProjectRootResponse": { "description": "One (VE, project) workspace root row.", "properties": { "agent_account_id": { "title": "Agent Account Id", "type": "string" }, "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "id": { "title": "Id", "type": "string" }, "last_error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Last Error" }, "project_id": { "title": "Project Id", "type": "string" }, "repo_cloned": { "title": "Repo Cloned", "type": "boolean" }, "root_path": { "title": "Root Path", "type": "string" }, "status": { "description": "pending | ready | error | detached", "title": "Status", "type": "string" }, "tenant_id": { "title": "Tenant Id", "type": "string" }, "updated_at": { "format": "date-time", "title": "Updated At", "type": "string" } }, "required": [ "id", "tenant_id", "agent_account_id", "project_id", "root_path", "status", "repo_cloned", "created_at", "updated_at" ], "title": "AgentProjectRootResponse", "type": "object" }, "AgentPromptAnswerRequest": { "properties": { "answer": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The answer to the question.", "title": "Answer" }, "decline_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Why you cannot or will not answer it; declines the question.", "title": "Decline Reason" }, "escalate": { "default": false, "description": "Pass the question on to the person the asking conversation is for: it opens on a card for them, and their answer goes back to the asker. Instead of answer or decline_reason.", "title": "Escalate", "type": "boolean" }, "note": { "anyOf": [ { "maxLength": 2000, "type": "string" }, { "type": "null" } ], "description": "With escalate: a line for the person, shown under the question.", "title": "Note" } }, "title": "AgentPromptAnswerRequest", "type": "object" }, "AgentPromptAnswerResponse": { "properties": { "delivery": { "description": "delivered (it is in the asking conversation) | owed (it will be) | undeliverable (it cannot be: undelivered_reason says why; the asker can still read it) | nothing_owed (a person asked from outside Tidy and reads it back, TIDY-19705 F18)", "title": "Delivery", "type": "string" }, "id": { "title": "Id", "type": "string" }, "status": { "description": "answered | closed (declined) | waiting (escalated: it is with the person now, and their answer is delivered when they give it)", "title": "Status", "type": "string" }, "undelivered_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Undelivered Reason" } }, "required": [ "id", "status", "delivery" ], "title": "AgentPromptAnswerResponse", "type": "object" }, "AgentPromptCreateRequest": { "properties": { "activity_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Bare activity uuid of the task the question is about.", "title": "Activity Id" }, "asked_from": { "anyOf": [ { "maxLength": 200, "type": "string" }, { "type": "null" } ], "description": "TIDY-19705 F18: required when a person asks, from outside Tidy on their own token: where they ask from (the harness, the device, the project), shown on the card and the phone. Refused from an employee.", "title": "Asked From" }, "choices": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "description": "Optional quick answers.", "title": "Choices" }, "context": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "TIDY-19705 F18: when a person asks another person (or themselves), what the Tidy Assistant says above the card: markdown, with links such as [[N-]] to a note holding the detail. Refused from an employee, and for an employee recipient.", "title": "Context" }, "kind": { "description": "'question' (tidy_ask_user). 'approval' is refused here: an approval is asked for one exact call through POST /agents/approvals.", "title": "Kind", "type": "string" }, "prompt_text": { "description": "The question shown on the card.", "minLength": 1, "title": "Prompt Text", "type": "string" }, "recipient_account_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "TIDY-19705 F15: put the question to this member instead of the conversation's person: an account id of an active member the employee may message. Their card opens in their own conversation with the employee; the answer comes back here.", "title": "Recipient Account Id" }, "recipient_employee": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "TIDY-19705 F15: put the question to another virtual employee (name, slug or @handle). It becomes a conversation of its own on that employee, started when it has a free slot; the answer comes back here. At most one recipient.", "title": "Recipient Employee" }, "run_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Correlates the prompt to the dispatched run.", "title": "Run Id" }, "timeout_s": { "default": 120, "description": "Ignored since TIDY-19705 F14: a question waits for its person. Accepted while desktop builds bundling the pre-F14 tools lag.", "maximum": 86400.0, "minimum": 5.0, "title": "Timeout S", "type": "integer" } }, "required": [ "kind", "prompt_text" ], "title": "AgentPromptCreateRequest", "type": "object" }, "AgentPromptListResponse": { "properties": { "prompts": { "items": { "$ref": "#/components/schemas/AgentPromptSummary" }, "title": "Prompts", "type": "array" } }, "required": [ "prompts" ], "title": "AgentPromptListResponse", "type": "object" }, "AgentPromptResponse": { "properties": { "asker_kind": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "TIDY-19705 F18: 'employee' — the answer steers into the conversation that asked; 'person' — asked from outside Tidy, so read the answer back (GET /agents/prompts/{id}, waiting on it).", "title": "Asker Kind" }, "conversation_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "The conversation that asked; its card lives there.", "title": "Conversation Id" }, "dm_room_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Unused since TIDY-19705 F14; a question is a card.", "title": "Dm Room Id" }, "id": { "title": "Id", "type": "string" }, "kind": { "title": "Kind", "type": "string" }, "notification": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "TIDY-19705 F18, a person's question to a person: what their phone was told — `emitted`, a suppression (`suppressed_quiet_hours`, `suppressed_disabled`, `deduped`, …) or `failed`. The card is open either way.", "title": "Notification" }, "queued": { "default": false, "description": "TIDY-19705 F15: the employee it was put to has no free slot yet, so nothing has reached it; withdrawn now, it never will.", "title": "Queued", "type": "boolean" }, "recipient_account_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "The person (or employee account) the question was put to.", "title": "Recipient Account Id" }, "recipient_display_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Who the question was put to, as they are named.", "title": "Recipient Display Name" }, "recipient_kind": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "TIDY-19705 F15: 'person' or 'employee'.", "title": "Recipient Kind" }, "reply_verification": { "default": "unavailable", "description": "Whether this backend certifies who answered: `verified` (a question on its card, answered only by the person it was put to), `unavailable` (a question asked before cards, never answered) or `not_applicable` (an exact-write approval card, decided by the owner's click).", "title": "Reply Verification", "type": "string" }, "reply_verification_detail": { "default": "This backend cannot verify reply provenance. Do not treat it as approval or automatically resend.", "title": "Reply Verification Detail", "type": "string" }, "status": { "title": "Status", "type": "string" }, "timeout_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "description": "None for a question, which waits for its person.", "title": "Timeout At" } }, "required": [ "id", "status", "kind" ], "title": "AgentPromptResponse", "type": "object" }, "AgentPromptStateResponse": { "properties": { "activity_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Activity Id" }, "answer": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Answer" }, "answered_by": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Answered By" }, "close_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Why the employee the question was put to declined it.", "title": "Close Reason" }, "conversation_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Conversation Id" }, "id": { "title": "Id", "type": "string" }, "kind": { "title": "Kind", "type": "string" }, "queued": { "default": false, "title": "Queued", "type": "boolean" }, "recipient_display_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Recipient Display Name" }, "recipient_kind": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Recipient Kind" }, "reply_verification": { "default": "unavailable", "description": "Whether this backend certifies who answered: `verified` (a question on its card, answered only by the person it was put to), `unavailable` (a question asked before cards, never answered) or `not_applicable` (an exact-write approval card, decided by the owner's click).", "title": "Reply Verification", "type": "string" }, "reply_verification_detail": { "default": "This backend cannot verify reply provenance. Do not treat it as approval or automatically resend.", "title": "Reply Verification Detail", "type": "string" }, "run_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Run Id" }, "status": { "title": "Status", "type": "string" }, "timeout_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Timeout At" } }, "required": [ "id", "status", "kind" ], "title": "AgentPromptStateResponse", "type": "object" }, "AgentPromptSummary": { "properties": { "activity_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Activity Id" }, "answer": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Answer" }, "choices": { "items": { "type": "string" }, "title": "Choices", "type": "array" }, "close_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Close Reason" }, "conversation_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Conversation Id" }, "conversation_title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Conversation Title" }, "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "id": { "title": "Id", "type": "string" }, "kind": { "description": "'question' or 'approval'.", "title": "Kind", "type": "string" }, "prompt_text": { "title": "Prompt Text", "type": "string" }, "queued": { "default": false, "description": "Waiting for the employee it was put to to have a free slot.", "title": "Queued", "type": "boolean" }, "recipient_display_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Recipient Display Name" }, "recipient_kind": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "TIDY-19705 F15: 'person' or 'employee'; None for an approval.", "title": "Recipient Kind" }, "resolved_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Resolved At" }, "status": { "description": "waiting | answered | closed (by its person) | withdrawn | timed_out | cancelled", "title": "Status", "type": "string" } }, "required": [ "id", "kind", "status", "prompt_text", "created_at" ], "title": "AgentPromptSummary", "type": "object" }, "AgentProviderReport": { "description": "TIDY-17537 (S7) — one provider sign-in this host reports.\n\nThe native_box_login witness: the connector observes the HARNESS's own\nprovider sign-in state (pi's Grok login, a codex ChatGPT session) and\nreports the FACT. Tidy never touches the token — the sign-in lives on the\nbox and re-auth is the harness's flow. Absent means the connector\npredates provider reporting; the server judges that UNKNOWN, never\nsigned-in.", "properties": { "provider": { "maxLength": 64, "title": "Provider", "type": "string" }, "runtime": { "anyOf": [ { "maxLength": 64, "type": "string" }, { "type": "null" } ], "title": "Runtime" }, "signed_in": { "title": "Signed In", "type": "boolean" } }, "required": [ "provider", "signed_in" ], "title": "AgentProviderReport", "type": "object" }, "AgentProvisionRequest": { "properties": { "current_user_systemd_acknowledged": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Current User Systemd Acknowledged" }, "default_playback_speed": { "default": 1.0, "maximum": 2.0, "minimum": 0.5, "title": "Default Playback Speed", "type": "number" }, "default_voice_id": { "anyOf": [ { "maxLength": 120, "type": "string" }, { "type": "null" } ], "title": "Default Voice Id" }, "display_name": { "maxLength": 160, "minLength": 1, "title": "Display Name", "type": "string" }, "elevated_privileges": { "default": true, "title": "Elevated Privileges", "type": "boolean" }, "github_access": { "default": false, "title": "Github Access", "type": "boolean" }, "harness": { "default": "local_connector", "enum": [ "local_connector", "pi", "claude-code", "codex", "hermes", "opencode", "openclaw", "antigravity" ], "title": "Harness", "type": "string" }, "harness_auth_method": { "anyOf": [ { "enum": [ "existing", "api_key", "bedrock", "vertex", "subscription", "tidy_inference" ], "type": "string" }, { "type": "null" } ], "title": "Harness Auth Method" }, "harness_auth_settings": { "anyOf": [ { "additionalProperties": { "type": "string" }, "type": "object" }, { "type": "null" } ], "title": "Harness Auth Settings" }, "harnesses": { "anyOf": [ { "items": { "enum": [ "pi", "claude-code", "codex", "hermes", "opencode", "openclaw", "antigravity" ], "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Harnesses" }, "host_arch": { "anyOf": [ { "enum": [ "x86_64", "aarch64" ], "type": "string" }, { "type": "null" } ], "title": "Host Arch" }, "host_build": { "anyOf": [ { "minimum": 17763.0, "type": "integer" }, { "type": "null" } ], "title": "Host Build" }, "host_os": { "anyOf": [ { "enum": [ "linux", "macos", "windows" ], "type": "string" }, { "type": "null" } ], "title": "Host Os" }, "host_os_major": { "anyOf": [ { "minimum": 12.0, "type": "integer" }, { "type": "null" } ], "title": "Host Os Major" }, "install_harness_if_missing": { "default": false, "title": "Install Harness If Missing", "type": "boolean" }, "legacy_migration_confirmation_slug": { "anyOf": [ { "maxLength": 120, "type": "string" }, { "type": "null" } ], "title": "Legacy Migration Confirmation Slug" }, "libc": { "anyOf": [ { "enum": [ "glibc", "musl" ], "type": "string" }, { "type": "null" } ], "title": "Libc" }, "libc_min": { "anyOf": [ { "pattern": "^[0-9]+\\.[0-9]+$", "type": "string" }, { "type": "null" } ], "title": "Libc Min" }, "lifecycle": { "anyOf": [ { "enum": [ "systemd-user", "launch-agent", "scheduled-task" ], "type": "string" }, { "type": "null" } ], "title": "Lifecycle" }, "manners_markdown": { "default": "# TIDY MANNERS\n\nYou are connected to Tidy as a virtual employee.\n\nWhen you are in a group chat, you can read the conversation for context, but you should not reply to every message. Speak up when someone addresses you by name, asks you a question, delegates a task to you, replies to your current work, or you need to report meaningful progress, a blocker, or completion. Answer once, in the thread you were reached in. Never reply only to agree, thank or acknowledge, and never repeat what someone else already said.\n\nDo not assume every group message is for you. If the conversation is between other people or other employees, follow along silently. If you are unsure whether you are being asked to act, ask one short clarifying question or wait.\n\nDo not take action on private data or delegated work unless Tidy grants you the needed tool access.\n\n## Work skill-first\n\nBefore starting any multi-step task, list your installed skills and read the one that matches the task: its SKILL.md first, then only the reference file it points you to for this task, not every file. It carries the commands, paths, credentials, and failure remedies you would otherwise rediscover by trial and error. Follow the matching skill's steps instead of probing with ad-hoc terminal commands. Improvise only when no installed skill matches the task.\n\n## Colleagues and your inbox\n\nYou may work alongside other virtual employees. To tell, ask, or update a colleague, call `message_employee` with their name, and pass the item's `item_ref` when the message is about one. On shared work, a comment on the task that @mentions their handle reaches them too. `send_to_assistant` reaches Tidy's built-in assistant, never a colleague, and its reply is not theirs.\n\nMessages colleagues send you and @mentions waiting on you are in your inbox. Check it with `agent_inbox` when you start work, and before you tell anyone whether a message arrived. Answer a comment mention with `comment_reply` in its thread; reply to a colleague with `message_employee`.\n\nTidy also keeps a home room for you, where it posts system alerts. It is not a chat and no one waits in it to talk; every mention and colleague message it alerts you to is also in `agent_inbox`.\n\n## Shared knowledge framing\n\nTidy's memory holds facts from ALL of the user's assistants and from their notes, email, calendar and contacts, and recalls the ones relevant to a message for you under \"Personal Context\". Present a shared fact that did not come from your own conversation with this user as Tidy's record (\"our records show the launch moved to March\"), NEVER as your own history with them (\"as we discussed\", \"you told me\"): that fabricates a history and breaks their trust.\n\n## Recording and correcting memory\n\nWrite to memory only deliberately, never every turn. The tidy-mcp skill says when to correct a fact in the user's shared memory, when to keep a note of your own, and how to check what you remember.", "maxLength": 20000, "title": "Manners Markdown", "type": "string" }, "mention_handle": { "anyOf": [ { "maxLength": 80, "type": "string" }, { "type": "null" } ], "title": "Mention Handle" }, "owner_account_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Owner Account Id" }, "role_title": { "anyOf": [ { "maxLength": 160, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Role Title" }, "skills": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Skills" }, "slug": { "pattern": "^[a-z0-9][a-z0-9-]{1,78}[a-z0-9]$", "title": "Slug", "type": "string" }, "soul_markdown": { "default": "", "maxLength": 20000, "title": "Soul Markdown", "type": "string" }, "working_directory": { "anyOf": [ { "maxLength": 2048, "minLength": 2, "type": "string" }, { "type": "null" } ], "title": "Working Directory" } }, "required": [ "display_name", "slug" ], "title": "AgentProvisionRequest", "type": "object" }, "AgentProvisionResponse": { "properties": { "agent": { "$ref": "#/components/schemas/AgentMemberPayload" }, "employee_settings": { "$ref": "#/components/schemas/EmployeeAgentSettingsPayload" }, "setup": { "$ref": "#/components/schemas/AgentSetupPayload" } }, "required": [ "agent", "setup", "employee_settings" ], "title": "AgentProvisionResponse", "type": "object" }, "AgentReconnectRequest": { "description": "Reconnect body: optionally the portable target for a fresh protected\ninstall command; empty body keeps the legacy behaviour.", "properties": { "current_user_systemd_acknowledged": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Current User Systemd Acknowledged" }, "elevated_privileges": { "default": true, "title": "Elevated Privileges", "type": "boolean" }, "github_access": { "default": false, "title": "Github Access", "type": "boolean" }, "harness": { "anyOf": [ { "enum": [ "pi", "claude-code", "codex", "hermes", "opencode", "openclaw", "antigravity" ], "type": "string" }, { "type": "null" } ], "title": "Harness" }, "harness_auth_method": { "anyOf": [ { "enum": [ "existing", "api_key", "bedrock", "vertex", "subscription", "tidy_inference" ], "type": "string" }, { "type": "null" } ], "title": "Harness Auth Method" }, "harness_auth_settings": { "anyOf": [ { "additionalProperties": { "type": "string" }, "type": "object" }, { "type": "null" } ], "title": "Harness Auth Settings" }, "host_arch": { "anyOf": [ { "enum": [ "x86_64", "aarch64" ], "type": "string" }, { "type": "null" } ], "title": "Host Arch" }, "host_build": { "anyOf": [ { "minimum": 17763.0, "type": "integer" }, { "type": "null" } ], "title": "Host Build" }, "host_os": { "anyOf": [ { "enum": [ "linux", "macos", "windows" ], "type": "string" }, { "type": "null" } ], "title": "Host Os" }, "host_os_major": { "anyOf": [ { "minimum": 12.0, "type": "integer" }, { "type": "null" } ], "title": "Host Os Major" }, "install_harness_if_missing": { "default": false, "title": "Install Harness If Missing", "type": "boolean" }, "legacy_migration_confirmation_slug": { "anyOf": [ { "maxLength": 120, "type": "string" }, { "type": "null" } ], "title": "Legacy Migration Confirmation Slug" }, "libc": { "anyOf": [ { "enum": [ "glibc", "musl" ], "type": "string" }, { "type": "null" } ], "title": "Libc" }, "libc_min": { "anyOf": [ { "pattern": "^[0-9]+\\.[0-9]+$", "type": "string" }, { "type": "null" } ], "title": "Libc Min" }, "lifecycle": { "anyOf": [ { "enum": [ "systemd-user", "launch-agent", "scheduled-task" ], "type": "string" }, { "type": "null" } ], "title": "Lifecycle" }, "reason": { "anyOf": [ { "maxLength": 500, "type": "string" }, { "type": "null" } ], "title": "Reason" }, "working_directory": { "anyOf": [ { "maxLength": 2048, "minLength": 2, "type": "string" }, { "type": "null" } ], "title": "Working Directory" } }, "title": "AgentReconnectRequest", "type": "object" }, "AgentRoomKeySession": { "description": "One backed-up megolm session blob for an agent's own Matrix account.", "properties": { "ciphertext": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Ciphertext" }, "ephemeral": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Ephemeral" }, "first_message_index": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "First Message Index" }, "mac": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Mac" }, "room_id": { "title": "Room Id", "type": "string" }, "session_id": { "title": "Session Id", "type": "string" }, "session_key": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Session Key" } }, "required": [ "room_id", "session_id" ], "title": "AgentRoomKeySession", "type": "object" }, "AgentRoomKeysBootstrapResponse": { "description": "Agent-authenticated Matrix E2EE bootstrap bundle.", "properties": { "account_id": { "title": "Account Id", "type": "string" }, "backup_private_key": { "title": "Backup Private Key", "type": "string" }, "key_backup_version": { "title": "Key Backup Version", "type": "string" }, "matrix_user_id": { "title": "Matrix User Id", "type": "string" }, "sessions": { "items": { "$ref": "#/components/schemas/AgentRoomKeySession" }, "title": "Sessions", "type": "array" } }, "required": [ "account_id", "matrix_user_id", "key_backup_version", "backup_private_key", "sessions" ], "title": "AgentRoomKeysBootstrapResponse", "type": "object" }, "AgentRoomKeysBootstrapV2Request": { "properties": { "boot_id": { "format": "uuid", "title": "Boot Id", "type": "string" }, "generation": { "title": "Generation", "type": "integer" }, "include_platform_bot_identity": { "default": false, "title": "Include Platform Bot Identity", "type": "boolean" }, "installation_id": { "format": "uuid", "title": "Installation Id", "type": "string" }, "known_backup_version": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Known Backup Version" }, "matrix_device_id": { "title": "Matrix Device Id", "type": "string" } }, "required": [ "installation_id", "boot_id", "generation", "matrix_device_id" ], "title": "AgentRoomKeysBootstrapV2Request", "type": "object" }, "AgentRoomKeysBootstrapV2Response": { "properties": { "agent_account_id": { "title": "Agent Account Id", "type": "string" }, "backup_version": { "title": "Backup Version", "type": "string" }, "matrix_device_id": { "title": "Matrix Device Id", "type": "string" }, "matrix_user_id": { "title": "Matrix User Id", "type": "string" }, "platform_bot_matrix_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Platform Bot Matrix Id" }, "recovery_key_b64": { "title": "Recovery Key B64", "type": "string" }, "room_keys": { "items": { "$ref": "#/components/schemas/AgentRoomKeySession" }, "title": "Room Keys", "type": "array" } }, "required": [ "agent_account_id", "matrix_user_id", "matrix_device_id", "backup_version", "recovery_key_b64", "room_keys" ], "title": "AgentRoomKeysBootstrapV2Response", "type": "object" }, "AgentRunItem": { "properties": { "agent_name": { "title": "Agent Name", "type": "string" }, "error_count": { "default": 0, "title": "Error Count", "type": "integer" }, "finished_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Finished At" }, "id": { "title": "Id", "type": "string" }, "last_error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Last Error" }, "started_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Started At" }, "status": { "title": "Status", "type": "string" }, "write_count": { "default": 0, "title": "Write Count", "type": "integer" } }, "required": [ "id", "agent_name", "status" ], "title": "AgentRunItem", "type": "object" }, "AgentRunListResponse": { "properties": { "runs": { "items": { "$ref": "#/components/schemas/AgentRunItem" }, "title": "Runs", "type": "array" } }, "required": [ "runs" ], "title": "AgentRunListResponse", "type": "object" }, "AgentRuntimeApiContractResponse": { "properties": { "contracts": { "items": { "type": "string" }, "title": "Contracts", "type": "array" }, "nonce": { "title": "Nonce", "type": "string" } }, "required": [ "nonce", "contracts" ], "title": "AgentRuntimeApiContractResponse", "type": "object" }, "AgentRuntimeLiveness": { "description": "Heartbeat-staleness view of a virtual employee's runtime (D5).", "properties": { "account_id": { "title": "Account Id", "type": "string" }, "artifact_digest": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Artifact Digest" }, "artifact_version": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Artifact Version" }, "autonomy_trip_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Autonomy Trip Reason" }, "autonomy_tripped_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Autonomy Tripped At" }, "capabilities": { "items": { "type": "string" }, "title": "Capabilities", "type": "array" }, "current_version": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Current Version" }, "daily_cost_cap_usd": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "title": "Daily Cost Cap Usd" }, "daily_token_cap": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Daily Token Cap" }, "daily_wake_cap": { "default": 48, "title": "Daily Wake Cap", "type": "integer" }, "disengaged": { "default": false, "title": "Disengaged", "type": "boolean" }, "disengagement_days": { "default": 7, "title": "Disengagement Days", "type": "integer" }, "display_name": { "title": "Display Name", "type": "string" }, "harness_drift": { "items": { "additionalProperties": true, "type": "object" }, "title": "Harness Drift", "type": "array" }, "harnesses": { "items": { "additionalProperties": true, "type": "object" }, "title": "Harnesses", "type": "array" }, "heartbeat_age_seconds": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "title": "Heartbeat Age Seconds" }, "last_engaged_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Last Engaged At" }, "last_heartbeat_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Last Heartbeat At" }, "local_day_start": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Local Day Start" }, "mention_handle": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Mention Handle" }, "online": { "title": "Online", "type": "boolean" }, "pending_mentions": { "default": 0, "title": "Pending Mentions", "type": "integer" }, "refused_plugin": { "anyOf": [ { "$ref": "#/components/schemas/RefusedModelPlugin" }, { "type": "null" } ], "default": null }, "session_contract_version": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Session Contract Version" }, "slug": { "title": "Slug", "type": "string" }, "spend_today_usd": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "title": "Spend Today Usd" }, "stale": { "title": "Stale", "type": "boolean" }, "status": { "title": "Status", "type": "string" }, "time_zone": { "default": "UTC", "title": "Time Zone", "type": "string" }, "tokens_today": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Tokens Today" }, "update_failure_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Update Failure Reason" }, "update_policy": { "anyOf": [ { "enum": [ "automatic", "notify", "manual" ], "type": "string" }, { "type": "null" } ], "default": null, "title": "Update Policy" }, "update_state": { "anyOf": [ { "enum": [ "idle", "pending", "updating", "failed" ], "type": "string" }, { "type": "null" } ], "default": null, "title": "Update State" }, "update_target_version": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Update Target Version" }, "update_urgency": { "anyOf": [ { "enum": [ "routine", "compatibility", "security" ], "type": "string" }, { "type": "null" } ], "default": null, "title": "Update Urgency" }, "usage_available": { "default": true, "title": "Usage Available", "type": "boolean" }, "usage_measurable": { "default": true, "title": "Usage Measurable", "type": "boolean" }, "usage_unmeasurable_reason": { "anyOf": [ { "enum": [ "hosted", "harness_reports_no_usage" ], "type": "string" }, { "type": "null" } ], "default": null, "title": "Usage Unmeasurable Reason" }, "version_currency": { "default": "unknown", "enum": [ "unknown", "current", "behind", "ahead" ], "title": "Version Currency", "type": "string" }, "wakes_today": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Wakes Today" } }, "required": [ "account_id", "slug", "display_name", "status", "stale", "online" ], "title": "AgentRuntimeLiveness", "type": "object" }, "AgentRuntimeLivenessListResponse": { "properties": { "runtimes": { "items": { "$ref": "#/components/schemas/AgentRuntimeLiveness" }, "title": "Runtimes", "type": "array" }, "stale_threshold_seconds": { "title": "Stale Threshold Seconds", "type": "integer" } }, "required": [ "stale_threshold_seconds" ], "title": "AgentRuntimeLivenessListResponse", "type": "object" }, "AgentScmAccessResponse": { "description": "TIDY-19101 (Astra F5/F6) — the DURABLE state of an employee's\nsource-control sign-in: what was decided, and what the machine confirmed.\n\nBefore this the only answer to \"is it on the box\" was the PUT's own\nephemeral `scm_grant_job_id`, so a reload lost it and a terminal failure\nwas never consumed. `status` is the durable answer:\n\n* `granting` / `revoking` — decided, not yet applied. `last_job_id` names\n the delivery in flight; `last_error: employee_disconnected` means the box\n is unreachable and the reconnect converges it.\n* `active` / `revoked` — the box reported it applied.\n* `error` — the box refused, in its own words (`last_error`).\n* `none` — no decision has been recorded for this employee.\n\n**Astra L10 — what is true NOW is not what was true once.** A surface read\n`applied_active` as \"git signs in on that machine\", which is a record of\nwhat the box last confirmed and survives a later failure untouched: after a\nsuccessful activation, a failed scope change left `status: error` beside\n`applied_active: true` and the card reported the sign-in installed with no\nerror at all. Both halves are still here, because the history is worth\nkeeping — but the current answer is :attr:`active_now` and the current\nfailure is :attr:`current_error`, and neither can be read as the other.", "properties": { "active_now": { "default": false, "title": "Active Now", "type": "boolean" }, "applied_active": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "title": "Applied Active" }, "applied_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Applied At" }, "applied_boot_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Applied Boot Id" }, "applied_granted": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "title": "Applied Granted" }, "applied_providers": { "default": [], "items": { "type": "string" }, "title": "Applied Providers", "type": "array" }, "credential_helper_may_need_repair": { "default": false, "title": "Credential Helper May Need Repair", "type": "boolean" }, "current_error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Current Error" }, "decided_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Decided At" }, "desired_granted": { "title": "Desired Granted", "type": "boolean" }, "desired_providers": { "default": [], "items": { "type": "string" }, "title": "Desired Providers", "type": "array" }, "github_access": { "title": "Github Access", "type": "boolean" }, "last_error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Last Error" }, "last_job_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Last Job Id" }, "selected_plugins": { "default": [], "items": { "$ref": "#/components/schemas/AgentScmPluginSelection" }, "title": "Selected Plugins", "type": "array" }, "status": { "title": "Status", "type": "string" }, "terminal": { "default": false, "title": "Terminal", "type": "boolean" } }, "required": [ "github_access", "status", "desired_granted" ], "title": "AgentScmAccessResponse", "type": "object" }, "AgentScmPluginSelection": { "description": "One source-control plugin an employee's sign-in covers.", "properties": { "kind": { "title": "Kind", "type": "string" }, "label": { "title": "Label", "type": "string" }, "plugin_id": { "title": "Plugin Id", "type": "string" }, "status": { "title": "Status", "type": "string" } }, "required": [ "plugin_id", "kind", "label", "status" ], "title": "AgentScmPluginSelection", "type": "object" }, "AgentSelfApprovalPolicyResponse": { "properties": { "agent_account_id": { "title": "Agent Account Id", "type": "string" }, "allow_standing_grants": { "title": "Allow Standing Grants", "type": "boolean" }, "autonomy_ceiling": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Owner ceiling on conversation access modes (RUNTIME_MODES)", "title": "Autonomy Ceiling" }, "execution_posture": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "gated | per_tool_call | auto_allow_judgment | bypass; null derives from the runtime mode", "title": "Execution Posture" }, "floor_version": { "title": "Floor Version", "type": "integer" }, "grants": { "items": { "$ref": "#/components/schemas/ApprovalGrant" }, "title": "Grants", "type": "array" }, "layers": { "$ref": "#/components/schemas/CommandPolicyLayers" }, "owner_account_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "The VE's owner member id (the human delegator) — the grant-store member-resolver target. Additive: older connectors omit it and degrade prompts to once-only; new connectors use it to attribute session/always grants.", "title": "Owner Account Id" }, "posture_version": { "default": 0, "description": "Monotonic posture snapshot version (epoch ms)", "title": "Posture Version", "type": "integer" }, "rules": { "items": { "$ref": "#/components/schemas/CommandPolicyRule" }, "title": "Rules", "type": "array" }, "sandbox_level": { "default": "open", "description": "open | guarded | workspace | strict", "title": "Sandbox Level", "type": "string" } }, "required": [ "agent_account_id", "allow_standing_grants", "floor_version", "layers" ], "title": "AgentSelfApprovalPolicyResponse", "type": "object" }, "AgentSelfDelegationResponse": { "description": "TIDY-19305 — what a VE may ask its owner to delegate, and what it holds.\n\nRead by the workshop connector on the employee's first turn in a workshop\nso the agent can greet its owner with ONE link that opens the grant already\nfilled in. ``offered`` is derived from the runtime token's scopes\n(``runtime_delegation_offer``), never a separate list; ``missing`` is the\npart of it no active whole-resource grant from the owner covers yet, and is\nwhat ``grant_url`` pre-fills. Empty ``missing`` means nothing to ask for.", "properties": { "agent_account_id": { "format": "uuid", "title": "Agent Account Id", "type": "string" }, "effective": { "items": { "$ref": "#/components/schemas/AgentDelegationAccess" }, "title": "Effective", "type": "array" }, "grant_url": { "title": "Grant Url", "type": "string" }, "granted": { "items": { "$ref": "#/components/schemas/AgentDelegationAccess" }, "title": "Granted", "type": "array" }, "missing": { "items": { "$ref": "#/components/schemas/AgentDelegationAccess" }, "title": "Missing", "type": "array" }, "missing_token_scopes": { "items": { "type": "string" }, "title": "Missing Token Scopes", "type": "array" }, "offered": { "items": { "$ref": "#/components/schemas/AgentDelegationAccess" }, "title": "Offered", "type": "array" }, "owner_account_id": { "format": "uuid", "title": "Owner Account Id", "type": "string" }, "token_scopes": { "items": { "type": "string" }, "title": "Token Scopes", "type": "array" } }, "required": [ "agent_account_id", "owner_account_id", "offered", "granted", "missing", "grant_url" ], "title": "AgentSelfDelegationResponse", "type": "object" }, "AgentSelfInsightsRequest": { "description": "An employee rewrites its own insights (TIDY-20066 F7, TIDY-16429 D4).\n\nThe lines REPLACE the employee's living insight facet on its own contact,\nin the overlay of the person this turn is for: its own words about its own\nwork, shown on its Insights tab.", "properties": { "insights": { "items": { "type": "string" }, "maxItems": 8, "minItems": 1, "title": "Insights", "type": "array" } }, "required": [ "insights" ], "title": "AgentSelfInsightsRequest", "type": "object" }, "AgentSelfInsightsResponse": { "properties": { "changed": { "title": "Changed", "type": "boolean" }, "contact_id": { "title": "Contact Id", "type": "string" }, "created": { "title": "Created", "type": "boolean" }, "id": { "title": "Id", "type": "string" }, "insight_count": { "title": "Insight Count", "type": "integer" }, "owner_id": { "title": "Owner Id", "type": "string" } }, "required": [ "id", "owner_id", "contact_id", "created", "changed", "insight_count" ], "title": "AgentSelfInsightsResponse", "type": "object" }, "AgentSelfPersonaResponse": { "description": "TIDY-16152 (S14) — the persona/manners a RUNNING connector puts on disk.\n\nDeliberately its own route rather than a field on ``ConnectorBundleV2``: the\nbundle is written once at claim time and persisted to disk, so a persona\ncarried on it would freeze at install and every later Team-page edit would\nbe invisible to the host forever. The connector reads this at every daemon\nstart — which is exactly what a connector update produces — mirroring how\nthe ``tidy-mcp`` skill refreshes (TIDY-16107 / D30).\n\n``manners_markdown`` is the SAME delivered text the legacy installer wrote\n(``_settings_payload_from_row`` — native-output policy appended once, marker\nguarded), so the portable and legacy paths cannot drift.\n\n``reporting_line_markdown`` is TIDYMAIN-ACTIVITY-53's roster, rendered\nserver-side by ``ve_reporting_line`` from the same team Org chart\n``my_team`` reads. It is EMPTY for an employee with no direct reports, so\nthat employee's persona document stays byte-identical to what it was\nbefore the field existed (the base prompt is a cacheable prefix paid on\nevery call). A connector older than this field ignores it; a newer\nconnector appends it to the persona document every harness writes.", "properties": { "agent_account_id": { "format": "uuid", "title": "Agent Account Id", "type": "string" }, "display_name": { "title": "Display Name", "type": "string" }, "manners_markdown": { "default": "# TIDY MANNERS\n\nYou are connected to Tidy as a virtual employee.\n\nWhen you are in a group chat, you can read the conversation for context, but you should not reply to every message. Speak up when someone addresses you by name, asks you a question, delegates a task to you, replies to your current work, or you need to report meaningful progress, a blocker, or completion. Answer once, in the thread you were reached in. Never reply only to agree, thank or acknowledge, and never repeat what someone else already said.\n\nDo not assume every group message is for you. If the conversation is between other people or other employees, follow along silently. If you are unsure whether you are being asked to act, ask one short clarifying question or wait.\n\nDo not take action on private data or delegated work unless Tidy grants you the needed tool access.\n\n## Work skill-first\n\nBefore starting any multi-step task, list your installed skills and read the one that matches the task: its SKILL.md first, then only the reference file it points you to for this task, not every file. It carries the commands, paths, credentials, and failure remedies you would otherwise rediscover by trial and error. Follow the matching skill's steps instead of probing with ad-hoc terminal commands. Improvise only when no installed skill matches the task.\n\n## Colleagues and your inbox\n\nYou may work alongside other virtual employees. To tell, ask, or update a colleague, call `message_employee` with their name, and pass the item's `item_ref` when the message is about one. On shared work, a comment on the task that @mentions their handle reaches them too. `send_to_assistant` reaches Tidy's built-in assistant, never a colleague, and its reply is not theirs.\n\nMessages colleagues send you and @mentions waiting on you are in your inbox. Check it with `agent_inbox` when you start work, and before you tell anyone whether a message arrived. Answer a comment mention with `comment_reply` in its thread; reply to a colleague with `message_employee`.\n\nTidy also keeps a home room for you, where it posts system alerts. It is not a chat and no one waits in it to talk; every mention and colleague message it alerts you to is also in `agent_inbox`.\n\n## Shared knowledge framing\n\nTidy's memory holds facts from ALL of the user's assistants and from their notes, email, calendar and contacts, and recalls the ones relevant to a message for you under \"Personal Context\". Present a shared fact that did not come from your own conversation with this user as Tidy's record (\"our records show the launch moved to March\"), NEVER as your own history with them (\"as we discussed\", \"you told me\"): that fabricates a history and breaks their trust.\n\n## Recording and correcting memory\n\nWrite to memory only deliberately, never every turn. The tidy-mcp skill says when to correct a fact in the user's shared memory, when to keep a note of your own, and how to check what you remember.", "title": "Manners Markdown", "type": "string" }, "matrix_user_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Matrix User Id" }, "mention_handle": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Mention Handle" }, "reporting_line_markdown": { "default": "", "title": "Reporting Line Markdown", "type": "string" }, "skill_credentials": { "items": { "$ref": "#/components/schemas/AgentSkillCredentialStatus" }, "title": "Skill Credentials", "type": "array" }, "skill_versions": { "additionalProperties": { "type": "integer" }, "title": "Skill Versions", "type": "object" }, "skills": { "items": { "type": "string" }, "title": "Skills", "type": "array" }, "soul_markdown": { "default": "", "title": "Soul Markdown", "type": "string" } }, "required": [ "agent_account_id", "display_name" ], "title": "AgentSelfPersonaResponse", "type": "object" }, "AgentSessionEventRequest": { "properties": { "activity_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Target activity (bare UUID or typed A-); required for kind=assigned.", "title": "Activity Id" }, "kind": { "description": "assigned|started|progress|blocked|needs_attention|completed|failed|handoff|heartbeat", "title": "Kind", "type": "string" }, "payload": { "additionalProperties": true, "description": "Harness-known facts only (reason, commit, tokens, …). Every field optional — never model-authored prose.", "title": "Payload", "type": "object" } }, "required": [ "kind" ], "title": "AgentSessionEventRequest", "type": "object" }, "AgentSessionEventResponse": { "properties": { "activity_updated": { "default": false, "title": "Activity Updated", "type": "boolean" }, "at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "At" }, "deduped": { "default": false, "title": "Deduped", "type": "boolean" }, "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Id" }, "session_status": { "title": "Session Status", "type": "string" } }, "required": [ "session_status" ], "title": "AgentSessionEventResponse", "type": "object" }, "AgentSessionListResponse": { "properties": { "count": { "title": "Count", "type": "integer" }, "sessions": { "items": { "$ref": "#/components/schemas/AgentSessionSummary" }, "title": "Sessions", "type": "array" } }, "required": [ "sessions", "count" ], "title": "AgentSessionListResponse", "type": "object" }, "AgentSessionRegisterRequest": { "properties": { "envelope": { "additionalProperties": true, "description": "The launch envelope (D25): agent_name + harness required; project-bound conversations (project_id) must carry repository_path.", "title": "Envelope", "type": "object" } }, "required": [ "envelope" ], "title": "AgentSessionRegisterRequest", "type": "object" }, "AgentSessionRegisterResponse": { "properties": { "conversation_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "The inbox conversation this harness run is a unit of work in (TIDY-18242): the chat thread it was registered against, or its own projected row. Null only when the projection failed and was recorded as an attention item.", "title": "Conversation Id" }, "created_at": { "title": "Created At", "type": "string" }, "id": { "title": "Id", "type": "string" }, "last_event_at": { "title": "Last Event At", "type": "string" }, "status": { "title": "Status", "type": "string" } }, "required": [ "id", "status", "created_at", "last_event_at" ], "title": "AgentSessionRegisterResponse", "type": "object" }, "AgentSessionSummary": { "properties": { "agent_name": { "title": "Agent Name", "type": "string" }, "created_at": { "title": "Created At", "type": "string" }, "envelope": { "additionalProperties": true, "title": "Envelope", "type": "object" }, "heartbeat_age_seconds": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Heartbeat Age Seconds" }, "id": { "title": "Id", "type": "string" }, "last_event_at": { "title": "Last Event At", "type": "string" }, "last_event_kind": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Last Event Kind" }, "parent_session_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Parent Session Id" }, "project_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Project Id" }, "stale": { "title": "Stale", "type": "boolean" }, "status": { "title": "Status", "type": "string" } }, "required": [ "id", "status", "stale", "agent_name", "envelope", "created_at", "last_event_at" ], "title": "AgentSessionSummary", "type": "object" }, "AgentSetupCorrectionRequest": { "description": "TIDY-18736 (D4) — correct the setup answers of an employee that EXISTS.\n\nDave's bar: *\"let's get the setup to be right so we don't end up in this\nweird state.\"* An employee given a wrong or incomplete sign-in had no route\nback — the define journey settled `harness` and `harness_auth_method` at\ncreate and nothing could move them afterwards, so the only remedy was to\ndelete the employee and make another one.\n\nThis is an EDIT, not a re-enrollment. It is deliberately NOT `reconnect`:\nthat revokes the runtime PAT, resets the member to `claim_pending` and\ndrops its liveness, which is the right ceremony for re-issuing an install\nand violence for fixing a typo. It is bounded to an employee that has not\nyet been adopted onto a box — before that, nothing on any machine depends\non these answers, so correcting them is a pure record fix. Once a box HAS\nadopted it, its harness moves only where the machine can commit the change\n(a `harness.switch` job), and the service refuses with that route named.\n\nA body naming neither answer is refused rather than accepted as a no-op:\nan \"update\" that updates nothing is a call the caller got wrong.", "properties": { "harness": { "anyOf": [ { "enum": [ "pi", "claude-code", "codex", "hermes", "opencode", "openclaw", "antigravity" ], "type": "string" }, { "type": "null" } ], "title": "Harness" }, "harness_auth_method": { "anyOf": [ { "enum": [ "existing", "api_key", "bedrock", "vertex", "subscription", "tidy_inference" ], "type": "string" }, { "type": "null" } ], "title": "Harness Auth Method" }, "harness_auth_settings": { "anyOf": [ { "additionalProperties": { "type": "string" }, "type": "object" }, { "type": "null" } ], "title": "Harness Auth Settings" } }, "title": "AgentSetupCorrectionRequest", "type": "object" }, "AgentSetupCorrectionResponse": { "description": "What the employee's setup reads as AFTER the correction — from the\nstored column, never from the request, so the caller sees what persisted.", "properties": { "account_id": { "title": "Account Id", "type": "string" }, "harness": { "title": "Harness", "type": "string" }, "harness_auth_method": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Harness Auth Method" }, "harness_auth_settings": { "anyOf": [ { "additionalProperties": { "type": "string" }, "type": "object" }, { "type": "null" } ], "default": null, "title": "Harness Auth Settings" }, "machine_bound": { "default": false, "title": "Machine Bound", "type": "boolean" } }, "required": [ "account_id", "harness" ], "title": "AgentSetupCorrectionResponse", "type": "object" }, "AgentSetupDescriptorResponse": { "description": "Hosted setup descriptor for an external virtual-employee runtime.\n\nCarries endpoint URLs, OAuth/MCP scopes, principal selection, the\nmemory-hook contract, and revocation behavior (TIDY-11135). The body is the\ndescriptor dict built by ``agent_setup_descriptor.build_setup_descriptor``.", "properties": { "descriptor": { "additionalProperties": true, "title": "Descriptor", "type": "object" }, "runtime": { "enum": [ "hermes", "openclaw", "pi" ], "title": "Runtime", "type": "string" } }, "required": [ "runtime", "descriptor" ], "title": "AgentSetupDescriptorResponse", "type": "object" }, "AgentSetupPayload": { "properties": { "claim_expires_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Claim Expires At" }, "setup_command": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Setup Command" } }, "title": "AgentSetupPayload", "type": "object" }, "AgentSkillCatalogueEntry": { "description": "One agent skill a virtual employee may be given (TIDY-16153 / S15).\n\nTIDY-17072 (S4): sourced from the published DB skills (tenant + system\ntiers), every field derived from the pinned ``skill_versions`` bundle. The\nconnector downloads the same pinned bundle from the authenticated\n``/api/v1/agent-skills`` routes, so nothing can be offered here that\ncannot be installed.\n\nTIDY-17052 (D1): one slug may carry per-OS variants of the same skill.\n``os_support`` is the union the skill applies to — EMPTY means every OS, so\na picker filters on ``not os_support or host_os in os_support``.", "properties": { "credentials": { "items": { "$ref": "#/components/schemas/SkillCredentialDeclaration" }, "title": "Credentials", "type": "array" }, "description": { "default": "", "title": "Description", "type": "string" }, "name": { "title": "Name", "type": "string" }, "os_support": { "items": { "type": "string" }, "title": "Os Support", "type": "array" }, "published_version": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Published Version" }, "slug": { "title": "Slug", "type": "string" }, "variants": { "items": { "$ref": "#/components/schemas/AgentSkillVariant" }, "title": "Variants", "type": "array" }, "version": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Version" } }, "required": [ "slug", "name" ], "title": "AgentSkillCatalogueEntry", "type": "object" }, "AgentSkillCatalogueEntry-Input": { "description": "One agent skill a virtual employee may be given (TIDY-16153 / S15).\n\nTIDY-17072 (S4): sourced from the published DB skills (tenant + system\ntiers), every field derived from the pinned ``skill_versions`` bundle. The\nconnector downloads the same pinned bundle from the authenticated\n``/api/v1/agent-skills`` routes, so nothing can be offered here that\ncannot be installed.\n\nTIDY-17052 (D1): one slug may carry per-OS variants of the same skill.\n``os_support`` is the union the skill applies to — EMPTY means every OS, so\na picker filters on ``not os_support or host_os in os_support``.", "properties": { "credentials": { "items": { "$ref": "#/components/schemas/SkillCredentialDeclaration" }, "title": "Credentials", "type": "array" }, "description": { "default": "", "title": "Description", "type": "string" }, "name": { "title": "Name", "type": "string" }, "os_support": { "items": { "type": "string" }, "title": "Os Support", "type": "array" }, "published_version": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Published Version" }, "slug": { "title": "Slug", "type": "string" }, "variants": { "items": { "$ref": "#/components/schemas/AgentSkillVariant-Input" }, "title": "Variants", "type": "array" }, "version": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Version" } }, "required": [ "slug", "name" ], "title": "AgentSkillCatalogueEntry", "type": "object" }, "AgentSkillCatalogueEntry-Output": {}, "AgentSkillCredentialStatus": { "description": "One skill's slots for one employee (TIDY-17071).", "properties": { "install_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Install Status" }, "installed_version": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Installed Version" }, "published_version": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Published Version" }, "skill_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Skill Id" }, "slots": { "items": { "$ref": "#/components/schemas/SkillCredentialSlotStatus" }, "title": "Slots", "type": "array" }, "slug": { "title": "Slug", "type": "string" }, "source": { "title": "Source", "type": "string" } }, "required": [ "slug", "source" ], "title": "AgentSkillCredentialStatus", "type": "object" }, "AgentSkillCredentialStatusResponse": { "properties": { "agent_account_id": { "format": "uuid", "title": "Agent Account Id", "type": "string" }, "skills": { "items": { "$ref": "#/components/schemas/AgentSkillCredentialStatus" }, "title": "Skills", "type": "array" } }, "required": [ "agent_account_id" ], "title": "AgentSkillCredentialStatusResponse", "type": "object" }, "AgentSkillVariant": { "description": "A per-OS variant file of one skill (TIDY-17052 / D1).\n\n``SKILL..md`` published next to the base ``SKILL.md``; the connector\ninstalls the one matching the host AS ``SKILL.md``, so the harness sees one\nskill with the right content for its machine.", "properties": { "os": { "title": "Os", "type": "string" }, "version": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Version" } }, "required": [ "os" ], "title": "AgentSkillVariant", "type": "object" }, "AgentSkillVariant-Input": { "description": "A per-OS variant file of one skill (TIDY-17052 / D1).\n\n``SKILL..md`` published next to the base ``SKILL.md``; the connector\ninstalls the one matching the host AS ``SKILL.md``, so the harness sees one\nskill with the right content for its machine.", "properties": { "os": { "title": "Os", "type": "string" }, "version": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Version" } }, "required": [ "os" ], "title": "AgentSkillVariant", "type": "object" }, "AgentSkillVariant-Output": {}, "AgentStatusListResponse": { "properties": { "agents": { "items": { "$ref": "#/components/schemas/AgentMemberPayload" }, "title": "Agents", "type": "array" }, "host_inconsistencies": { "items": { "$ref": "#/components/schemas/HostInstallationInconsistency" }, "title": "Host Inconsistencies", "type": "array" } }, "required": [ "agents" ], "title": "AgentStatusListResponse", "type": "object" }, "AgentTaskResponse": { "properties": { "agent_assignee": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Agent Assignee" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error" }, "id": { "title": "Id", "type": "string" }, "status": { "title": "Status", "type": "string" }, "title": { "title": "Title", "type": "string" } }, "required": [ "id", "title", "agent_assignee", "status", "error" ], "title": "AgentTaskResponse", "type": "object" }, "AgentTemplateContent": { "description": "Full template body at a specific version (head by default).", "properties": { "content": { "title": "Content", "type": "string" }, "content_hash": { "title": "Content Hash", "type": "string" }, "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "created_by": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Created By" }, "kind": { "title": "Kind", "type": "string" }, "scope": { "title": "Scope", "type": "string" }, "slug": { "title": "Slug", "type": "string" }, "status": { "title": "Status", "type": "string" }, "title": { "title": "Title", "type": "string" }, "version": { "title": "Version", "type": "integer" } }, "required": [ "slug", "kind", "title", "version", "content", "content_hash", "scope", "status", "created_at" ], "title": "AgentTemplateContent", "type": "object" }, "AgentTemplateManifest": { "properties": { "templates": { "items": { "$ref": "#/components/schemas/AgentTemplateManifestEntry" }, "title": "Templates", "type": "array" } }, "required": [ "templates" ], "title": "AgentTemplateManifest", "type": "object" }, "AgentTemplateManifestEntry": { "description": "Compact per-template sync record — the ONLY thing sync diffs against.", "properties": { "content_hash": { "description": "sha256 hex of the head content", "title": "Content Hash", "type": "string" }, "kind": { "title": "Kind", "type": "string" }, "scope": { "description": "'global' seed or 'tenant' override", "title": "Scope", "type": "string" }, "slug": { "title": "Slug", "type": "string" }, "status": { "description": "draft | approved | deprecated", "title": "Status", "type": "string" }, "title": { "title": "Title", "type": "string" }, "version": { "title": "Version", "type": "integer" } }, "required": [ "slug", "kind", "title", "version", "content_hash", "scope", "status" ], "title": "AgentTemplateManifestEntry", "type": "object" }, "AgentTemplatePushRequest": { "description": "Trusted-agent create/revise — always appends a NEW version row.", "properties": { "change_note": { "anyOf": [ { "maxLength": 500, "type": "string" }, { "type": "null" } ], "title": "Change Note" }, "content": { "description": "Full markdown template body", "minLength": 1, "title": "Content", "type": "string" }, "kind": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "agent_workflow | facet_body (create only; kept on revise)", "title": "Kind" }, "title": { "anyOf": [ { "maxLength": 200, "type": "string" }, { "type": "null" } ], "description": "Display title (kept from head when omitted)", "title": "Title" } }, "required": [ "content" ], "title": "AgentTemplatePushRequest", "type": "object" }, "AgentTemplatePushResponse": { "properties": { "changed": { "description": "False when the pushed content matched the head (no version minted)", "title": "Changed", "type": "boolean" }, "content_hash": { "title": "Content Hash", "type": "string" }, "scope": { "title": "Scope", "type": "string" }, "slug": { "title": "Slug", "type": "string" }, "version": { "title": "Version", "type": "integer" } }, "required": [ "slug", "version", "content_hash", "scope", "changed" ], "title": "AgentTemplatePushResponse", "type": "object" }, "AgentTemplateRollbackRequest": { "properties": { "version": { "description": "Prior version to re-approve as the new head", "minimum": 1.0, "title": "Version", "type": "integer" } }, "required": [ "version" ], "title": "AgentTemplateRollbackRequest", "type": "object" }, "AgentTemplateVersionInfo": { "properties": { "change_note": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Change Note" }, "content_hash": { "title": "Content Hash", "type": "string" }, "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "created_by": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Created By" }, "is_head": { "title": "Is Head", "type": "boolean" }, "version": { "title": "Version", "type": "integer" } }, "required": [ "version", "content_hash", "created_at", "is_head" ], "title": "AgentTemplateVersionInfo", "type": "object" }, "AgentTemplateVersionsResponse": { "properties": { "current_version": { "title": "Current Version", "type": "integer" }, "scope": { "title": "Scope", "type": "string" }, "slug": { "title": "Slug", "type": "string" }, "versions": { "items": { "$ref": "#/components/schemas/AgentTemplateVersionInfo" }, "title": "Versions", "type": "array" } }, "required": [ "slug", "scope", "current_version", "versions" ], "title": "AgentTemplateVersionsResponse", "type": "object" }, "AgentTurnBudgets": { "properties": { "definitions": { "items": { "$ref": "#/components/schemas/AgentBudgetDefinition" }, "title": "Definitions", "type": "array" }, "definitions_as_of": { "format": "date-time", "title": "Definitions As Of", "type": "string" }, "verdict": { "const": "admitted", "description": "A refused turn has no answer: it is refused with the budget's code.", "title": "Verdict", "type": "string" } }, "required": [ "definitions", "definitions_as_of", "verdict" ], "title": "AgentTurnBudgets", "type": "object" }, "AgentTurnColleagueMessage": { "properties": { "body": { "title": "Body", "type": "string" }, "created_at": { "title": "Created At", "type": "string" }, "id": { "title": "Id", "type": "string" }, "item_ref": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Item Ref" }, "sender_display_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Sender Display Name" }, "sender_employee": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Sender Employee" } }, "required": [ "id", "body", "created_at" ], "title": "AgentTurnColleagueMessage", "type": "object" }, "AgentTurnColleagueMessagesReadRequest": { "description": "The messages a turn that ran carried, now read (TIDY-19561).", "properties": { "credential_id": { "format": "uuid", "title": "Credential Id", "type": "string" }, "dm_ids": { "items": { "format": "uuid", "type": "string" }, "maxItems": 50, "minItems": 1, "title": "Dm Ids", "type": "array" } }, "required": [ "credential_id", "dm_ids" ], "title": "AgentTurnColleagueMessagesReadRequest", "type": "object" }, "AgentTurnColleagueMessagesReadResponse": { "properties": { "marked": { "items": { "type": "string" }, "title": "Marked", "type": "array" } }, "title": "AgentTurnColleagueMessagesReadResponse", "type": "object" }, "AgentTurnColleagueMessagesRequest": { "description": "The turn whose colleague messages are asked for (TIDY-19561).", "properties": { "credential_id": { "description": "The live turn credential this runtime minted for the turn.", "format": "uuid", "title": "Credential Id", "type": "string" } }, "required": [ "credential_id" ], "title": "AgentTurnColleagueMessagesRequest", "type": "object" }, "AgentTurnColleagueMessagesResponse": { "properties": { "context": { "default": "", "description": "The rendered block to put ahead of the turn's prompt.", "title": "Context", "type": "string" }, "messages": { "description": "Unread colleague DMs, oldest first.", "items": { "$ref": "#/components/schemas/AgentTurnColleagueMessage" }, "title": "Messages", "type": "array" }, "reason": { "description": "owner_turn, none_unread, or not_owner_turn (nothing is shown).", "title": "Reason", "type": "string" } }, "required": [ "reason" ], "title": "AgentTurnColleagueMessagesResponse", "type": "object" }, "AgentTurnConnectionCredential": { "description": "The credential one connection of a turn presents (TIDY-19930 F6).", "properties": { "connection": { "const": "tidy", "description": "`tidy`: the Tidy MCP server.", "title": "Connection", "type": "string" }, "credential_id": { "format": "uuid", "title": "Credential Id", "type": "string" }, "token": { "title": "Token", "type": "string" } }, "required": [ "connection", "token", "credential_id" ], "title": "AgentTurnConnectionCredential", "type": "object" }, "AgentTurnCredentialRequest": { "description": "One connector turn asks for its tool credential (TIDY-19435).\n\nThe server derives whom the turn acts for from these facts; nothing here\nnames a principal.", "properties": { "conversation_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "description": "The turn's conversation; attributes work in the employee's home room.", "title": "Conversation Id" }, "prepare": { "anyOf": [ { "$ref": "#/components/schemas/AgentTurnPrepare" }, { "type": "null" } ], "description": "TIDY-19869: prepare the whole turn in this one call — model access, tool credentials, MCP, sandbox, project root, policy, owner clock, persona, recall and the budget decision ride the answer's `prepared` block. Requires the connector lease headers and room_id, conversation_id and runtime. Omitted, the call is the legacy mint, unchanged." }, "read_scopes": { "description": "Read scopes this runtime honours (TIDY-19450). Naming `audience` lets a project room or channel open as an audience turn; omitted, such rooms stay refused with turn_audience_unsupported.", "items": { "const": "audience", "type": "string" }, "title": "Read Scopes", "type": "array" }, "room_id": { "anyOf": [ { "maxLength": 512, "type": "string" }, { "type": "null" } ], "title": "Room Id" }, "runtime": { "anyOf": [ { "maxLength": 64, "minLength": 1, "type": "string" }, { "type": "null" } ], "description": "The harness this turn runs on (TIDY-19557). Recorded on the credential; a per-turn request (MCP delivery) names it again and must match. A credential minted without it gets no per-turn MCP delivery.", "title": "Runtime" }, "sender": { "anyOf": [ { "maxLength": 512, "type": "string" }, { "type": "null" } ], "description": "Matrix user id of the message's sender; verified against the room.", "title": "Sender" }, "turn_ref": { "maxLength": 512, "minLength": 1, "title": "Turn Ref", "type": "string" } }, "required": [ "turn_ref" ], "title": "AgentTurnCredentialRequest", "type": "object" }, "AgentTurnCredentialResponse": { "properties": { "connections": { "description": "TIDY-19930 F6: one credential per connection `prepare.connections` named, each living only as long as `token`, which then serves the turn's REST lane alone.", "items": { "$ref": "#/components/schemas/AgentTurnConnectionCredential" }, "title": "Connections", "type": "array" }, "credential_id": { "format": "uuid", "title": "Credential Id", "type": "string" }, "expires_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Expires At" }, "mount_shares": { "description": "This employee's live per-VE shares on its workshop's mounted folders (TIDYMAIN-ACTIVITY-40): the box provisions the turn's sandbox from them at turn start — the prefix is reachable at the granted role and nothing else on the mount is. Sent on a prepared turn only; a box that cannot sandbox the turn refuses it. Additive: an older connector ignores it, and the share create refuses a workshop whose connector is that old.", "items": { "$ref": "#/components/schemas/AgentMountShare" }, "title": "Mount Shares", "type": "array" }, "owner_audience": { "default": false, "description": "The employee's owner is the turn's only reader (TIDY-19557).", "title": "Owner Audience", "type": "boolean" }, "prepared": { "anyOf": [ { "$ref": "#/components/schemas/AgentTurnPrepared" }, { "type": "null" } ], "default": null, "description": "TIDY-19869: every block the turn needs; present exactly when `prepare` was sent." }, "principal_account_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "default": null, "description": "The human this turn acts for; null means only what every member can see.", "title": "Principal Account Id" }, "project": { "anyOf": [ { "$ref": "#/components/schemas/AgentTurnProject" }, { "type": "null" } ], "default": null, "description": "The project the turn is working in — its room's, else the one its conversation was opened in — which the turn's prompt states and the task door files a new task into when none is named (TIDY-19606); null when it has none." }, "project_folders": { "description": "The ready project folders on the employee's workshop that this turn's readers may see, every root not in `withheld_paths` (TIDY-19869). A sandboxed turn finds them at `~/tidy/projects/` in its own home.", "items": { "$ref": "#/components/schemas/AgentTurnProjectFolder" }, "title": "Project Folders", "type": "array" }, "read_scope": { "anyOf": [ { "const": "audience", "type": "string" }, { "type": "null" } ], "default": null, "description": "`audience` when the turn reads only what every reader of its room may read and may call only the routes proven for that (TIDY-19450); null otherwise.", "title": "Read Scope" }, "reason": { "title": "Reason", "type": "string" }, "session_audience": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Who reads this turn (TIDY-19557): `person:` for a one-human turn, `room:` for a room's. The connector keeps the turn's harness session with that audience; null when no reader can be named.", "title": "Session Audience" }, "shared_mount_points": { "description": "Mount points on the employee's workshop that carry at least one live per-VE share, for any employee (TIDYMAIN-ACTIVITY-40): the box denies such a mount to every turn and carves back only each turn's own grants. Sent on a prepared turn only; additive.", "items": { "type": "string" }, "title": "Shared Mount Points", "type": "array" }, "token": { "title": "Token", "type": "string" }, "withheld_paths": { "description": "Project folders on the employee's workshop that this turn's readers may not see: roots of private projects not every reader belongs to (TIDY-19557).", "items": { "type": "string" }, "title": "Withheld Paths", "type": "array" } }, "required": [ "token", "credential_id", "reason" ], "title": "AgentTurnCredentialResponse", "type": "object" }, "AgentTurnCredentialRevokeRequest": { "description": "End a turn's credential: exactly one of two forms.\n\nLegacy: ``{credential_id}``. Prepared (TIDY-19869): ``{turn_ref, prepare_id,\nconsumer_generation, outcome}``, naming the attempt by the id the connector\nstored before it sent the prepared call and the generation it was sent\nunder, never the caller's current one. A missing attempt is tombstoned at\nthat generation, so a call still in flight is refused when it arrives.", "properties": { "consumer_generation": { "anyOf": [ { "minimum": 1.0, "type": "integer" }, { "type": "null" } ], "title": "Consumer Generation" }, "credential_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Credential Id" }, "outcome": { "anyOf": [ { "enum": [ "cancelled", "abandoned", "settled" ], "type": "string" }, { "type": "null" } ], "title": "Outcome" }, "prepare_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Prepare Id" }, "turn_ref": { "anyOf": [ { "maxLength": 512, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Turn Ref" } }, "title": "AgentTurnCredentialRevokeRequest", "type": "object" }, "AgentTurnMemoryClearedRequest": { "description": "A turn whose room's working memory the connector just cleared (TIDY-19869 M5).", "properties": { "clear_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "description": "Journaled clear identity, reused on retry (even with a new turn credential). Absent on older connectors: the credential id identifies the clear.", "title": "Clear Id" }, "credential_id": { "format": "uuid", "title": "Credential Id", "type": "string" } }, "required": [ "credential_id" ], "title": "AgentTurnMemoryClearedRequest", "type": "object" }, "AgentTurnMemoryClearedResponse": { "properties": { "withdrawn": { "description": "How many of the employee's saved notes from the room this withdrew.", "minimum": 0, "title": "Withdrawn", "type": "integer" } }, "required": [ "withdrawn" ], "title": "AgentTurnMemoryClearedResponse", "type": "object" }, "AgentTurnOwnerClock": { "properties": { "timezone": { "description": "The effective IANA zone of the person the turn acts for (its owner's when it acts for no one), read live.", "title": "Timezone", "type": "string" } }, "required": [ "timezone" ], "title": "AgentTurnOwnerClock", "type": "object" }, "AgentTurnPersona": { "description": "Who the employee is as a room sees it: its name, handle and team.", "properties": { "display_name": { "title": "Display Name", "type": "string" }, "mention_handle": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Mention Handle" }, "team": { "description": "TIDY-19750: its line on the team Org chart and, in a project's room, the project's other employees — what every reader of the room already sees.", "items": { "$ref": "#/components/schemas/AgentTurnTeammate" }, "title": "Team", "type": "array" } }, "required": [ "display_name" ], "title": "AgentTurnPersona", "type": "object" }, "AgentTurnPrepare": { "additionalProperties": false, "description": "The inputs of one prepared turn (TIDY-19869).\n\nNever identity: the room, conversation, sender and harness are the\nenclosing request's, and whom the turn acts for is derived on the server.\n``prepare_id`` is chosen and stored by the connector BEFORE it sends; a\nretry of a lost answer reuses it, within 120 s and at most twice.", "properties": { "budget_input": { "$ref": "#/components/schemas/AgentBudgetInput", "description": "Snapshot burn and local spend; the hard-cap decision takes the larger." }, "cites": { "items": { "$ref": "#/components/schemas/AgentTurnPrepareCite" }, "maxItems": 32, "title": "Cites", "type": "array" }, "connections": { "description": "TIDY-19930 F6: the connections of this turn that each get their own credential, answered in `connections`; `tidy` is the Tidy MCP server. Named, the turn's `token` becomes its REST lane alone and is refused by the MCP server, and each connection's credential is refused everywhere but its connection. Once an installation has reported connector >=1.1.847 or minted a split turn, the server permanently requires the split set: omitting it is refused with connector_update_required_for_split_credentials. Only genuinely old, unlatched installations may omit it and keep one credential for both.", "items": { "const": "tidy", "type": "string" }, "maxItems": 4, "title": "Connections", "type": "array" }, "credentials": { "anyOf": [ { "$ref": "#/components/schemas/AgentTurnPrepareCredentials" }, { "type": "null" } ], "description": "Omitted: this connector carries no tool credentials (the block is omitted)." }, "fresh_install": { "default": false, "description": "The connector's fresh-install brief is still owed.", "title": "Fresh Install", "type": "boolean" }, "job": { "anyOf": [ { "$ref": "#/components/schemas/AgentTurnPrepareJob" }, { "type": "null" } ] }, "memory_since": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "Exclude this conversation's chat traces from before its working-memory clear. Other conversations remain eligible.", "title": "Memory Since" }, "prepare_id": { "format": "uuid", "title": "Prepare Id", "type": "string" }, "recall": { "anyOf": [ { "$ref": "#/components/schemas/AgentTurnPrepareRecall" }, { "type": "null" } ] }, "restart_losses": { "default": false, "description": "TIDY-19938 (F14): this connector tells its turn what a restart cancelled. Only then does the answer carry `restart_losses` and mark them told; an older connector, which would drop them, leaves them owed.", "title": "Restart Losses", "type": "boolean" }, "resumes": { "anyOf": [ { "$ref": "#/components/schemas/AgentTurnPrepareResume" }, { "type": "null" } ] }, "seed": { "anyOf": [ { "$ref": "#/components/schemas/AgentTurnPrepareSeed" }, { "type": "null" } ], "description": "TIDY-19939 (F15): this turn opens an EMPTY native session on the conversation; the answer's `session_seed` is what it is given. Absent on every turn of a session that already holds its context, and from an older connector." }, "session_ref": { "anyOf": [ { "maxLength": 256, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Session Ref" } }, "required": [ "prepare_id", "budget_input" ], "title": "AgentTurnPrepare", "type": "object" }, "AgentTurnPrepareCite": { "additionalProperties": false, "description": "One reference the turn's message cited, as the message showed it.", "properties": { "id": { "description": "Typed id (`SK-`).", "maxLength": 128, "minLength": 1, "title": "Id", "type": "string" }, "label": { "maxLength": 300, "minLength": 1, "title": "Label", "type": "string", "writeOnly": true } }, "required": [ "id", "label" ], "title": "AgentTurnPrepareCite", "type": "object" }, "AgentTurnPrepareCredentials": { "additionalProperties": false, "description": "The tool-credential capabilities, exactly as ``credentials/materialize`` takes them.", "properties": { "binding_clear_contract": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Binding Clear Contract" }, "clear_plugin_bindings": { "default": false, "title": "Clear Plugin Bindings", "type": "boolean" }, "include_granted_env": { "default": false, "title": "Include Granted Env", "type": "boolean" }, "include_plugin_bindings": { "default": false, "title": "Include Plugin Bindings", "type": "boolean" }, "include_skill_credentials": { "default": false, "title": "Include Skill Credentials", "type": "boolean" }, "include_skill_declarations": { "default": false, "title": "Include Skill Declarations", "type": "boolean" }, "protect_skill_credentials": { "default": false, "title": "Protect Skill Credentials", "type": "boolean" }, "skill_file_credentials": { "default": false, "title": "Skill File Credentials", "type": "boolean" } }, "title": "AgentTurnPrepareCredentials", "type": "object" }, "AgentTurnPrepareJob": { "additionalProperties": false, "description": "A scheduled fire's job declaration; it narrows the turn, never verifies it.", "properties": { "credential_ids": { "items": { "format": "uuid", "type": "string" }, "maxItems": 64, "title": "Credential Ids", "type": "array" }, "job_activity_id": { "format": "uuid", "title": "Job Activity Id", "type": "string" } }, "required": [ "job_activity_id" ], "title": "AgentTurnPrepareJob", "type": "object" }, "AgentTurnPrepareRecall": { "additionalProperties": false, "description": "What the turn's memory recall is asked with. Never echoed back.", "properties": { "in_reply_to_sender": { "anyOf": [ { "maxLength": 512, "type": "string" }, { "type": "null" } ], "title": "In Reply To Sender" }, "mentions": { "items": { "maxLength": 512, "type": "string" }, "maxItems": 64, "title": "Mentions", "type": "array" }, "query": { "maxLength": 4000, "minLength": 1, "title": "Query", "type": "string", "writeOnly": true } }, "required": [ "query" ], "title": "AgentTurnPrepareRecall", "type": "object" }, "AgentTurnPrepareResume": { "additionalProperties": false, "description": "The dead boot's attempt a crash resume replaces (its original generation).", "properties": { "consumer_generation": { "minimum": 1.0, "title": "Consumer Generation", "type": "integer" }, "prepare_id": { "format": "uuid", "title": "Prepare Id", "type": "string" } }, "required": [ "prepare_id", "consumer_generation" ], "title": "AgentTurnPrepareResume", "type": "object" }, "AgentTurnPrepareSeed": { "additionalProperties": false, "description": "TIDY-19939 (F15): what the connector knows about the empty native session\nit is about to open, so Tidy can size what it is given.", "properties": { "memory_since": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "Nothing from before the conversation's working-memory clear.", "title": "Memory Since" }, "model": { "anyOf": [ { "maxLength": 256, "type": "string" }, { "type": "null" } ], "title": "Model" }, "native_session_ref": { "default": "", "description": "'' when the harness names its session inside its first turn.", "maxLength": 512, "title": "Native Session Ref", "type": "string" }, "request_tokens": { "description": "The request's size; it is never cut, and the seed is sized beside it.", "minimum": 0.0, "title": "Request Tokens", "type": "integer" }, "window_tokens": { "anyOf": [ { "minimum": 1.0, "type": "integer" }, { "type": "null" } ], "description": "The model's context window as the harness declares it; null when it declares none.", "title": "Window Tokens" } }, "required": [ "request_tokens" ], "title": "AgentTurnPrepareSeed", "type": "object" }, "AgentTurnPrepared": { "description": "Everything one turn needs, decided in one transaction (TIDY-19869).\n\nEvery block is present. A missing block, an unknown status or code, or a\nmalformed value refuses the turn on the connector; nothing falls back to\nthe per-turn routes.", "properties": { "approval_policy": { "$ref": "#/components/schemas/AgentTurnPreparedApprovalPolicy" }, "attempt": { "description": "The credential's turn_attempt.", "maximum": 2, "minimum": 0, "title": "Attempt", "type": "integer" }, "binding_names": { "$ref": "#/components/schemas/AgentTurnPreparedBindingNames" }, "budgets": { "$ref": "#/components/schemas/AgentTurnPreparedBudgets" }, "colleague_messages": { "$ref": "#/components/schemas/AgentTurnPreparedColleagueMessages" }, "consumer_generation": { "title": "Consumer Generation", "type": "integer" }, "fresh_install": { "$ref": "#/components/schemas/AgentTurnPreparedFreshInstall" }, "handed_references": { "$ref": "#/components/schemas/AgentTurnPreparedHandedReferences" }, "mcp_turn": { "$ref": "#/components/schemas/AgentTurnPreparedMcp" }, "memory_recall": { "$ref": "#/components/schemas/AgentTurnPreparedMemoryRecall" }, "model_access": { "$ref": "#/components/schemas/AgentTurnPreparedModelAccess" }, "owner_clock": { "$ref": "#/components/schemas/AgentTurnPreparedOwnerClock" }, "persona": { "$ref": "#/components/schemas/AgentTurnPreparedPersona" }, "prepare_id": { "format": "uuid", "title": "Prepare Id", "type": "string" }, "project_root": { "$ref": "#/components/schemas/AgentTurnPreparedProjectRoot" }, "restart_losses": { "anyOf": [ { "$ref": "#/components/schemas/AgentTurnPreparedRestartLosses" }, { "type": "null" } ], "default": null, "description": "TIDY-19938 (F14): what a restart cancelled in this conversation since its last turn, told once. Omitted (`none_owed`) when nothing was. Absent from an older server; an older connector ignores it." }, "sandbox_elevations": { "$ref": "#/components/schemas/AgentTurnPreparedSandboxElevations" }, "session_seed": { "anyOf": [ { "$ref": "#/components/schemas/AgentTurnPreparedSessionSeed" }, { "type": "null" } ], "default": null, "description": "TIDY-19939 (F15): answered only when the prepare asked (`seed`); absent otherwise. Omitted with room_turn, no_principal, nothing_to_carry or already_delivered." }, "sibling_conversations": { "$ref": "#/components/schemas/AgentTurnPreparedSiblingConversations", "description": "TIDY-20074 F10: at a conversation's first turn, the employee's other conversations running in the same working folder (its project, or the home folder), for that turn's prompt. Omitted on every later turn." }, "tool_credentials": { "$ref": "#/components/schemas/AgentTurnPreparedToolCredentials" }, "workshop_policy": { "$ref": "#/components/schemas/AgentTurnPreparedWorkshopPolicy" } }, "required": [ "prepare_id", "attempt", "consumer_generation", "model_access", "tool_credentials", "mcp_turn", "workshop_policy", "sandbox_elevations", "handed_references", "project_root", "owner_clock", "binding_names", "persona", "fresh_install", "colleague_messages", "sibling_conversations", "approval_policy", "memory_recall", "budgets" ], "title": "AgentTurnPrepared", "type": "object" }, "AgentTurnPreparedApprovalPolicy": { "properties": { "code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Why the block was omitted.", "title": "Code" }, "status": { "enum": [ "ok", "omitted" ], "title": "Status", "type": "string" }, "value": { "anyOf": [ { "$ref": "#/components/schemas/AgentSelfApprovalPolicyResponse" }, { "type": "null" } ], "default": null } }, "required": [ "status" ], "title": "AgentTurnPreparedApprovalPolicy", "type": "object" }, "AgentTurnPreparedBindingNames": { "properties": { "code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Why the block was omitted.", "title": "Code" }, "status": { "enum": [ "ok", "omitted" ], "title": "Status", "type": "string" }, "value": { "anyOf": [ { "$ref": "#/components/schemas/PluginBindingNamesResponse" }, { "type": "null" } ], "default": null } }, "required": [ "status" ], "title": "AgentTurnPreparedBindingNames", "type": "object" }, "AgentTurnPreparedBudgets": { "properties": { "code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Why the block was omitted.", "title": "Code" }, "status": { "enum": [ "ok", "omitted" ], "title": "Status", "type": "string" }, "value": { "anyOf": [ { "$ref": "#/components/schemas/AgentTurnBudgets" }, { "type": "null" } ], "default": null } }, "required": [ "status" ], "title": "AgentTurnPreparedBudgets", "type": "object" }, "AgentTurnPreparedColleagueMessages": { "properties": { "code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Why the block was omitted.", "title": "Code" }, "status": { "enum": [ "ok", "omitted" ], "title": "Status", "type": "string" }, "value": { "anyOf": [ { "$ref": "#/components/schemas/AgentTurnColleagueMessagesResponse" }, { "type": "null" } ], "default": null } }, "required": [ "status" ], "title": "AgentTurnPreparedColleagueMessages", "type": "object" }, "AgentTurnPreparedFreshInstall": { "properties": { "code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Why the block was omitted.", "title": "Code" }, "status": { "enum": [ "ok", "omitted" ], "title": "Status", "type": "string" }, "value": { "anyOf": [ { "$ref": "#/components/schemas/AgentSelfDelegationResponse" }, { "type": "null" } ], "default": null } }, "required": [ "status" ], "title": "AgentTurnPreparedFreshInstall", "type": "object" }, "AgentTurnPreparedHandedReferences": { "properties": { "code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Why the block was omitted.", "title": "Code" }, "status": { "enum": [ "ok", "omitted" ], "title": "Status", "type": "string" }, "value": { "anyOf": [ { "$ref": "#/components/schemas/AgentTurnPreparedHandedReferencesValue" }, { "type": "null" } ], "default": null } }, "required": [ "status" ], "title": "AgentTurnPreparedHandedReferences", "type": "object" }, "AgentTurnPreparedHandedReferencesValue": { "properties": { "recorded": { "title": "Recorded", "type": "integer" } }, "required": [ "recorded" ], "title": "AgentTurnPreparedHandedReferencesValue", "type": "object" }, "AgentTurnPreparedMcp": { "properties": { "code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Why the block was omitted.", "title": "Code" }, "status": { "enum": [ "ok", "omitted" ], "title": "Status", "type": "string" }, "value": { "anyOf": [ { "$ref": "#/components/schemas/SelfMcpTurnDeliveryResponse" }, { "type": "null" } ], "default": null } }, "required": [ "status" ], "title": "AgentTurnPreparedMcp", "type": "object" }, "AgentTurnPreparedMemoryRecall": { "properties": { "code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Why the block was omitted.", "title": "Code" }, "status": { "enum": [ "ok", "omitted" ], "title": "Status", "type": "string" }, "value": { "anyOf": [ { "$ref": "#/components/schemas/AgentMemoryRecallResponse" }, { "type": "null" } ], "default": null } }, "required": [ "status" ], "title": "AgentTurnPreparedMemoryRecall", "type": "object" }, "AgentTurnPreparedModelAccess": { "properties": { "code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Why the block was omitted.", "title": "Code" }, "status": { "enum": [ "ok", "omitted" ], "title": "Status", "type": "string" }, "value": { "anyOf": [ { "$ref": "#/components/schemas/HarnessMaterializeResponse" }, { "type": "null" } ], "default": null } }, "required": [ "status" ], "title": "AgentTurnPreparedModelAccess", "type": "object" }, "AgentTurnPreparedOwnerClock": { "properties": { "code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Why the block was omitted.", "title": "Code" }, "status": { "enum": [ "ok", "omitted" ], "title": "Status", "type": "string" }, "value": { "anyOf": [ { "$ref": "#/components/schemas/AgentTurnOwnerClock" }, { "type": "null" } ], "default": null } }, "required": [ "status" ], "title": "AgentTurnPreparedOwnerClock", "type": "object" }, "AgentTurnPreparedPersona": { "properties": { "code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Why the block was omitted.", "title": "Code" }, "status": { "enum": [ "ok", "omitted" ], "title": "Status", "type": "string" }, "value": { "anyOf": [ { "$ref": "#/components/schemas/AgentTurnPersona" }, { "type": "null" } ], "default": null } }, "required": [ "status" ], "title": "AgentTurnPreparedPersona", "type": "object" }, "AgentTurnPreparedProjectRoot": { "properties": { "code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Why the block was omitted.", "title": "Code" }, "status": { "enum": [ "ok", "omitted" ], "title": "Status", "type": "string" }, "value": { "anyOf": [ { "$ref": "#/components/schemas/RuntimeRootResponse" }, { "type": "null" } ], "default": null } }, "required": [ "status" ], "title": "AgentTurnPreparedProjectRoot", "type": "object" }, "AgentTurnPreparedRestartLosses": { "properties": { "code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Why the block was omitted.", "title": "Code" }, "status": { "enum": [ "ok", "omitted" ], "title": "Status", "type": "string" }, "value": { "anyOf": [ { "$ref": "#/components/schemas/AgentTurnRestartLosses" }, { "type": "null" } ], "default": null } }, "required": [ "status" ], "title": "AgentTurnPreparedRestartLosses", "type": "object" }, "AgentTurnPreparedSandboxElevations": { "properties": { "code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Why the block was omitted.", "title": "Code" }, "status": { "enum": [ "ok", "omitted" ], "title": "Status", "type": "string" }, "value": { "anyOf": [ { "$ref": "#/components/schemas/AgentTurnSandboxElevationsResponse" }, { "type": "null" } ], "default": null } }, "required": [ "status" ], "title": "AgentTurnPreparedSandboxElevations", "type": "object" }, "AgentTurnPreparedSessionSeed": { "properties": { "code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Why the block was omitted.", "title": "Code" }, "status": { "enum": [ "ok", "omitted" ], "title": "Status", "type": "string" }, "value": { "anyOf": [ { "$ref": "#/components/schemas/AgentTurnSessionSeed" }, { "type": "null" } ], "default": null } }, "required": [ "status" ], "title": "AgentTurnPreparedSessionSeed", "type": "object" }, "AgentTurnPreparedSiblingConversations": { "properties": { "code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Why the block was omitted.", "title": "Code" }, "status": { "enum": [ "ok", "omitted" ], "title": "Status", "type": "string" }, "value": { "anyOf": [ { "$ref": "#/components/schemas/AgentTurnSiblingConversations" }, { "type": "null" } ], "default": null } }, "required": [ "status" ], "title": "AgentTurnPreparedSiblingConversations", "type": "object" }, "AgentTurnPreparedToolCredentials": { "properties": { "code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Why the block was omitted.", "title": "Code" }, "status": { "enum": [ "ok", "omitted" ], "title": "Status", "type": "string" }, "value": { "anyOf": [ { "$ref": "#/components/schemas/MaterializeResponse" }, { "type": "null" } ], "default": null } }, "required": [ "status" ], "title": "AgentTurnPreparedToolCredentials", "type": "object" }, "AgentTurnPreparedWorkshopPolicy": { "properties": { "code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Why the block was omitted.", "title": "Code" }, "status": { "enum": [ "ok", "omitted" ], "title": "Status", "type": "string" }, "value": { "anyOf": [ { "$ref": "#/components/schemas/WorkshopPolicyResponse" }, { "type": "null" } ], "default": null } }, "required": [ "status" ], "title": "AgentTurnPreparedWorkshopPolicy", "type": "object" }, "AgentTurnProject": { "description": "The Tidy project a turn is working in (TIDY-19606).", "properties": { "id": { "description": "Typed project id (`P-`).", "title": "Id", "type": "string" }, "name": { "title": "Name", "type": "string" }, "shortcode": { "description": "The project's short-id prefix (`TIDYMAIN`).", "title": "Shortcode", "type": "string" } }, "required": [ "id", "name", "shortcode" ], "title": "AgentTurnProject", "type": "object" }, "AgentTurnProjectFolder": { "description": "A project folder a turn's readers may see (TIDY-19869 M2).", "properties": { "name": { "description": "The project's name, as the employee is told it.", "title": "Name", "type": "string" }, "path": { "description": "The stored root, `~/tidy/projects/-`, relative to the workshop home. The connector links it into the turn's own home under the same name.", "title": "Path", "type": "string" }, "project_id": { "description": "Typed id of the project (`P-`).", "title": "Project Id", "type": "string" }, "secret_file_paths": { "description": "Paths in the folder, relative to it, that a Tidy secret file deploys to on the employee's workshop (TIDY-20046). The connector tells an employee that wrote a secret-shaped file into the folder to propose it through Tidy, never for these.", "items": { "type": "string" }, "title": "Secret File Paths", "type": "array" } }, "required": [ "path", "project_id", "name" ], "title": "AgentTurnProjectFolder", "type": "object" }, "AgentTurnRestartLoss": { "description": "One thing a restart cancelled before it finished (TIDY-19938): a\nbackground command, watch, subagent or detached run (``process``), or a\nworkshop job started for the conversation (``job``).", "properties": { "detail": { "default": "", "maxLength": 500, "title": "Detail", "type": "string" }, "kind": { "enum": [ "process", "job" ], "title": "Kind", "type": "string" }, "label": { "maxLength": 300, "title": "Label", "type": "string" }, "started_at": { "title": "Started At", "type": "string" } }, "required": [ "kind", "label", "started_at" ], "title": "AgentTurnRestartLoss", "type": "object" }, "AgentTurnRestartLosses": { "description": "TIDY-19938 (F14): what a connector or workshop restart cancelled in this\nconversation since its last turn — background commands, watches,\nsubagents, workshop jobs. None of it reports back on its own.", "properties": { "losses": { "description": "Newest first, at most 8.", "items": { "$ref": "#/components/schemas/AgentTurnRestartLoss" }, "title": "Losses", "type": "array" }, "total": { "description": "How many there are in all; the rest are counted.", "minimum": 0, "title": "Total", "type": "integer" } }, "required": [ "total" ], "title": "AgentTurnRestartLosses", "type": "object" }, "AgentTurnSandboxElevationsRequest": { "properties": { "credential_id": { "format": "uuid", "title": "Credential Id", "type": "string" } }, "required": [ "credential_id" ], "title": "AgentTurnSandboxElevationsRequest", "type": "object" }, "AgentTurnSandboxElevationsResponse": { "properties": { "grants": { "items": { "$ref": "#/components/schemas/AgentTurnSandboxGrant" }, "title": "Grants", "type": "array" } }, "required": [ "grants" ], "title": "AgentTurnSandboxElevationsResponse", "type": "object" }, "AgentTurnSandboxExercisedRequest": { "properties": { "credential_id": { "format": "uuid", "title": "Credential Id", "type": "string" }, "elevation_ids": { "items": { "format": "uuid", "type": "string" }, "maxItems": 50, "title": "Elevation Ids", "type": "array" } }, "required": [ "credential_id", "elevation_ids" ], "title": "AgentTurnSandboxExercisedRequest", "type": "object" }, "AgentTurnSandboxExercisedResponse": { "properties": { "recorded": { "items": { "type": "string" }, "title": "Recorded", "type": "array" } }, "required": [ "recorded" ], "title": "AgentTurnSandboxExercisedResponse", "type": "object" }, "AgentTurnSandboxGrant": { "properties": { "expires_at": { "format": "date-time", "title": "Expires At", "type": "string" }, "id": { "title": "Id", "type": "string" }, "kind": { "enum": [ "docker_mount", "docker_container" ], "title": "Kind", "type": "string" }, "scope": { "enum": [ "once", "project", "employee" ], "title": "Scope", "type": "string" }, "spec": { "additionalProperties": true, "title": "Spec", "type": "object" } }, "required": [ "id", "kind", "spec", "scope", "expires_at" ], "title": "AgentTurnSandboxGrant", "type": "object" }, "AgentTurnSessionSeed": { "description": "TIDY-19939 (F15): what an empty native session's first turn is given — the\nitem, its latest completion report and the earlier work that fits the\nmodel's window, each part attributed — or why it cannot be.", "properties": { "budget_tokens": { "default": 0, "minimum": 0, "title": "Budget Tokens", "type": "integer" }, "included_count": { "default": 0, "minimum": 0, "title": "Included Count", "type": "integer" }, "omitted_count": { "default": 0, "minimum": 0, "title": "Omitted Count", "type": "integer" }, "over_budget": { "anyOf": [ { "$ref": "#/components/schemas/AgentTurnSessionSeedOverBudget" }, { "type": "null" } ], "default": null, "description": "The leading parts do not fit beside the request: the turn fails by name." }, "rotate": { "default": false, "description": "An earlier hand-out to this native session was never proven delivered: open a fresh native session before using this one, so nothing is injected twice.", "title": "Rotate", "type": "boolean" }, "seed_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Seed Id" }, "text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Text" } }, "title": "AgentTurnSessionSeed", "type": "object" }, "AgentTurnSessionSeedOverBudget": { "properties": { "budget_tokens": { "minimum": 0, "title": "Budget Tokens", "type": "integer" }, "needed_tokens": { "minimum": 0, "title": "Needed Tokens", "type": "integer" }, "window_tokens": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Window Tokens" } }, "required": [ "needed_tokens", "budget_tokens" ], "title": "AgentTurnSessionSeedOverBudget", "type": "object" }, "AgentTurnSiblingConversation": { "description": "One of the employee's own conversations running in a starting turn's folder.", "properties": { "conversation_ref": { "description": "The running conversation, `H-`.", "title": "Conversation Ref", "type": "string" }, "items": { "description": "The work it is on (`A-`), only what the turn's person may see.", "items": { "type": "string" }, "title": "Items", "type": "array" } }, "required": [ "conversation_ref" ], "title": "AgentTurnSiblingConversation", "type": "object" }, "AgentTurnSiblingConversations": { "properties": { "context": { "default": "", "description": "The rendered block to put ahead of the turn's prompt.", "title": "Context", "type": "string" }, "conversations": { "description": "Oldest first; empty when none is running there.", "items": { "$ref": "#/components/schemas/AgentTurnSiblingConversation" }, "title": "Conversations", "type": "array" } }, "title": "AgentTurnSiblingConversations", "type": "object" }, "AgentTurnTeammate": { "description": "Someone the employee works with, as every reader of its room sees them (TIDY-19750).", "properties": { "display_name": { "title": "Display Name", "type": "string" }, "employee_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Employee Status" }, "in_room": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "description": "Whether they are in this room; null for a card with no account", "title": "In Room" }, "kind": { "enum": [ "employee", "member", "contact" ], "title": "Kind", "type": "string" }, "mention_handle": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Mention Handle" }, "relation": { "description": "Its manager or a direct report on the team Org chart, or another employee in this project's room", "enum": [ "manager", "direct_report", "colleague" ], "title": "Relation", "type": "string" } }, "required": [ "relation", "display_name", "kind" ], "title": "AgentTurnTeammate", "type": "object" }, "AgentUnsuppressRequest": { "description": "Clear the loop detector's suppression on one conversation.", "properties": { "conversation_id": { "title": "Conversation Id", "type": "string" } }, "required": [ "conversation_id" ], "title": "AgentUnsuppressRequest", "type": "object" }, "AgentUnsuppressResponse": { "properties": { "cleared": { "title": "Cleared", "type": "boolean" }, "conversation_id": { "title": "Conversation Id", "type": "string" }, "signal": { "title": "Signal", "type": "string" } }, "required": [ "conversation_id", "cleared", "signal" ], "title": "AgentUnsuppressResponse", "type": "object" }, "AgentUpdateDirective": { "description": "TIDY-16106 (D34) — the update directive carried by a heartbeat response.\n\nAbsent means \"nothing to do\". A connector that does not understand it is\nunaffected: the client parser tolerates unknown response fields.", "properties": { "directive_id": { "format": "uuid", "title": "Directive Id", "type": "string" }, "release_index_sha256": { "pattern": "^[0-9a-f]{64}$", "title": "Release Index Sha256", "type": "string" }, "release_index_url": { "title": "Release Index Url", "type": "string" }, "target_version": { "title": "Target Version", "type": "string" }, "urgency": { "enum": [ "routine", "compatibility", "security" ], "title": "Urgency", "type": "string" } }, "required": [ "directive_id", "target_version", "release_index_url", "release_index_sha256", "urgency" ], "title": "AgentUpdateDirective", "type": "object" }, "AgentUpdatePhaseReport": { "description": "TIDY-16106 — one self-update phase the connector reports back.\n\nRides the heartbeat request rather than a second endpoint, for the same\nreason the directive rides the response: the connector is outbound-only and\nalready fenced on this call.", "properties": { "detail": { "anyOf": [ { "maxLength": 500, "type": "string" }, { "type": "null" } ], "title": "Detail" }, "directive_id": { "format": "uuid", "title": "Directive Id", "type": "string" }, "phase": { "enum": [ "accepted", "declined", "downloaded", "verified", "handed_off", "proved", "committed", "rolled_back", "failed" ], "title": "Phase", "type": "string" } }, "required": [ "directive_id", "phase" ], "title": "AgentUpdatePhaseReport", "type": "object" }, "AgentUpdatePolicyRequest": { "description": "Operator control for one installation's update policy / consent.", "properties": { "policy": { "anyOf": [ { "enum": [ "automatic", "notify", "manual" ], "type": "string" }, { "type": "null" } ], "title": "Policy" }, "update_now": { "default": false, "title": "Update Now", "type": "boolean" } }, "title": "AgentUpdatePolicyRequest", "type": "object" }, "AgentUpdatePolicyResponse": { "properties": { "account_id": { "title": "Account Id", "type": "string" }, "update_policy": { "enum": [ "automatic", "notify", "manual" ], "title": "Update Policy", "type": "string" }, "update_state": { "enum": [ "idle", "pending", "updating", "failed" ], "title": "Update State", "type": "string" }, "update_target_version": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Update Target Version" } }, "required": [ "account_id", "update_policy", "update_state" ], "title": "AgentUpdatePolicyResponse", "type": "object" }, "AgentWakeDecision": { "description": "One row of the append-only wake-decision audit (A2 writes it).", "properties": { "clauses": { "additionalProperties": true, "title": "Clauses", "type": "object" }, "conversation_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Conversation Id" }, "conversation_title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Conversation Title" }, "created_primitives": { "items": {}, "title": "Created Primitives", "type": "array" }, "decided_at": { "format": "date-time", "title": "Decided At", "type": "string" }, "decision": { "enum": [ "wake", "suppressed" ], "title": "Decision", "type": "string" }, "decision_class": { "default": "work-stall", "title": "Decision Class", "type": "string" }, "decision_key": { "title": "Decision Key", "type": "string" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Error" }, "id": { "title": "Id", "type": "string" }, "message_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Message Id" }, "proposal_counts": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "title": "Proposal Counts" }, "resume_mode": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Resume Mode" }, "suppression_class": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Suppression Class" } }, "required": [ "id", "decided_at", "decision", "decision_key" ], "title": "AgentWakeDecision", "type": "object" }, "AgentWakeDecisionsResponse": { "properties": { "decisions": { "items": { "$ref": "#/components/schemas/AgentWakeDecision" }, "title": "Decisions", "type": "array" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Next Cursor" } }, "title": "AgentWakeDecisionsResponse", "type": "object" }, "AggregateRow": { "description": "Generic aggregate row — fields populated depend on group_by.", "properties": { "account_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "default": null, "title": "Account Id" }, "billable_cost_usd": { "title": "Billable Cost Usd", "type": "number" }, "billable_quantity": { "title": "Billable Quantity", "type": "number" }, "channel": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Channel" }, "day": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Day" }, "event_count": { "title": "Event Count", "type": "integer" }, "failure_count": { "title": "Failure Count", "type": "integer" }, "provider": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Provider" }, "resource_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Resource Type" }, "service_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Service Name" }, "status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Status" }, "success_count": { "title": "Success Count", "type": "integer" }, "tenant_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "default": null, "title": "Tenant Id" }, "tool_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Tool Name" } }, "required": [ "event_count", "billable_quantity", "billable_cost_usd", "success_count", "failure_count" ], "title": "AggregateRow", "type": "object" }, "AgingBucket": { "properties": { "bucket": { "title": "Bucket", "type": "string" }, "count": { "title": "Count", "type": "integer" } }, "required": [ "bucket", "count" ], "title": "AgingBucket", "type": "object" }, "AiDraftEditMetricsResponse": { "description": "Send-without-edit rate + median edit distance for AI drafts (S5).", "properties": { "mean_edit_distance": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "title": "Mean Edit Distance" }, "median_edit_distance": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "title": "Median Edit Distance" }, "scope": { "title": "Scope", "type": "string" }, "send_without_edit_count": { "title": "Send Without Edit Count", "type": "integer" }, "send_without_edit_rate": { "title": "Send Without Edit Rate", "type": "number" }, "sent_count": { "title": "Sent Count", "type": "integer" } }, "required": [ "scope", "sent_count", "send_without_edit_count", "send_without_edit_rate" ], "title": "AiDraftEditMetricsResponse", "type": "object" }, "AiEmployeeItem": { "additionalProperties": true, "properties": { "display_name": { "minLength": 1, "title": "Display Name", "type": "string" }, "mcp_servers": { "items": { "$ref": "#/components/schemas/AiEmployeeMcpServerItem" }, "title": "Mcp Servers", "type": "array" }, "mention_handle": { "anyOf": [ { "maxLength": 80, "minLength": 2, "type": "string" }, { "type": "null" } ], "title": "Mention Handle" }, "model_tier": { "default": "medium", "enum": [ "low", "medium", "high" ], "title": "Model Tier", "type": "string" }, "ref": { "description": "Unique reference within the definition", "minLength": 1, "title": "Ref", "type": "string" }, "skills": { "items": { "type": "string" }, "title": "Skills", "type": "array" }, "system_prompt_slice": { "default": "", "title": "System Prompt Slice", "type": "string" }, "tool_groups": { "items": { "type": "string" }, "title": "Tool Groups", "type": "array" } }, "required": [ "ref", "display_name" ], "title": "AiEmployeeItem", "type": "object" }, "AiEmployeeMcpServerItem": { "additionalProperties": false, "description": "One MCP server an AI-employee persona names (R10, TIDY-14047).\n\nSecret-free by construction: ``extra='forbid'`` rejects any secret-bearing\nfield (``secret_value``/``credential_id``/``api_key``/``access_token``/…)\nwith a 422, so a template can NAME the server + its public auth config but\ncan NEVER ship a credential. Auth is (re)established per install by the user\n(the needs-setup checklist), never carried in the definition.", "properties": { "auth_method": { "default": "none", "enum": [ "none", "oauth", "bearer_token", "api_key", "pat" ], "title": "Auth Method", "type": "string" }, "connection_type": { "default": "external", "enum": [ "internal", "external" ], "title": "Connection Type", "type": "string" }, "endpoint_url": { "maxLength": 2048, "minLength": 1, "title": "Endpoint Url", "type": "string" }, "name": { "maxLength": 120, "minLength": 1, "title": "Name", "type": "string" }, "oauth_authorize_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Oauth Authorize Url" }, "oauth_client_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Oauth Client Id" }, "oauth_scope": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Oauth Scope" }, "oauth_token_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Oauth Token Url" } }, "required": [ "name", "endpoint_url" ], "title": "AiEmployeeMcpServerItem", "type": "object" }, "AiExtractItem": { "description": "One text to extract from. ``id`` is the caller's correlation key.", "properties": { "id": { "maxLength": 255, "minLength": 1, "title": "Id", "type": "string" }, "text": { "maxLength": 100000, "minLength": 1, "title": "Text", "type": "string" } }, "required": [ "id", "text" ], "title": "AiExtractItem", "type": "object" }, "AiExtractRequest": { "properties": { "instructions": { "anyOf": [ { "maxLength": 4000, "type": "string" }, { "type": "null" } ], "description": "Optional task framing prepended to every extraction call.", "title": "Instructions" }, "items": { "items": { "$ref": "#/components/schemas/AiExtractItem" }, "maxItems": 50, "minItems": 1, "title": "Items", "type": "array" }, "json_schema": { "additionalProperties": true, "description": "JSON schema for the fields to extract. Subset: root object with 'properties'; types string/number/integer/boolean/object/array; nullable via ['', 'null']; 'enum'; 'description'; 'required'. No $ref/anyOf/oneOf/allOf.", "title": "Json Schema", "type": "object" }, "trace_id": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "title": "Trace Id" } }, "required": [ "json_schema", "items" ], "title": "AiExtractRequest", "type": "object" }, "AiExtractResponse": { "properties": { "failed": { "title": "Failed", "type": "integer" }, "model": { "title": "Model", "type": "string" }, "results": { "items": { "$ref": "#/components/schemas/AiExtractResult" }, "title": "Results", "type": "array" }, "succeeded": { "title": "Succeeded", "type": "integer" }, "total_tokens": { "title": "Total Tokens", "type": "integer" } }, "required": [ "results", "model", "succeeded", "failed", "total_tokens" ], "title": "AiExtractResponse", "type": "object" }, "AiExtractResult": { "properties": { "data": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "title": "Data" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Error" }, "id": { "title": "Id", "type": "string" }, "ok": { "title": "Ok", "type": "boolean" } }, "required": [ "id", "ok" ], "title": "AiExtractResult", "type": "object" }, "AiProviderSplitResponse": { "description": "The tenant's cloud-vs-desktop AI usage split over a rolling window.\n\n``total`` equals ``cloud + desktop`` (calls + cost) — the reconciliation\ninvariant against ``llm_usage_logs``. ``daily`` is the per-UTC-day series.", "properties": { "cloud": { "$ref": "#/components/schemas/ProviderUsage" }, "daily": { "items": { "$ref": "#/components/schemas/DailyProviderUsage" }, "title": "Daily", "type": "array" }, "desktop": { "$ref": "#/components/schemas/ProviderUsage" }, "total": { "$ref": "#/components/schemas/ProviderUsage" }, "window_days": { "title": "Window Days", "type": "integer" } }, "required": [ "window_days", "cloud", "desktop", "total", "daily" ], "title": "AiProviderSplitResponse", "type": "object" }, "AlertDetail": { "properties": { "alert_type": { "title": "Alert Type", "type": "string" }, "contact_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Contact Id" }, "contact_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Contact Name" }, "message": { "title": "Message", "type": "string" }, "severity": { "title": "Severity", "type": "string" } }, "required": [ "contact_name", "contact_id", "alert_type", "message", "severity" ], "title": "AlertDetail", "type": "object" }, "AlertPreference": { "properties": { "cadence": { "title": "Cadence", "type": "string" }, "channel": { "title": "Channel", "type": "string" }, "enabled": { "title": "Enabled", "type": "boolean" }, "event_type": { "title": "Event Type", "type": "string" } }, "required": [ "event_type", "channel", "cadence", "enabled" ], "title": "AlertPreference", "type": "object" }, "AlertPreferenceUpsert": { "properties": { "cadence": { "default": "immediate", "title": "Cadence", "type": "string" }, "channel": { "title": "Channel", "type": "string" }, "enabled": { "default": true, "title": "Enabled", "type": "boolean" }, "event_type": { "title": "Event Type", "type": "string" } }, "required": [ "event_type", "channel" ], "title": "AlertPreferenceUpsert", "type": "object" }, "AliasObject": { "description": "Full alias representation including visibility.", "properties": { "address": { "title": "Address", "type": "string" }, "display_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Display Name" }, "is_visible": { "default": true, "title": "Is Visible", "type": "boolean" } }, "required": [ "address" ], "title": "AliasObject", "type": "object" }, "AliasPreferencesRequest": { "description": "Update alias visibility settings.", "properties": { "aliases": { "description": "Alias visibility updates", "items": { "$ref": "#/components/schemas/AliasVisibilityItem" }, "title": "Aliases", "type": "array" } }, "required": [ "aliases" ], "title": "AliasPreferencesRequest", "type": "object" }, "AliasPreferencesResponse": { "description": "Response with full alias list after update.", "properties": { "aliases": { "items": { "$ref": "#/components/schemas/AliasObject" }, "title": "Aliases", "type": "array" }, "connection_id": { "title": "Connection Id", "type": "string" } }, "required": [ "connection_id", "aliases" ], "title": "AliasPreferencesResponse", "type": "object" }, "AliasVisibilityItem": { "description": "Single alias visibility update.", "properties": { "address": { "description": "Alias email address", "title": "Address", "type": "string" }, "is_visible": { "description": "Whether alias appears in compose", "title": "Is Visible", "type": "boolean" } }, "required": [ "address", "is_visible" ], "title": "AliasVisibilityItem", "type": "object" }, "AllowOnceResponse": { "properties": { "emails_routed": { "default": 0, "title": "Emails Routed", "type": "integer" }, "status": { "default": "allowed_once", "title": "Status", "type": "string" } }, "title": "AllowOnceResponse", "type": "object" }, "AllowanceSnoozeRequest": { "additionalProperties": false, "properties": { "until": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "UTC instant to snooze until; the provider-named reset. Omitted when the provider named no reset — the item snoozes one hour.", "title": "Until" } }, "title": "AllowanceSnoozeRequest", "type": "object" }, "AllowanceSnoozeResult": { "properties": { "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Reason" }, "snoozed_until": { "title": "Snoozed Until", "type": "string" } }, "required": [ "snoozed_until" ], "title": "AllowanceSnoozeResult", "type": "object" }, "AllowlistEntryRequest": { "properties": { "account_id": { "format": "uuid", "title": "Account Id", "type": "string" } }, "required": [ "account_id" ], "title": "AllowlistEntryRequest", "type": "object" }, "AlternativeProposalModel": { "description": "One proposal — exactly the schema TIDY-15405 consumes.", "properties": { "end": { "format": "date-time", "title": "End", "type": "string" }, "floating": { "title": "Floating", "type": "boolean" }, "not_evaluated_beyond": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "description": "Set when the conflict evaluation could not see past this instant. A proposal carrying it may NOT be applied until a re-check of its exact range comes back clear and complete.", "title": "Not Evaluated Beyond" }, "proposal_id": { "title": "Proposal Id", "type": "string" }, "provider_action": { "enum": [ "accept", "counter" ], "title": "Provider Action", "type": "string" }, "recurrence_scope": { "enum": [ "this_occurrence", "future", "series" ], "title": "Recurrence Scope", "type": "string" }, "start": { "format": "date-time", "title": "Start", "type": "string" }, "timezone": { "title": "Timezone", "type": "string" }, "travel_buffer_after_minutes": { "title": "Travel Buffer After Minutes", "type": "integer" }, "travel_buffer_before_minutes": { "title": "Travel Buffer Before Minutes", "type": "integer" } }, "required": [ "proposal_id", "start", "end", "timezone", "floating", "recurrence_scope", "travel_buffer_before_minutes", "travel_buffer_after_minutes", "provider_action" ], "title": "AlternativeProposalModel", "type": "object" }, "AlternativeRecheckRequest": { "description": "One proposal, re-evaluated against its own exact range.", "properties": { "all_day": { "default": false, "description": "Treat the range as an all-day date range", "title": "All Day", "type": "boolean" }, "end_time": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "End Time" }, "exclude_event_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Event ID to exclude from conflict check (for updates)", "title": "Exclude Event Id" }, "floating": { "default": false, "description": "The event's times are floating wall-clock values in its own timezone. Alternatives preserve the wall clock across DST rather than the UTC instant.", "title": "Floating", "type": "boolean" }, "horizon_days": { "default": 14, "description": "How many days ahead the search may walk.", "maximum": 60.0, "minimum": 1.0, "title": "Horizon Days", "type": "integer" }, "ical_uid": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Normalized iCalUID. The only identity used for double-booking and provider-divergence detection; without it neither is inferred from title or proximity.", "title": "Ical Uid" }, "max_alternatives": { "default": 5, "description": "At most 5 proposals are ever returned.", "maximum": 5.0, "minimum": 1.0, "title": "Max Alternatives", "type": "integer" }, "proposal_id": { "description": "The proposal_id returned by /events/alternatives.", "title": "Proposal Id", "type": "string" }, "recurrence_rule": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Bare RRULE value, e.g. FREQ=WEEKLY;BYDAY=MO", "title": "Recurrence Rule" }, "recurrence_scope": { "default": "this_occurrence", "description": "Which occurrences the mutation affects: this_occurrence | future | series", "title": "Recurrence Scope", "type": "string" }, "resource_ids": { "description": "Room/resource identifiers the event claims", "items": { "type": "string" }, "title": "Resource Ids", "type": "array" }, "start_time": { "format": "date-time", "title": "Start Time", "type": "string" }, "timezone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "IANA timezone for all-day and floating values. Required when all_day is true — an all-day range is anchored to local midnight, never UTC midnight, and no timezone is ever assumed.", "title": "Timezone" }, "travel_buffer_after_minutes": { "default": 0, "description": "Travel time needed after the event; participates in detection", "minimum": 0.0, "title": "Travel Buffer After Minutes", "type": "integer" }, "travel_buffer_before_minutes": { "default": 0, "description": "Travel time needed before the event; participates in detection", "minimum": 0.0, "title": "Travel Buffer Before Minutes", "type": "integer" } }, "required": [ "start_time", "proposal_id" ], "title": "AlternativeRecheckRequest", "type": "object" }, "AlternativeRecheckResponse": { "description": "The apply gate's verdict for one proposal.", "properties": { "apply_allowed": { "title": "Apply Allowed", "type": "boolean" }, "block_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "conflict_on_recheck | truncated_on_recheck | stale_watermark | recheck_range_mismatch", "title": "Block Reason" }, "conflict_kinds": { "items": { "type": "string" }, "title": "Conflict Kinds", "type": "array" }, "evaluated_through": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Evaluated Through" }, "proposal_id": { "title": "Proposal Id", "type": "string" }, "truncated": { "default": false, "title": "Truncated", "type": "boolean" }, "warnings": { "items": { "type": "string" }, "title": "Warnings", "type": "array" } }, "required": [ "proposal_id", "apply_allowed" ], "title": "AlternativeRecheckResponse", "type": "object" }, "AlternativesRequest": { "description": "A conflict check, plus how far and how wide to look for alternatives.", "properties": { "all_day": { "default": false, "description": "Treat the range as an all-day date range", "title": "All Day", "type": "boolean" }, "end_time": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "End Time" }, "exclude_event_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Event ID to exclude from conflict check (for updates)", "title": "Exclude Event Id" }, "floating": { "default": false, "description": "The event's times are floating wall-clock values in its own timezone. Alternatives preserve the wall clock across DST rather than the UTC instant.", "title": "Floating", "type": "boolean" }, "horizon_days": { "default": 14, "description": "How many days ahead the search may walk.", "maximum": 60.0, "minimum": 1.0, "title": "Horizon Days", "type": "integer" }, "ical_uid": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Normalized iCalUID. The only identity used for double-booking and provider-divergence detection; without it neither is inferred from title or proximity.", "title": "Ical Uid" }, "max_alternatives": { "default": 5, "description": "At most 5 proposals are ever returned.", "maximum": 5.0, "minimum": 1.0, "title": "Max Alternatives", "type": "integer" }, "recurrence_rule": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Bare RRULE value, e.g. FREQ=WEEKLY;BYDAY=MO", "title": "Recurrence Rule" }, "recurrence_scope": { "default": "this_occurrence", "description": "Which occurrences the mutation affects: this_occurrence | future | series", "title": "Recurrence Scope", "type": "string" }, "resource_ids": { "description": "Room/resource identifiers the event claims", "items": { "type": "string" }, "title": "Resource Ids", "type": "array" }, "start_time": { "format": "date-time", "title": "Start Time", "type": "string" }, "timezone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "IANA timezone for all-day and floating values. Required when all_day is true — an all-day range is anchored to local midnight, never UTC midnight, and no timezone is ever assumed.", "title": "Timezone" }, "travel_buffer_after_minutes": { "default": 0, "description": "Travel time needed after the event; participates in detection", "minimum": 0.0, "title": "Travel Buffer After Minutes", "type": "integer" }, "travel_buffer_before_minutes": { "default": 0, "description": "Travel time needed before the event; participates in detection", "minimum": 0.0, "title": "Travel Buffer Before Minutes", "type": "integer" } }, "required": [ "start_time" ], "title": "AlternativesRequest", "type": "object" }, "AlternativesResponse": { "description": "Bounded proposals plus the honesty fields that make them usable.\n\nThere is no pagination on purpose: a second page would be computed against a\nnewer watermark, so it could contradict the first. ``candidate_count`` says\nhow many viable slots the bounded search actually saw; when\n``alternatives_truncated`` is true, more exist beyond what was returned.", "properties": { "alternatives": { "items": { "$ref": "#/components/schemas/AlternativeProposalModel" }, "title": "Alternatives", "type": "array" }, "alternatives_truncated": { "default": false, "title": "Alternatives Truncated", "type": "boolean" }, "candidate_count": { "default": 0, "title": "Candidate Count", "type": "integer" }, "has_conflicts": { "description": "Whether the requested time itself conflicts", "title": "Has Conflicts", "type": "boolean" }, "not_evaluated_beyond": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Not Evaluated Beyond" }, "refusal_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Why no alternative is offered: no_alternative_within_horizon | search_budget_exhausted. Never a silent reschedule.", "title": "Refusal Reason" }, "warnings": { "items": { "type": "string" }, "title": "Warnings", "type": "array" } }, "required": [ "has_conflicts" ], "title": "AlternativesResponse", "type": "object" }, "AnchorResolveResponse": { "description": "R19 anchor resolution outcome. A miss is a VALID answer carrying the\nthen-vs-now offer or a named reason — never a silent empty.", "properties": { "content_hash": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Content Hash" }, "file_version": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "title": "File Version" }, "path": { "title": "Path", "type": "string" }, "provider": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "title": "Provider" }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Reason" }, "resolved_by": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Resolved By" }, "then_vs_now": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "title": "Then Vs Now" } }, "required": [ "path" ], "title": "AnchorResolveResponse", "type": "object" }, "AnomalyAlertItem": { "properties": { "anomaly_type": { "title": "Anomaly Type", "type": "string" }, "baseline_value": { "title": "Baseline Value", "type": "number" }, "current_value": { "title": "Current Value", "type": "number" }, "description": { "title": "Description", "type": "string" }, "detected_at": { "title": "Detected At", "type": "string" }, "dismissed": { "title": "Dismissed", "type": "boolean" }, "metric_name": { "title": "Metric Name", "type": "string" }, "recommendation": { "title": "Recommendation", "type": "string" }, "record_id": { "title": "Record Id", "type": "string" }, "severity": { "title": "Severity", "type": "string" }, "z_score": { "title": "Z Score", "type": "number" } }, "required": [ "record_id", "anomaly_type", "metric_name", "current_value", "baseline_value", "z_score", "severity", "description", "recommendation", "detected_at", "dismissed" ], "title": "AnomalyAlertItem", "type": "object" }, "AnswerQuestionRequest": { "properties": { "limit": { "default": 8, "maximum": 20.0, "minimum": 1.0, "title": "Limit", "type": "integer" }, "question": { "maxLength": 1000, "minLength": 1, "title": "Question", "type": "string" }, "room_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Room Id" } }, "required": [ "question" ], "title": "AnswerQuestionRequest", "type": "object" }, "AnswerQuestionResponse": { "properties": { "answer": { "title": "Answer", "type": "string" }, "citations": { "items": { "$ref": "#/components/schemas/SuggestedEmbed" }, "title": "Citations", "type": "array" }, "elapsed_ms": { "title": "Elapsed Ms", "type": "integer" } }, "required": [ "answer", "citations", "elapsed_ms" ], "title": "AnswerQuestionResponse", "type": "object" }, "AnswerResponse": { "properties": { "huddle_id": { "format": "uuid", "title": "Huddle Id", "type": "string" }, "join_deadline": { "format": "date-time", "title": "Join Deadline", "type": "string" }, "join_token": { "title": "Join Token", "type": "string" }, "recipient_state": { "title": "Recipient State", "type": "string" }, "ring_id": { "format": "uuid", "title": "Ring Id", "type": "string" }, "session_state": { "title": "Session State", "type": "string" } }, "required": [ "ring_id", "huddle_id", "session_state", "recipient_state", "join_deadline", "join_token" ], "title": "AnswerResponse", "type": "object" }, "AppPasswordRequest": { "description": "Store an app-specific password for IMAP connections (Zoho, Apple).", "properties": { "app_password": { "description": "App-specific password for IMAP", "minLength": 1, "title": "App Password", "type": "string" } }, "required": [ "app_password" ], "title": "AppPasswordRequest", "type": "object" }, "AppendPlacement": { "additionalProperties": false, "description": "At the end of the body.", "properties": { "mode": { "const": "append", "title": "Mode", "type": "string" } }, "required": [ "mode" ], "title": "AppendPlacement", "type": "object" }, "AppendSectionOp": { "additionalProperties": false, "properties": { "markdown": { "maxLength": 100000, "minLength": 1, "title": "Markdown", "type": "string" }, "op": { "const": "append_section", "title": "Op", "type": "string" } }, "required": [ "op", "markdown" ], "title": "AppendSectionOp", "type": "object" }, "AppliedPluginAccess": { "properties": { "grant_id": { "title": "Grant Id", "type": "string" }, "lent": { "title": "Lent", "type": "boolean" }, "plugin_id": { "title": "Plugin Id", "type": "string" }, "plugin_kind": { "title": "Plugin Kind", "type": "string" }, "replaced_shipment_ids": { "items": { "type": "string" }, "title": "Replaced Shipment Ids", "type": "array" }, "shipment_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Shipment Id" }, "shipped": { "title": "Shipped", "type": "boolean" }, "workshop_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Workshop Id" } }, "required": [ "plugin_kind", "plugin_id", "grant_id", "lent", "shipped" ], "title": "AppliedPluginAccess", "type": "object" }, "ApplyCouponRequest": { "properties": { "coupon_id": { "title": "Coupon Id", "type": "string" } }, "required": [ "coupon_id" ], "title": "ApplyCouponRequest", "type": "object" }, "ApplyEventUpdateRequest": { "properties": { "candidate_event_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional explicit merge target. Defaults to the pending fuzzy match candidate.", "title": "Candidate Event Id" } }, "title": "ApplyEventUpdateRequest", "type": "object" }, "ApplyEventUpdateResponse": { "properties": { "merge_status": { "const": "updated_existing", "title": "Merge Status", "type": "string" }, "pending_event_id": { "title": "Pending Event Id", "type": "string" }, "updated_event_id": { "title": "Updated Event Id", "type": "string" } }, "required": [ "pending_event_id", "updated_event_id", "merge_status" ], "title": "ApplyEventUpdateResponse", "type": "object" }, "ApplyResponse": { "properties": { "applied": { "title": "Applied", "type": "integer" }, "errors": { "items": { "additionalProperties": true, "type": "object" }, "title": "Errors", "type": "array" } }, "required": [ "applied", "errors" ], "title": "ApplyResponse", "type": "object" }, "ApprovalActionResponse": { "description": "Response for approve/reject actions.", "properties": { "id": { "title": "Id", "type": "string" }, "status": { "title": "Status", "type": "string" }, "type": { "title": "Type", "type": "string" }, "updated_at": { "format": "date-time", "title": "Updated At", "type": "string" } }, "required": [ "id", "type", "status", "updated_at" ], "title": "ApprovalActionResponse", "type": "object" }, "ApprovalApproveRequest": { "additionalProperties": false, "description": "Optional approve body carrying the approval-destination choice.\n\nNo body, `{}` and `{\"destination\": null}` all mean one-click approve to the\nmember's default — the compatibility contract every existing client relies\non (TIDY-17980 / D8).", "properties": { "destination": { "anyOf": [ { "$ref": "#/components/schemas/ApprovalDestination" }, { "type": "null" } ] } }, "title": "ApprovalApproveRequest", "type": "object" }, "ApprovalCountsResponse": { "description": "Response for approval counts grouped by date.", "properties": { "older": { "additionalProperties": true, "title": "Older", "type": "object" }, "today": { "additionalProperties": true, "title": "Today", "type": "object" }, "total": { "default": 0, "title": "Total", "type": "integer" } }, "title": "ApprovalCountsResponse", "type": "object" }, "ApprovalDestination": { "additionalProperties": false, "description": "TIDY-15323: a facet's `approval_destination` placement choice — the\nfield named by the facet config (e.g. `collection_id` for events) and the\npicked value (destination calendar collection id).\n\nTIDY-17980: unknown properties are refused. A destination is an instruction;\na misspelled key that silently degraded to \"no destination\" would route a\ndeliberately chosen event to the default calendar instead.", "properties": { "field": { "maxLength": 64, "title": "Field", "type": "string" }, "value": { "maxLength": 128, "title": "Value", "type": "string" } }, "required": [ "field", "value" ], "title": "ApprovalDestination", "type": "object" }, "ApprovalDismissResponse": { "description": "Response for the per-user 'not now' dismiss action (TIDY-15323).", "properties": { "id": { "title": "Id", "type": "string" }, "status": { "title": "Status", "type": "string" }, "type": { "title": "Type", "type": "string" }, "updated_at": { "format": "date-time", "title": "Updated At", "type": "string" } }, "required": [ "id", "type", "status", "updated_at" ], "title": "ApprovalDismissResponse", "type": "object" }, "ApprovalGrant": { "properties": { "action": { "title": "Action", "type": "string" }, "conversation_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Conversation Id" }, "exercise_count": { "default": 0, "title": "Exercise Count", "type": "integer" }, "granted_at": { "default": null, "title": "Granted At" }, "granted_by_account_id": { "title": "Granted By Account Id", "type": "string" }, "id": { "title": "Id", "type": "string" }, "last_exercised_at": { "default": null, "title": "Last Exercised At" }, "matched_rule_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Matched Rule Id" }, "scope": { "description": "session | always", "title": "Scope", "type": "string" }, "target": { "title": "Target", "type": "string" } }, "required": [ "id", "scope", "action", "target", "granted_by_account_id" ], "title": "ApprovalGrant", "type": "object" }, "ApprovalGrantListResponse": { "properties": { "agent_account_id": { "title": "Agent Account Id", "type": "string" }, "allow_standing_grants": { "title": "Allow Standing Grants", "type": "boolean" }, "can_manage": { "default": false, "description": "True when the caller may flip the standing-grant switch and sees every member's grants for this employee (its owner, or a tenant Owner/Admin). Every grant RETURNED is revocable by the caller either way — a client never has to probe a revoke to learn that.", "title": "Can Manage", "type": "boolean" }, "grants": { "items": { "$ref": "#/components/schemas/ApprovalGrant" }, "title": "Grants", "type": "array" } }, "required": [ "agent_account_id", "allow_standing_grants" ], "title": "ApprovalGrantListResponse", "type": "object" }, "ApprovalGrantRevokeResponse": { "properties": { "already_revoked": { "default": false, "title": "Already Revoked", "type": "boolean" }, "id": { "title": "Id", "type": "string" }, "revoked": { "title": "Revoked", "type": "boolean" } }, "required": [ "id", "revoked" ], "title": "ApprovalGrantRevokeResponse", "type": "object" }, "ApprovalItem": { "description": "A primitive awaiting approval.", "properties": { "confidence": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "title": "Confidence" }, "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Description" }, "due_date": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Due Date" }, "id": { "title": "Id", "type": "string" }, "priority": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Priority" }, "source": { "anyOf": [ { "$ref": "#/components/schemas/SourceInfo" }, { "type": "null" } ], "default": null }, "title": { "title": "Title", "type": "string" }, "type": { "title": "Type", "type": "string" } }, "required": [ "id", "type", "title", "created_at" ], "title": "ApprovalItem", "type": "object" }, "ApprovalListResponse": { "description": "Response for listing approval items.", "properties": { "has_more": { "default": false, "title": "Has More", "type": "boolean" }, "items": { "items": { "$ref": "#/components/schemas/ApprovalItem" }, "title": "Items", "type": "array" }, "total": { "title": "Total", "type": "integer" } }, "required": [ "items", "total" ], "title": "ApprovalListResponse", "type": "object" }, "ApprovalSettingsRequest": { "description": "Every field is optional; an omitted one is left as it is.", "properties": { "allow_standing_grants": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "May this employee be given standing ('always') grants? Turning it off revokes the standing grants that already exist.", "title": "Allow Standing Grants" }, "approval_authority": { "anyOf": [ { "enum": [ "none", "team", "team_including_destructive" ], "type": "string" }, { "type": "null" } ], "description": "TIDY-19611, retired by TIDY-20066 F14 and kept for released Android: replaces its team-approvals toggles with every work kind on for the team (and destructive commands for 'team_including_destructive'), or none.", "title": "Approval Authority" }, "approvers": { "anyOf": [ { "items": { "type": "string" }, "maxItems": 20, "type": "array" }, { "type": "null" } ], "description": "TIDY-17352 — who else may be asked to approve for it: active human members of the workspace. An empty list returns it to the owner alone.", "title": "Approvers" }, "automation_authority": { "anyOf": [ { "enum": [ "draft", "enable" ], "type": "string" }, { "type": "null" } ], "description": "TIDY-19611 — may it switch on the automation rules it writes?", "title": "Automation Authority" } }, "title": "ApprovalSettingsRequest", "type": "object" }, "ApprovalSettingsResponse": { "properties": { "agent_account_id": { "title": "Agent Account Id", "type": "string" }, "allow_standing_grants": { "title": "Allow Standing Grants", "type": "boolean" }, "approval_authority": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "TIDY-19611, retired by TIDY-20066 F14 (its team-approvals toggles), kept for released Android — 'none': no kind is on for any report; 'team': some are; 'team_including_destructive': destructive commands are on for the team too.", "title": "Approval Authority" }, "approvers": { "description": "TIDY-17352 — account ids that may be asked to approve for this employee when the ask is not about an owned work item. Empty = the owner alone.", "items": { "type": "string" }, "title": "Approvers", "type": "array" }, "automation_authority": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "TIDY-19611 — 'draft': a rule this employee writes is saved switched off for its owner to switch on; 'enable': it may switch its rules on. Either way the rule runs as the owner.", "title": "Automation Authority" }, "can_edit": { "default": false, "description": "True when the caller may change these settings (the employee's owner, or a tenant Owner/Admin). Render read-only when false rather than discovering it from a 403.", "title": "Can Edit", "type": "boolean" }, "owner_account_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Owner Account Id" }, "standing_grants_revoked": { "default": 0, "title": "Standing Grants Revoked", "type": "integer" }, "team": { "description": "The employees directly below it on the team Org chart — its team today.", "items": { "$ref": "#/components/schemas/TeamMember" }, "title": "Team", "type": "array" } }, "required": [ "agent_account_id", "allow_standing_grants", "approvers" ], "title": "ApprovalSettingsResponse", "type": "object" }, "ApproveAuthorizeResponse": { "properties": { "redirect_to": { "title": "Redirect To", "type": "string" } }, "required": [ "redirect_to" ], "title": "ApproveAuthorizeResponse", "type": "object" }, "ApproveBody": { "properties": {}, "title": "ApproveBody", "type": "object" }, "ApproveProposedItemRequest": { "description": "Optional approve options (TIDY-14317).", "properties": { "attach_source_email": { "default": false, "description": "Event approvals only: append the source email's text to the event description so invitees receive the original context.", "title": "Attach Source Email", "type": "boolean" } }, "title": "ApproveProposedItemRequest", "type": "object" }, "ApproveRequest": { "properties": { "client_id": { "title": "Client Id", "type": "string" }, "code_challenge": { "title": "Code Challenge", "type": "string" }, "code_challenge_method": { "title": "Code Challenge Method", "type": "string" }, "redirect_uri": { "title": "Redirect Uri", "type": "string" }, "resource": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Resource" }, "scope": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Scope" }, "state": { "title": "State", "type": "string" } }, "required": [ "client_id", "redirect_uri", "state", "code_challenge", "code_challenge_method" ], "title": "ApproveRequest", "type": "object" }, "ApproveResponse": { "properties": { "emails_routed": { "default": 0, "title": "Emails Routed", "type": "integer" }, "status": { "default": "approved", "title": "Status", "type": "string" } }, "title": "ApproveResponse", "type": "object" }, "ApproveSenderRequest": { "properties": { "mark_done": { "default": false, "title": "Mark Done", "type": "boolean" } }, "title": "ApproveSenderRequest", "type": "object" }, "ArmHarnessRequest": { "properties": { "install_if_missing": { "default": false, "title": "Install If Missing", "type": "boolean" } }, "title": "ArmHarnessRequest", "type": "object" }, "ArmHarnessResponse": { "properties": { "ensure_job_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Ensure Job Id" }, "ensure_state": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Ensure State" }, "job_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Job Id" }, "runtime": { "title": "Runtime", "type": "string" }, "status": { "title": "Status", "type": "string" } }, "required": [ "status", "runtime" ], "title": "ArmHarnessResponse", "type": "object" }, "ArtifactResponse": { "properties": { "path": { "title": "Path", "type": "string" }, "sha256": { "title": "Sha256", "type": "string" }, "size": { "title": "Size", "type": "integer" }, "state": { "title": "State", "type": "string" } }, "required": [ "path", "sha256", "size", "state" ], "title": "ArtifactResponse", "type": "object" }, "ArtifactVersion": { "description": "One version row. ``snapshot`` is present only when the list was asked\nfor it (``?include=snapshot``) or on create.", "properties": { "artifact_id": { "title": "Artifact Id", "type": "string" }, "artifact_type": { "title": "Artifact Type", "type": "string" }, "created_at": { "title": "Created At", "type": "string" }, "created_by": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Created By" }, "id": { "title": "Id", "type": "string" }, "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Label" }, "owner_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Owner Id" }, "snapshot": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "title": "Snapshot" }, "trigger": { "title": "Trigger", "type": "string" } }, "required": [ "id", "artifact_type", "artifact_id", "trigger", "created_at" ], "title": "ArtifactVersion", "type": "object" }, "ArtifactVersionCreateRequest": { "description": "A version to record. ``trigger='manual'`` is a named checkpoint, always\naccepted. ``'save'``/``'restore'`` are accepted only for a local-first\nartifact type (``CLIENT_SAVE_PATH_TYPES``), whose commit the client owns;\nfor a server-saved type they are appended inside that artifact's save\ntransaction instead, and the router rejects them here.", "properties": { "artifact_id": { "maxLength": 64, "minLength": 1, "title": "Artifact Id", "type": "string" }, "artifact_type": { "maxLength": 32, "minLength": 1, "title": "Artifact Type", "type": "string" }, "label": { "anyOf": [ { "maxLength": 200, "type": "string" }, { "type": "null" } ], "title": "Label" }, "snapshot": { "additionalProperties": true, "title": "Snapshot", "type": "object" }, "trigger": { "default": "manual", "maxLength": 16, "title": "Trigger", "type": "string" } }, "required": [ "artifact_type", "artifact_id", "snapshot" ], "title": "ArtifactVersionCreateRequest", "type": "object" }, "ArtifactVersionList": { "properties": { "versions": { "items": { "$ref": "#/components/schemas/ArtifactVersion" }, "title": "Versions", "type": "array" } }, "required": [ "versions" ], "title": "ArtifactVersionList", "type": "object" }, "AskCallbackResult": { "properties": { "behavior": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Behavior" }, "outcome": { "title": "Outcome", "type": "string" }, "run_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Run Status" } }, "required": [ "outcome" ], "title": "AskCallbackResult", "type": "object" }, "AskResponseCallback": { "properties": { "response_text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The assistant's final response text", "title": "Response Text" }, "status": { "description": "'completed' or 'failed'", "title": "Status", "type": "string" } }, "required": [ "status" ], "title": "AskResponseCallback", "type": "object" }, "AssembleCandidateRequest": { "description": "Bind an ordered set of uploaded staging parts into one candidate object.\n\nThe parts are an internal rehearsal detail: a client that cannot PUT a\nsingle body past a proxy limit PUTs ``part-NNNN`` chunks into\n``/staging-parts//`` and asks the server to\nreassemble them in the order given. Every path is canonical and every part\nmust belong to the same candidate id as the target.", "properties": { "candidate_path": { "title": "Candidate Path", "type": "string" }, "part_paths": { "items": { "type": "string" }, "minItems": 1, "title": "Part Paths", "type": "array" }, "part_sha256": { "items": { "type": "string" }, "title": "Part Sha256", "type": "array" }, "sha256": { "title": "Sha256", "type": "string" }, "size": { "exclusiveMinimum": 0.0, "title": "Size", "type": "integer" } }, "required": [ "candidate_path", "part_paths", "part_sha256", "sha256", "size" ], "title": "AssembleCandidateRequest", "type": "object" }, "AssignHuddleSpeakerRequest": { "description": "Exactly ONE of account_id / contact_id (D7 one-click correction).", "properties": { "account_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Account Id" }, "contact_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Contact Id" }, "speaker_label": { "maxLength": 200, "minLength": 1, "title": "Speaker Label", "type": "string" } }, "required": [ "speaker_label" ], "title": "AssignHuddleSpeakerRequest", "type": "object" }, "AssignHuddleSpeakerResponse": { "properties": { "changed": { "title": "Changed", "type": "boolean" }, "huddle_id": { "format": "uuid", "title": "Huddle Id", "type": "string" }, "speaker_map": { "additionalProperties": true, "title": "Speaker Map", "type": "object" } }, "required": [ "huddle_id", "speaker_map", "changed" ], "title": "AssignHuddleSpeakerResponse", "type": "object" }, "AssignRequest": { "properties": { "assignee_account_id": { "description": "Account id of the member or employee to assign. Same namespace for both — `agent_members.account_id` for an employee.", "title": "Assignee Account Id", "type": "string" } }, "required": [ "assignee_account_id" ], "title": "AssignRequest", "type": "object" }, "AssignResponse": { "properties": { "activity_id": { "title": "Activity Id", "type": "string" }, "assigned_by": { "title": "Assigned By", "type": "string" }, "assigned_by_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Assigned By Name" }, "assignee": { "title": "Assignee", "type": "string" }, "short_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Short Id" }, "stuck_work": { "anyOf": [ { "$ref": "#/components/schemas/StuckWorkNote" }, { "type": "null" } ], "default": null, "description": "TIDY-20074: set when this assignment left the item stuck — assigned to an employee whose Wakes for leaves its state out, so nothing will wake anyone for it. Your one try to hand it on." } }, "required": [ "activity_id", "assignee", "assigned_by" ], "title": "AssignResponse", "type": "object" }, "AssignVeActionConfig": { "description": "Declarative config for a plugin event's assign_virtual_employee action.\n\nStored as ``plugin_event_types.assign_ve_action`` JSONB; also the shape the\nplugin's Events section edits.", "properties": { "dedup_key_field": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Bundle key whose value dedups repeat intakes (idempotency).", "title": "Dedup Key Field" }, "dispatch_timeout_s": { "default": 300, "deprecated": true, "description": "Ignored: the employee is sent a message, which has no timeout.", "maximum": 86400.0, "minimum": 5.0, "title": "Dispatch Timeout S", "type": "integer" }, "facet_slug": { "default": "task", "description": "Board facet the item lands on.", "title": "Facet Slug", "type": "string" }, "field_mapping": { "additionalProperties": { "type": "string" }, "description": "item field -> bundle key (title/description/labels/repo). Empty = identity.", "title": "Field Mapping", "type": "object" }, "message": { "anyOf": [ { "maxLength": 4000, "type": "string" }, { "type": "null" } ], "description": "What to tell the employee about each delivery — the message's instruction. Omit for the default: work the task.", "title": "Message" }, "repo": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Default repo when the bundle omits one.", "title": "Repo" }, "ve_slug": { "description": "Target virtual employee slug.", "minLength": 1, "title": "Ve Slug", "type": "string" } }, "required": [ "ve_slug" ], "title": "AssignVeActionConfig", "type": "object" }, "AssignVirtualEmployeeRequest": { "description": "Direct invocation of the action (e.g. from a workflow script).", "properties": { "dedup_key_field": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Dedup Key Field" }, "dispatch_timeout_s": { "default": 300, "deprecated": true, "description": "Ignored: the employee is sent a message, which has no timeout.", "maximum": 86400.0, "minimum": 5.0, "title": "Dispatch Timeout S", "type": "integer" }, "facet_slug": { "default": "task", "title": "Facet Slug", "type": "string" }, "field_mapping": { "additionalProperties": { "type": "string" }, "title": "Field Mapping", "type": "object" }, "message": { "anyOf": [ { "maxLength": 4000, "type": "string" }, { "type": "null" } ], "description": "What to tell the employee about each delivery — the message's instruction. Omit for the default: work the task.", "title": "Message" }, "payload": { "additionalProperties": true, "description": "The bundle to map.", "title": "Payload", "type": "object" }, "repo": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Repo" }, "ve_slug": { "minLength": 1, "title": "Ve Slug", "type": "string" }, "workflow_execution_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Workflow Execution Id" } }, "required": [ "ve_slug" ], "title": "AssignVirtualEmployeeRequest", "type": "object" }, "AssignVirtualEmployeeResponse": { "description": "Outcome of an intake: the item ALWAYS exists; the message may have failed.\n\n``dispatched`` means the message is posted in the actor's DM with the\nemployee and ``conversation_id`` names that conversation.", "properties": { "activity_id": { "title": "Activity Id", "type": "string" }, "conversation_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Conversation Id" }, "deduplicated": { "default": false, "title": "Deduplicated", "type": "boolean" }, "dev_status": { "title": "Dev Status", "type": "string" }, "dispatch_error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Dispatch Error" }, "dispatched": { "title": "Dispatched", "type": "boolean" }, "title": { "title": "Title", "type": "string" }, "validation_notes": { "items": { "type": "string" }, "title": "Validation Notes", "type": "array" }, "work_order_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "deprecated": true, "description": "Always null: no work order is sent.", "title": "Work Order Id" } }, "required": [ "activity_id", "dev_status", "title", "dispatched" ], "title": "AssignVirtualEmployeeResponse", "type": "object" }, "AssignmentResult": { "description": "TIDY-14151 (S7): the assign_virtual_employee outcome of one delivery.\nTIDY-19869: ``conversation_id`` is the message the employee was sent.", "properties": { "activity_id": { "title": "Activity Id", "type": "string" }, "conversation_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Conversation Id" }, "deduplicated": { "default": false, "title": "Deduplicated", "type": "boolean" }, "dev_status": { "title": "Dev Status", "type": "string" }, "dispatch_error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Dispatch Error" }, "dispatched": { "title": "Dispatched", "type": "boolean" }, "title": { "title": "Title", "type": "string" }, "validation_notes": { "items": { "type": "string" }, "title": "Validation Notes", "type": "array" }, "work_order_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "deprecated": true, "description": "Always null: no work order is sent.", "title": "Work Order Id" } }, "required": [ "activity_id", "dev_status", "title", "dispatched" ], "title": "AssignmentResult", "type": "object" }, "AssistantCallRequest": { "properties": { "context": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "Optional context object passed to the assistant.", "title": "Context" }, "employee_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Custom AI employee id. Absent = the tenant's Tidy Assistant (tier 2); present = the employee persona overlay (tier 3).", "title": "Employee Id" }, "prompt": { "description": "The single-turn prompt.", "minLength": 1, "title": "Prompt", "type": "string" }, "workflow_execution_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Workflow execution id for cost attribution.", "title": "Workflow Execution Id" } }, "required": [ "prompt" ], "title": "AssistantCallRequest", "type": "object" }, "AssistantCallResponse": { "properties": { "answer_text": { "title": "Answer Text", "type": "string" }, "conversation_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Conversation Id" }, "tier": { "enum": [ "assistant", "employee" ], "title": "Tier", "type": "string" } }, "required": [ "answer_text", "tier" ], "title": "AssistantCallResponse", "type": "object" }, "AssistantInvokeRequest": { "properties": { "context": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Context" }, "conversation_continuation_token": { "anyOf": [ { "maxLength": 512, "type": "string" }, { "type": "null" } ], "title": "Conversation Continuation Token" }, "mcp_client_id": { "anyOf": [ { "maxLength": 160, "type": "string" }, { "type": "null" } ], "title": "Mcp Client Id" }, "mcp_client_label": { "anyOf": [ { "maxLength": 120, "type": "string" }, { "type": "null" } ], "title": "Mcp Client Label" }, "mcp_session_id": { "anyOf": [ { "maxLength": 160, "type": "string" }, { "type": "null" } ], "title": "Mcp Session Id" }, "message": { "maxLength": 10000, "minLength": 1, "title": "Message", "type": "string" }, "response_pattern": { "default": "sync", "enum": [ "sync", "async_callback", "channel_handoff" ], "title": "Response Pattern", "type": "string" } }, "required": [ "message" ], "title": "AssistantInvokeRequest", "type": "object" }, "AssistantInvokeResponse": { "properties": { "answer_text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Answer Text" }, "callback_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Callback Url" }, "channel": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Channel" }, "conversation_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Conversation Id" }, "error": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Error" }, "retry_after_seconds": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Retry After Seconds" }, "status": { "default": "completed", "enum": [ "completed", "processing", "delegated", "error" ], "title": "Status", "type": "string" } }, "title": "AssistantInvokeResponse", "type": "object" }, "AssistantRedactRequest": { "description": "POST /api/v1/internal/matrix/assistant-redact body.", "properties": { "event_id": { "maxLength": 255, "minLength": 1, "title": "Event Id", "type": "string" }, "reason": { "anyOf": [ { "maxLength": 255, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Reason" }, "room_id": { "minLength": 1, "title": "Room Id", "type": "string" }, "sender_matrix_user_id": { "maxLength": 255, "minLength": 1, "title": "Sender Matrix User Id", "type": "string" }, "transaction_id": { "maxLength": 255, "minLength": 1, "title": "Transaction Id", "type": "string" } }, "required": [ "room_id", "event_id", "transaction_id", "sender_matrix_user_id" ], "title": "AssistantRedactRequest", "type": "object" }, "AssistantRedactResponse": { "properties": { "redacted": { "title": "Redacted", "type": "boolean" } }, "required": [ "redacted" ], "title": "AssistantRedactResponse", "type": "object" }, "AssistantSendRequest": { "description": "POST /api/v1/internal/matrix/assistant-send body.", "properties": { "content": { "additionalProperties": true, "title": "Content", "type": "object" }, "event_type": { "default": "m.room.message", "maxLength": 255, "minLength": 1, "title": "Event Type", "type": "string" }, "room_id": { "minLength": 1, "title": "Room Id", "type": "string" }, "sender_matrix_user_id": { "anyOf": [ { "maxLength": 255, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Sender Matrix User Id" }, "transaction_id": { "maxLength": 255, "minLength": 1, "title": "Transaction Id", "type": "string" } }, "required": [ "room_id", "content", "transaction_id" ], "title": "AssistantSendRequest", "type": "object" }, "AssistantSendResponse": { "properties": { "encrypted": { "title": "Encrypted", "type": "boolean" }, "event_id": { "title": "Event Id", "type": "string" } }, "required": [ "event_id", "encrypted" ], "title": "AssistantSendResponse", "type": "object" }, "AssistantSettingsResponse": { "properties": { "automation_authority": { "enum": [ "draft", "enable" ], "title": "Automation Authority", "type": "string" }, "daily_wake_cap": { "title": "Daily Wake Cap", "type": "integer" }, "heartbeat_enabled": { "title": "Heartbeat Enabled", "type": "boolean" }, "heartbeat_flag_enabled": { "description": "The workspace lets employees work on their own.", "title": "Heartbeat Flag Enabled", "type": "boolean" }, "last_reflection_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Reflection At" }, "reflection_cadence": { "anyOf": [ { "enum": [ "P1D", "P3D", "P7D" ], "type": "string" }, { "type": "null" } ], "title": "Reflection Cadence" }, "reflection_flag_enabled": { "description": "The workspace lets employees reflect and propose work.", "title": "Reflection Flag Enabled", "type": "boolean" }, "reflection_max_proposals": { "title": "Reflection Max Proposals", "type": "integer" }, "reflection_member_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Whose work it reflects on — the member who set the cadence.", "title": "Reflection Member Name" }, "wake_idle_minutes": { "title": "Wake Idle Minutes", "type": "integer" }, "wakes_today": { "description": "Times it woke on its own since 00:00 UTC.", "title": "Wakes Today", "type": "integer" }, "work_policy": { "$ref": "#/components/schemas/EmployeeWorkPolicyResponse" } }, "required": [ "heartbeat_enabled", "wake_idle_minutes", "daily_wake_cap", "wakes_today", "reflection_cadence", "reflection_max_proposals", "reflection_member_name", "last_reflection_at", "automation_authority", "work_policy", "heartbeat_flag_enabled", "reflection_flag_enabled" ], "title": "AssistantSettingsResponse", "type": "object" }, "AssistantSettingsUpdate": { "additionalProperties": false, "description": "A partial save: only the fields sent change. An explicit null on\n``reflection_cadence`` stops it reflecting; on ``work_policy`` it follows\nthe workspace default again.", "properties": { "automation_authority": { "anyOf": [ { "enum": [ "draft", "enable" ], "type": "string" }, { "type": "null" } ], "description": "A rule it writes in a member's chat runs as that member: `enable` switches it on straight away, `draft` asks the member to.", "title": "Automation Authority" }, "daily_wake_cap": { "anyOf": [ { "maximum": 10000.0, "minimum": 0.0, "type": "integer" }, { "type": "null" } ], "description": "The most times a day it wakes on its own.", "title": "Daily Wake Cap" }, "heartbeat_enabled": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Work its backlog on its own, without waiting for a message.", "title": "Heartbeat Enabled" }, "reflection_cadence": { "anyOf": [ { "enum": [ "P1D", "P3D", "P7D" ], "type": "string" }, { "type": "null" } ], "description": "How often it steps back to reflect on its backlog and objectives and propose work; null stops it. It reflects for the member who sets this.", "title": "Reflection Cadence" }, "reflection_max_proposals": { "anyOf": [ { "maximum": 20.0, "minimum": 1.0, "type": "integer" }, { "type": "null" } ], "description": "The most it proposes in one reflection.", "title": "Reflection Max Proposals" }, "wake_idle_minutes": { "anyOf": [ { "maximum": 1440.0, "minimum": 15.0, "type": "integer" }, { "type": "null" } ], "description": "How often it checks its backlog for work.", "title": "Wake Idle Minutes" }, "work_policy": { "anyOf": [ { "$ref": "#/components/schemas/VeWorkPolicy" }, { "type": "null" } ], "description": "Its own work policy; null follows the workspace default." } }, "title": "AssistantSettingsUpdate", "type": "object" }, "AssistantThreadRequest": { "description": "POST /api/v1/internal/matrix/assistant-thread body.", "properties": { "account_id": { "minLength": 1, "title": "Account Id", "type": "string" }, "tenant_id": { "minLength": 1, "title": "Tenant Id", "type": "string" }, "title": { "maxLength": 500, "minLength": 1, "title": "Title", "type": "string" } }, "required": [ "tenant_id", "account_id", "title" ], "title": "AssistantThreadRequest", "type": "object" }, "AssistantThreadResponse": { "properties": { "conversation_id": { "title": "Conversation Id", "type": "string" }, "matrix_room_id": { "title": "Matrix Room Id", "type": "string" }, "matrix_thread_root_event_id": { "title": "Matrix Thread Root Event Id", "type": "string" } }, "required": [ "conversation_id", "matrix_room_id", "matrix_thread_root_event_id" ], "title": "AssistantThreadResponse", "type": "object" }, "AssistantTurnMessage": { "properties": { "content": { "maxLength": 8000, "title": "Content", "type": "string" }, "role": { "maxLength": 32, "title": "Role", "type": "string" } }, "required": [ "role", "content" ], "title": "AssistantTurnMessage", "type": "object" }, "AssistantTurnRequest": { "properties": { "conversation_id": { "anyOf": [ { "maxLength": 64, "type": "string" }, { "type": "null" } ], "title": "Conversation Id" }, "recent_turns": { "items": { "$ref": "#/components/schemas/AssistantTurnMessage" }, "maxItems": 20, "title": "Recent Turns", "type": "array" }, "user_query": { "maxLength": 4000, "minLength": 1, "title": "User Query", "type": "string" } }, "required": [ "user_query" ], "title": "AssistantTurnRequest", "type": "object" }, "AssistantTurnResponse": { "properties": { "assistant_response": { "default": "", "title": "Assistant Response", "type": "string" }, "conversation_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Conversation Id" }, "source_ids": { "items": { "$ref": "#/components/schemas/AssistantTurnSource" }, "title": "Source Ids", "type": "array" } }, "title": "AssistantTurnResponse", "type": "object" }, "AssistantTurnSource": { "properties": { "id": { "title": "Id", "type": "string" }, "kind": { "title": "Kind", "type": "string" }, "snippet": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Snippet" } }, "required": [ "kind", "id" ], "title": "AssistantTurnSource", "type": "object" }, "AssociatedAttachment": { "properties": { "ai_summary": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Ai Summary" }, "content_type": { "title": "Content Type", "type": "string" }, "filename": { "title": "Filename", "type": "string" }, "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Id" }, "locator": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Locator" }, "locator_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Locator Reason" }, "size": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Size" }, "storage_path": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Storage Path" } }, "required": [ "filename", "content_type" ], "title": "AssociatedAttachment", "type": "object" }, "AssociatedContact": { "properties": { "approval_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Approval Status" }, "id": { "title": "Id", "type": "string" }, "name": { "title": "Name", "type": "string" }, "requires_review": { "default": false, "title": "Requires Review", "type": "boolean" } }, "required": [ "id", "name" ], "title": "AssociatedContact", "type": "object" }, "AssociatedEvent": { "properties": { "date": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Date" }, "id": { "title": "Id", "type": "string" }, "requires_review": { "default": false, "title": "Requires Review", "type": "boolean" }, "status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Status" }, "title": { "title": "Title", "type": "string" } }, "required": [ "id", "title" ], "title": "AssociatedEvent", "type": "object" }, "AssociatedNote": { "properties": { "content": { "title": "Content", "type": "string" }, "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "id": { "title": "Id", "type": "string" }, "note_type": { "title": "Note Type", "type": "string" } }, "required": [ "id", "content", "created_at", "note_type" ], "title": "AssociatedNote", "type": "object" }, "AssociatedObjectsResponse": { "properties": { "attachments": { "items": { "$ref": "#/components/schemas/AssociatedAttachment" }, "title": "Attachments", "type": "array" }, "contacts": { "items": { "$ref": "#/components/schemas/AssociatedContact" }, "title": "Contacts", "type": "array" }, "events": { "items": { "$ref": "#/components/schemas/AssociatedEvent" }, "title": "Events", "type": "array" }, "notes": { "items": { "$ref": "#/components/schemas/AssociatedNote" }, "title": "Notes", "type": "array" }, "reference_extractions": { "items": { "$ref": "#/components/schemas/AssociatedReferenceExtraction" }, "title": "Reference Extractions", "type": "array" }, "reminders": { "items": { "$ref": "#/components/schemas/AssociatedReminder" }, "title": "Reminders", "type": "array" }, "tasks": { "items": { "$ref": "#/components/schemas/AssociatedTask" }, "title": "Tasks", "type": "array" } }, "required": [ "events", "tasks", "contacts", "reminders", "notes", "attachments", "reference_extractions" ], "title": "AssociatedObjectsResponse", "type": "object" }, "AssociatedReferenceExtraction": { "properties": { "attachment_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Attachment Id" }, "attachment_locator": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "title": "Attachment Locator" }, "attachment_locator_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Attachment Locator Reason" }, "attachment_storage_path": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Attachment Storage Path" }, "classification_category": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Classification Category" }, "classification_routing": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Classification Routing" }, "content_preview": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Content Preview" }, "id": { "title": "Id", "type": "string" }, "metadata_only": { "default": false, "title": "Metadata Only", "type": "boolean" }, "per_document_routing": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Per Document Routing" }, "primitive_counts": { "$ref": "#/components/schemas/AssociatedReferencePrimitiveCounts" }, "prompt_variant": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Prompt Variant" }, "routing_decision": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Routing Decision" }, "source_content_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Source Content Type" }, "source_domain": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Source Domain" }, "source_filename": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Source Filename" }, "source_title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Source Title" }, "source_type": { "title": "Source Type", "type": "string" }, "source_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Source Url" }, "summary": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Summary" }, "updated_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Updated At" } }, "required": [ "id", "source_type" ], "title": "AssociatedReferenceExtraction", "type": "object" }, "AssociatedReferencePrimitiveCounts": { "properties": { "commitments": { "default": 0, "title": "Commitments", "type": "integer" }, "contacts": { "default": 0, "title": "Contacts", "type": "integer" }, "events": { "default": 0, "title": "Events", "type": "integer" }, "reminders": { "default": 0, "title": "Reminders", "type": "integer" }, "tasks": { "default": 0, "title": "Tasks", "type": "integer" } }, "title": "AssociatedReferencePrimitiveCounts", "type": "object" }, "AssociatedReminder": { "properties": { "approval_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Approval Status" }, "id": { "title": "Id", "type": "string" }, "reminder_date": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Reminder Date" }, "requires_review": { "default": false, "title": "Requires Review", "type": "boolean" }, "title": { "title": "Title", "type": "string" } }, "required": [ "id", "title" ], "title": "AssociatedReminder", "type": "object" }, "AssociatedTask": { "properties": { "approval_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Approval Status" }, "due_date": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Due Date" }, "id": { "title": "Id", "type": "string" }, "requires_review": { "default": false, "title": "Requires Review", "type": "boolean" }, "status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Status" }, "title": { "title": "Title", "type": "string" } }, "required": [ "id", "title" ], "title": "AssociatedTask", "type": "object" }, "AttachFromObjectRequest": { "description": "Attach a serialized Tidy object (email → .eml, event → .ics) by reference.\n\nThe server materializes the interchange file server-side and appends it as a\nfrozen-snapshot attachment; the bytes never round-trip the browser.", "properties": { "object_id": { "description": "ID of the email or event to attach", "format": "uuid", "title": "Object Id", "type": "string" }, "object_type": { "description": "Kind of object to serialize and attach", "enum": [ "email", "event" ], "title": "Object Type", "type": "string" } }, "required": [ "object_type", "object_id" ], "title": "AttachFromObjectRequest", "type": "object" }, "AttachmentLegacy": { "description": "Email attachment metadata (legacy view format).", "properties": { "filename": { "title": "Filename", "type": "string" }, "mimeType": { "title": "Mimetype", "type": "string" }, "size": { "default": 0, "title": "Size", "type": "integer" } }, "required": [ "filename", "mimeType" ], "title": "AttachmentLegacy", "type": "object" }, "AttachmentResponse": { "properties": { "fileName": { "title": "Filename", "type": "string" }, "id": { "description": "Generated UUID for this attachment", "title": "Id", "type": "string" }, "size": { "title": "Size", "type": "integer" }, "storagePath": { "description": "Object storage key path", "title": "Storagepath", "type": "string" }, "success": { "title": "Success", "type": "boolean" }, "type": { "title": "Type", "type": "string" }, "url": { "description": "Authenticated proxy URL for the uploaded file", "title": "Url", "type": "string" } }, "required": [ "success", "id", "url", "storagePath", "fileName", "size", "type" ], "title": "AttachmentResponse", "type": "object" }, "AttachmentSignedUrlResponse": { "description": "Response for attachment signed URL endpoint.", "properties": { "expires_in": { "description": "URL validity in seconds", "title": "Expires In", "type": "integer" }, "url": { "description": "Signed URL for downloading attachment", "title": "Url", "type": "string" } }, "required": [ "url", "expires_in" ], "title": "AttachmentSignedUrlResponse", "type": "object" }, "AttentionDismissRequest": { "additionalProperties": false, "properties": { "item_id": { "format": "uuid", "title": "Item Id", "type": "string" }, "source_table": { "description": "The table the Attention item's id belongs to: a push or liveness item, an open conversation request, an undelivered escalation, or an overdue review.", "enum": [ "workforce_attention_items", "agent_session_requests", "escalations", "activities" ], "title": "Source Table", "type": "string" } }, "required": [ "source_table", "item_id" ], "title": "AttentionDismissRequest", "type": "object" }, "AttentionDismissResult": { "properties": { "dismissed_at": { "title": "Dismissed At", "type": "string" }, "item_id": { "format": "uuid", "title": "Item Id", "type": "string" } }, "required": [ "item_id", "dismissed_at" ], "title": "AttentionDismissResult", "type": "object" }, "AuditActor": { "description": "Compact actor reference for list responses.", "properties": { "id": { "title": "Id", "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Name" } }, "required": [ "id" ], "title": "AuditActor", "type": "object" }, "AuditEntryResponse": { "properties": { "action": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Action" }, "actor_account_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "default": null, "title": "Actor Account Id" }, "actor_pseudonym": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Actor Pseudonym" }, "actor_type": { "title": "Actor Type", "type": "string" }, "args_hash": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Args Hash" }, "entry_hash": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Entry Hash" }, "error_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Error Code" }, "event_timestamp": { "format": "date-time", "title": "Event Timestamp", "type": "string" }, "event_type": { "title": "Event Type", "type": "string" }, "failure_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Failure Reason" }, "id": { "format": "uuid", "title": "Id", "type": "string" }, "latency_ms": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Latency Ms" }, "mcp_session_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Mcp Session Id" }, "outcome": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Outcome" }, "payload": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "title": "Payload" }, "prev_hash": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Prev Hash" }, "request_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Request Id" }, "resource_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Resource Id" }, "resource_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Resource Type" }, "scopes": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "default": null, "title": "Scopes" }, "severity": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Severity" }, "success": { "title": "Success", "type": "boolean" }, "tenant_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "default": null, "title": "Tenant Id" } }, "required": [ "id", "event_type", "event_timestamp", "actor_type", "success" ], "title": "AuditEntryResponse", "type": "object" }, "AuditEventModel": { "properties": { "action": { "title": "Action", "type": "string" }, "affected": { "additionalProperties": true, "title": "Affected", "type": "object" }, "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "definition_id": { "format": "uuid", "title": "Definition Id", "type": "string" }, "delegation_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Delegation Id" }, "evidence": { "additionalProperties": true, "title": "Evidence", "type": "object" }, "id": { "format": "uuid", "title": "Id", "type": "string" }, "principal_id": { "format": "uuid", "title": "Principal Id", "type": "string" }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Reason" }, "rollout_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Rollout Id" }, "version_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Version Id" } }, "required": [ "id", "definition_id", "version_id", "rollout_id", "action", "principal_id", "delegation_id", "reason", "evidence", "affected", "created_at" ], "title": "AuditEventModel", "type": "object" }, "AuditLogListResponse": { "description": "Cursor-paginated list of audit rows.", "properties": { "items": { "items": { "$ref": "#/components/schemas/AuditLogSummary" }, "title": "Items", "type": "array" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Opaque cursor for the next page; None when at end.", "title": "Next Cursor" } }, "title": "AuditLogListResponse", "type": "object" }, "AuditLogPage": { "properties": { "has_more": { "default": false, "title": "Has More", "type": "boolean" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Next Cursor" }, "rows": { "items": { "$ref": "#/components/schemas/AuditLogRow" }, "title": "Rows", "type": "array" } }, "required": [ "rows" ], "title": "AuditLogPage", "type": "object" }, "AuditLogRow": { "properties": { "action": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Action" }, "actor_account_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "default": null, "title": "Actor Account Id" }, "actor_type": { "title": "Actor Type", "type": "string" }, "event_timestamp": { "format": "date-time", "title": "Event Timestamp", "type": "string" }, "event_type": { "title": "Event Type", "type": "string" }, "id": { "format": "uuid", "title": "Id", "type": "string" }, "outcome": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Outcome" }, "resource_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Resource Id" }, "resource_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Resource Type" }, "seq": { "title": "Seq", "type": "integer" }, "severity": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Severity" }, "tenant_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "default": null, "title": "Tenant Id" } }, "required": [ "id", "seq", "actor_type", "event_type", "event_timestamp" ], "title": "AuditLogRow", "type": "object" }, "AuditLogSummary": { "description": "Single audit row in the compact list shape used by GET /contacts/{id}/audit.", "properties": { "actor": { "anyOf": [ { "$ref": "#/components/schemas/AuditActor" }, { "type": "null" } ], "default": null, "description": "Account that performed the operation; None for system actions." }, "id": { "title": "Id", "type": "string" }, "occurred_at": { "description": "When the operation happened (ISO UTC).", "format": "date-time", "title": "Occurred At", "type": "string" }, "operation": { "description": "Dot-notation entity operation, e.g. contact.merge.", "title": "Operation", "type": "string" }, "outcome": { "description": "success | failure | partial", "enum": [ "success", "failure", "partial" ], "title": "Outcome", "type": "string" }, "payload_summary": { "default": "", "description": "Short human-readable summary derived from payload_snapshot.", "title": "Payload Summary", "type": "string" }, "secondary_entity_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "The other entity involved (e.g. the absorbed contact in a merge).", "title": "Secondary Entity Id" } }, "required": [ "id", "operation", "occurred_at", "outcome" ], "title": "AuditLogSummary", "type": "object" }, "AuditRecordRequest": { "properties": { "action": { "title": "Action", "type": "string" }, "actor_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Actor Id" }, "actor_type": { "default": "mcp_session", "enum": [ "user", "admin", "support", "system", "service", "oauth_app", "pat", "service_account", "delegated", "system_admin", "mcp_session", "web_session" ], "title": "Actor Type", "type": "string" }, "ai_employee_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Ai Employee Id" }, "connection_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Connection Id" }, "connection_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Connection Name" }, "delegation_actor_account_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Delegation Actor Account Id" }, "delegation_grant_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Delegation Grant Id" }, "delegation_principal_account_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Delegation Principal Account Id" }, "error_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error Code" }, "inputs": { "additionalProperties": true, "title": "Inputs", "type": "object" }, "latency_ms": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Latency Ms" }, "outcome": { "default": "success", "enum": [ "success", "error", "denied", "cancelled" ], "title": "Outcome", "type": "string" }, "principal_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Principal Id" }, "resource_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Resource Id" }, "resource_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Resource Type" }, "scopes": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Scopes" }, "session_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Session Id" }, "subject_user_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Subject User Id" }, "tenant_id": { "format": "uuid", "title": "Tenant Id", "type": "string" }, "tool_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Tool Name" }, "trace_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Trace Id" } }, "required": [ "tenant_id", "action" ], "title": "AuditRecordRequest", "type": "object" }, "AuditRecordResponse": { "properties": { "id": { "format": "uuid", "title": "Id", "type": "string" } }, "required": [ "id" ], "title": "AuditRecordResponse", "type": "object" }, "AuditTrailEntry": { "properties": { "action": { "title": "Action", "type": "string" }, "actor_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Actor Id" }, "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "id": { "title": "Id", "type": "string" }, "outcome": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Outcome" }, "payload": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "title": "Payload" }, "resource_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Resource Type" } }, "required": [ "id", "action", "created_at" ], "title": "AuditTrailEntry", "type": "object" }, "AuthAccountSession": { "properties": { "account_id": { "title": "Account Id", "type": "string" }, "account_name": { "title": "Account Name", "type": "string" }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Email" }, "is_active": { "title": "Is Active", "type": "boolean" }, "role": { "title": "Role", "type": "string" }, "tenant_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Tenant Id" }, "tenant_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Tenant Name" } }, "required": [ "account_id", "email", "account_name", "tenant_id", "tenant_name", "role", "is_active" ], "title": "AuthAccountSession", "type": "object" }, "AuthMeResponse": { "properties": { "account_id": { "title": "Account Id", "type": "string" }, "account_name": { "title": "Account Name", "type": "string" }, "accounts": { "items": { "$ref": "#/components/schemas/AuthAccountSession" }, "title": "Accounts", "type": "array" }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Email" }, "tenant_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Tenant Id" }, "tenant_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Tenant Name" } }, "required": [ "account_id", "email", "account_name", "tenant_id", "tenant_name", "accounts" ], "title": "AuthMeResponse", "type": "object" }, "AuthMethod": { "description": "Authentication method for a provider connection.", "enum": [ "oauth2", "app_password" ], "title": "AuthMethod", "type": "string" }, "AuthoringRewriteRequest": { "description": "Request to rewrite a virtual-employee setup field with AI.", "properties": { "field_kind": { "description": "Which field is being authored: 'soul' or 'manners'.", "enum": [ "soul", "manners" ], "title": "Field Kind", "type": "string" }, "instruction": { "anyOf": [ { "maxLength": 2000, "type": "string" }, { "type": "null" } ], "description": "Optional freeform user guidance layered on the baseline.", "title": "Instruction" }, "operation": { "description": "Quick action: 'rewrite' (polish), 'fix_grammar', or 'shorten'.", "enum": [ "rewrite", "fix_grammar", "shorten" ], "title": "Operation", "type": "string" }, "text": { "default": "", "description": "Current field text. May be empty-ish.", "maxLength": 20000, "title": "Text", "type": "string" } }, "required": [ "field_kind", "operation" ], "title": "AuthoringRewriteRequest", "type": "object" }, "AuthoringRewriteResponse": { "description": "Rewritten field text.", "properties": { "result": { "title": "Result", "type": "string" } }, "required": [ "result" ], "title": "AuthoringRewriteResponse", "type": "object" }, "AuthorizeClientInfo": { "properties": { "client_id": { "title": "Client Id", "type": "string" }, "client_type": { "title": "Client Type", "type": "string" }, "homepage_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Homepage Url" }, "logo_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Logo Url" }, "name": { "title": "Name", "type": "string" }, "review_status": { "title": "Review Status", "type": "string" }, "self_registered": { "default": false, "title": "Self Registered", "type": "boolean" } }, "required": [ "client_id", "name", "client_type", "review_status" ], "title": "AuthorizeClientInfo", "type": "object" }, "AuthorizeScopeDescription": { "properties": { "description": { "title": "Description", "type": "string" }, "scope": { "title": "Scope", "type": "string" } }, "required": [ "scope", "description" ], "title": "AuthorizeScopeDescription", "type": "object" }, "AuthorizeUserInfo": { "properties": { "display_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Display Name" }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Email" }, "tenant_id": { "title": "Tenant Id", "type": "string" }, "tenant_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Tenant Name" }, "user_id": { "title": "User Id", "type": "string" } }, "required": [ "user_id", "tenant_id" ], "title": "AuthorizeUserInfo", "type": "object" }, "AutoTranscribedCreate": { "properties": { "artwork_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Artwork Url" }, "author": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Author" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "diarization_enabled": { "default": true, "title": "Diarization Enabled", "type": "boolean" }, "priority": { "default": 100, "title": "Priority", "type": "integer" }, "rss_feed_url": { "title": "Rss Feed Url", "type": "string" }, "title": { "title": "Title", "type": "string" } }, "required": [ "rss_feed_url", "title" ], "title": "AutoTranscribedCreate", "type": "object" }, "AutoTranscribedFeed": { "properties": { "diarization_enabled": { "default": true, "title": "Diarization Enabled", "type": "boolean" }, "last_seen_guid": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Seen Guid" }, "priority": { "default": 100, "title": "Priority", "type": "integer" }, "rss_feed_url": { "title": "Rss Feed Url", "type": "string" } }, "required": [ "rss_feed_url" ], "title": "AutoTranscribedFeed", "type": "object" }, "AutoTranscribedResponse": { "properties": { "added_by_account_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Added By Account Id" }, "artwork_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Artwork Url" }, "author": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Author" }, "created_at": { "title": "Created At", "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "diarization_enabled": { "title": "Diarization Enabled", "type": "boolean" }, "global_show_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Global Show Id" }, "id": { "title": "Id", "type": "string" }, "last_seen_guid": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Seen Guid" }, "priority": { "title": "Priority", "type": "integer" }, "rss_feed_url": { "title": "Rss Feed Url", "type": "string" }, "title": { "title": "Title", "type": "string" }, "updated_at": { "title": "Updated At", "type": "string" } }, "required": [ "id", "rss_feed_url", "title", "priority", "diarization_enabled", "created_at", "updated_at" ], "title": "AutoTranscribedResponse", "type": "object" }, "AutoTranscribedUpdate": { "properties": { "diarization_enabled": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Diarization Enabled" }, "priority": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Priority" } }, "title": "AutoTranscribedUpdate", "type": "object" }, "AutomationAction": { "additionalProperties": false, "properties": { "params": { "additionalProperties": true, "title": "AutomationActionParams", "type": "object" }, "verb": { "maxLength": 128, "minLength": 1, "title": "Verb", "type": "string" }, "when": { "anyOf": [ { "$ref": "#/components/schemas/ConditionGroup" }, { "type": "null" } ] } }, "required": [ "verb" ], "title": "AutomationAction", "type": "object" }, "AutomationActivityItem": { "properties": { "id": { "title": "Id", "type": "string" }, "links": { "items": { "$ref": "#/components/schemas/AutomationActivityLink" }, "title": "Links", "type": "array" }, "occurred_at": { "format": "date-time", "title": "Occurred At", "type": "string" }, "origin_room_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Origin Room Id" }, "origin_surface": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Origin Surface" }, "status": { "enum": [ "success", "failed", "partial", "running", "queued" ], "title": "Status", "type": "string" }, "summary": { "title": "Summary", "type": "string" }, "trigger_source": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Trigger Source" }, "type": { "enum": [ "workflow", "rule", "subagent", "artifact" ], "title": "Type", "type": "string" }, "workflow_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Workflow Id" } }, "required": [ "id", "type", "status", "summary", "occurred_at" ], "title": "AutomationActivityItem", "type": "object" }, "AutomationActivityLink": { "properties": { "deleted": { "default": false, "title": "Deleted", "type": "boolean" }, "href": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Href" }, "label": { "title": "Label", "type": "string" }, "target_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Target Id" }, "type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Type" } }, "required": [ "label" ], "title": "AutomationActivityLink", "type": "object" }, "AutomationActivityResponse": { "properties": { "items": { "items": { "$ref": "#/components/schemas/AutomationActivityItem" }, "title": "Items", "type": "array" }, "limit": { "title": "Limit", "type": "integer" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Next Cursor" }, "window_days": { "title": "Window Days", "type": "integer" } }, "required": [ "items", "window_days", "limit" ], "title": "AutomationActivityResponse", "type": "object" }, "AutomationAssignee": { "description": "One principal an automation may assign work to (TIDY-16717 / S2, R5).\n\n``kind`` distinguishes a human member from an agent member (virtual\nemployee) for LABELLING only — both own work through the same\n``activities.owner`` column and no behavior branches on it.", "properties": { "account_id": { "title": "Account Id", "type": "string" }, "display_name": { "title": "Display Name", "type": "string" }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Email" }, "kind": { "enum": [ "human", "agent" ], "title": "Kind", "type": "string" }, "slug": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Slug" } }, "required": [ "account_id", "kind", "display_name" ], "title": "AutomationAssignee", "type": "object" }, "AutomationCredentialCreate": { "properties": { "auth_scheme": { "default": "env", "enum": [ "env", "bearer", "basic", "api_key_header", "hmac", "aws_sigv4" ], "title": "Auth Scheme", "type": "string" }, "base_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Base Url" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "name": { "maxLength": 120, "minLength": 1, "title": "Name", "type": "string" }, "plugin_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Plugin Id" }, "scheme_config": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Scheme Config" }, "value": { "minLength": 1, "title": "Value", "type": "string" }, "visibility": { "default": "private", "enum": [ "private", "shared", "global" ], "title": "Visibility", "type": "string" } }, "required": [ "name", "value" ], "title": "AutomationCredentialCreate", "type": "object" }, "AutomationCredentialResponse": { "properties": { "auth_scheme": { "default": "env", "enum": [ "env", "bearer", "basic", "api_key_header", "hmac", "aws_sigv4" ], "title": "Auth Scheme", "type": "string" }, "base_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Base Url" }, "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Description" }, "has_value": { "default": true, "title": "Has Value", "type": "boolean" }, "id": { "title": "Id", "type": "string" }, "key_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Key Id" }, "key_version": { "default": 1, "title": "Key Version", "type": "integer" }, "last_used_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Last Used At" }, "name": { "title": "Name", "type": "string" }, "owner_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Owner Id" }, "plugin_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Plugin Id" }, "scheme_config": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "title": "Scheme Config" }, "tenant_id": { "title": "Tenant Id", "type": "string" }, "updated_at": { "format": "date-time", "title": "Updated At", "type": "string" }, "visibility": { "enum": [ "private", "shared", "global" ], "title": "Visibility", "type": "string" } }, "required": [ "id", "tenant_id", "name", "visibility", "created_at", "updated_at" ], "title": "AutomationCredentialResponse", "type": "object" }, "AutomationCredentialUpdate": { "properties": { "auth_scheme": { "anyOf": [ { "enum": [ "env", "bearer", "basic", "api_key_header", "hmac", "aws_sigv4" ], "type": "string" }, { "type": "null" } ], "title": "Auth Scheme" }, "base_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Base Url" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "name": { "anyOf": [ { "maxLength": 120, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Name" }, "scheme_config": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Scheme Config" }, "value": { "anyOf": [ { "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Value" }, "visibility": { "anyOf": [ { "enum": [ "private", "shared", "global" ], "type": "string" }, { "type": "null" } ], "title": "Visibility" } }, "title": "AutomationCredentialUpdate", "type": "object" }, "AutomationPromotionStatus": { "description": "Why Auto-CRM still requires a human (TIDY-15442, R80/D21).\n\n``auto_approval_allowed`` is False in v1 for every tenant and every\nmeasurement; ``refusals`` always contains ``auto_approval_unsupported_in_v1``\nbecause no auto-approval contract exists to satisfy.", "properties": { "approved": { "title": "Approved", "type": "integer" }, "auto_approval_allowed": { "title": "Auto Approval Allowed", "type": "boolean" }, "decided_sample": { "title": "Decided Sample", "type": "integer" }, "precision": { "title": "Precision", "type": "number" }, "refusals": { "items": { "type": "string" }, "title": "Refusals", "type": "array" }, "required_precision": { "title": "Required Precision", "type": "number" }, "required_sample": { "title": "Required Sample", "type": "integer" }, "supported_contract_version": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Supported Contract Version" } }, "required": [ "auto_approval_allowed", "refusals", "supported_contract_version", "decided_sample", "approved", "precision", "required_sample", "required_precision" ], "title": "AutomationPromotionStatus", "type": "object" }, "AutomationRuleCreate": { "additionalProperties": false, "properties": { "actions": { "items": { "$ref": "#/components/schemas/AutomationAction" }, "title": "Actions", "type": "array" }, "actor_member_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "D9: defaults to the creating member; any other member is refused with 403 (structural anti-escalation).", "title": "Actor Member Id" }, "allow_automation_trigger": { "default": false, "title": "Allow Automation Trigger", "type": "boolean" }, "conditions": { "$ref": "#/components/schemas/ConditionGroup" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "enabled": { "default": false, "title": "Enabled", "type": "boolean" }, "facet_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Facet whose instances the rule matches for data triggers; NULL for system-event-lane rules.", "title": "Facet Id" }, "idempotency_key": { "anyOf": [ { "$ref": "#/components/schemas/IdempotencyKey" }, { "type": "null" } ] }, "name": { "maxLength": 200, "minLength": 1, "title": "Name", "type": "string" }, "on_failure": { "items": { "$ref": "#/components/schemas/AutomationAction" }, "title": "On Failure", "type": "array" }, "owner_member_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Routing and visibility owner; null (the default) means tenant-shared. Set to yourself to make the rule private. Execution actor is unchanged.", "title": "Owner Member Id" }, "slug": { "maxLength": 128, "minLength": 1, "title": "Slug", "type": "string" }, "status": { "default": "draft", "enum": [ "draft", "active", "paused" ], "title": "Status", "type": "string" }, "trigger": { "discriminator": { "mapping": { "button": "#/components/schemas/ButtonTrigger", "created": "#/components/schemas/CreatedTrigger", "deleted": "#/components/schemas/DeletedTrigger", "email": "#/components/schemas/EmailTrigger", "link_added": "#/components/schemas/LinkAddedTrigger", "plugin_event": "#/components/schemas/PluginEventTrigger", "property_changed": "#/components/schemas/PropertyChangedTrigger", "scheduled": "#/components/schemas/ScheduledTrigger", "system_event": "#/components/schemas/SystemEventTrigger" }, "propertyName": "kind" }, "oneOf": [ { "$ref": "#/components/schemas/CreatedTrigger" }, { "$ref": "#/components/schemas/PropertyChangedTrigger" }, { "$ref": "#/components/schemas/DeletedTrigger" }, { "$ref": "#/components/schemas/ButtonTrigger" }, { "$ref": "#/components/schemas/ScheduledTrigger" }, { "$ref": "#/components/schemas/LinkAddedTrigger" }, { "$ref": "#/components/schemas/SystemEventTrigger" }, { "$ref": "#/components/schemas/EmailTrigger" }, { "$ref": "#/components/schemas/PluginEventTrigger" } ], "title": "Trigger" } }, "required": [ "name", "slug", "trigger" ], "title": "AutomationRuleCreate", "type": "object" }, "AutomationRuleListResponse": { "description": "Tenant automation list (R19/R20/R23): the rules the caller may see\n(own rules; all rules for tenant admins — D9 visibility without\nimpersonation) plus the tenant metering summary surfaced as the\npause-on-exceed banner state.", "properties": { "rules": { "items": { "$ref": "#/components/schemas/AutomationRuleResponse" }, "title": "Rules", "type": "array" }, "usage": { "$ref": "#/components/schemas/AutomationUsageSummary" } }, "required": [ "rules", "usage" ], "title": "AutomationRuleListResponse", "type": "object" }, "AutomationRuleResponse": { "properties": { "actions": { "items": { "additionalProperties": true, "type": "object" }, "title": "Actions", "type": "array" }, "actor_member_id": { "title": "Actor Member Id", "type": "string" }, "allow_automation_trigger": { "title": "Allow Automation Trigger", "type": "boolean" }, "conditions": { "additionalProperties": true, "title": "Conditions", "type": "object" }, "consecutive_failures": { "title": "Consecutive Failures", "type": "integer" }, "created_at": { "title": "Created At" }, "created_by_member_id": { "title": "Created By Member Id", "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Description" }, "enabled": { "title": "Enabled", "type": "boolean" }, "facet_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Facet Id" }, "failure_count": { "title": "Failure Count", "type": "integer" }, "id": { "title": "Id", "type": "string" }, "idempotency_key": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "title": "Idempotency Key" }, "name": { "title": "Name", "type": "string" }, "on_failure": { "items": { "additionalProperties": true, "type": "object" }, "title": "On Failure", "type": "array" }, "owner_member_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Owner Member Id" }, "paused_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Paused Reason" }, "published_version_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Published Version Id" }, "run_count": { "title": "Run Count", "type": "integer" }, "slug": { "title": "Slug", "type": "string" }, "status": { "title": "Status", "type": "string" }, "tenant_id": { "title": "Tenant Id", "type": "string" }, "trigger": { "additionalProperties": true, "title": "Trigger", "type": "object" }, "updated_at": { "title": "Updated At" } }, "required": [ "id", "tenant_id", "name", "slug", "enabled", "status", "actor_member_id", "trigger", "conditions", "actions", "allow_automation_trigger", "run_count", "failure_count", "consecutive_failures", "created_by_member_id", "created_at", "updated_at" ], "title": "AutomationRuleResponse", "type": "object" }, "AutomationRuleUpdate": { "additionalProperties": false, "description": "PATCH payload — every field optional; zero-action and actor semantics\nare re-validated in the router against the merged row. ``status`` is\nsystem-derived (enabled -> active, disabled -> draft, evaluator ->\npaused) and deliberately NOT patchable.", "properties": { "actions": { "anyOf": [ { "items": { "$ref": "#/components/schemas/AutomationAction" }, "type": "array" }, { "type": "null" } ], "title": "Actions" }, "actor_member_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Actor Member Id" }, "allow_automation_trigger": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Allow Automation Trigger" }, "conditions": { "anyOf": [ { "$ref": "#/components/schemas/ConditionGroup" }, { "type": "null" } ] }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "enabled": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Enabled" }, "facet_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Facet Id" }, "idempotency_key": { "anyOf": [ { "$ref": "#/components/schemas/IdempotencyKey" }, { "type": "null" } ] }, "name": { "anyOf": [ { "maxLength": 200, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Name" }, "on_failure": { "anyOf": [ { "items": { "$ref": "#/components/schemas/AutomationAction" }, "type": "array" }, { "type": "null" } ], "title": "On Failure" }, "owner_member_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Owner Member Id" }, "restored_from_version_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Restored From Version Id" }, "slug": { "anyOf": [ { "maxLength": 128, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Slug" }, "trigger": { "anyOf": [ { "discriminator": { "mapping": { "button": "#/components/schemas/ButtonTrigger", "created": "#/components/schemas/CreatedTrigger", "deleted": "#/components/schemas/DeletedTrigger", "email": "#/components/schemas/EmailTrigger", "link_added": "#/components/schemas/LinkAddedTrigger", "plugin_event": "#/components/schemas/PluginEventTrigger", "property_changed": "#/components/schemas/PropertyChangedTrigger", "scheduled": "#/components/schemas/ScheduledTrigger", "system_event": "#/components/schemas/SystemEventTrigger" }, "propertyName": "kind" }, "oneOf": [ { "$ref": "#/components/schemas/CreatedTrigger" }, { "$ref": "#/components/schemas/PropertyChangedTrigger" }, { "$ref": "#/components/schemas/DeletedTrigger" }, { "$ref": "#/components/schemas/ButtonTrigger" }, { "$ref": "#/components/schemas/ScheduledTrigger" }, { "$ref": "#/components/schemas/LinkAddedTrigger" }, { "$ref": "#/components/schemas/SystemEventTrigger" }, { "$ref": "#/components/schemas/EmailTrigger" }, { "$ref": "#/components/schemas/PluginEventTrigger" } ] }, { "type": "null" } ], "title": "Trigger" } }, "title": "AutomationRuleUpdate", "type": "object" }, "AutomationRunResponse": { "properties": { "chain_depth": { "title": "Chain Depth", "type": "integer" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Error" }, "finished_at": { "anyOf": [ {}, { "type": "null" } ], "default": null, "title": "Finished At" }, "id": { "title": "Id", "type": "string" }, "metered_units": { "default": 1, "title": "Metered Units", "type": "integer" }, "origin": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Origin" }, "parent_run_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Parent Run Id" }, "payload_expired": { "default": false, "title": "Payload Expired", "type": "boolean" }, "resolved_actions": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "default": null, "title": "Resolved Actions" }, "rule_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Rule Id" }, "rule_version_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Rule Version Id" }, "started_at": { "title": "Started At" }, "status": { "title": "Status", "type": "string" }, "tenant_id": { "title": "Tenant Id", "type": "string" }, "trigger_event": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "title": "Trigger Event" } }, "required": [ "id", "tenant_id", "status", "chain_depth", "started_at" ], "title": "AutomationRunResponse", "type": "object" }, "AutomationUsageSummary": { "description": "Tenant metering summary (TIDY-14800 / S11, R23): monthly metered\nusage against the entitlement ceiling plus the pause-on-exceed state.", "properties": { "automations_paused": { "title": "Automations Paused", "type": "boolean" }, "ceiling": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Ceiling" }, "feature_enabled": { "title": "Feature Enabled", "type": "boolean" }, "pause_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Pause Reason" }, "used": { "title": "Used", "type": "integer" } }, "required": [ "used", "feature_enabled", "automations_paused" ], "title": "AutomationUsageSummary", "type": "object" }, "AvailabilityBlockModel": { "description": "One busy interval of the member's week.\n\nBlocks only, by contract (TIDY-16595 / D-blocks-only): this model has no\ntitle, location, attendee or event-id field, and must not grow one — the\nsame payload is what the counterparty sees in the proposal email.", "properties": { "all_day": { "default": false, "description": "Whether the block spans a whole day", "title": "All Day", "type": "boolean" }, "end": { "description": "Busy interval end", "format": "date-time", "title": "End", "type": "string" }, "start": { "description": "Busy interval start", "format": "date-time", "title": "Start", "type": "string" } }, "required": [ "start", "end" ], "title": "AvailabilityBlockModel", "type": "object" }, "AvailabilityPreviewResponse": { "description": "The snippet the outbound proposal will carry, for pre-send preview.", "properties": { "blocks": { "description": "Merged busy intervals, blocks only", "items": { "$ref": "#/components/schemas/AvailabilityBlockModel" }, "title": "Blocks", "type": "array" }, "timezone": { "description": "IANA zone the blocks are labeled in", "title": "Timezone", "type": "string" }, "window_end": { "description": "End of the previewed week (exclusive)", "format": "date-time", "title": "Window End", "type": "string" }, "window_start": { "description": "Start of the previewed week", "format": "date-time", "title": "Window Start", "type": "string" } }, "required": [ "window_start", "window_end", "timezone" ], "title": "AvailabilityPreviewResponse", "type": "object" }, "AvailabilityResponse": { "description": "Response with availability information.", "properties": { "slots": { "default": [], "items": { "$ref": "#/components/schemas/AvailabilitySlot" }, "title": "Slots", "type": "array" }, "total_conflicts": { "default": 0, "title": "Total Conflicts", "type": "integer" } }, "title": "AvailabilityResponse", "type": "object" }, "AvailabilitySlot": { "description": "A time slot with availability status.", "properties": { "conflicting_event": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Conflicting Event" }, "end": { "format": "date-time", "title": "End", "type": "string" }, "is_available": { "title": "Is Available", "type": "boolean" }, "start": { "format": "date-time", "title": "Start", "type": "string" } }, "required": [ "start", "end", "is_available" ], "title": "AvailabilitySlot", "type": "object" }, "AvailabilityWindow": { "description": "A single open window within a weekday, in the owner's local tz.", "properties": { "end": { "description": "Local HH:MM (24h) window end", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$", "title": "End", "type": "string" }, "start": { "description": "Local HH:MM (24h) window start", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$", "title": "Start", "type": "string" } }, "required": [ "start", "end" ], "title": "AvailabilityWindow", "type": "object" }, "AvailableLabelsResponse": { "description": "Response for available labels endpoint.\n\nLists all unique labels used across tenant's emails for autocomplete.\n\nAttributes:\n labels: Alphabetically sorted list of unique labels\n count: Number of unique labels\n\nExample:\n {\"labels\": [\"family\", \"important\", \"school\", \"work\"], \"count\": 4}", "properties": { "count": { "description": "Number of unique labels", "title": "Count", "type": "integer" }, "labels": { "description": "Alphabetically sorted unique labels", "items": { "type": "string" }, "title": "Labels", "type": "array" } }, "required": [ "labels", "count" ], "title": "AvailableLabelsResponse", "type": "object" }, "AvatarConvertResponse": { "properties": { "cached": { "title": "Cached", "type": "boolean" }, "schema": { "additionalProperties": true, "title": "Schema", "type": "object" } }, "required": [ "schema", "cached" ], "title": "AvatarConvertResponse", "type": "object" }, "AvatarDescribeRequest": { "properties": { "description": { "maxLength": 300, "minLength": 1, "title": "Description", "type": "string" }, "schema": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Schema" }, "seed": { "default": "anonymous", "maxLength": 200, "title": "Seed", "type": "string" } }, "required": [ "description" ], "title": "AvatarDescribeRequest", "type": "object" }, "AvatarDescribeResponse": { "properties": { "dropped": { "items": { "type": "string" }, "title": "Dropped", "type": "array" }, "schema": { "additionalProperties": true, "title": "Schema", "type": "object" } }, "required": [ "schema", "dropped" ], "title": "AvatarDescribeResponse", "type": "object" }, "AvatarSchemaBody": { "description": "Body for setting/clearing the account self vector-avatar (TIDY-13113).", "properties": { "avatar_schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Avatar Schema" } }, "title": "AvatarSchemaBody", "type": "object" }, "AwayStateResponse": { "description": "Resolved away state for the current user.", "properties": { "is_away": { "description": "True if the user should appear away to others (OOO active OR manual override).", "title": "Is Away", "type": "boolean" }, "manual_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "User's last-set manual chat status (e.g. 'online', 'away', 'dnd'). Null if unset.", "title": "Manual Status" }, "source": { "description": "Origin of the away state: 'ooo', 'manual', 'none'.", "title": "Source", "type": "string" }, "until": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "description": "When the away state ends (OOO end_at) — null if open-ended or sourced from manual.", "title": "Until" } }, "required": [ "is_away", "source" ], "title": "AwayStateResponse", "type": "object" }, "BackfillHistoryResponse": { "description": "Response payload for the retroactive backfill admin endpoint.", "properties": { "folder_discovery": { "anyOf": [ { "additionalProperties": { "type": "integer" }, "type": "object" }, { "type": "null" } ], "description": "Folder discovery counts when the endpoint had to seed mappings before scheduling history backfill.", "title": "Folder Discovery" }, "job_id": { "description": "Stable identifier the operator can correlate to header_sync_folder_progress rows for this source. Equal to the email_source_config_id.", "title": "Job Id", "type": "string" }, "provider_type": { "description": "Provider, e.g. 'zoho', 'google'.", "title": "Provider Type", "type": "string" }, "source_id": { "description": "email_source_config_id", "title": "Source Id", "type": "string" }, "status": { "description": "'scheduled' if the orchestrator was launched, 'already_running' if a backfill is in flight, 'already_completed' if the source's backfill already finished.", "title": "Status", "type": "string" }, "tenant_id": { "description": "Owning tenant.", "title": "Tenant Id", "type": "string" } }, "required": [ "status", "job_id", "source_id", "tenant_id", "provider_type" ], "title": "BackfillHistoryResponse", "type": "object" }, "BackfillPreviewResponse": { "description": "Preview of items that would be linked during backfill.", "properties": { "capped_at": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Max limit if total exceeds safety threshold", "title": "Capped At" }, "emails": { "default": 0, "description": "Number of matching emails", "title": "Emails", "type": "integer" }, "events": { "default": 0, "description": "Number of matching events", "title": "Events", "type": "integer" }, "tasks": { "default": 0, "description": "Number of matching tasks", "title": "Tasks", "type": "integer" }, "total": { "default": 0, "description": "Total items to link", "title": "Total", "type": "integer" } }, "title": "BackfillPreviewResponse", "type": "object" }, "BadgesResponse": { "properties": { "earned": { "items": { "$ref": "#/components/schemas/EarnedBadge" }, "title": "Earned", "type": "array" }, "in_progress": { "items": { "$ref": "#/components/schemas/InProgressBadge" }, "title": "In Progress", "type": "array" } }, "required": [ "earned", "in_progress" ], "title": "BadgesResponse", "type": "object" }, "BatchCreateRequest": { "description": "Request model for batch event creation.", "properties": { "common_fields": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "Common fields applied to all events", "examples": [ { "metadata": { "batch_source": "season_schedule" }, "source_email": "coach@soccerleague.com", "type": "sports" } ], "title": "Common Fields" }, "events": { "description": "List of events to create", "items": { "$ref": "#/components/schemas/CalendarEventCreate" }, "maxItems": 100, "minItems": 1, "title": "Events", "type": "array" } }, "required": [ "events" ], "title": "BatchCreateRequest", "type": "object" }, "BatchCreateResponse": { "description": "Response model for batch event creation.", "properties": { "created": { "description": "Number of successfully created events", "title": "Created", "type": "integer" }, "events": { "items": { "$ref": "#/components/schemas/BatchEventResult" }, "title": "Events", "type": "array" }, "failed": { "description": "Number of failed event creations", "title": "Failed", "type": "integer" } }, "required": [ "created", "failed", "events" ], "title": "BatchCreateResponse", "type": "object" }, "BatchEventResult": { "description": "Result for a single event in batch creation.", "properties": { "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error" }, "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Id" }, "status": { "description": "Creation status", "examples": [ "created", "failed" ], "title": "Status", "type": "string" }, "title": { "title": "Title", "type": "string" } }, "required": [ "title", "status" ], "title": "BatchEventResult", "type": "object" }, "BatchItem": { "description": "Single item in a batch operation.", "properties": { "id": { "title": "Id", "type": "string" }, "type": { "title": "Type", "type": "string" } }, "required": [ "type", "id" ], "title": "BatchItem", "type": "object" }, "BatchMergeItem": { "description": "Single merge operation in a batch.", "properties": { "create_note_from_unmapped": { "default": true, "description": "Deprecated (TIDY-12173): no longer creates a note; has no effect", "title": "Create Note From Unmapped", "type": "boolean" }, "primary_id": { "description": "Contact ID to keep", "title": "Primary Id", "type": "string" }, "secondary_ids": { "description": "Contact IDs to merge into primary", "items": { "type": "string" }, "title": "Secondary Ids", "type": "array" } }, "required": [ "primary_id", "secondary_ids" ], "title": "BatchMergeItem", "type": "object" }, "BatchMergeRequest": { "description": "Request for POST /api/v1/contacts/merge/batch.\n\nAttributes:\n merges: List of merge operations to execute", "properties": { "merges": { "description": "Merge operations to execute", "items": { "$ref": "#/components/schemas/BatchMergeItem" }, "title": "Merges", "type": "array" } }, "required": [ "merges" ], "title": "BatchMergeRequest", "type": "object" }, "BatchMergeResponse": { "description": "Response from POST /api/v1/contacts/merge/batch.\n\nAttributes:\n success: Whether all merges succeeded\n merged_count: Number of contacts merged\n results: Individual results for each merge", "properties": { "merged_count": { "description": "Total contacts merged", "title": "Merged Count", "type": "integer" }, "results": { "default": [], "description": "Individual merge results", "items": { "$ref": "#/components/schemas/BatchMergeResultItem" }, "title": "Results", "type": "array" }, "success": { "description": "Whether all merges succeeded", "title": "Success", "type": "boolean" } }, "required": [ "success", "merged_count" ], "title": "BatchMergeResponse", "type": "object" }, "BatchMergeResultItem": { "description": "Result of a single merge in a batch.", "properties": { "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Error message if failed", "title": "Error" }, "primary_id": { "description": "The contact the merge kept: the requested primary, unless a workspace-member or Shared contact among the secondaries had to survive instead (TIDY-15266, TIDY-19981).", "title": "Primary Id", "type": "string" }, "secondary_ids": { "description": "Contact IDs merged into primary_id", "items": { "type": "string" }, "title": "Secondary Ids", "type": "array" }, "success": { "description": "Whether merge succeeded", "title": "Success", "type": "boolean" } }, "required": [ "primary_id", "secondary_ids", "success" ], "title": "BatchMergeResultItem", "type": "object" }, "BatchRequest": { "description": "Request body for batch operations.", "properties": { "items": { "items": { "$ref": "#/components/schemas/BatchItem" }, "title": "Items", "type": "array" } }, "required": [ "items" ], "title": "BatchRequest", "type": "object" }, "BatchResponse": { "description": "Response for batch operations.", "properties": { "errors": { "items": { "type": "string" }, "title": "Errors", "type": "array" }, "failed": { "title": "Failed", "type": "integer" }, "processed": { "title": "Processed", "type": "integer" } }, "required": [ "processed", "failed" ], "title": "BatchResponse", "type": "object" }, "BatchRunCreate": { "description": "Create a batch run: an audience (saved view), an action chain, a rate.\n\nThe run is created idle — nothing resolves or executes until ``start``.", "properties": { "actions": { "description": "Automation action chain — [{verb, params, when?}] — validated by the same rules automation rule saves use.", "items": { "additionalProperties": true, "type": "object" }, "minItems": 1, "title": "Actions", "type": "array" }, "rate_per_second": { "default": 1.0, "description": "Items per second, 0.1–50.0. Held across worker restarts.", "maximum": 50.0, "minimum": 0.1, "title": "Rate Per Second", "type": "number" }, "saved_view_id": { "description": "The saved view (or database record view) whose items the run acts on.", "examples": [ "W-550e8400-e29b-41d4-a716-446655440000" ], "pattern": "^W-[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "title": "SavedViewId", "type": "string", "x-tidy-typed-id-prefix": "W", "x-tidy-typed-id-table": "saved_views" } }, "required": [ "saved_view_id", "actions" ], "title": "BatchRunCreate", "type": "object" }, "BatchRunItem": { "properties": { "attempts": { "title": "Attempts", "type": "integer" }, "id": { "title": "Id", "type": "string" }, "item_id": { "title": "Item Id", "type": "string" }, "item_table": { "title": "Item Table", "type": "string" }, "last_error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Last Error" }, "ordering": { "title": "Ordering", "type": "integer" }, "state": { "title": "State", "type": "string" }, "updated_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Updated At" } }, "required": [ "id", "item_table", "item_id", "state", "attempts", "ordering" ], "title": "BatchRunItem", "type": "object" }, "BatchRunItemsResponse": { "properties": { "items": { "items": { "$ref": "#/components/schemas/BatchRunItem" }, "title": "Items", "type": "array" }, "limit": { "title": "Limit", "type": "integer" }, "offset": { "title": "Offset", "type": "integer" }, "run_id": { "title": "Run Id", "type": "string" } }, "required": [ "run_id", "items", "limit", "offset" ], "title": "BatchRunItemsResponse", "type": "object" }, "BatchRunListResponse": { "description": "The caller's runs, newest first.", "properties": { "limit": { "title": "Limit", "type": "integer" }, "offset": { "title": "Offset", "type": "integer" }, "runs": { "items": { "$ref": "#/components/schemas/BatchRunResponse" }, "title": "Runs", "type": "array" } }, "required": [ "runs", "limit", "offset" ], "title": "BatchRunListResponse", "type": "object" }, "BatchRunPreflightResponse": { "description": "What a view resolves to before anything is created — the number the\nauthor reviews, plus the facet/table the run would act on.", "properties": { "facet_slug": { "title": "Facet Slug", "type": "string" }, "item_count": { "title": "Item Count", "type": "integer" }, "item_table": { "title": "Item Table", "type": "string" }, "saved_view_id": { "title": "Saved View Id", "type": "string" }, "view_name": { "title": "View Name", "type": "string" } }, "required": [ "saved_view_id", "view_name", "facet_slug", "item_table", "item_count" ], "title": "BatchRunPreflightResponse", "type": "object" }, "BatchRunResponse": { "description": "A run's configuration plus its live progress.\n\n``at_least_once`` is stated, not implied: an item's ledger row is its\nreceipt, and a verb without a delivery claim can re-run on a resume.", "properties": { "actions": { "items": { "additionalProperties": true, "type": "object" }, "title": "Actions", "type": "array" }, "at_least_once": { "default": true, "description": "Per-item execution is at-least-once. Verbs with a delivery claim (the communicate family) will not repeat a completed send on a resume; other verbs may re-run an interrupted item.", "title": "At Least Once", "type": "boolean" }, "created_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Created At" }, "created_by_member_id": { "title": "Created By Member Id", "type": "string" }, "facet_slug": { "title": "Facet Slug", "type": "string" }, "failed_count": { "title": "Failed Count", "type": "integer" }, "finished_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Finished At" }, "id": { "title": "Id", "type": "string" }, "item_table": { "title": "Item Table", "type": "string" }, "last_error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Last Error" }, "pending_count": { "title": "Pending Count", "type": "integer" }, "rate_per_second": { "title": "Rate Per Second", "type": "number" }, "running_count": { "title": "Running Count", "type": "integer" }, "saved_view_id": { "title": "Saved View Id", "type": "string" }, "skipped_count": { "title": "Skipped Count", "type": "integer" }, "stalled_count": { "default": 0, "description": "In-flight items whose lease expired — the run is making no progress and the reap has not returned them yet.", "title": "Stalled Count", "type": "integer" }, "started_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Started At" }, "state": { "title": "State", "type": "string" }, "succeeded_count": { "title": "Succeeded Count", "type": "integer" }, "tenant_id": { "title": "Tenant Id", "type": "string" }, "total_count": { "title": "Total Count", "type": "integer" }, "updated_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Updated At" } }, "required": [ "id", "tenant_id", "created_by_member_id", "saved_view_id", "facet_slug", "item_table", "actions", "rate_per_second", "state", "total_count", "succeeded_count", "failed_count", "skipped_count", "pending_count", "running_count" ], "title": "BatchRunResponse", "type": "object" }, "BeaconEvent": { "description": "A single surface visit. ``count`` collapses repeat visits client-side.", "properties": { "count": { "default": 1, "maximum": 1000.0, "minimum": 1.0, "title": "Count", "type": "integer" }, "surface": { "enum": [ "mail", "calendar", "contacts", "tasks", "projects", "notes", "chat", "photos", "podcasts", "workspace", "assistant", "search", "settings" ], "title": "Surface", "type": "string" } }, "required": [ "surface" ], "title": "BeaconEvent", "type": "object" }, "BeaconRequest": { "description": "A batch of surface events. Identity is NEVER carried here — tenant_id and\nuser_id come from the bearer token only, so the body cannot spoof them.", "properties": { "events": { "items": { "$ref": "#/components/schemas/BeaconEvent" }, "maxItems": 20, "minItems": 1, "title": "Events", "type": "array" } }, "required": [ "events" ], "title": "BeaconRequest", "type": "object" }, "BeforeSpanPlacement": { "additionalProperties": false, "description": "Immediately before the top-level block containing ``old``.", "properties": { "mode": { "const": "before_span", "title": "Mode", "type": "string" }, "old": { "maxLength": 10000, "minLength": 1, "title": "Old", "type": "string" } }, "required": [ "mode", "old" ], "title": "BeforeSpanPlacement", "type": "object" }, "BenchmarkComparison": { "properties": { "color": { "title": "Color", "type": "string" }, "comparison": { "title": "Comparison", "type": "string" }, "percentile_label": { "title": "Percentile Label", "type": "string" }, "user_value": { "title": "User Value", "type": "number" } }, "required": [ "user_value", "comparison", "percentile_label", "color" ], "title": "BenchmarkComparison", "type": "object" }, "BetaInviteRedeemRequest": { "description": "POST /api/v1/beta/invite/redeem request body.", "properties": { "invite_code": { "description": "Invite code value from invite_codes.code", "maxLength": 64, "minLength": 4, "title": "Invite Code", "type": "string" } }, "required": [ "invite_code" ], "title": "BetaInviteRedeemRequest", "type": "object" }, "BetaInviteRedeemResponse": { "description": "POST /api/v1/beta/invite/redeem success response.\n\n`status` is `added` on the first redeem, `already_member` if the tester\nwas already in the Google Group (idempotent re-redeem by the same\naccount).", "properties": { "play_track": { "const": "internal", "default": "internal", "title": "Play Track", "type": "string" }, "play_track_opt_in_url": { "title": "Play Track Opt In Url", "type": "string" }, "status": { "enum": [ "added", "already_member" ], "title": "Status", "type": "string" }, "tester_email": { "title": "Tester Email", "type": "string" } }, "required": [ "status", "play_track_opt_in_url", "tester_email" ], "title": "BetaInviteRedeemResponse", "type": "object" }, "BillingAccountItem": { "properties": { "billing_exempt": { "default": false, "title": "Billing Exempt", "type": "boolean" }, "credits_allocated": { "default": 0, "title": "Credits Allocated", "type": "integer" }, "credits_used": { "default": 0, "title": "Credits Used", "type": "number" }, "owner_email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Owner Email" }, "plan_tier": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Plan Tier" }, "seats": { "default": 0, "title": "Seats", "type": "integer" }, "subscription_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Subscription Status" }, "tenant_id": { "title": "Tenant Id", "type": "string" }, "tenant_name": { "title": "Tenant Name", "type": "string" } }, "required": [ "tenant_id", "tenant_name" ], "title": "BillingAccountItem", "type": "object" }, "BillingAccountsResponse": { "properties": { "accounts": { "items": { "$ref": "#/components/schemas/BillingAccountItem" }, "title": "Accounts", "type": "array" }, "stripe_dashboard_url": { "title": "Stripe Dashboard Url", "type": "string" } }, "required": [ "accounts", "stripe_dashboard_url" ], "title": "BillingAccountsResponse", "type": "object" }, "BillingCoupon": { "properties": { "amount_off_cents": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Amount Off Cents" }, "currency": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Currency" }, "duration": { "title": "Duration", "type": "string" }, "duration_in_months": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Duration In Months" }, "id": { "title": "Id", "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name" }, "percent_off": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Percent Off" } }, "required": [ "id", "duration" ], "title": "BillingCoupon", "type": "object" }, "BillingDiscount": { "description": "A Stripe discount on the subscription (Stripe owns it, decision 1).", "properties": { "coupon": { "$ref": "#/components/schemas/BillingCoupon" }, "end": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "End" }, "promotion_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Promotion Code" } }, "required": [ "coupon" ], "title": "BillingDiscount", "type": "object" }, "BillingModeResponse": { "description": "The Stripe mode this deployment bills in, from its key (TIDY-19279).", "properties": { "dashboard_url": { "title": "Dashboard Url", "type": "string" }, "env": { "title": "Env", "type": "string" }, "livemode": { "title": "Livemode", "type": "boolean" } }, "required": [ "env", "livemode", "dashboard_url" ], "title": "BillingModeResponse", "type": "object" }, "BindableWorkflow": { "description": "A workflow surfaced to the facet-action authoring picker (TIDY-11015 / S1).", "properties": { "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "enabled": { "title": "Enabled", "type": "boolean" }, "id": { "description": "workflow_scripts.id", "title": "Id", "type": "string" }, "inputs": { "description": "Declared bindable inputs", "items": { "$ref": "#/components/schemas/WorkflowInputSpec" }, "title": "Inputs", "type": "array" }, "name": { "title": "Name", "type": "string" } }, "required": [ "id", "name", "enabled" ], "title": "BindableWorkflow", "type": "object" }, "BlockRejectionModel": { "properties": { "block_path": { "title": "Block Path", "type": "string" }, "block_type": { "title": "Block Type", "type": "string" }, "code": { "title": "Code", "type": "string" }, "message": { "title": "Message", "type": "string" } }, "required": [ "block_path", "block_type", "code", "message" ], "title": "BlockRejectionModel", "type": "object" }, "BlockRequest": { "properties": { "scope": { "default": "address", "title": "Scope", "type": "string" }, "unsubscribe": { "default": false, "title": "Unsubscribe", "type": "boolean" } }, "title": "BlockRequest", "type": "object" }, "BlockResponse": { "properties": { "status": { "default": "blocked", "title": "Status", "type": "string" }, "unsubscribe_attempted": { "default": false, "title": "Unsubscribe Attempted", "type": "boolean" }, "unsubscribe_result": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Unsubscribe Result" } }, "title": "BlockResponse", "type": "object" }, "BlockSenderRequest": { "properties": { "apply_to_all_from_sender": { "default": false, "description": "Block all emails from sender", "title": "Apply To All From Sender", "type": "boolean" }, "attempt_unsubscribe": { "default": false, "description": "Try to unsubscribe via List-Unsubscribe", "title": "Attempt Unsubscribe", "type": "boolean" }, "scope": { "default": "address", "description": "Block scope: 'address' or 'domain'", "title": "Scope", "type": "string" } }, "title": "BlockSenderRequest", "type": "object" }, "BlockSenderResponse": { "properties": { "block_scope": { "title": "Block Scope", "type": "string" }, "defense_rule_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Defense Rule Id" }, "email_id": { "format": "uuid", "title": "Email Id", "type": "string" }, "emails_blocked": { "default": 1, "title": "Emails Blocked", "type": "integer" }, "sender_email": { "title": "Sender Email", "type": "string" }, "success": { "default": true, "title": "Success", "type": "boolean" }, "unsubscribe_attempted": { "default": false, "title": "Unsubscribe Attempted", "type": "boolean" }, "unsubscribe_result": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Unsubscribe Result" } }, "required": [ "email_id", "sender_email", "block_scope" ], "title": "BlockSenderResponse", "type": "object" }, "BodyEditsRequest": { "additionalProperties": false, "description": "Legacy adapter body. Optional request_id; header may supply identity.", "properties": { "operations": { "items": { "discriminator": { "mapping": { "add_element": "#/components/schemas/AddElementOp", "append_section": "#/components/schemas/AppendSectionOp", "delete_element": "#/components/schemas/DeleteElementOp", "delete_span": "#/components/schemas/DeleteSpanOp", "insert_column": "#/components/schemas/InsertColumnOp", "insert_embed": "#/components/schemas/InsertEmbedOp", "insert_row": "#/components/schemas/InsertRowOp", "insert_slide": "#/components/schemas/InsertSlideOp", "remove_block": "#/components/schemas/RemoveBlockOp", "remove_slide": "#/components/schemas/RemoveSlideOp", "reorder_slide": "#/components/schemas/ReorderSlideOp", "replace_blocks": "#/components/schemas/ReplaceBlocksOp", "replace_section": "#/components/schemas/ReplaceSectionOp", "replace_span": "#/components/schemas/ReplaceSpanOp", "set_cell": "#/components/schemas/SetCellOp", "set_layout": "#/components/schemas/SetSlideLayoutOp", "set_range": "#/components/schemas/SetRangeOp", "toggle_checklist_item": "#/components/schemas/ToggleChecklistItemOp", "update_element": "#/components/schemas/UpdateElementOp" }, "propertyName": "op" }, "oneOf": [ { "$ref": "#/components/schemas/ToggleChecklistItemOp" }, { "$ref": "#/components/schemas/ReplaceSpanOp" }, { "$ref": "#/components/schemas/DeleteSpanOp" }, { "$ref": "#/components/schemas/RemoveBlockOp" }, { "$ref": "#/components/schemas/AppendSectionOp" }, { "$ref": "#/components/schemas/ReplaceSectionOp" }, { "$ref": "#/components/schemas/ReplaceBlocksOp" }, { "$ref": "#/components/schemas/InsertEmbedOp" }, { "$ref": "#/components/schemas/InsertColumnOp" }, { "$ref": "#/components/schemas/InsertRowOp" }, { "$ref": "#/components/schemas/SetCellOp" }, { "$ref": "#/components/schemas/SetRangeOp" }, { "$ref": "#/components/schemas/UpdateElementOp" }, { "$ref": "#/components/schemas/DeleteElementOp" }, { "$ref": "#/components/schemas/AddElementOp" }, { "$ref": "#/components/schemas/InsertSlideOp" }, { "$ref": "#/components/schemas/RemoveSlideOp" }, { "$ref": "#/components/schemas/ReorderSlideOp" }, { "$ref": "#/components/schemas/SetSlideLayoutOp" } ] }, "maxItems": 20, "minItems": 1, "title": "Operations", "type": "array" }, "request_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Request Id" } }, "required": [ "operations" ], "title": "BodyEditsRequest", "type": "object" }, "BodyEditsResponse": { "properties": { "actor_type": { "title": "Actor Type", "type": "string" }, "checklist": { "items": { "$ref": "#/components/schemas/ChecklistItemState" }, "title": "Checklist", "type": "array" }, "id": { "title": "Id", "type": "string" }, "live_broadcast": { "title": "Live Broadcast", "type": "boolean" }, "results": { "items": { "additionalProperties": true, "type": "object" }, "title": "Results", "type": "array" }, "version_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Version Id" } }, "required": [ "id", "results", "actor_type", "live_broadcast" ], "title": "BodyEditsResponse", "type": "object" }, "Body_attachChannelFile": { "properties": { "attached_via": { "default": "files_tab", "enum": [ "files_tab", "message" ], "title": "Attached Via", "type": "string" }, "file": { "contentMediaType": "application/octet-stream", "description": "File to attach to the channel", "title": "File", "type": "string" }, "matrix_event_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Matrix event id when the file came from a message attachment", "title": "Matrix Event Id" } }, "required": [ "file" ], "title": "Body_attachChannelFile", "type": "object" }, "Body_convertDocx": { "properties": { "emailId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Emailid" }, "file": { "contentMediaType": "application/octet-stream", "title": "File", "type": "string" }, "fileHash": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Filehash" } }, "required": [ "file" ], "title": "Body_convertDocx", "type": "object" }, "Body_convertPptx": { "properties": { "emailId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Emailid" }, "file": { "contentMediaType": "application/octet-stream", "title": "File", "type": "string" }, "fileHash": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Filehash" } }, "required": [ "file" ], "title": "Body_convertPptx", "type": "object" }, "Body_convertXlsx": { "properties": { "emailId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Emailid" }, "file": { "contentMediaType": "application/octet-stream", "title": "File", "type": "string" }, "fileHash": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Filehash" } }, "required": [ "file" ], "title": "Body_convertXlsx", "type": "object" }, "Body_createVoiceCapture": { "properties": { "audio": { "contentMediaType": "application/octet-stream", "description": "Complete audio file (audio/ogg Opus, <=15MB).", "title": "Audio", "type": "string" }, "captured_at": { "description": "Device-clock capture time, ISO 8601 UTC with Z.", "title": "Captured At", "type": "string" }, "client_capture_id": { "description": "Client-generated UUIDv4 idempotency key.", "title": "Client Capture Id", "type": "string" }, "duration_seconds": { "anyOf": [ { "minimum": 0.0, "type": "number" }, { "type": "null" } ], "title": "Duration Seconds" }, "facet_slug": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Custom facet slug, or null for plain capture.", "title": "Facet Slug" } }, "required": [ "audio", "client_capture_id", "captured_at" ], "title": "Body_createVoiceCapture", "type": "object" }, "Body_extensionUploadWebClippingScreenshot": { "properties": { "capture_mode": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Clip mode: bookmark | image_capture | text_capture. When 'image_capture', the clipped image also becomes a photo-faceted photos row (source='extension_clip'). TIDY-13904.", "title": "Capture Mode" }, "file": { "contentMediaType": "application/octet-stream", "description": "Visible-tab screenshot image", "title": "File", "type": "string" } }, "required": [ "file" ], "title": "Body_extensionUploadWebClippingScreenshot", "type": "object" }, "Body_importEvernote": { "properties": { "file": { "contentMediaType": "application/octet-stream", "title": "File", "type": "string" } }, "required": [ "file" ], "title": "Body_importEvernote", "type": "object" }, "Body_importIcs": { "properties": { "file": { "contentMediaType": "application/octet-stream", "title": "File", "type": "string" } }, "required": [ "file" ], "title": "Body_importIcs", "type": "object" }, "Body_importMbox": { "properties": { "file": { "contentMediaType": "application/octet-stream", "title": "File", "type": "string" } }, "required": [ "file" ], "title": "Body_importMbox", "type": "object" }, "Body_importNotion": { "properties": { "file": { "contentMediaType": "application/octet-stream", "title": "File", "type": "string" } }, "required": [ "file" ], "title": "Body_importNotion", "type": "object" }, "Body_importPodcastSubscriptionsOpml": { "properties": { "file": { "contentMediaType": "application/octet-stream", "description": "OPML file containing RSS subscriptions", "title": "File", "type": "string" } }, "required": [ "file" ], "title": "Body_importPodcastSubscriptionsOpml", "type": "object" }, "Body_importVcf": { "properties": { "file": { "contentMediaType": "application/octet-stream", "title": "File", "type": "string" } }, "required": [ "file" ], "title": "Body_importVcf", "type": "object" }, "Body_ingestPhoto": { "properties": { "client_analysis": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional on-device analysis envelope (JSON, kind=photo) carrying device vision description/ocr_text — see TIDY-13519 D1.", "title": "Client Analysis" }, "client_upload_id": { "anyOf": [ { "maxLength": 200, "type": "string" }, { "type": "null" } ], "description": "Optional stable client upload id (TIDY-19719). Makes the upload idempotent per caller: a replay of the same bytes returns the photo already saved (201, same id); different bytes are HTTP 409.", "title": "Client Upload Id" }, "context": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Originating note/journal id (telemetry).", "title": "Context" }, "file": { "contentMediaType": "application/octet-stream", "description": "Image file (<=25 MB).", "title": "File", "type": "string" }, "lat": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Latitude (wins over EXIF GPS).", "title": "Lat" }, "lng": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Longitude (wins over EXIF GPS).", "title": "Lng" }, "source": { "description": "capture | share | web_upload | email_extraction | gallery", "title": "Source", "type": "string" }, "taken_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO UTC capture time (wins over EXIF).", "title": "Taken At" } }, "required": [ "file", "source" ], "title": "Body_ingestPhoto", "type": "object" }, "Body_publishDeliverable": { "properties": { "commit": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Commit sha this content was published from.", "title": "Commit" }, "file": { "contentMediaType": "application/octet-stream", "description": "The deliverable's bytes.", "title": "File", "type": "string" }, "old_path": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Previous path, when this publish is a rename. Moves the identity.", "title": "Old Path" }, "path": { "description": "Repo-relative path (or workspace-root-relative for a project with no linked repository). This is the deliverable's IDENTITY: publishing the same path again versions the same file.", "title": "Path", "type": "string" } }, "required": [ "file", "path" ], "title": "Body_publishDeliverable", "type": "object" }, "Body_saveAnimatedAvatarPhoto": { "properties": { "file": { "contentMediaType": "application/octet-stream", "description": "Animated GIF (<=2 MB).", "title": "File", "type": "string" } }, "required": [ "file" ], "title": "Body_saveAnimatedAvatarPhoto", "type": "object" }, "Body_speechRecordingChunkUpload": { "properties": { "audio": { "contentMediaType": "application/octet-stream", "description": "Opus chunk (~30s recommended).", "title": "Audio", "type": "string" }, "chunk_index": { "description": "Zero-based chunk index in the recording.", "minimum": 0.0, "title": "Chunk Index", "type": "integer" }, "started_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO 8601 UTC timestamp when the recording itself began.", "title": "Started At" } }, "required": [ "audio", "chunk_index" ], "title": "Body_speechRecordingChunkUpload", "type": "object" }, "Body_speechRecordingFinalize": { "properties": { "audio": { "contentMediaType": "application/octet-stream", "description": "Full concatenated Opus blob for the recording.", "title": "Audio", "type": "string" }, "cursor_anchor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Mobile-side JSON capturing where the transcript should land in the note.", "title": "Cursor Anchor" }, "diarization_mode": { "default": "general", "description": "Diarization mode forwarded to whisperx (off|general|podcast_2speaker).", "title": "Diarization Mode", "type": "string" } }, "required": [ "audio" ], "title": "Body_speechRecordingFinalize", "type": "object" }, "Body_upload": { "properties": { "access_scope_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "description": "Named record/file scope; requires the caller's own edit grant", "title": "Access Scope Id" }, "client_analysis": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional on-device analysis envelope (JSON, kind=document_ocr) carrying device OCR text — see TIDY-13519 D1.", "title": "Client Analysis" }, "client_upload_id": { "anyOf": [ { "maxLength": 200, "type": "string" }, { "type": "null" } ], "description": "Optional stable client upload id (TIDY-15284). Makes the upload idempotent on (tenant, caller, client_upload_id): an exact byte/name/MIME/folder replay returns the existing file; a mismatched replay is HTTP 409. Inline tags are forbidden with this field (422) — assign tags post-upload. GET /api/v1/files/upload-receipt reads what an id landed.", "title": "Client Upload Id" }, "file": { "contentMediaType": "application/octet-stream", "description": "File to upload", "title": "File", "type": "string" }, "folder_path": { "default": "/Uploads", "description": "Virtual folder path (default: /Uploads)", "title": "Folder Path", "type": "string" }, "project_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Project to associate (P- or UUID). Omitted: the project of the assistant or employee turn uploading it, else none. 'none': no project.", "title": "Project Id" }, "source": { "anyOf": [ { "const": "capture", "type": "string" }, { "type": "null" } ], "description": "Optional upload source (TIDY-19719). 'capture' — the file is the input of a capture that creates its own item: it is stored, read and searchable, but no items are extracted from it. Omitted → the file is processed like any upload.", "title": "Source" }, "tags": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional comma-separated canonical tags (TIDY-15281). Normalized and case-insensitively deduped. Omitted → no tags.", "title": "Tags" }, "visibility": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "private or shared; omitted inherits a shared project, otherwise private", "title": "Visibility" } }, "required": [ "file" ], "title": "Body_upload", "type": "object" }, "Body_uploadAdminChatEmoji": { "properties": { "image": { "contentMediaType": "application/octet-stream", "title": "Image", "type": "string" }, "shortcode": { "title": "Shortcode", "type": "string" } }, "required": [ "shortcode", "image" ], "title": "Body_uploadAdminChatEmoji", "type": "object" }, "Body_uploadAttachment": { "properties": { "file": { "contentMediaType": "application/octet-stream", "description": "File to upload", "title": "File", "type": "string" } }, "required": [ "file" ], "title": "Body_uploadAttachment", "type": "object" }, "Body_uploadBanner": { "properties": { "file": { "contentMediaType": "application/octet-stream", "description": "Banner/icon image to upload", "title": "File", "type": "string" }, "note_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Owning note/journal UUID. When set, the uploaded asset's visibility is aligned to that note's visibility (R19, owner-gated).", "title": "Note Id" }, "note_type": { "default": "note", "description": "'note' (default) or 'journal' — which table owns the banner.", "title": "Note Type", "type": "string" } }, "required": [ "file" ], "title": "Body_uploadBanner", "type": "object" }, "Body_uploadCoachingDocument": { "properties": { "file": { "contentMediaType": "application/octet-stream", "description": "Document to upload", "title": "File", "type": "string" }, "module": { "default": "wellness", "description": "Coaching module folder", "title": "Module", "type": "string" } }, "required": [ "file" ], "title": "Body_uploadCoachingDocument", "type": "object" }, "Body_uploadContactPhoto": { "properties": { "file": { "contentMediaType": "application/octet-stream", "title": "File", "type": "string" } }, "required": [ "file" ], "title": "Body_uploadContactPhoto", "type": "object" }, "Body_uploadDraftAttachment": { "properties": { "file": { "contentMediaType": "application/octet-stream", "description": "File to upload", "title": "File", "type": "string" } }, "required": [ "file" ], "title": "Body_uploadDraftAttachment", "type": "object" }, "Body_uploadEventAttachment": { "properties": { "file": { "contentMediaType": "application/octet-stream", "description": "File to upload", "title": "File", "type": "string" } }, "required": [ "file" ], "title": "Body_uploadEventAttachment", "type": "object" }, "Body_uploadOrganizationPhoto": { "properties": { "file": { "contentMediaType": "application/octet-stream", "title": "File", "type": "string" } }, "required": [ "file" ], "title": "Body_uploadOrganizationPhoto", "type": "object" }, "Body_uploadProfileAvatar": { "properties": { "file": { "contentMediaType": "application/octet-stream", "title": "File", "type": "string" } }, "required": [ "file" ], "title": "Body_uploadProfileAvatar", "type": "object" }, "Body_uploadRichTextAttachment": { "properties": { "client_upload_id": { "anyOf": [ { "maxLength": 200, "type": "string" }, { "type": "null" } ], "description": "Optional stable client upload id (TIDY-19719). The attachment id and storage key derive from it, so a replay of the same upload returns the same id and URL; different content is HTTP 409.", "title": "Client Upload Id" }, "context": { "default": "general", "description": "Logical grouping (e.g. 'notes', 'feedback')", "title": "Context", "type": "string" }, "file": { "contentMediaType": "application/octet-stream", "description": "File to upload", "title": "File", "type": "string" }, "target_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Typed id (`N-` / `J-` note or journal, or `M-` comment) of the document the file is embedded in. Keys the object on that document so its readers can load it; a comment keys on the comment and reads through its parent (TIDY-20218). Omit for an upload only its uploader reads.", "title": "Target Id" } }, "required": [ "file" ], "title": "Body_uploadRichTextAttachment", "type": "object" }, "Body_voiceServerStt": { "properties": { "audio": { "contentMediaType": "application/octet-stream", "description": "Audio clip to transcribe (wav/opus/mp3/...).", "title": "Audio", "type": "string" } }, "required": [ "audio" ], "title": "Body_voiceServerStt", "type": "object" }, "BookingAvailability": { "description": "Weekly availability rules — all times interpreted in the page timezone.", "properties": { "buffer_min": { "default": 0, "description": "Gap enforced around existing events", "maximum": 480.0, "minimum": 0.0, "title": "Buffer Min", "type": "integer" }, "horizon_days": { "default": 30, "description": "How far ahead slots are offered", "maximum": 365.0, "minimum": 1.0, "title": "Horizon Days", "type": "integer" }, "lead_time_min": { "default": 0, "description": "Minimum notice before a slot", "maximum": 43200.0, "minimum": 0.0, "title": "Lead Time Min", "type": "integer" }, "slot_interval_min": { "anyOf": [ { "maximum": 1440.0, "minimum": 5.0, "type": "integer" }, { "type": "null" } ], "description": "Slot start cadence; defaults to the service duration", "title": "Slot Interval Min" }, "weekly": { "additionalProperties": { "items": { "$ref": "#/components/schemas/AvailabilityWindow" }, "type": "array" }, "description": "weekday (mon..sun) -> open windows", "title": "Weekly", "type": "object" } }, "title": "BookingAvailability", "type": "object" }, "BookingConfirmationResponse": { "description": "Returned to the public visitor on a successful booking.", "properties": { "booking_id": { "format": "uuid", "title": "Booking Id", "type": "string" }, "confirmation_email_sent": { "title": "Confirmation Email Sent", "type": "boolean" }, "confirmation_message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Confirmation Message" }, "manage_url": { "title": "Manage Url", "type": "string" }, "owner_timezone": { "title": "Owner Timezone", "type": "string" }, "service_name": { "title": "Service Name", "type": "string" }, "slot_end": { "format": "date-time", "title": "Slot End", "type": "string" }, "slot_start": { "format": "date-time", "title": "Slot Start", "type": "string" }, "status": { "title": "Status", "type": "string" } }, "required": [ "booking_id", "status", "service_name", "slot_start", "slot_end", "owner_timezone", "manage_url", "confirmation_message", "confirmation_email_sent" ], "title": "BookingConfirmationResponse", "type": "object" }, "BookingPageResponse": { "description": "Full owner-facing booking page.", "properties": { "availability": { "additionalProperties": true, "title": "Availability", "type": "object" }, "confirmation_config": { "additionalProperties": true, "title": "Confirmation Config", "type": "object" }, "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "enabled": { "title": "Enabled", "type": "boolean" }, "id": { "format": "uuid", "title": "Id", "type": "string" }, "intake_form": { "items": { "additionalProperties": true, "type": "object" }, "title": "Intake Form", "type": "array" }, "owner_account_id": { "format": "uuid", "title": "Owner Account Id", "type": "string" }, "public_url": { "title": "Public Url", "type": "string" }, "service_description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Service Description" }, "service_duration_min": { "title": "Service Duration Min", "type": "integer" }, "service_name": { "title": "Service Name", "type": "string" }, "slug": { "title": "Slug", "type": "string" }, "tenant_id": { "format": "uuid", "title": "Tenant Id", "type": "string" }, "timezone": { "title": "Timezone", "type": "string" }, "title": { "title": "Title", "type": "string" }, "updated_at": { "format": "date-time", "title": "Updated At", "type": "string" } }, "required": [ "id", "tenant_id", "owner_account_id", "slug", "title", "description", "service_name", "service_duration_min", "service_description", "timezone", "availability", "intake_form", "confirmation_config", "enabled", "public_url", "created_at", "updated_at" ], "title": "BookingPageResponse", "type": "object" }, "BookingPageUpsert": { "description": "Create/replace the owner's booking page (v1: one active page per owner).", "properties": { "availability": { "$ref": "#/components/schemas/BookingAvailability" }, "confirmation_config": { "additionalProperties": true, "title": "Confirmation Config", "type": "object" }, "description": { "anyOf": [ { "maxLength": 2000, "type": "string" }, { "type": "null" } ], "title": "Description" }, "enabled": { "default": true, "title": "Enabled", "type": "boolean" }, "intake_form": { "items": { "$ref": "#/components/schemas/IntakeFieldDef" }, "title": "Intake Form", "type": "array" }, "service_description": { "anyOf": [ { "maxLength": 2000, "type": "string" }, { "type": "null" } ], "title": "Service Description" }, "service_duration_min": { "default": 60, "maximum": 1440.0, "minimum": 5.0, "title": "Service Duration Min", "type": "integer" }, "service_name": { "maxLength": 200, "minLength": 1, "title": "Service Name", "type": "string" }, "slug": { "anyOf": [ { "maxLength": 64, "minLength": 3, "pattern": "^[a-z0-9][a-z0-9-]*[a-z0-9]$", "type": "string" }, { "type": "null" } ], "description": "Public URL slug; auto-derived from the title when omitted", "title": "Slug" }, "timezone": { "description": "IANA tz, e.g. America/New_York", "maxLength": 64, "minLength": 1, "title": "Timezone", "type": "string" }, "title": { "maxLength": 200, "minLength": 1, "title": "Title", "type": "string" } }, "required": [ "title", "service_name", "timezone" ], "title": "BookingPageUpsert", "type": "object" }, "BookingSummary": { "description": "A booking as the owner sees it in the manage surface.", "properties": { "contact_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Contact Id" }, "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "customer_email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Customer Email" }, "customer_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Customer Name" }, "event_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Event Id" }, "id": { "format": "uuid", "title": "Id", "type": "string" }, "slot_end": { "format": "date-time", "title": "Slot End", "type": "string" }, "slot_start": { "format": "date-time", "title": "Slot Start", "type": "string" }, "status": { "title": "Status", "type": "string" } }, "required": [ "id", "slot_start", "slot_end", "status", "customer_name", "customer_email", "event_id", "contact_id", "created_at" ], "title": "BookingSummary", "type": "object" }, "BookmarkCreateRequest": { "properties": { "facet_id": { "anyOf": [ { "maxLength": 64, "type": "string" }, { "type": "null" } ], "title": "Facet Id" }, "facet_type": { "anyOf": [ { "maxLength": 64, "type": "string" }, { "type": "null" } ], "title": "Facet Type" }, "label": { "maxLength": 80, "minLength": 1, "title": "Label", "type": "string" }, "target_kind": { "enum": [ "url", "facet" ], "title": "Target Kind", "type": "string" }, "target_url": { "anyOf": [ { "maxLength": 2048, "type": "string" }, { "type": "null" } ], "title": "Target Url" } }, "required": [ "label", "target_kind" ], "title": "BookmarkCreateRequest", "type": "object" }, "BookmarkPatchRequest": { "properties": { "facet_id": { "anyOf": [ { "maxLength": 64, "type": "string" }, { "type": "null" } ], "title": "Facet Id" }, "facet_type": { "anyOf": [ { "maxLength": 64, "type": "string" }, { "type": "null" } ], "title": "Facet Type" }, "label": { "anyOf": [ { "maxLength": 80, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Label" }, "sort_order": { "anyOf": [ { "maximum": 10000.0, "minimum": 0.0, "type": "integer" }, { "type": "null" } ], "title": "Sort Order" }, "target_url": { "anyOf": [ { "maxLength": 2048, "type": "string" }, { "type": "null" } ], "title": "Target Url" } }, "title": "BookmarkPatchRequest", "type": "object" }, "BookmarkResponse": { "properties": { "created_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Created At" }, "facet_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Facet Id" }, "facet_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Facet Type" }, "id": { "title": "Id", "type": "string" }, "label": { "title": "Label", "type": "string" }, "sort_order": { "title": "Sort Order", "type": "integer" }, "target_kind": { "title": "Target Kind", "type": "string" }, "target_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Target Url" }, "updated_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Updated At" } }, "required": [ "id", "label", "target_kind", "sort_order" ], "title": "BookmarkResponse", "type": "object" }, "BootstrapRedeemRequest": { "description": "The raw installer-printed secret. Never logged, stored only hashed.", "properties": { "secret": { "maxLength": 256, "minLength": 16, "title": "Secret", "type": "string" } }, "required": [ "secret" ], "title": "BootstrapRedeemRequest", "type": "object" }, "BootstrapRedeemResponse": { "properties": { "account_id": { "title": "Account Id", "type": "string" }, "fingerprint": { "title": "Fingerprint", "type": "string" }, "ok": { "title": "Ok", "type": "boolean" } }, "required": [ "ok", "account_id", "fingerprint" ], "title": "BootstrapRedeemResponse", "type": "object" }, "BounceRequest": { "properties": { "reason": { "description": "Why you cannot complete this item. Lands as a comment and as the notification body — the person receiving it decides from this.", "maxLength": 2000, "minLength": 1, "title": "Reason", "type": "string" } }, "required": [ "reason" ], "title": "BounceRequest", "type": "object" }, "BounceResponse": { "properties": { "activity_id": { "title": "Activity Id", "type": "string" }, "assignee": { "title": "Assignee", "type": "string" }, "reason": { "title": "Reason", "type": "string" }, "routed_to": { "title": "Routed To", "type": "string" }, "short_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Short Id" } }, "required": [ "activity_id", "routed_to", "assignee", "reason" ], "title": "BounceResponse", "type": "object" }, "BrokenChainModel": { "properties": { "cron": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cron" }, "definition_id": { "format": "uuid", "title": "Definition Id", "type": "string" }, "rollout_id": { "format": "uuid", "title": "Rollout Id", "type": "string" }, "slug": { "title": "Slug", "type": "string" }, "timezone": { "title": "Timezone", "type": "string" }, "version_id": { "format": "uuid", "title": "Version Id", "type": "string" } }, "required": [ "definition_id", "slug", "rollout_id", "version_id", "cron", "timezone" ], "title": "BrokenChainModel", "type": "object" }, "BrokerExerciseRequest": { "properties": { "conversation_id": { "format": "uuid", "title": "Conversation Id", "type": "string" }, "credential_id": { "format": "uuid", "title": "Credential Id", "type": "string" }, "job_activity_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Job Activity Id" }, "operation": { "maxLength": 128, "minLength": 1, "title": "Operation", "type": "string" }, "room_id": { "maxLength": 512, "minLength": 1, "title": "Room Id", "type": "string" }, "runtime": { "anyOf": [ { "maxLength": 64, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Runtime" }, "session_ref": { "maxLength": 256, "minLength": 1, "title": "Session Ref", "type": "string" } }, "required": [ "credential_id", "conversation_id", "room_id", "session_ref", "operation" ], "title": "BrokerExerciseRequest", "type": "object" }, "BrokerExerciseResponse": { "properties": { "credential_id": { "title": "Credential Id", "type": "string" }, "materialization_id": { "title": "Materialization Id", "type": "string" }, "proxied": { "title": "Proxied", "type": "boolean" }, "result": { "default": null, "title": "Result", "type": "null" } }, "required": [ "credential_id", "proxied", "materialization_id" ], "title": "BrokerExerciseResponse", "type": "object" }, "BrowserAccountCreateRequest": { "additionalProperties": false, "description": "Create a browsing account: a NAME, a persona, an optional site policy and\nan optional start page — no URL required (D19). Shape only: the policy\nsemantics are resolved by :func:`resolve_account_policy` so REST and the\nregistered facet action refuse with the same named codes.", "properties": { "allowed_origins": { "description": "Canonical https origins for allowlist.", "items": { "type": "string" }, "maxItems": 64, "title": "Allowed Origins", "type": "array" }, "label": { "maxLength": 160, "minLength": 1, "title": "Label", "type": "string" }, "origin_policy": { "anyOf": [ { "enum": [ "open", "allowlist" ], "type": "string" }, { "type": "null" } ], "description": "open: any https site; allowlist: exactly allowed_origins (D17). Omitted: derived — allowlist when site_origin/allowed_origins name sites, else open.", "title": "Origin Policy" }, "persona_account_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "description": "The member or virtual employee this account is for; omitted = the creator (D16).", "title": "Persona Account Id" }, "request_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Request Id" }, "site_origin": { "anyOf": [ { "maxLength": 512, "type": "string" }, { "type": "null" } ], "description": "Legacy alias for one train: a single-origin allowlist starting on that origin.", "title": "Site Origin" }, "startup_url": { "anyOf": [ { "maxLength": 2048, "type": "string" }, { "type": "null" } ], "description": "The page a session lands on (D19).", "title": "Startup Url" }, "workshop_id": { "format": "uuid", "title": "Workshop Id", "type": "string" } }, "required": [ "workshop_id", "label" ], "title": "BrowserAccountCreateRequest", "type": "object" }, "BrowserAccountEgressDeviceRequest": { "additionalProperties": false, "description": "TIDY-18934 F13: browse through one of the owner's own computers.", "properties": { "device_id": { "description": "One of the caller's own desktop-app installs with the browser network setting on", "format": "uuid", "title": "Device Id", "type": "string" } }, "required": [ "device_id" ], "title": "BrowserAccountEgressDeviceRequest", "type": "object" }, "BrowserAccountEgressRequest": { "additionalProperties": false, "properties": { "label": { "description": "The owner's name for this network", "maxLength": 80, "minLength": 1, "title": "Label", "type": "string" }, "url": { "description": "socks5:// or http:// proxy URL, credentials included; kept only in the vault", "format": "password", "maxLength": 1024, "minLength": 8, "title": "Url", "type": "string", "writeOnly": true } }, "required": [ "label", "url" ], "title": "BrowserAccountEgressRequest", "type": "object" }, "BrowserAccountEgressResponse": { "properties": { "browser_account_id": { "format": "uuid", "title": "Browser Account Id", "type": "string" }, "closed_sessions": { "items": { "format": "uuid", "type": "string" }, "title": "Closed Sessions", "type": "array" }, "egress_device_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "default": null, "title": "Egress Device Id" }, "egress_label": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Egress Label" } }, "required": [ "browser_account_id", "egress_label", "closed_sessions" ], "title": "BrowserAccountEgressResponse", "type": "object" }, "BrowserAccountPolicyRequest": { "additionalProperties": false, "description": "Exactly one of three shapes (TIDY-18714): ``{origin_policy, allowed_origins?}``,\n``{allow_origin}`` or ``{startup_url}``. Owner-only; the service enforces it.", "properties": { "allow_origin": { "anyOf": [ { "maxLength": 512, "type": "string" }, { "type": "null" } ], "title": "Allow Origin" }, "allowed_origins": { "anyOf": [ { "items": { "type": "string" }, "maxItems": 64, "type": "array" }, { "type": "null" } ], "title": "Allowed Origins" }, "origin_policy": { "anyOf": [ { "enum": [ "open", "allowlist" ], "type": "string" }, { "type": "null" } ], "title": "Origin Policy" }, "startup_url": { "anyOf": [ { "maxLength": 2048, "type": "string" }, { "type": "null" } ], "title": "Startup Url" } }, "title": "BrowserAccountPolicyRequest", "type": "object" }, "BrowserAccountPolicyResponse": { "properties": { "account_id": { "format": "uuid", "title": "Account Id", "type": "string" }, "allowed_origins": { "items": { "type": "string" }, "title": "Allowed Origins", "type": "array" }, "origin_policy": { "enum": [ "open", "allowlist" ], "title": "Origin Policy", "type": "string" }, "policy_version": { "title": "Policy Version", "type": "integer" }, "startup_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Startup Url" } }, "required": [ "account_id", "policy_version", "origin_policy", "allowed_origins", "startup_url" ], "title": "BrowserAccountPolicyResponse", "type": "object" }, "BrowserAccountResponse": { "properties": { "access_scope_id": { "format": "uuid", "title": "Access Scope Id", "type": "string" }, "account_id": { "format": "uuid", "title": "Account Id", "type": "string" }, "allowed_origins": { "items": { "type": "string" }, "title": "Allowed Origins", "type": "array" }, "origin_policy": { "enum": [ "open", "allowlist" ], "title": "Origin Policy", "type": "string" }, "persona_account_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Persona Account Id" }, "persona_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Persona Name" }, "policy_version": { "title": "Policy Version", "type": "integer" }, "record_id": { "format": "uuid", "title": "Record Id", "type": "string" }, "startup_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Startup Url" } }, "required": [ "account_id", "record_id", "access_scope_id", "origin_policy", "allowed_origins", "startup_url", "persona_account_id", "persona_name", "policy_version" ], "title": "BrowserAccountResponse", "type": "object" }, "BrowserAuthorityRefreshRequest": { "additionalProperties": false, "properties": { "authorization": { "format": "password", "maxLength": 8192, "minLength": 1, "title": "Authorization", "type": "string", "writeOnly": true }, "client_id": { "maxLength": 128, "minLength": 1, "title": "Client Id", "type": "string" } }, "required": [ "authorization", "client_id" ], "title": "BrowserAuthorityRefreshRequest", "type": "object" }, "BrowserAuthorityResponse": { "properties": { "authorization": { "title": "Authorization", "type": "string" }, "expires_at": { "format": "date-time", "title": "Expires At", "type": "string" }, "max_lifetime_seconds": { "const": 10, "default": 10, "title": "Max Lifetime Seconds", "type": "integer" }, "refresh_after_seconds": { "const": 3, "default": 3, "title": "Refresh After Seconds", "type": "integer" }, "renewable_until": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Renewable Until" } }, "required": [ "authorization", "expires_at" ], "title": "BrowserAuthorityResponse", "type": "object" }, "BrowserDemonstrationHandoffResponse": { "description": "What the teacher's client sends, as its own message, to the employee.\n\nEvery agent conversation is end-to-end encrypted, so only the person's own\nclient can send as them; the words and the recipient are decided here once.", "properties": { "employee_account_id": { "format": "uuid", "title": "Employee Account Id", "type": "string" }, "employee_display_name": { "title": "Employee Display Name", "type": "string" }, "employee_matrix_user_id": { "title": "Employee Matrix User Id", "type": "string" }, "file_id": { "format": "uuid", "title": "File Id", "type": "string" }, "message": { "title": "Message", "type": "string" }, "storyboard": { "anyOf": [ { "$ref": "#/components/schemas/BrowserDemonstrationStoryboard" }, { "type": "null" } ] } }, "required": [ "employee_account_id", "employee_matrix_user_id", "employee_display_name", "file_id", "message", "storyboard" ], "title": "BrowserDemonstrationHandoffResponse", "type": "object" }, "BrowserDemonstrationSaveResponse": { "description": "TIDY-18934 F10: the filed demonstration, for the person to hand to the employee.", "properties": { "demonstration_id": { "format": "uuid", "title": "Demonstration Id", "type": "string" }, "file_id": { "format": "uuid", "title": "File Id", "type": "string" }, "storyboard_file_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Storyboard File Id" } }, "required": [ "demonstration_id", "file_id", "storyboard_file_id" ], "title": "BrowserDemonstrationSaveResponse", "type": "object" }, "BrowserDemonstrationStoryboard": { "properties": { "content_base64": { "description": "The storyboard JPEG, sent as the message's picture.", "title": "Content Base64", "type": "string" }, "file_id": { "format": "uuid", "title": "File Id", "type": "string" }, "mime_type": { "title": "Mime Type", "type": "string" }, "name": { "title": "Name", "type": "string" } }, "required": [ "file_id", "name", "mime_type", "content_base64" ], "title": "BrowserDemonstrationStoryboard", "type": "object" }, "BrowserDownloadSelection": { "additionalProperties": false, "properties": { "download_id": { "format": "uuid", "title": "Download Id", "type": "string" }, "operation": { "const": "save", "title": "Operation", "type": "string" } }, "required": [ "operation", "download_id" ], "title": "BrowserDownloadSelection", "type": "object" }, "BrowserDriverInterval": { "description": "One entry of ``browser_sessions.driver_intervals`` (TIDY-18718 / D24): who\ndrove the session while it was in ``mode``. ``driver_account_id`` is the\ncontrolling person for a human mode, the employee for ``agent`` and null\nwhile paused; ``to`` is null for the interval still open.", "properties": { "driver_account_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Driver Account Id" }, "from": { "format": "date-time", "title": "From", "type": "string" }, "mode": { "enum": [ "paused", "agent", "private", "teach", "shared", "unavailable", "closed" ], "title": "Mode", "type": "string" }, "to": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "To" } }, "required": [ "mode", "driver_account_id", "from", "to" ], "title": "BrowserDriverInterval", "type": "object" }, "BrowserEgressDeviceAttachRequest": { "additionalProperties": false, "description": "A computer's link: its device access token, renewed over the link.", "properties": { "access_token": { "format": "password", "maxLength": 512, "minLength": 1, "title": "Access Token", "type": "string", "writeOnly": true } }, "required": [ "access_token" ], "title": "BrowserEgressDeviceAttachRequest", "type": "object" }, "BrowserEgressDeviceCheckRequest": { "additionalProperties": false, "properties": { "access_token": { "format": "password", "maxLength": 512, "minLength": 1, "title": "Access Token", "type": "string", "writeOnly": true }, "device_id": { "format": "uuid", "title": "Device Id", "type": "string" }, "tenant_id": { "format": "uuid", "title": "Tenant Id", "type": "string" } }, "required": [ "access_token", "tenant_id", "device_id" ], "title": "BrowserEgressDeviceCheckRequest", "type": "object" }, "BrowserEgressDeviceLinkResponse": { "properties": { "account_id": { "format": "uuid", "title": "Account Id", "type": "string" }, "device_id": { "format": "uuid", "title": "Device Id", "type": "string" }, "expires_at": { "format": "date-time", "title": "Expires At", "type": "string" }, "name": { "title": "Name", "type": "string" }, "tenant_id": { "format": "uuid", "title": "Tenant Id", "type": "string" } }, "required": [ "tenant_id", "account_id", "device_id", "name", "expires_at" ], "title": "BrowserEgressDeviceLinkResponse", "type": "object" }, "BrowserEgressSessionAttachRequest": { "additionalProperties": false, "description": "A session's link, opened by the workshop's protected proxy with the\nticket its controller read through ``egress.read``.", "properties": { "ticket": { "format": "password", "maxLength": 8192, "minLength": 1, "title": "Ticket", "type": "string", "writeOnly": true } }, "required": [ "ticket" ], "title": "BrowserEgressSessionAttachRequest", "type": "object" }, "BrowserEgressSessionBinding-Input": { "additionalProperties": false, "properties": { "browser_account_id": { "format": "uuid", "title": "Browser Account Id", "type": "string" }, "controller_epoch": { "anyOf": [ { "minimum": 0.0, "type": "integer" }, { "type": "null" } ], "title": "Controller Epoch" }, "device_id": { "format": "uuid", "title": "Device Id", "type": "string" }, "egress_id": { "format": "uuid", "title": "Egress Id", "type": "string" }, "expires_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Expires At" }, "generation": { "minimum": 1.0, "title": "Generation", "type": "integer" }, "session_id": { "format": "uuid", "title": "Session Id", "type": "string" }, "tenant_id": { "format": "uuid", "title": "Tenant Id", "type": "string" }, "workshop_id": { "format": "uuid", "title": "Workshop Id", "type": "string" } }, "required": [ "tenant_id", "session_id", "browser_account_id", "workshop_id", "egress_id", "generation", "device_id" ], "title": "BrowserEgressSessionBinding", "type": "object" }, "BrowserEgressSessionBinding-Output": {}, "BrowserEgressSessionCheckRequest": { "additionalProperties": false, "properties": { "binding": { "$ref": "#/components/schemas/BrowserEgressSessionBinding-Input" } }, "required": [ "binding" ], "title": "BrowserEgressSessionCheckRequest", "type": "object" }, "BrowserFileReadRequest": { "additionalProperties": false, "properties": { "authorization": { "format": "password", "maxLength": 8192, "minLength": 1, "title": "Authorization", "type": "string", "writeOnly": true }, "message": { "$ref": "#/components/schemas/ControllerEnvelope" }, "signature": { "format": "password", "maxLength": 128, "minLength": 80, "title": "Signature", "type": "string", "writeOnly": true } }, "required": [ "message", "signature", "authorization" ], "title": "BrowserFileReadRequest", "type": "object" }, "BrowserFileSavedResponse": { "properties": { "file_id": { "format": "uuid", "title": "File Id", "type": "string" } }, "required": [ "file_id" ], "title": "BrowserFileSavedResponse", "type": "object" }, "BrowserFileSelection": { "additionalProperties": false, "properties": { "file_ids": { "items": { "format": "uuid", "type": "string" }, "maxItems": 5, "minItems": 1, "title": "File Ids", "type": "array" }, "operation": { "const": "read", "title": "Operation", "type": "string" } }, "required": [ "operation", "file_ids" ], "title": "BrowserFileSelection", "type": "object" }, "BrowserFileTransferRequest": { "additionalProperties": false, "properties": { "authorization": { "format": "password", "maxLength": 8192, "minLength": 1, "title": "Authorization", "type": "string", "writeOnly": true }, "client_id": { "maxLength": 128, "minLength": 1, "title": "Client Id", "type": "string" }, "handshake": { "$ref": "#/components/schemas/BrowserRelayHandshake" }, "selection": { "discriminator": { "mapping": { "read": "#/components/schemas/BrowserFileSelection", "save": "#/components/schemas/BrowserDownloadSelection" }, "propertyName": "operation" }, "oneOf": [ { "$ref": "#/components/schemas/BrowserFileSelection" }, { "$ref": "#/components/schemas/BrowserDownloadSelection" } ], "title": "Selection" }, "session_id": { "format": "uuid", "title": "Session Id", "type": "string" } }, "required": [ "handshake", "session_id", "client_id", "authorization", "selection" ], "title": "BrowserFileTransferRequest", "type": "object" }, "BrowserJudgmentAction": { "additionalProperties": false, "description": "Controller-derived metadata, never input values.", "properties": { "destination_origin": { "anyOf": [ { "maxLength": 512, "type": "string" }, { "type": "null" } ], "title": "Destination Origin" }, "operation": { "enum": [ "navigate", "click", "fill", "select.option", "drag", "press", "scroll", "tab.new", "tab.select", "tab.close", "dialog.accept", "dialog.dismiss", "file.upload", "file.save" ], "title": "Operation", "type": "string" }, "page": { "anyOf": [ { "$ref": "#/components/schemas/BrowserPageFacts" }, { "type": "null" } ] }, "request_digest": { "pattern": "^[0-9a-f]{64}$", "title": "Request Digest", "type": "string" }, "site_origin": { "maxLength": 512, "minLength": 1, "title": "Site Origin", "type": "string" }, "target_name": { "anyOf": [ { "maxLength": 256, "type": "string" }, { "type": "null" } ], "title": "Target Name" }, "target_role": { "anyOf": [ { "maxLength": 64, "type": "string" }, { "type": "null" } ], "title": "Target Role" }, "target_type": { "anyOf": [ { "maxLength": 64, "type": "string" }, { "type": "null" } ], "title": "Target Type" } }, "required": [ "operation", "site_origin", "request_digest" ], "title": "BrowserJudgmentAction", "type": "object" }, "BrowserModeRequest": { "additionalProperties": false, "properties": { "client_id": { "maxLength": 128, "minLength": 1, "title": "Client Id", "type": "string" }, "expected_epoch": { "minimum": 0.0, "title": "Expected Epoch", "type": "integer" }, "requested_mode": { "enum": [ "paused", "agent", "private", "teach", "shared" ], "title": "Requested Mode", "type": "string" } }, "required": [ "requested_mode", "expected_epoch", "client_id" ], "title": "BrowserModeRequest", "type": "object" }, "BrowserModeResponse": { "properties": { "status": { "const": "pending", "default": "pending", "title": "Status", "type": "string" }, "transition_id": { "format": "uuid", "title": "Transition Id", "type": "string" } }, "required": [ "transition_id" ], "title": "BrowserModeResponse", "type": "object" }, "BrowserPageControl": { "additionalProperties": false, "description": "One visible form control on the page, by its declared names: never its value.", "properties": { "autocomplete": { "maxLength": 64, "title": "Autocomplete", "type": "string" }, "id": { "maxLength": 64, "title": "Id", "type": "string" }, "in_target_form": { "title": "In Target Form", "type": "boolean" }, "name": { "maxLength": 64, "title": "Name", "type": "string" }, "type": { "maxLength": 32, "title": "Type", "type": "string" } }, "required": [ "autocomplete", "name", "id", "type", "in_target_form" ], "title": "BrowserPageControl", "type": "object" }, "BrowserPageFacts": { "additionalProperties": false, "description": "What the page shows around one employee action (TIDY-18934 F17).\n\nRead by the controller's fixed DOM inspection, never caller script and never\nan input value. The purchase gate classifies on it, the approval the person\nanswers carries it, and it is folded into the request digest, so a page whose\ntotal changed after the approval no longer matches it. Every key is always\npresent (null or empty when the page has none): the claim compares the stored\napproval with the re-issued action exactly.", "properties": { "controls": { "items": { "$ref": "#/components/schemas/BrowserPageControl" }, "maxItems": 32, "title": "Controls", "type": "array" }, "destination_path": { "anyOf": [ { "maxLength": 256, "type": "string" }, { "type": "null" } ], "title": "Destination Path" }, "destination_query_keys": { "items": { "maxLength": 32, "type": "string" }, "maxItems": 8, "title": "Destination Query Keys", "type": "array" }, "dialog_message": { "anyOf": [ { "maxLength": 256, "type": "string" }, { "type": "null" } ], "title": "Dialog Message" }, "heading": { "maxLength": 128, "title": "Heading", "type": "string" }, "in_form": { "title": "In Form", "type": "boolean" }, "key": { "anyOf": [ { "maxLength": 32, "type": "string" }, { "type": "null" } ], "title": "Key" }, "path": { "maxLength": 256, "title": "Path", "type": "string" }, "payment_frames": { "items": { "maxLength": 512, "type": "string" }, "maxItems": 8, "title": "Payment Frames", "type": "array" }, "title": { "maxLength": 128, "title": "Title", "type": "string" }, "total": { "anyOf": [ { "maxLength": 120, "type": "string" }, { "type": "null" } ], "title": "Total" } }, "required": [ "path", "title", "heading", "total", "in_form", "controls", "payment_frames", "key", "dialog_message", "destination_path", "destination_query_keys" ], "title": "BrowserPageFacts", "type": "object" }, "BrowserRelayAttachRequest": { "additionalProperties": false, "properties": { "client_id": { "maxLength": 128, "minLength": 1, "title": "Client Id", "type": "string" }, "handshake": { "$ref": "#/components/schemas/BrowserRelayHandshake" }, "intent": { "enum": [ "watch", "private", "teach", "shared", "execute" ], "title": "Intent", "type": "string" }, "session_id": { "format": "uuid", "title": "Session Id", "type": "string" }, "ticket": { "format": "password", "maxLength": 4096, "minLength": 1, "title": "Ticket", "type": "string", "writeOnly": true } }, "required": [ "handshake", "session_id", "client_id", "intent", "ticket" ], "title": "BrowserRelayAttachRequest", "type": "object" }, "BrowserRelayAuthorityResponse": { "properties": { "authorization": { "title": "Authorization", "type": "string" }, "binding": { "$ref": "#/components/schemas/BrowserRelayBinding" }, "expires_at": { "format": "date-time", "title": "Expires At", "type": "string" }, "max_lifetime_seconds": { "const": 10, "default": 10, "title": "Max Lifetime Seconds", "type": "integer" }, "refresh_after_seconds": { "const": 3, "default": 3, "title": "Refresh After Seconds", "type": "integer" } }, "required": [ "authorization", "expires_at", "binding" ], "title": "BrowserRelayAuthorityResponse", "type": "object" }, "BrowserRelayBinding": { "properties": { "acting_account_id": { "format": "uuid", "title": "Acting Account Id", "type": "string" }, "browser_account_id": { "format": "uuid", "title": "Browser Account Id", "type": "string" }, "controller_account_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Controller Account Id" }, "controller_client_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Controller Client Id" }, "controller_epoch": { "title": "Controller Epoch", "type": "integer" }, "controller_id": { "format": "uuid", "title": "Controller Id", "type": "string" }, "controller_key_generation": { "title": "Controller Key Generation", "type": "integer" }, "host_instance_id": { "format": "uuid", "title": "Host Instance Id", "type": "string" }, "intent": { "enum": [ "watch", "private", "teach", "shared", "execute" ], "title": "Intent", "type": "string" }, "mode": { "enum": [ "paused", "agent", "private", "teach", "shared", "unavailable", "closed" ], "title": "Mode", "type": "string" }, "rights": { "items": { "type": "string" }, "title": "Rights", "type": "array" }, "session_id": { "format": "uuid", "title": "Session Id", "type": "string" }, "tenant_id": { "format": "uuid", "title": "Tenant Id", "type": "string" }, "workshop_id": { "format": "uuid", "title": "Workshop Id", "type": "string" } }, "required": [ "tenant_id", "acting_account_id", "browser_account_id", "session_id", "workshop_id", "host_instance_id", "controller_id", "controller_key_generation", "controller_epoch", "mode", "rights", "intent", "controller_account_id", "controller_client_id" ], "title": "BrowserRelayBinding", "type": "object" }, "BrowserRelayControllerAttachRequest": { "additionalProperties": false, "properties": { "challenge": { "maxLength": 128, "minLength": 43, "pattern": "^[A-Za-z0-9_-]+$", "title": "Challenge", "type": "string" }, "signed": { "$ref": "#/components/schemas/ControllerSignedRequest" } }, "required": [ "challenge", "signed" ], "title": "BrowserRelayControllerAttachRequest", "type": "object" }, "BrowserRelayControllerResponse": { "properties": { "controller_id": { "format": "uuid", "title": "Controller Id", "type": "string" }, "host_instance_id": { "format": "uuid", "title": "Host Instance Id", "type": "string" }, "key_generation": { "title": "Key Generation", "type": "integer" }, "status": { "const": "ready", "title": "Status", "type": "string" }, "tenant_id": { "format": "uuid", "title": "Tenant Id", "type": "string" }, "workshop_id": { "format": "uuid", "title": "Workshop Id", "type": "string" } }, "required": [ "tenant_id", "workshop_id", "host_instance_id", "controller_id", "key_generation", "status" ], "title": "BrowserRelayControllerResponse", "type": "object" }, "BrowserRelayHandshake": { "additionalProperties": false, "properties": { "authorization": { "anyOf": [ { "format": "password", "maxLength": 16384, "type": "string", "writeOnly": true }, { "type": "null" } ], "title": "Authorization" }, "origin": { "anyOf": [ { "maxLength": 512, "pattern": "^[^\\r\\n]*$", "type": "string" }, { "type": "null" } ], "title": "Origin" }, "sec_websocket_protocol": { "anyOf": [ { "format": "password", "maxLength": 16384, "type": "string", "writeOnly": true }, { "type": "null" } ], "title": "Sec Websocket Protocol" } }, "title": "BrowserRelayHandshake", "type": "object" }, "BrowserRelayModeRequest": { "additionalProperties": false, "properties": { "client_id": { "maxLength": 128, "minLength": 1, "title": "Client Id", "type": "string" }, "expected_epoch": { "minimum": 0.0, "title": "Expected Epoch", "type": "integer" }, "handshake": { "$ref": "#/components/schemas/BrowserRelayHandshake" }, "requested_mode": { "enum": [ "paused", "agent", "private", "teach", "shared" ], "title": "Requested Mode", "type": "string" }, "session_id": { "format": "uuid", "title": "Session Id", "type": "string" } }, "required": [ "handshake", "session_id", "client_id", "requested_mode", "expected_epoch" ], "title": "BrowserRelayModeRequest", "type": "object" }, "BrowserRelayModeResponse": { "properties": { "authorization": { "title": "Authorization", "type": "string" }, "binding": { "$ref": "#/components/schemas/BrowserRelayBinding" }, "expires_at": { "format": "date-time", "title": "Expires At", "type": "string" }, "max_lifetime_seconds": { "const": 10, "default": 10, "title": "Max Lifetime Seconds", "type": "integer" }, "refresh_after_seconds": { "const": 3, "default": 3, "title": "Refresh After Seconds", "type": "integer" }, "status": { "const": "pending", "default": "pending", "title": "Status", "type": "string" }, "transition_id": { "format": "uuid", "title": "Transition Id", "type": "string" } }, "required": [ "authorization", "expires_at", "binding", "transition_id" ], "title": "BrowserRelayModeResponse", "type": "object" }, "BrowserRelayPauseRequest": { "additionalProperties": false, "properties": { "client_id": { "maxLength": 128, "minLength": 1, "title": "Client Id", "type": "string" }, "expected_epoch": { "minimum": 0.0, "title": "Expected Epoch", "type": "integer" }, "handshake": { "$ref": "#/components/schemas/BrowserRelayHandshake" }, "reason": { "enum": [ "disconnect", "heartbeat_timeout", "relay_lost", "transition_timeout" ], "title": "Reason", "type": "string" }, "session_id": { "format": "uuid", "title": "Session Id", "type": "string" } }, "required": [ "handshake", "session_id", "client_id", "expected_epoch", "reason" ], "title": "BrowserRelayPauseRequest", "type": "object" }, "BrowserRelayRefreshRequest": { "additionalProperties": false, "properties": { "authorization": { "format": "password", "maxLength": 8192, "minLength": 1, "title": "Authorization", "type": "string", "writeOnly": true }, "client_id": { "maxLength": 128, "minLength": 1, "title": "Client Id", "type": "string" }, "handshake": { "$ref": "#/components/schemas/BrowserRelayHandshake" }, "session_id": { "format": "uuid", "title": "Session Id", "type": "string" } }, "required": [ "handshake", "session_id", "client_id", "authorization" ], "title": "BrowserRelayRefreshRequest", "type": "object" }, "BrowserRunsRetiredProblem": { "description": "The problem+json body every retired browser-run route answers.", "properties": { "code": { "const": "resource_gone", "title": "Code", "type": "string" }, "detail": { "title": "Detail", "type": "string" }, "error_code": { "const": "browser_runs_retired", "title": "Error Code", "type": "string" }, "status": { "const": 410, "title": "Status", "type": "integer" } }, "required": [ "status", "code", "error_code", "detail" ], "title": "BrowserRunsRetiredProblem", "type": "object" }, "BrowserSessionClosedResponse": { "properties": { "mode": { "const": "closed", "default": "closed", "title": "Mode", "type": "string" }, "session_id": { "format": "uuid", "title": "Session Id", "type": "string" } }, "required": [ "session_id" ], "title": "BrowserSessionClosedResponse", "type": "object" }, "BrowserSessionCreateRequest": { "additionalProperties": false, "properties": { "agent_account_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Agent Account Id" }, "request_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Request Id" } }, "title": "BrowserSessionCreateRequest", "type": "object" }, "BrowserSessionDeviceEgress": { "description": "TIDY-18934 F13: one of the owner's computers, reached through the relay.", "properties": { "device": { "$ref": "#/components/schemas/BrowserSessionEgressComputer" }, "generation": { "minimum": 1.0, "title": "Generation", "type": "integer" }, "id": { "format": "uuid", "title": "Id", "type": "string" } }, "required": [ "id", "generation", "device" ], "title": "BrowserSessionDeviceEgress", "type": "object" }, "BrowserSessionEgress": { "description": "A proxy (TIDY-18940): exactly these three keys, as its controller parses them.", "properties": { "generation": { "minimum": 1.0, "title": "Generation", "type": "integer" }, "id": { "format": "uuid", "title": "Id", "type": "string" }, "url": { "title": "Url", "type": "string" } }, "required": [ "id", "generation", "url" ], "title": "BrowserSessionEgress", "type": "object" }, "BrowserSessionEgressComputer": { "description": "The owner's computer, and the relay ticket for this session's link.", "properties": { "expires_at": { "format": "date-time", "title": "Expires At", "type": "string" }, "id": { "format": "uuid", "title": "Id", "type": "string" }, "name": { "maxLength": 80, "minLength": 1, "title": "Name", "type": "string" }, "ticket": { "maxLength": 8192, "minLength": 1, "title": "Ticket", "type": "string" } }, "required": [ "id", "name", "ticket", "expires_at" ], "title": "BrowserSessionEgressComputer", "type": "object" }, "BrowserSessionEgressRequest": { "additionalProperties": false, "properties": { "authorization": { "format": "password", "maxLength": 8192, "minLength": 1, "title": "Authorization", "type": "string", "writeOnly": true }, "message": { "$ref": "#/components/schemas/ControllerEnvelope" }, "signature": { "format": "password", "maxLength": 128, "minLength": 80, "title": "Signature", "type": "string", "writeOnly": true } }, "required": [ "message", "signature", "authorization" ], "title": "BrowserSessionEgressRequest", "type": "object" }, "BrowserSessionEgressResponse": { "properties": { "egress": { "anyOf": [ { "$ref": "#/components/schemas/BrowserSessionEgress" }, { "$ref": "#/components/schemas/BrowserSessionDeviceEgress" }, { "type": "null" } ], "title": "Egress" } }, "required": [ "egress" ], "title": "BrowserSessionEgressResponse", "type": "object" }, "BrowserSessionFileTransferRequest": { "additionalProperties": false, "properties": { "authorization": { "format": "password", "maxLength": 8192, "minLength": 1, "title": "Authorization", "type": "string", "writeOnly": true }, "client_id": { "maxLength": 128, "minLength": 1, "title": "Client Id", "type": "string" }, "selection": { "discriminator": { "mapping": { "read": "#/components/schemas/BrowserFileSelection", "save": "#/components/schemas/BrowserDownloadSelection" }, "propertyName": "operation" }, "oneOf": [ { "$ref": "#/components/schemas/BrowserFileSelection" }, { "$ref": "#/components/schemas/BrowserDownloadSelection" } ], "title": "Selection" } }, "required": [ "authorization", "client_id", "selection" ], "title": "BrowserSessionFileTransferRequest", "type": "object" }, "BrowserSessionHistoryEntry": { "properties": { "agent_account_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Agent Account Id" }, "close_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Close Reason" }, "closed_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Closed At" }, "controller_account_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Controller Account Id" }, "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "driver_intervals": { "items": { "$ref": "#/components/schemas/BrowserDriverInterval" }, "title": "Driver Intervals", "type": "array" }, "mode": { "enum": [ "paused", "agent", "private", "teach", "shared", "unavailable", "closed" ], "title": "Mode", "type": "string" }, "pause_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Pause Reason" }, "released_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Released At" }, "session_id": { "format": "uuid", "title": "Session Id", "type": "string" } }, "required": [ "session_id", "mode", "agent_account_id", "controller_account_id", "driver_intervals", "created_at", "closed_at", "close_reason" ], "title": "BrowserSessionHistoryEntry", "type": "object" }, "BrowserSessionHistoryResponse": { "description": "The last 50 sessions of one browsing account with their driver intervals\n(TIDY-18718 / D24). Owner or ``watch`` right; the control table is unsynced,\nso this endpoint is the read path.", "properties": { "sessions": { "items": { "$ref": "#/components/schemas/BrowserSessionHistoryEntry" }, "title": "Sessions", "type": "array" } }, "required": [ "sessions" ], "title": "BrowserSessionHistoryResponse", "type": "object" }, "BrowserSessionResponse": { "properties": { "controller_epoch": { "title": "Controller Epoch", "type": "integer" }, "mode": { "enum": [ "paused", "agent", "private", "teach", "shared", "unavailable", "closed" ], "title": "Mode", "type": "string" }, "session_id": { "format": "uuid", "title": "Session Id", "type": "string" } }, "required": [ "session_id", "mode", "controller_epoch" ], "title": "BrowserSessionResponse", "type": "object" }, "BrowserTeachingSaveRequest": { "additionalProperties": false, "properties": { "authorization": { "format": "password", "maxLength": 8192, "minLength": 1, "title": "Authorization", "type": "string", "writeOnly": true }, "message": { "$ref": "#/components/schemas/ControllerEnvelope" }, "signature": { "format": "password", "maxLength": 128, "minLength": 80, "title": "Signature", "type": "string", "writeOnly": true } }, "required": [ "message", "signature", "authorization" ], "title": "BrowserTeachingSaveRequest", "type": "object" }, "BrowserTicketRedeemRequest": { "additionalProperties": false, "properties": { "client_id": { "maxLength": 128, "minLength": 1, "title": "Client Id", "type": "string" }, "intent": { "enum": [ "watch", "private", "teach", "shared", "execute" ], "title": "Intent", "type": "string" }, "ticket": { "format": "password", "maxLength": 4096, "minLength": 1, "title": "Ticket", "type": "string", "writeOnly": true } }, "required": [ "intent", "client_id", "ticket" ], "title": "BrowserTicketRedeemRequest", "type": "object" }, "BrowserTicketRequest": { "additionalProperties": false, "properties": { "client_id": { "maxLength": 128, "minLength": 1, "title": "Client Id", "type": "string" }, "intent": { "enum": [ "watch", "private", "teach", "shared", "execute" ], "title": "Intent", "type": "string" } }, "required": [ "intent", "client_id" ], "title": "BrowserTicketRequest", "type": "object" }, "BrowserTicketResponse": { "properties": { "browser_account_id": { "format": "uuid", "title": "Browser Account Id", "type": "string" }, "controller_capabilities": { "items": { "type": "string" }, "title": "Controller Capabilities", "type": "array" }, "expires_at": { "format": "date-time", "title": "Expires At", "type": "string" }, "has_employee": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Has Employee" }, "label": { "title": "Label", "type": "string" }, "persona_account_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "default": null, "title": "Persona Account Id" }, "stream_path": { "title": "Stream Path", "type": "string" }, "ticket": { "title": "Ticket", "type": "string" }, "workshop_id": { "format": "uuid", "title": "Workshop Id", "type": "string" } }, "required": [ "browser_account_id", "ticket", "expires_at", "stream_path", "label", "workshop_id" ], "title": "BrowserTicketResponse", "type": "object" }, "BrowserTrailAccount": { "description": "A browsing account the trail drove, and whether its pictures are shown to the reader.", "properties": { "browser_account_id": { "format": "uuid", "title": "Browser Account Id", "type": "string" }, "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Label" }, "pictures": { "enum": [ "shown", "withheld", "none" ], "title": "Pictures", "type": "string" }, "withheld_because": { "anyOf": [ { "enum": [ "audience", "viewer", "storage" ], "type": "string" }, { "type": "null" } ], "description": "audience: not everyone who reads the conversation may watch this browser, so no picture was kept; viewer: you may not watch it; storage: the workspace had no room.", "title": "Withheld Because" } }, "required": [ "browser_account_id", "label", "pictures", "withheld_because" ], "title": "BrowserTrailAccount", "type": "object" }, "BrowserTrailPage": { "additionalProperties": false, "description": "The page a step happened on: origin and path only, never a query or fragment.", "properties": { "title": { "maxLength": 256, "title": "Title", "type": "string" }, "url": { "maxLength": 1024, "minLength": 1, "title": "Url", "type": "string" } }, "required": [ "url", "title" ], "title": "BrowserTrailPage", "type": "object" }, "BrowserTrailPicture": { "properties": { "index": { "title": "Index", "type": "integer" }, "url": { "description": "The masked JPEG, read with the caller's own credential: every read is authorized again, like any browser evidence (getBrowserTrailPicture).", "title": "Url", "type": "string" } }, "required": [ "index", "url" ], "title": "BrowserTrailPicture", "type": "object" }, "BrowserTrailRecord": { "properties": { "accounts": { "items": { "$ref": "#/components/schemas/BrowserTrailAccount" }, "title": "Accounts", "type": "array" }, "ended_at": { "format": "date-time", "title": "Ended At", "type": "string" }, "outcome": { "enum": [ "completed", "failed", "stopped", "parked" ], "title": "Outcome", "type": "string" }, "pictures": { "items": { "$ref": "#/components/schemas/BrowserTrailPicture" }, "title": "Pictures", "type": "array" }, "started_at": { "format": "date-time", "title": "Started At", "type": "string" }, "steps": { "items": { "$ref": "#/components/schemas/BrowserTrailStep" }, "title": "Steps", "type": "array" }, "trail_id": { "format": "uuid", "title": "Trail Id", "type": "string" }, "turn_ref": { "title": "Turn Ref", "type": "string" } }, "required": [ "trail_id", "turn_ref", "outcome", "started_at", "ended_at", "steps", "pictures", "accounts" ], "title": "BrowserTrailRecord", "type": "object" }, "BrowserTrailStep": { "additionalProperties": false, "properties": { "at": { "format": "date-time", "title": "At", "type": "string" }, "browser_account_id": { "format": "uuid", "title": "Browser Account Id", "type": "string" }, "masked": { "default": false, "description": "The picture is the placeholder watchers see while a secret field is focused.", "title": "Masked", "type": "boolean" }, "operation": { "enum": [ "open", "navigate", "click", "fill", "select.option", "drag", "press", "scroll", "file.upload", "file.save", "tab.new", "tab.select", "tab.close", "dialog.accept", "dialog.dismiss", "final" ], "title": "Operation", "type": "string" }, "outcome": { "enum": [ "applied", "approval_required", "refused" ], "title": "Outcome", "type": "string" }, "page": { "anyOf": [ { "$ref": "#/components/schemas/BrowserTrailPage" }, { "type": "null" } ] }, "picture": { "anyOf": [ { "exclusiveMaximum": 16.0, "minimum": 0.0, "type": "integer" }, { "type": "null" } ], "title": "Picture" }, "refusal": { "anyOf": [ { "maxLength": 64, "pattern": "^[a-z][a-z0-9_]{0,63}$", "type": "string" }, { "type": "null" } ], "title": "Refusal" }, "target": { "anyOf": [ { "$ref": "#/components/schemas/BrowserTrailTarget" }, { "type": "null" } ] } }, "required": [ "at", "operation", "browser_account_id", "outcome" ], "title": "BrowserTrailStep", "type": "object" }, "BrowserTrailTarget": { "additionalProperties": false, "description": "What the step acted on, as the page names it (accessible role and name).", "properties": { "name": { "maxLength": 160, "title": "Name", "type": "string" }, "role": { "maxLength": 64, "minLength": 1, "title": "Role", "type": "string" } }, "required": [ "role", "name" ], "title": "BrowserTrailTarget", "type": "object" }, "BrowserTrailUploadRequest": { "additionalProperties": false, "description": "One turn's trail, sent once by the workshop when the turn ends.\n\n``trail_id`` is the idempotency key: a retry after a crash returns the\ntrail already stored. ``pictures`` are base64 JPEGs the steps point at by\nindex.", "properties": { "conversation_id": { "format": "uuid", "title": "Conversation Id", "type": "string" }, "ended_at": { "format": "date-time", "title": "Ended At", "type": "string" }, "outcome": { "enum": [ "completed", "failed", "stopped", "parked" ], "title": "Outcome", "type": "string" }, "pictures": { "items": { "maxLength": 350000, "minLength": 4, "type": "string" }, "maxItems": 16, "title": "Pictures", "type": "array" }, "started_at": { "format": "date-time", "title": "Started At", "type": "string" }, "steps": { "items": { "$ref": "#/components/schemas/BrowserTrailStep" }, "maxItems": 60, "minItems": 1, "title": "Steps", "type": "array" }, "trail_id": { "format": "uuid", "title": "Trail Id", "type": "string" }, "turn_ref": { "maxLength": 512, "minLength": 1, "title": "Turn Ref", "type": "string" } }, "required": [ "trail_id", "conversation_id", "turn_ref", "outcome", "started_at", "ended_at", "steps" ], "title": "BrowserTrailUploadRequest", "type": "object" }, "BrowserTrailUploadResponse": { "properties": { "pictures": { "description": "Pictures kept; withheld ones were never stored.", "title": "Pictures", "type": "integer" }, "steps": { "title": "Steps", "type": "integer" }, "trail_id": { "format": "uuid", "title": "Trail Id", "type": "string" } }, "required": [ "trail_id", "steps", "pictures" ], "title": "BrowserTrailUploadResponse", "type": "object" }, "BrowserTrailsResponse": { "properties": { "trails": { "items": { "$ref": "#/components/schemas/BrowserTrailRecord" }, "title": "Trails", "type": "array" } }, "required": [ "trails" ], "title": "BrowserTrailsResponse", "type": "object" }, "BulkActionRequest": { "properties": { "action": { "title": "Action", "type": "string" }, "code_ids": { "items": { "type": "string" }, "title": "Code Ids", "type": "array" }, "days": { "default": 14, "title": "Days", "type": "integer" } }, "required": [ "action", "code_ids" ], "title": "BulkActionRequest", "type": "object" }, "BulkAddFailure": { "description": "One id that could not be added, and why — never a silent drop.", "properties": { "detail": { "title": "Detail", "type": "string" }, "error_code": { "title": "Error Code", "type": "string" }, "typed_id": { "title": "Typed Id", "type": "string" } }, "required": [ "typed_id", "error_code", "detail" ], "title": "BulkAddFailure", "type": "object" }, "BulkAddItemsRequest": { "description": "Add a whole selection in ONE request (TIDY-15762).\n\nBulk add rides each surface's existing multi-select, so the client sends\nthe typed ids it already has. One request rather than N keeps the caps\nevaluated against a single, consistent view of the bundle — N parallel adds\nwould each see the pre-add count and could sail past the item cap together.", "properties": { "gesture": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Gesture" }, "source_surface": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Source Surface" }, "typed_ids": { "items": { "type": "string" }, "maxItems": 200, "minItems": 1, "title": "Typed Ids", "type": "array" } }, "required": [ "typed_ids" ], "title": "BulkAddItemsRequest", "type": "object" }, "BulkAddItemsResponse": { "description": "Per-id outcomes. A partial success is reported as one, not hidden.", "properties": { "added_count": { "title": "Added Count", "type": "integer" }, "duplicate_count": { "title": "Duplicate Count", "type": "integer" }, "failed": { "items": { "$ref": "#/components/schemas/BulkAddFailure" }, "title": "Failed", "type": "array" }, "items": { "items": { "$ref": "#/components/schemas/AddItemResponse" }, "title": "Items", "type": "array" } }, "required": [ "items", "added_count", "duplicate_count", "failed" ], "title": "BulkAddItemsResponse", "type": "object" }, "BulkAssignRequest": { "description": "Input for bulk content assignment.", "properties": { "items": { "description": "List of content items to assign/unassign", "items": { "$ref": "#/components/schemas/ContentItem" }, "minItems": 1, "title": "Items", "type": "array" } }, "required": [ "items" ], "title": "BulkAssignRequest", "type": "object" }, "BulkAssignResponse": { "description": "Result of a bulk assign or unassign operation.", "properties": { "processed": { "description": "Number of items processed", "title": "Processed", "type": "integer" }, "skipped": { "default": 0, "description": "Number of items skipped (not found)", "title": "Skipped", "type": "integer" } }, "required": [ "processed" ], "title": "BulkAssignResponse", "type": "object" }, "BulkEmailActionItemResult": { "properties": { "error_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error Code" }, "id": { "format": "uuid", "title": "Id", "type": "string" }, "message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Message" }, "success": { "title": "Success", "type": "boolean" } }, "required": [ "id", "success" ], "title": "BulkEmailActionItemResult", "type": "object" }, "BulkEmailActionRequest": { "properties": { "action": { "description": "Action to apply to every email id", "title": "Action", "type": "string" }, "email_ids": { "description": "Target email ids", "items": { "type": "string" }, "maxItems": 500, "minItems": 1, "title": "Email Ids", "type": "array" }, "params": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "Reserved for action-specific parameters", "title": "Params" } }, "required": [ "action", "email_ids" ], "title": "BulkEmailActionRequest", "type": "object" }, "BulkEmailActionResponse": { "properties": { "action": { "title": "Action", "type": "string" }, "failed": { "title": "Failed", "type": "integer" }, "results": { "items": { "$ref": "#/components/schemas/BulkEmailActionItemResult" }, "title": "Results", "type": "array" }, "succeeded": { "title": "Succeeded", "type": "integer" } }, "required": [ "action", "succeeded", "failed", "results" ], "title": "BulkEmailActionResponse", "type": "object" }, "BulkEventReviewItemResult": { "description": "Per-item failure record for a bulk review call.", "properties": { "error": { "title": "Error", "type": "string" }, "event_id": { "title": "Event Id", "type": "string" } }, "required": [ "event_id", "error" ], "title": "BulkEventReviewItemResult", "type": "object" }, "BulkEventReviewRequest": { "description": "Bulk approve/reject request for pending calendar events (TIDY-13541).", "properties": { "action": { "enum": [ "approve", "reject" ], "title": "Action", "type": "string" }, "event_ids": { "items": { "type": "string" }, "maxItems": 500, "minItems": 1, "title": "Event Ids", "type": "array" } }, "required": [ "event_ids", "action" ], "title": "BulkEventReviewRequest", "type": "object" }, "BulkEventReviewResponse": { "description": "Aggregate result of a bulk review call.\n\n`succeeded`/`failed` are the original TIDY-13541 aggregates and stay exactly\nas they were for existing clients. `results` (TIDY-17980) is the additive,\ncomplete, ordered, one-entry-per-id typed view new clients read.", "properties": { "failed": { "items": { "$ref": "#/components/schemas/BulkEventReviewItemResult" }, "title": "Failed", "type": "array" }, "results": { "items": { "$ref": "#/components/schemas/BulkReviewItemResult" }, "title": "Results", "type": "array" }, "succeeded": { "items": { "type": "string" }, "title": "Succeeded", "type": "array" } }, "title": "BulkEventReviewResponse", "type": "object" }, "BulkGrantError": { "properties": { "error": { "title": "Error", "type": "string" }, "index": { "title": "Index", "type": "integer" } }, "required": [ "index", "error" ], "title": "BulkGrantError", "type": "object" }, "BulkGrantItem": { "properties": { "action": { "enum": [ "read", "read_write" ], "title": "Action", "type": "string" }, "container_ref": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Container Ref" }, "delegatee_account_id": { "format": "uuid", "title": "Delegatee Account Id", "type": "string" }, "delegatee_member_type": { "enum": [ "human", "virtual_employee" ], "title": "Delegatee Member Type", "type": "string" }, "delegator_account_id": { "format": "uuid", "title": "Delegator Account Id", "type": "string" }, "expires_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Expires At" }, "facet_keys": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Facet Keys" }, "resource_type": { "enum": [ "calendar", "notes", "projects", "contacts", "activities", "inbox", "photos", "podcasts", "files", "structure", "sessions", "records" ], "title": "Resource Type", "type": "string" } }, "required": [ "resource_type", "delegator_account_id", "delegatee_account_id", "delegatee_member_type", "action" ], "title": "BulkGrantItem", "type": "object" }, "BulkGrantRequest": { "properties": { "grants": { "items": { "$ref": "#/components/schemas/BulkGrantItem" }, "title": "Grants", "type": "array" } }, "required": [ "grants" ], "title": "BulkGrantRequest", "type": "object" }, "BulkGrantResponse": { "properties": { "created": { "title": "Created", "type": "integer" }, "errors": { "items": { "$ref": "#/components/schemas/BulkGrantError" }, "title": "Errors", "type": "array" } }, "required": [ "created", "errors" ], "title": "BulkGrantResponse", "type": "object" }, "BulkIdsRequest": { "properties": { "dry_run": { "default": false, "description": "Preview only; no mutation, no audit", "title": "Dry Run", "type": "boolean" }, "ids": { "items": { "format": "uuid", "type": "string" }, "maxItems": 500, "minItems": 1, "title": "Ids", "type": "array" } }, "required": [ "ids" ], "title": "BulkIdsRequest", "type": "object" }, "BulkItemResult": { "description": "Per-item outcome for a bulk operation.", "properties": { "error_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error Code" }, "id": { "format": "uuid", "title": "Id", "type": "string" }, "message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Message" }, "success": { "title": "Success", "type": "boolean" } }, "required": [ "id", "success" ], "title": "BulkItemResult", "type": "object" }, "BulkResolveRequest": { "properties": { "event_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Event Type" }, "ids": { "items": { "format": "uuid", "type": "string" }, "title": "Ids", "type": "array" } }, "title": "BulkResolveRequest", "type": "object" }, "BulkResult": { "description": "Aggregate result for a bulk operation.", "properties": { "action": { "title": "Action", "type": "string" }, "failed": { "title": "Failed", "type": "integer" }, "results": { "items": { "$ref": "#/components/schemas/BulkItemResult" }, "title": "Results", "type": "array" }, "succeeded": { "title": "Succeeded", "type": "integer" } }, "required": [ "action", "succeeded", "failed", "results" ], "title": "BulkResult", "type": "object" }, "BulkReviewItemResult": { "description": "Typed per-item outcome for one submitted id (TIDY-17980).\n\nExactly one of these exists for every id in the request, in submitted\norder, including ids that are invalid or belong to another member — the\noutcome is `failed` with a stable code and a bounded, safe message, which\nreports the refusal without disclosing whether the id exists.", "properties": { "error_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error Code" }, "event_id": { "title": "Event Id", "type": "string" }, "message": { "anyOf": [ { "maxLength": 300, "type": "string" }, { "type": "null" } ], "title": "Message" }, "outcome": { "enum": [ "approved", "rejected", "failed" ], "title": "Outcome", "type": "string" } }, "required": [ "event_id", "outcome" ], "title": "BulkReviewItemResult", "type": "object" }, "BulkVCardRequest": { "properties": { "contact_ids": { "items": { "type": "string" }, "maxItems": 500, "minItems": 1, "title": "Contact Ids", "type": "array" } }, "required": [ "contact_ids" ], "title": "BulkVCardRequest", "type": "object" }, "BundleDetailResponse": { "properties": { "created_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Created At" }, "facet_slug": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Facet Slug" }, "id": { "title": "Id", "type": "string" }, "instructions": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Instructions" }, "item_count": { "title": "Item Count", "type": "integer" }, "items": { "default": [], "items": { "$ref": "#/components/schemas/BundleItemResponse" }, "title": "Items", "type": "array" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Name" }, "resolution": { "anyOf": [ { "$ref": "#/components/schemas/ResolutionResponse" }, { "type": "null" } ], "default": null }, "status": { "title": "Status", "type": "string" }, "token_estimate": { "title": "Token Estimate", "type": "integer" }, "updated_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Updated At" } }, "required": [ "id", "status", "item_count", "token_estimate" ], "title": "BundleDetailResponse", "type": "object" }, "BundleItemResponse": { "properties": { "bundle_id": { "title": "Bundle Id", "type": "string" }, "child_count": { "default": 0, "description": "For a container chip: how many direct children it resolved to, excluding deselected ones. Zero for every other item.", "title": "Child Count", "type": "integer" }, "client_item_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Client Item Id" }, "context_role": { "default": "source", "description": "'source' (citeable evidence) or 'instruction' (the user's own steering, which never enters the numbered source blocks).", "title": "Context Role", "type": "string" }, "created_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Created At" }, "excluded": { "default": false, "title": "Excluded", "type": "boolean" }, "external_final_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Where the fetch actually landed, when a redirect took it somewhere other than the submitted URL. Null when it did not.", "title": "External Final Url" }, "external_kind": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "External Kind" }, "external_metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "description": "Provider-reported facts about an external source, shaped per external_kind. A YouTube source (external_kind 'youtube') carries video_id, channel, duration_seconds, published_at and transcript_source.", "title": "External Metadata" }, "external_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "External Url" }, "failure_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Failure Code" }, "id": { "title": "Id", "type": "string" }, "inline_text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Inline Text" }, "instruction_reviewed_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "When a member confirmed instruction_text. Null means a machine wrote it and nobody has read it back — which blocks generation.", "title": "Instruction Reviewed At" }, "instruction_text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "The member-owned, editable instruction text this run consumes.", "title": "Instruction Text" }, "parent_item_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Parent Item Id" }, "position": { "title": "Position", "type": "integer" }, "primitive_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Primitive Id" }, "primitive_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Primitive Type" }, "scope_note": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Scope Note" }, "source_kind": { "title": "Source Kind", "type": "string" }, "state": { "title": "State", "type": "string" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Title" }, "token_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Token Count" }, "typed_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Public typed id of the source primitive, when it has one.", "title": "Typed Id" }, "updated_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Updated At" } }, "required": [ "id", "bundle_id", "position", "source_kind", "state" ], "title": "BundleItemResponse", "type": "object" }, "BundleResponse": { "properties": { "created_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Created At" }, "facet_slug": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Facet Slug" }, "id": { "title": "Id", "type": "string" }, "instructions": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Instructions" }, "item_count": { "title": "Item Count", "type": "integer" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Name" }, "status": { "title": "Status", "type": "string" }, "token_estimate": { "title": "Token Estimate", "type": "integer" }, "updated_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Updated At" } }, "required": [ "id", "status", "item_count", "token_estimate" ], "title": "BundleResponse", "type": "object" }, "BusiestDay": { "properties": { "date": { "title": "Date", "type": "string" }, "emails": { "title": "Emails", "type": "integer" } }, "required": [ "date", "emails" ], "title": "BusiestDay", "type": "object" }, "ButtonTrigger": { "additionalProperties": false, "description": "Human-invoked from a facet placement (the D1 sanctioned chain point).", "properties": { "kind": { "const": "button", "title": "Kind", "type": "string" }, "placement": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Placement" } }, "required": [ "kind" ], "title": "ButtonTrigger", "type": "object" }, "ByoCapabilityConfigResponse": { "properties": { "api_key_masked": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Write-only key, masked to the last 4 chars; null when absent.", "title": "Api Key Masked" }, "base_url": { "title": "Base Url", "type": "string" }, "capability": { "title": "Capability", "type": "string" }, "chain": { "description": "The capability's whole ordered chain, including the preferred provider at index 0. The top-level fields above mirror that first entry.", "items": { "$ref": "#/components/schemas/ByoChainProviderResponse" }, "title": "Chain", "type": "array" }, "enabled": { "title": "Enabled", "type": "boolean" }, "key_fingerprint": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Non-secret fingerprint of the encrypted credential.", "title": "Key Fingerprint" }, "last_test_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Last Test At" }, "last_test_ok": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "title": "Last Test Ok" }, "model": { "title": "Model", "type": "string" }, "provider_org_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Provider organization id, sent as the OpenAI-Organization header. Non-secret, so it reads back.", "title": "Provider Org Id" }, "provider_region": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Region for a regional endpoint, substituted into the {region} placeholder in base_url. Non-secret, so it reads back.", "title": "Provider Region" }, "revoked_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Revoked At" }, "rotated_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Rotated At" }, "updated_at": { "format": "date-time", "title": "Updated At", "type": "string" } }, "required": [ "capability", "base_url", "model", "enabled", "updated_at" ], "title": "ByoCapabilityConfigResponse", "type": "object" }, "ByoChainProviderRequest": { "description": "One fallback provider as the settings form submits it.", "properties": { "api_key": { "anyOf": [ { "maxLength": 8192, "type": "string" }, { "type": "null" } ], "description": "Write-only. Absent = keep the key already stored at this position; required when this position is new.", "title": "Api Key" }, "base_url": { "title": "Base Url", "type": "string" }, "key_fingerprint": { "anyOf": [ { "maxLength": 64, "type": "string" }, { "type": "null" } ], "description": "Echo the fingerprint this provider was read back with to keep its stored key while MOVING it in the chain. Without it, an omitted api_key keeps whatever key already sat at this position — which is the wrong key the moment the user reorders. Not a secret.", "title": "Key Fingerprint" }, "model": { "maxLength": 256, "minLength": 1, "title": "Model", "type": "string" }, "provider_org_id": { "anyOf": [ { "maxLength": 128, "type": "string" }, { "type": "null" } ], "title": "Provider Org Id" }, "provider_region": { "anyOf": [ { "maxLength": 64, "type": "string" }, { "type": "null" } ], "title": "Provider Region" } }, "required": [ "base_url", "model" ], "title": "ByoChainProviderRequest", "type": "object" }, "ByoChainProviderResponse": { "description": "One member of the capability's ordered provider chain (TIDY-15841).", "properties": { "api_key_masked": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Write-only key, masked to the last 4 chars; null when absent.", "title": "Api Key Masked" }, "base_url": { "title": "Base Url", "type": "string" }, "enabled": { "title": "Enabled", "type": "boolean" }, "key_fingerprint": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Key Fingerprint" }, "last_test_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Last Test At" }, "last_test_ok": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "title": "Last Test Ok" }, "model": { "title": "Model", "type": "string" }, "priority": { "description": "Position in the chain — 0 is the preferred provider, 1..N the ordered fallbacks.", "title": "Priority", "type": "integer" }, "provider_org_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Provider Org Id" }, "provider_region": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Provider Region" }, "revoked_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Revoked At" }, "rotated_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Rotated At" }, "updated_at": { "format": "date-time", "title": "Updated At", "type": "string" } }, "required": [ "priority", "base_url", "model", "enabled", "updated_at" ], "title": "ByoChainProviderResponse", "type": "object" }, "ByoConfigPutRequest": { "properties": { "api_key": { "anyOf": [ { "maxLength": 8192, "type": "string" }, { "type": "null" } ], "description": "Write-only. Absent = keep the stored key; empty string = revoke and disable it.", "title": "Api Key" }, "base_url": { "description": "OpenAI-compatible base URL, e.g. https://api.openai.com/v1 — the caller appends /chat/completions etc. against it. Trailing slash is stripped.", "title": "Base Url", "type": "string" }, "enabled": { "default": false, "title": "Enabled", "type": "boolean" }, "fallbacks": { "anyOf": [ { "items": { "$ref": "#/components/schemas/ByoChainProviderRequest" }, "type": "array" }, { "type": "null" } ], "description": "The ordered fallback providers behind the preferred one, in the tenant's own order. Absent keeps the stored chain; [] removes every fallback; a list REPLACES the chain wholesale. Bounded — at most 3 fallbacks.", "title": "Fallbacks" }, "model": { "maxLength": 256, "minLength": 1, "title": "Model", "type": "string" }, "provider_org_id": { "anyOf": [ { "maxLength": 128, "type": "string" }, { "type": "null" } ], "description": "Provider organization id, sent as the OpenAI-Organization header on every call made with this key. Not a secret.", "title": "Provider Org Id" }, "provider_region": { "anyOf": [ { "maxLength": 64, "type": "string" }, { "type": "null" } ], "description": "Region for a regional endpoint — required when base_url carries the {region} placeholder, ignored otherwise. Not a secret.", "title": "Provider Region" } }, "required": [ "base_url", "model" ], "title": "ByoConfigPutRequest", "type": "object" }, "ByoConfigsResponse": { "properties": { "embedding": { "anyOf": [ { "$ref": "#/components/schemas/ByoCapabilityConfigResponse" }, { "type": "null" } ], "default": null }, "entitled": { "title": "Entitled", "type": "boolean" }, "gated_by": { "anyOf": [ { "$ref": "#/components/schemas/FeatureGate" }, { "type": "null" } ], "default": null, "description": "What would unlock BYO inference for this workspace; null when entitled." }, "image": { "anyOf": [ { "$ref": "#/components/schemas/ByoCapabilityConfigResponse" }, { "type": "null" } ], "default": null }, "stt": { "anyOf": [ { "$ref": "#/components/schemas/ByoCapabilityConfigResponse" }, { "type": "null" } ], "default": null }, "text": { "anyOf": [ { "$ref": "#/components/schemas/ByoCapabilityConfigResponse" }, { "type": "null" } ], "default": null }, "tts": { "anyOf": [ { "$ref": "#/components/schemas/ByoCapabilityConfigResponse" }, { "type": "null" } ], "default": null }, "video": { "anyOf": [ { "$ref": "#/components/schemas/ByoCapabilityConfigResponse" }, { "type": "null" } ], "default": null } }, "required": [ "entitled" ], "title": "ByoConfigsResponse", "type": "object" }, "ByoProviderTestResult": { "properties": { "detail": { "title": "Detail", "type": "string" }, "ok": { "title": "Ok", "type": "boolean" }, "priority": { "title": "Priority", "type": "integer" }, "provider_host": { "description": "Host only — never a path, query or credential.", "title": "Provider Host", "type": "string" } }, "required": [ "priority", "provider_host", "ok", "detail" ], "title": "ByoProviderTestResult", "type": "object" }, "ByoTestResponse": { "properties": { "detail": { "description": "Secret-free provider probe result; the terminal outcome is audit-recorded.", "title": "Detail", "type": "string" }, "ok": { "description": "True only when EVERY provider in the chain answered. A fallback runs during the primary's outage, so a broken one has to be visible now.", "title": "Ok", "type": "boolean" }, "providers": { "description": "Per-provider probe result, in chain order.", "items": { "$ref": "#/components/schemas/ByoProviderTestResult" }, "title": "Providers", "type": "array" } }, "required": [ "ok", "detail" ], "title": "ByoTestResponse", "type": "object" }, "CacheStats": { "properties": { "avg_latency_hit_ms": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Avg Latency Hit Ms" }, "avg_latency_miss_ms": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Avg Latency Miss Ms" }, "cache_hits": { "default": 0, "title": "Cache Hits", "type": "integer" }, "cache_misses": { "default": 0, "title": "Cache Misses", "type": "integer" }, "hit_rate_pct": { "default": 0.0, "title": "Hit Rate Pct", "type": "number" }, "latency_savings_pct": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Latency Savings Pct" }, "provider_cache_calls": { "default": 0, "title": "Provider Cache Calls", "type": "integer" }, "provider_cached_tokens": { "default": 0, "title": "Provider Cached Tokens", "type": "integer" }, "total_calls": { "default": 0, "title": "Total Calls", "type": "integer" } }, "title": "CacheStats", "type": "object" }, "CalendarAttendee": { "description": "Complete calendar attendee object (response).", "properties": { "agent_account_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "TIDY-16410: the agent account of a virtual-employee attendee. This column IS the VE marker — identity is never inferred from the email address. NULL for humans and external invitees.", "title": "Agent Account Id" }, "attendee_email": { "description": "Attendee email address", "title": "Attendee Email", "type": "string" }, "attendee_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Attendee display name", "title": "Attendee Name" }, "contact_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Linked contact UUID", "title": "Contact Id" }, "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "event_id": { "description": "Parent event UUID", "title": "Event Id", "type": "string" }, "id": { "description": "Attendee UUID", "title": "Id", "type": "string" }, "invite_sent_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "description": "When an invite email was sent to this attendee. NULL = not invited yet.", "title": "Invite Sent At" }, "is_self": { "default": false, "description": "TIDY-16909: this participant is the calling member, resolved across every address they answer to (account address, connection primary, send-as aliases) — not by matching one address.", "title": "Is Self", "type": "boolean" }, "partstat": { "default": "NEEDS-ACTION", "description": "Status: NEEDS-ACTION, ACCEPTED, DECLINED, TENTATIVE", "title": "Partstat", "type": "string" }, "role": { "default": "REQ-PARTICIPANT", "description": "Role: CHAIR, REQ-PARTICIPANT, OPT-PARTICIPANT, NON-PARTICIPANT", "title": "Role", "type": "string" }, "rsvp": { "default": true, "description": "Whether RSVP is requested", "title": "Rsvp", "type": "boolean" }, "tenant_id": { "description": "Tenant UUID", "title": "Tenant Id", "type": "string" }, "updated_at": { "format": "date-time", "title": "Updated At", "type": "string" } }, "required": [ "attendee_email", "id", "event_id", "tenant_id", "created_at", "updated_at" ], "title": "CalendarAttendee", "type": "object" }, "CalendarCollection": { "description": "Complete calendar collection object (response).", "properties": { "account_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Owning member UUID; null for a tenant-shared internal calendar", "title": "Account Id" }, "calendar_source_config_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Linked calendar source config UUID", "title": "Calendar Source Config Id" }, "color": { "anyOf": [ { "pattern": "^#[0-9A-Fa-f]{6}$", "type": "string" }, { "type": "null" } ], "default": null, "description": "Hex color for UI display (#RRGGBB)", "examples": [ "#FF5733", "#3498DB" ], "title": "Color" }, "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "date_pivot_field": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "default": "dtstart", "description": "Date field used for rendering this calendar view. Use 'dtstart' for the core event start date.", "title": "Date Pivot Field" }, "dav_displayname": { "description": "Display name for the calendar", "examples": [ "Family", "Work", "School" ], "maxLength": 255, "minLength": 1, "title": "Dav Displayname", "type": "string" }, "dav_etag": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Entity tag for sync", "title": "Dav Etag" }, "dav_name": { "description": "CalDAV path segment", "title": "Dav Name", "type": "string" }, "default_facet_slug": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "default": null, "description": "Default facet slug associated with this custom calendar", "title": "Default Facet Slug" }, "description": { "anyOf": [ { "maxLength": 1000, "type": "string" }, { "type": "null" } ], "default": null, "description": "Calendar description", "title": "Description" }, "device_import_enabled": { "default": true, "description": "False when the member turned this phone calendar's import off (TIDY-20055)", "title": "Device Import Enabled", "type": "boolean" }, "id": { "description": "Collection UUID", "title": "Id", "type": "string" }, "is_default": { "default": false, "description": "Whether this is the default calendar for new events", "title": "Is Default", "type": "boolean" }, "is_visible": { "default": true, "description": "Whether to show this calendar in the UI", "title": "Is Visible", "type": "boolean" }, "is_write_target": { "default": false, "description": "True for the single collection that a create without an explicit collection_id is routed to for this caller.", "title": "Is Write Target", "type": "boolean" }, "source_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Origin: internal, google_sync, zoho_sync, custom", "title": "Source Type" }, "tenant_id": { "description": "Tenant UUID", "title": "Tenant Id", "type": "string" }, "timezone": { "default": "America/New_York", "description": "IANA timezone identifier", "examples": [ "America/New_York", "UTC", "Europe/London" ], "title": "Timezone", "type": "string" }, "updated_at": { "format": "date-time", "title": "Updated At", "type": "string" }, "write_enabled": { "default": true, "description": "True when the user can write events to this collection", "title": "Write Enabled", "type": "boolean" } }, "required": [ "dav_displayname", "id", "tenant_id", "dav_name", "created_at", "updated_at" ], "title": "CalendarCollection", "type": "object" }, "CalendarCollectionCreate": { "description": "Input model for creating calendar collections.", "properties": { "color": { "anyOf": [ { "pattern": "^#[0-9A-Fa-f]{6}$", "type": "string" }, { "type": "null" } ], "description": "Hex color for UI display (#RRGGBB)", "examples": [ "#FF5733", "#3498DB" ], "title": "Color" }, "date_pivot_field": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "default": "dtstart", "description": "Date field used for rendering this calendar view. Use 'dtstart' for the core event start date.", "title": "Date Pivot Field" }, "dav_displayname": { "description": "Display name for the calendar", "examples": [ "Family", "Work", "School" ], "maxLength": 255, "minLength": 1, "title": "Dav Displayname", "type": "string" }, "default_facet_slug": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "description": "Default facet slug associated with this custom calendar", "title": "Default Facet Slug" }, "description": { "anyOf": [ { "maxLength": 1000, "type": "string" }, { "type": "null" } ], "description": "Calendar description", "title": "Description" }, "id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "description": "Caller-generated id for idempotent private internal calendar creation", "title": "Id" }, "is_default": { "default": false, "description": "Whether this is the default calendar for new events", "title": "Is Default", "type": "boolean" }, "is_visible": { "default": true, "description": "Whether to show this calendar in the UI", "title": "Is Visible", "type": "boolean" }, "private": { "default": false, "description": "Owned by the caller: no other member sees or writes this calendar", "title": "Private", "type": "boolean" }, "timezone": { "default": "America/New_York", "description": "IANA timezone identifier", "examples": [ "America/New_York", "UTC", "Europe/London" ], "title": "Timezone", "type": "string" } }, "required": [ "dav_displayname" ], "title": "CalendarCollectionCreate", "type": "object" }, "CalendarCollectionUpdate": { "description": "Input model for updating calendar collections (partial update).", "properties": { "color": { "anyOf": [ { "pattern": "^#[0-9A-Fa-f]{6}$", "type": "string" }, { "type": "null" } ], "title": "Color" }, "date_pivot_field": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "title": "Date Pivot Field" }, "dav_displayname": { "anyOf": [ { "maxLength": 255, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Dav Displayname" }, "default_facet_slug": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "title": "Default Facet Slug" }, "description": { "anyOf": [ { "maxLength": 1000, "type": "string" }, { "type": "null" } ], "title": "Description" }, "device_import_enabled": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Import this phone calendar into Tidy. False makes the phone stop importing it and remove the copies it imported; the phone keeps them.", "title": "Device Import Enabled" }, "is_default": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is Default" }, "is_visible": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is Visible" }, "timezone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Timezone" } }, "title": "CalendarCollectionUpdate", "type": "object" }, "CalendarDetectionResponse": { "description": "Response from calendar detection.", "properties": { "dates": { "default": [], "items": { "$ref": "#/components/schemas/DetectedDate" }, "title": "Dates", "type": "array" }, "has_calendar_content": { "default": false, "title": "Has Calendar Content", "type": "boolean" }, "meeting_links": { "default": [], "items": { "$ref": "#/components/schemas/DetectedMeetingLink" }, "title": "Meeting Links", "type": "array" }, "suggested_title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Suggested Title" } }, "title": "CalendarDetectionResponse", "type": "object" }, "CalendarEvent": { "description": "Complete calendar event object (response).", "example": { "all_day": false, "approval_status": "approved", "confidence": 0.92, "created_at": "2024-11-19T10:30:00Z", "description": "Weekly soccer practice", "end_time": "2024-11-20T16:30:00-05:00", "id": "550e8400-e29b-41d4-a716-446655440000", "location": "Central Park Soccer Field", "start_time": "2024-11-20T15:00:00-05:00", "tenant_id": "a1b2c3d4-e5f6-4789-abcd-ef1234567890", "timezone": "America/New_York", "title": "Soccer Practice", "type": "sports" }, "properties": { "all_day": { "default": false, "description": "Whether this is an all-day event", "title": "All Day", "type": "boolean" }, "approval_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Approval Reason" }, "approval_status": { "default": "approved", "description": "Approval status", "examples": [ "pending", "approved", "rejected" ], "title": "Approval Status", "type": "string" }, "approved_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Approved At" }, "approved_by": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Approved By" }, "confidence": { "anyOf": [ { "maximum": 1.0, "minimum": 0.0, "type": "number" }, { "type": "null" } ], "default": null, "description": "AI extraction confidence score (0.0-1.0)", "title": "Confidence" }, "countdown_enabled": { "default": false, "description": "Whether countdown surfaces are enabled for this event", "title": "Countdown Enabled", "type": "boolean" }, "created_at": { "description": "Creation timestamp", "format": "date-time", "title": "Created At", "type": "string" }, "custom_properties": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "description": "Facet field values (flat, keyed by field key)", "title": "Custom Properties" }, "deleted_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "description": "Soft delete timestamp (null if not deleted)", "title": "Deleted At" }, "description": { "anyOf": [ { "maxLength": 5000, "type": "string" }, { "type": "null" } ], "default": null, "description": "Event description/notes", "title": "Description" }, "end_time": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "description": "Event end time (ISO 8601 with timezone)", "examples": [ "2024-11-20T16:30:00-05:00" ], "title": "End Time" }, "facets": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "default": null, "description": "Facet slugs associated with this event", "title": "Facets" }, "id": { "description": "Event UUID", "examples": [ "550e8400-e29b-41d4-a716-446655440000" ], "title": "Id", "type": "string" }, "importance": { "default": false, "description": "Whether this event is marked important", "title": "Importance", "type": "boolean" }, "location": { "anyOf": [ { "maxLength": 500, "type": "string" }, { "type": "null" } ], "default": null, "description": "Event location", "examples": [ "Central Park Soccer Field" ], "title": "Location" }, "metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "Extensible metadata (JSON object)", "title": "Metadata" }, "provenance": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "description": "Provenance metadata: who created this event and how (D29).", "title": "Provenance" }, "recurrence_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Parent event UUID for recurring instances", "title": "Recurrence Id" }, "recurrence_rule": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Recurrence rule in RFC 5545 RRULE format", "examples": [ "FREQ=WEEKLY;BYDAY=MO,WE,FR" ], "title": "Recurrence Rule" }, "requires_review": { "default": false, "description": "Whether this event requires human review", "title": "Requires Review", "type": "boolean" }, "review_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Reason why review is required (e.g., low confidence)", "title": "Review Reason" }, "source_email": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "default": null, "description": "Source email address for auto-extracted events", "title": "Source Email" }, "source_email_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Email this event was extracted from, when available.", "title": "Source Email Id" }, "source_evidence": { "anyOf": [ { "items": { "$ref": "#/components/schemas/SourceEvidence" }, "type": "array" }, { "type": "null" } ], "default": null, "description": "Source records that produced this event.", "title": "Source Evidence" }, "source_evidence_error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Set when the source-evidence sub-fetch failed.", "title": "Source Evidence Error" }, "source_mappings": { "description": "External source mappings for this canonical event", "items": { "$ref": "#/components/schemas/EventSourceMapping" }, "title": "Source Mappings", "type": "array" }, "source_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Supabase Storage URL to the original source document", "title": "Source Url" }, "start_time": { "description": "Event start time (ISO 8601 with timezone)", "examples": [ "2024-11-20T15:00:00-05:00" ], "format": "date-time", "title": "Start Time", "type": "string" }, "tags": { "description": "Event tags mapped to note page titles", "items": { "type": "string" }, "title": "Tags", "type": "array" }, "tenant_id": { "description": "Tenant UUID", "examples": [ "a1b2c3d4-e5f6-4789-abcd-ef1234567890" ], "title": "Tenant Id", "type": "string" }, "timezone": { "default": "UTC", "description": "Event timezone (IANA timezone identifier)", "examples": [ "America/New_York", "UTC" ], "title": "Timezone", "type": "string" }, "title": { "description": "Event title (empty while the row is an unpublished draft)", "examples": [ "Soccer Practice" ], "title": "Title", "type": "string" }, "type": { "anyOf": [ { "maxLength": 50, "type": "string" }, { "type": "null" } ], "default": null, "description": "Event type/category", "examples": [ "school", "sports", "activity", "medical", "other" ], "title": "Type" }, "weather_data": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "description": "Weather forecast data (if available)", "title": "Weather Data" } }, "required": [ "title", "start_time", "id", "tenant_id", "created_at" ], "title": "CalendarEvent", "type": "object" }, "CalendarEventAttendeeInput": { "description": "Attendee shape carried on a create body (TIDY-11426 / R3).\n\nMirrors :class:`CalendarAttendeeCreate` minus ``event_id`` — the event row\ndoes not exist yet at create time. The router materializes each of these\ninto a ``CalendarAttendeeCreate`` once the event id is known and persists\nit via ``attendee_service.add_attendee`` (which auto-links ``contact_id``\nby email).", "properties": { "attendee_email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Attendee email address (ICS identity; resolved from contact_id when omitted)", "title": "Attendee Email" }, "attendee_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Attendee display name", "title": "Attendee Name" }, "contact_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional contacts.id when the attendee is a known contact", "title": "Contact Id" }, "partstat": { "default": "NEEDS-ACTION", "description": "Status: NEEDS-ACTION, ACCEPTED, DECLINED, TENTATIVE", "title": "Partstat", "type": "string" }, "role": { "default": "REQ-PARTICIPANT", "description": "Role: CHAIR, REQ-PARTICIPANT, OPT-PARTICIPANT, NON-PARTICIPANT", "title": "Role", "type": "string" }, "rsvp": { "default": true, "description": "Whether RSVP is requested", "title": "Rsvp", "type": "boolean" } }, "title": "CalendarEventAttendeeInput", "type": "object" }, "CalendarEventCreate": { "description": "Input model for creating calendar events.", "example": { "all_day": false, "confidence": 0.92, "description": "Weekly soccer practice at the park", "end_time": "2024-11-20T16:30:00-05:00", "location": "Central Park Soccer Field", "metadata": { "extracted_by": "n8n", "workflow_id": "event-extraction-v2" }, "source_email": "coach@soccerleague.com", "start_time": "2024-11-20T15:00:00-05:00", "timezone": "America/New_York", "title": "Soccer Practice", "type": "sports" }, "properties": { "all_day": { "default": false, "description": "Whether this is an all-day event", "title": "All Day", "type": "boolean" }, "attendees": { "anyOf": [ { "items": { "$ref": "#/components/schemas/CalendarEventAttendeeInput" }, "type": "array" }, { "type": "null" } ], "description": "Attendees to add when the event is created (one round-trip).", "title": "Attendees" }, "collection_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional target calendar collection UUID for manual events", "title": "Collection Id" }, "confidence": { "anyOf": [ { "maximum": 1.0, "minimum": 0.0, "type": "number" }, { "type": "null" } ], "description": "AI extraction confidence score (0.0-1.0)", "title": "Confidence" }, "countdown_enabled": { "default": false, "description": "Whether countdown surfaces are enabled for this event", "title": "Countdown Enabled", "type": "boolean" }, "custom_properties": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "Facet field values (flat, keyed by field key)", "title": "Custom Properties" }, "description": { "anyOf": [ { "maxLength": 5000, "type": "string" }, { "type": "null" } ], "description": "Event description/notes", "title": "Description" }, "end_time": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "Event end time (ISO 8601 with timezone)", "examples": [ "2024-11-20T16:30:00-05:00" ], "title": "End Time" }, "facets": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "description": "Facet slugs associated with this event", "title": "Facets" }, "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Client-provided UUID for idempotent creates (PowerSync offline sync)", "title": "Id" }, "importance": { "default": false, "description": "Whether this event is marked important", "title": "Importance", "type": "boolean" }, "location": { "anyOf": [ { "maxLength": 500, "type": "string" }, { "type": "null" } ], "description": "Event location", "examples": [ "Central Park Soccer Field" ], "title": "Location" }, "metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "Extensible metadata (JSON object)", "title": "Metadata" }, "notify_attendees": { "default": false, "description": "When true, send invites after attendee rows persist. Never implicit; the capture UI must confirm. Noninteractive extract-and-create stays false.", "title": "Notify Attendees", "type": "boolean" }, "override_pending_conflict_card": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Create-on-top: the id of a pending blocked-create conflict card the member has acknowledged ('Conflict's OK' on every entry). The create then lands on the acknowledged overlap; a moved or new collision still refuses. The card must still be pending and this member's own.", "title": "Override Pending Conflict Card" }, "project_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Project to link the new event into (P-). Omitted: the project of the assistant or employee turn creating it, else none. Null: no project.", "title": "Project Id" }, "recurrence_rule": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Recurrence rule in RFC 5545 RRULE format", "examples": [ "FREQ=WEEKLY;BYDAY=MO,WE,FR" ], "title": "Recurrence Rule" }, "source_email": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "description": "Source email address for auto-extracted events", "title": "Source Email" }, "source_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Supabase Storage URL to the original source document", "title": "Source Url" }, "start_time": { "description": "Event start time (ISO 8601 with timezone)", "examples": [ "2024-11-20T15:00:00-05:00" ], "format": "date-time", "title": "Start Time", "type": "string" }, "tags": { "description": "Event tags mapped to note page titles", "items": { "type": "string" }, "title": "Tags", "type": "array" }, "timezone": { "default": "UTC", "description": "Event timezone (IANA timezone identifier)", "examples": [ "America/New_York", "UTC" ], "title": "Timezone", "type": "string" }, "title": { "description": "Event title", "examples": [ "Soccer Practice" ], "maxLength": 500, "minLength": 1, "title": "Title", "type": "string" }, "type": { "anyOf": [ { "maxLength": 50, "type": "string" }, { "type": "null" } ], "description": "Event type/category", "examples": [ "school", "sports", "activity", "medical", "other" ], "title": "Type" }, "visibility": { "anyOf": [ { "enum": [ "private", "shared", "tenant" ], "type": "string" }, { "type": "null" } ], "description": "Per-row visibility. When omitted, an event is private to its owner unless it is created in a shared calendar or a shared project; one in a member's own calendar stays theirs whoever writes it there.", "title": "Visibility" } }, "required": [ "title", "start_time" ], "title": "CalendarEventCreate", "type": "object" }, "CalendarEventId": { "description": "Typed primitive ID for calendar_events (prefix 'V').", "examples": [ "V-550e8400-e29b-41d4-a716-446655440000" ], "pattern": "^V-[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "title": "CalendarEventId", "type": "string", "x-tidy-typed-id-prefix": "V", "x-tidy-typed-id-table": "calendar_events" }, "CalendarEventUpdate": { "description": "Input model for updating calendar events (partial update).", "example": { "description": "Location changed due to field maintenance", "location": "Updated Location - Field B" }, "properties": { "all_day": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "All Day" }, "approval_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Approval Status" }, "base_values": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "Internal-only autosave base values for field conflict detection", "title": "Base Values" }, "collection_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Collection Id" }, "countdown_enabled": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Countdown Enabled" }, "custom_properties": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "Facet field values to merge per-key (a provided key overwrites, null clears the key, unprovided keys survive)", "title": "Custom Properties" }, "description": { "anyOf": [ { "maxLength": 5000, "type": "string" }, { "type": "null" } ], "title": "Description" }, "end_time": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "End Time" }, "facets": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "description": "Facet slugs; replaces the full association array when provided", "title": "Facets" }, "importance": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Importance" }, "location": { "anyOf": [ { "maxLength": 500, "type": "string" }, { "type": "null" } ], "title": "Location" }, "metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Metadata" }, "recurrence_rule": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Recurrence Rule" }, "source_context": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "Internal-only audit/source attribution metadata", "title": "Source Context" }, "start_time": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Start Time" }, "tags": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Tags" }, "timezone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Timezone" }, "title": { "anyOf": [ { "maxLength": 500, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Title" }, "type": { "anyOf": [ { "maxLength": 50, "type": "string" }, { "type": "null" } ], "title": "Type" }, "visibility": { "anyOf": [ { "enum": [ "private", "shared", "tenant" ], "type": "string" }, { "type": "null" } ], "description": "Per-row visibility. Only the row owner may change this.", "title": "Visibility" } }, "title": "CalendarEventUpdate", "type": "object" }, "CalendarExceptionCreate": { "description": "Input model for a single-occurrence exception (TIDY-11427 / R5).\n\n``skip`` drops one occurrence (EXDATE on the parent, no row). ``reschedule``\ndrops the original occurrence AND creates a standalone override event at the\nnew time keyed by ``recurrence_id`` = the original occurrence start.", "properties": { "action": { "description": "'skip' removes the occurrence; 'reschedule' moves it.", "enum": [ "skip", "reschedule" ], "title": "Action", "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Override description for this occurrence.", "title": "Description" }, "location": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Override location for this occurrence.", "title": "Location" }, "new_end": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "New end for a reschedule; derived from parent duration if omitted.", "title": "New End" }, "new_start": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "New start for a reschedule (required-ish for reschedule).", "title": "New Start" }, "occurrence_start": { "description": "The original UTC start of the occurrence being excepted.", "examples": [ "2026-06-09T17:00:00.000Z" ], "format": "date-time", "title": "Occurrence Start", "type": "string" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Override title for this occurrence.", "title": "Title" } }, "required": [ "occurrence_start", "action" ], "title": "CalendarExceptionCreate", "type": "object" }, "CalendarFeedResponse": { "description": "Response for calendar feed URL during onboarding.", "properties": { "feed_url": { "description": "Full ICS feed URL", "title": "Feed Url", "type": "string" }, "include_events": { "default": true, "description": "Feed includes events", "title": "Include Events", "type": "boolean" }, "include_tasks": { "default": false, "description": "Feed includes tasks", "title": "Include Tasks", "type": "boolean" }, "token": { "description": "Feed token", "title": "Token", "type": "string" } }, "required": [ "feed_url", "token" ], "title": "CalendarFeedResponse", "type": "object" }, "CalendarHealthStatus": { "description": "Calendar source health status.", "enum": [ "healthy", "degraded", "disconnected" ], "title": "CalendarHealthStatus", "type": "string" }, "CalendarHealthSummary": { "description": "Aggregated calendar source health counts.", "properties": { "degraded": { "description": "Degraded source count", "title": "Degraded", "type": "integer" }, "disconnected": { "description": "Disconnected source count", "title": "Disconnected", "type": "integer" }, "healthy": { "description": "Healthy source count", "title": "Healthy", "type": "integer" }, "total": { "description": "Total sources in response", "title": "Total", "type": "integer" } }, "required": [ "total", "healthy", "degraded", "disconnected" ], "title": "CalendarHealthSummary", "type": "object" }, "CalendarNotificationBulkApproveResponse": { "description": "Bulk-approve endpoint response payload.", "properties": { "approved": { "title": "Approved", "type": "integer" }, "conflicted": { "default": 0, "title": "Conflicted", "type": "integer" }, "refused": { "default": 0, "title": "Refused", "type": "integer" }, "skipped_by_type": { "additionalProperties": { "type": "integer" }, "title": "Skipped By Type", "type": "object" } }, "required": [ "approved" ], "title": "CalendarNotificationBulkApproveResponse", "type": "object" }, "CalendarNotificationBulkDismissResponse": { "description": "Bulk-dismiss endpoint response payload.", "properties": { "dismissed": { "title": "Dismissed", "type": "integer" } }, "required": [ "dismissed" ], "title": "CalendarNotificationBulkDismissResponse", "type": "object" }, "CalendarNotificationDismissResponse": { "description": "Dismiss endpoint response payload.", "properties": { "actioned_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Actioned At" }, "id": { "title": "Id", "type": "string" }, "read_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Read At" }, "status": { "title": "Status", "type": "string" } }, "required": [ "id", "status" ], "title": "CalendarNotificationDismissResponse", "type": "object" }, "CalendarNotificationListResponse": { "description": "Calendar notifications list response payload.", "properties": { "notifications": { "items": { "$ref": "#/components/schemas/CalendarNotificationResponse" }, "title": "Notifications", "type": "array" }, "total": { "title": "Total", "type": "integer" }, "unread_total": { "title": "Unread Total", "type": "integer" } }, "required": [ "notifications", "total", "unread_total" ], "title": "CalendarNotificationListResponse", "type": "object" }, "CalendarNotificationResponse": { "description": "Calendar notification response payload.", "properties": { "actioned_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Actioned At" }, "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "event_id": { "title": "Event Id", "type": "string" }, "id": { "title": "Id", "type": "string" }, "notification_type": { "title": "Notification Type", "type": "string" }, "payload": { "additionalProperties": true, "title": "Payload", "type": "object" }, "read_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Read At" }, "status": { "title": "Status", "type": "string" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Title" } }, "required": [ "id", "event_id", "notification_type", "status", "created_at" ], "title": "CalendarNotificationResponse", "type": "object" }, "CalendarPeriodComparison": { "properties": { "meeting_hours_change_pct": { "title": "Meeting Hours Change Pct", "type": "number" }, "meetings_change_pct": { "title": "Meetings Change Pct", "type": "number" }, "prev_meeting_hours": { "title": "Prev Meeting Hours", "type": "number" }, "prev_meetings": { "title": "Prev Meetings", "type": "integer" } }, "required": [ "prev_meetings", "prev_meeting_hours", "meetings_change_pct", "meeting_hours_change_pct" ], "title": "CalendarPeriodComparison", "type": "object" }, "CalendarProvider": { "description": "Calendar provider type.", "enum": [ "google", "zoho", "microsoft", "apple", "ics" ], "title": "CalendarProvider", "type": "string" }, "CalendarSelectRequest": { "description": "Toggle calendar selection for sync.", "properties": { "calendar_config_ids": { "description": "Calendar config IDs to toggle", "items": { "type": "string" }, "title": "Calendar Config Ids", "type": "array" }, "is_selected": { "description": "Whether calendars should be selected", "title": "Is Selected", "type": "boolean" } }, "required": [ "calendar_config_ids", "is_selected" ], "title": "CalendarSelectRequest", "type": "object" }, "CalendarSourceConfigPatch": { "description": "Partial update payload for calendar_source_configs.", "properties": { "color": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Hex color (e.g. '#4285F4'). Pass null to clear.", "title": "Color" }, "display_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "User-assigned label. Pass empty string to clear (falls back to provider name).", "title": "Display Name" } }, "title": "CalendarSourceConfigPatch", "type": "object" }, "CalendarSourceConfigResponse": { "description": "A calendar source configuration tied to a provider connection.", "properties": { "calendar_id": { "description": "Provider-specific calendar identifier", "title": "Calendar Id", "type": "string" }, "calendar_name": { "description": "Display name of the calendar", "title": "Calendar Name", "type": "string" }, "color": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Calendar color hex code", "title": "Color" }, "display_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "User-assigned label override (TIDY-8378). NULL falls back to calendar_name.", "title": "Display Name" }, "id": { "description": "Config UUID", "title": "Id", "type": "string" }, "is_selected": { "default": true, "description": "Whether this calendar is selected for sync", "title": "Is Selected", "type": "boolean" }, "provider_connection_id": { "description": "Parent connection UUID", "title": "Provider Connection Id", "type": "string" }, "provider_primary": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "True when the provider reports this as the account's primary calendar (Google primary / Zoho isdefault / Microsoft isDefaultCalendar); NULL means the provider gave no signal.", "title": "Provider Primary" }, "provider_writable": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Provider per-calendar write capability. True/False reflects the provider's accessRole/isWritable/canEdit; NULL means unknown.", "title": "Provider Writable" }, "sync_token": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Opaque sync token", "title": "Sync Token" }, "tenant_id": { "description": "Tenant UUID", "title": "Tenant Id", "type": "string" } }, "required": [ "id", "provider_connection_id", "tenant_id", "calendar_id", "calendar_name" ], "title": "CalendarSourceConfigResponse", "type": "object" }, "CalendarSourceHealthResponse": { "description": "Per-source calendar health details.", "properties": { "calendar_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Connected calendar name", "title": "Calendar Name" }, "email_address": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Calendar account email", "title": "Email Address" }, "failure_count": { "default": 0, "description": "Consecutive failure count", "title": "Failure Count", "type": "integer" }, "failure_level": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Failure taxonomy level", "title": "Failure Level" }, "failure_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Latest failure reason", "title": "Failure Reason" }, "health_status": { "$ref": "#/components/schemas/CalendarHealthStatus", "description": "Computed health status" }, "last_error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Last sync error from source", "title": "Last Error" }, "last_failure_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "description": "Last failure timestamp", "title": "Last Failure At" }, "last_successful_sync_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "description": "Last successful sync timestamp", "title": "Last Successful Sync At" }, "last_sync_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "description": "Last source sync timestamp", "title": "Last Sync At" }, "next_retry_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "description": "Next retry schedule", "title": "Next Retry At" }, "provider": { "$ref": "#/components/schemas/CalendarProvider", "description": "Calendar provider" }, "source_id": { "description": "Calendar source ID", "title": "Source Id", "type": "string" }, "source_status": { "$ref": "#/components/schemas/CalendarSourceStatus", "description": "Source status from calendar_sources" } }, "required": [ "source_id", "provider", "source_status", "health_status" ], "title": "CalendarSourceHealthResponse", "type": "object" }, "CalendarSourceStatus": { "description": "Calendar source connection status.", "enum": [ "pending_auth", "pending_selection", "active", "needs_reauth", "error", "disconnected" ], "title": "CalendarSourceStatus", "type": "string" }, "CalendarSourcesHealthListResponse": { "description": "Response model for listing calendar source health.", "properties": { "checked_at": { "description": "Health check timestamp", "format": "date-time", "title": "Checked At", "type": "string" }, "sources": { "description": "Source health entries", "items": { "$ref": "#/components/schemas/CalendarSourceHealthResponse" }, "title": "Sources", "type": "array" }, "summary": { "$ref": "#/components/schemas/CalendarHealthSummary", "description": "Health summary counts" } }, "required": [ "sources", "summary", "checked_at" ], "title": "CalendarSourcesHealthListResponse", "type": "object" }, "CalendarSubscription": { "description": "Complete calendar subscription object (response).", "properties": { "access_count": { "title": "Access Count", "type": "integer" }, "account_id": { "title": "Account Id", "type": "string" }, "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "deleted_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Deleted At" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "filter_settings": { "additionalProperties": true, "title": "Filter Settings", "type": "object" }, "ical_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Full iCalendar subscription URL (computed)", "title": "Ical Url" }, "id": { "title": "Id", "type": "string" }, "is_active": { "title": "Is Active", "type": "boolean" }, "last_accessed_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Last Accessed At" }, "name": { "title": "Name", "type": "string" }, "subscription_token": { "description": "Unique token for iCal feed URL", "title": "Subscription Token", "type": "string" }, "tenant_id": { "title": "Tenant Id", "type": "string" } }, "required": [ "id", "tenant_id", "account_id", "subscription_token", "name", "description", "filter_settings", "is_active", "last_accessed_at", "access_count", "created_at", "deleted_at" ], "title": "CalendarSubscription", "type": "object" }, "CalendarSubscriptionCreate": { "description": "Input model for creating calendar subscriptions.", "example": { "description": "All soccer-related events", "filter_settings": { "event_types": [ "sports" ], "location_contains": "Soccer" }, "name": "Soccer Events" }, "properties": { "description": { "anyOf": [ { "maxLength": 1000, "type": "string" }, { "type": "null" } ], "description": "Subscription description", "title": "Description" }, "filter_settings": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "Event filter settings (types, sources, etc.)", "examples": [ { "event_types": [ "sports", "school" ] }, { "location_contains": "Soccer" } ], "title": "Filter Settings" }, "name": { "description": "Subscription name", "examples": [ "All Events", "Soccer Events Only" ], "maxLength": 255, "minLength": 1, "title": "Name", "type": "string" } }, "required": [ "name" ], "title": "CalendarSubscriptionCreate", "type": "object" }, "CalendarSubscriptionUpdate": { "description": "Input model for updating calendar subscriptions.", "properties": { "description": { "anyOf": [ { "maxLength": 1000, "type": "string" }, { "type": "null" } ], "title": "Description" }, "filter_settings": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Filter Settings" }, "is_active": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is Active" }, "name": { "anyOf": [ { "maxLength": 255, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Name" } }, "title": "CalendarSubscriptionUpdate", "type": "object" }, "CalendarSummaryResponse": { "properties": { "avg_attendees": { "title": "Avg Attendees", "type": "number" }, "avg_meeting_duration_minutes": { "title": "Avg Meeting Duration Minutes", "type": "integer" }, "busiest_day": { "title": "Busiest Day", "type": "string" }, "focus_hours_available": { "title": "Focus Hours Available", "type": "number" }, "focus_hours_pct": { "title": "Focus Hours Pct", "type": "number" }, "period_comparison": { "$ref": "#/components/schemas/CalendarPeriodComparison" }, "recurring_meeting_pct": { "title": "Recurring Meeting Pct", "type": "number" }, "total_meeting_hours": { "title": "Total Meeting Hours", "type": "number" }, "total_meetings": { "title": "Total Meetings", "type": "integer" } }, "required": [ "total_meetings", "total_meeting_hours", "avg_meeting_duration_minutes", "recurring_meeting_pct", "focus_hours_available", "focus_hours_pct", "busiest_day", "avg_attendees", "period_comparison" ], "title": "CalendarSummaryResponse", "type": "object" }, "CalendarVolumePeriod": { "properties": { "by_size": { "$ref": "#/components/schemas/SizeBreakdown" }, "focus_hours": { "title": "Focus Hours", "type": "number" }, "meeting_hours": { "title": "Meeting Hours", "type": "number" }, "meetings": { "title": "Meetings", "type": "integer" }, "period": { "title": "Period", "type": "string" } }, "required": [ "period", "meetings", "meeting_hours", "focus_hours", "by_size" ], "title": "CalendarVolumePeriod", "type": "object" }, "CampaignActionResponse": { "properties": { "campaign_id": { "title": "Campaign Id", "type": "string" }, "detail": { "default": "", "title": "Detail", "type": "string" }, "status": { "title": "Status", "type": "string" } }, "required": [ "campaign_id", "status" ], "title": "CampaignActionResponse", "type": "object" }, "CampaignDocRequest": { "properties": { "doc": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Doc" }, "note_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Note Id" } }, "title": "CampaignDocRequest", "type": "object" }, "CampaignSettingsBody": { "properties": { "postal_address": { "default": "", "description": "Physical postal address auto-injected into the campaign compliance footer (CAN-SPAM). Multiline text.", "maxLength": 1000, "title": "Postal Address", "type": "string" }, "unsubscribe_page_copy": { "default": "", "description": "Confirmation copy shown on the public unsubscribe landing page.", "maxLength": 4000, "title": "Unsubscribe Page Copy", "type": "string" }, "utm_defaults": { "additionalProperties": { "type": "string" }, "description": "Default UTM parameters the renderer appends to links in campaign emails (utm_source/utm_medium/utm_campaign/utm_term/utm_content).", "title": "Utm Defaults", "type": "object" } }, "title": "CampaignSettingsBody", "type": "object" }, "CampaignSettingsResponse": { "properties": { "postal_address": { "default": "", "title": "Postal Address", "type": "string" }, "unsubscribe_page_copy": { "default": "", "title": "Unsubscribe Page Copy", "type": "string" }, "utm_defaults": { "additionalProperties": { "type": "string" }, "title": "Utm Defaults", "type": "object" } }, "title": "CampaignSettingsResponse", "type": "object" }, "CampaignTestRenderRequest": { "properties": { "doc": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Doc" }, "note_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Note Id" }, "recipient_contact_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Sample recipient contact; omitted → a synthetic sample bag.", "title": "Recipient Contact Id" } }, "title": "CampaignTestRenderRequest", "type": "object" }, "CampaignTestRenderResponse": { "properties": { "html": { "title": "Html", "type": "string" }, "missing_fields": { "items": { "type": "string" }, "title": "Missing Fields", "type": "array" }, "plain_text": { "title": "Plain Text", "type": "string" }, "warnings": { "items": { "type": "string" }, "title": "Warnings", "type": "array" } }, "required": [ "html", "plain_text", "missing_fields", "warnings" ], "title": "CampaignTestRenderResponse", "type": "object" }, "CampaignValidateResponse": { "properties": { "rejections": { "items": { "$ref": "#/components/schemas/BlockRejectionModel" }, "title": "Rejections", "type": "array" }, "valid": { "title": "Valid", "type": "boolean" } }, "required": [ "valid", "rejections" ], "title": "CampaignValidateResponse", "type": "object" }, "CancelDeletionResponse": { "description": "Response for cancelling a pending deletion.", "properties": { "message": { "title": "Message", "type": "string" }, "status": { "title": "Status", "type": "string" } }, "required": [ "status", "message" ], "title": "CancelDeletionResponse", "type": "object" }, "CancelScheduledSubscriptionResponse": { "properties": { "cancel_at_period_end": { "title": "Cancel At Period End", "type": "boolean" } }, "required": [ "cancel_at_period_end" ], "title": "CancelScheduledSubscriptionResponse", "type": "object" }, "CandidateGrantRequest": { "properties": { "candidate_id": { "title": "Candidate Id", "type": "string" }, "paths_sha256": { "additionalProperties": { "type": "string" }, "maxProperties": 128, "minProperties": 1, "title": "Paths Sha256", "type": "object" } }, "required": [ "candidate_id", "paths_sha256" ], "title": "CandidateGrantRequest", "type": "object" }, "CandidateGrantResponse": { "properties": { "expires_at": { "format": "date-time", "title": "Expires At", "type": "string" }, "jti": { "format": "uuid", "title": "Jti", "type": "string" }, "token": { "title": "Token", "type": "string" } }, "required": [ "token", "expires_at", "jti" ], "title": "CandidateGrantResponse", "type": "object" }, "CanonicalDocInfo": { "properties": { "consolidated_markdown": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Consolidated Markdown" }, "created_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Created At" }, "filename": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Filename" }, "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Id" }, "md5_hash": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Md5 Hash" }, "source_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Source Type" } }, "title": "CanonicalDocInfo", "type": "object" }, "CapabilityHolder": { "properties": { "account_id": { "title": "Account Id", "type": "string" }, "display_name": { "title": "Display Name", "type": "string" }, "role": { "title": "Role", "type": "string" } }, "required": [ "account_id", "display_name", "role" ], "title": "CapabilityHolder", "type": "object" }, "CapabilityMatrixEntry": { "properties": { "capability": { "title": "Capability", "type": "string" }, "holders": { "default": [], "items": { "$ref": "#/components/schemas/CapabilityHolder" }, "title": "Holders", "type": "array" }, "is_admin_capability": { "title": "Is Admin Capability", "type": "boolean" }, "roles": { "items": { "type": "string" }, "title": "Roles", "type": "array" } }, "required": [ "capability", "roles", "is_admin_capability" ], "title": "CapabilityMatrixEntry", "type": "object" }, "CapabilityMutationResponse": { "properties": { "changed": { "title": "Changed", "type": "boolean" }, "ok": { "title": "Ok", "type": "boolean" } }, "required": [ "ok", "changed" ], "title": "CapabilityMutationResponse", "type": "object" }, "CapabilityPageInfo": { "description": "Bounded-response cursor for the one tenant-sized section (facets).", "properties": { "limit": { "title": "Limit", "type": "integer" }, "next_offset": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Next Offset" }, "offset": { "title": "Offset", "type": "integer" }, "returned": { "title": "Returned", "type": "integer" }, "total": { "title": "Total", "type": "integer" } }, "required": [ "total", "offset", "limit", "returned" ], "title": "CapabilityPageInfo", "type": "object" }, "CapabilityRequestItem": { "properties": { "capability": { "title": "Capability", "type": "string" }, "request_id": { "title": "Request Id", "type": "string" }, "requested_at": { "title": "Requested At", "type": "string" }, "status": { "title": "Status", "type": "string" }, "user_display_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "User Display Name" }, "user_email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "User Email" }, "user_id": { "title": "User Id", "type": "string" } }, "required": [ "request_id", "user_id", "capability", "status", "requested_at" ], "title": "CapabilityRequestItem", "type": "object" }, "CaptureLeadRequest": { "properties": { "email": { "title": "Email", "type": "string" }, "first_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "First Name" }, "invite_code_attempted": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Invite Code Attempted" }, "source": { "default": "organic", "title": "Source", "type": "string" } }, "required": [ "email" ], "title": "CaptureLeadRequest", "type": "object" }, "CaptureRequest": { "properties": { "consent": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "EXPLICIT consent flag (TIDY-14683 / R13). Accepted only on target_table='contacts'; a records capture carrying it is a 422.", "title": "Consent" }, "facet_slug": { "description": "The facet the captured row carries.", "title": "Facet Slug", "type": "string" }, "idempotency_key": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Your own event id. When present it IS the replay key (unique per tenant) and a re-POST is a no-op regardless of timing.", "title": "Idempotency Key" }, "match_field": { "description": "Field the upsert matches on. Must be a field the facet declares; on target_table='contacts' it must be 'email'.", "title": "Match Field", "type": "string" }, "raw_payload": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "Full original submission — unknown fields preserved verbatim.", "title": "CaptureRawPayload" }, "source": { "default": "", "description": "Capture source label. Free-form by design.", "title": "Source", "type": "string" }, "submitted_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "Submission timestamp (tz-aware ISO 8601). REQUIRED when no idempotency_key is given — it is part of the replay key, and a server-side default would make a re-delivery undetectable.", "title": "Submitted At" }, "target_table": { "default": "records", "description": "Primitive the facet extends. 'records' is the generic primitive; 'contacts' additionally applies the lead identity-key routing and the consent contract.", "enum": [ "contacts", "records" ], "title": "Target Table", "type": "string" }, "utm": { "additionalProperties": true, "description": "UTM parameters. On contacts: first-touch write-once, last-touch always updated. On records: written as ordinary facet fields where the facet declares matching keys, else ignored.", "title": "CaptureUtm", "type": "object" }, "values": { "additionalProperties": true, "description": "Field values to write, including the match field. Empty strings are treated as absent so a blank input never clobbers a stored value.", "title": "CaptureValues", "type": "object" }, "webhook_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The Custom webhook plugin whose event delivered this capture — recorded on the capture receipt.", "title": "Webhook Id" } }, "required": [ "facet_slug", "match_field" ], "title": "CaptureRequest", "type": "object" }, "CaptureResponse": { "properties": { "facet_slug": { "title": "Facet Slug", "type": "string" }, "outcome": { "enum": [ "created", "updated", "replay" ], "title": "Outcome", "type": "string" }, "target_id": { "description": "The row the capture created or updated.", "title": "Target Id", "type": "string" }, "target_table": { "title": "Target Table", "type": "string" } }, "required": [ "target_id", "target_table", "outcome", "facet_slug" ], "title": "CaptureResponse", "type": "object" }, "CardDAVAddressBookStatus": { "properties": { "contact_count": { "default": 0, "title": "Contact Count", "type": "integer" }, "last_error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Last Error" }, "last_sync_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Last Sync At" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Name" }, "url": { "title": "Url", "type": "string" } }, "required": [ "url" ], "title": "CardDAVAddressBookStatus", "type": "object" }, "CardDAVAddressBookSummary": { "properties": { "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name" }, "url": { "title": "Url", "type": "string" } }, "required": [ "url" ], "title": "CardDAVAddressBookSummary", "type": "object" }, "CardDAVBatchSyncRequest": { "description": "Optional filter for the batch-sync endpoint.", "properties": { "provider_connection_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Sync only this connection. If omitted, syncs all active CardDAV-capable connections for the tenant.", "title": "Provider Connection Id" } }, "title": "CardDAVBatchSyncRequest", "type": "object" }, "CardDAVConnectionSyncResult": { "properties": { "created": { "default": 0, "title": "Created", "type": "integer" }, "errors": { "items": { "type": "string" }, "title": "Errors", "type": "array" }, "merged": { "default": 0, "title": "Merged", "type": "integer" }, "provider_connection_id": { "title": "Provider Connection Id", "type": "string" }, "skipped": { "default": 0, "title": "Skipped", "type": "integer" }, "success": { "title": "Success", "type": "boolean" }, "total_fetched": { "default": 0, "title": "Total Fetched", "type": "integer" } }, "required": [ "provider_connection_id", "success" ], "title": "CardDAVConnectionSyncResult", "type": "object" }, "CardDAVCredentialsRequest": { "properties": { "app_password": { "description": "CardDAV-scoped app password", "title": "App Password", "type": "string" }, "carddav_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional CardDAV server URL override", "title": "Carddav Url" } }, "required": [ "app_password" ], "title": "CardDAVCredentialsRequest", "type": "object" }, "CardDAVCredentialsResponse": { "properties": { "success": { "title": "Success", "type": "boolean" } }, "required": [ "success" ], "title": "CardDAVCredentialsResponse", "type": "object" }, "CardDAVStatusResponse": { "properties": { "address_books": { "items": { "$ref": "#/components/schemas/CardDAVAddressBookStatus" }, "title": "Address Books", "type": "array" } }, "title": "CardDAVStatusResponse", "type": "object" }, "CardDAVSyncResponse": { "properties": { "created": { "default": 0, "title": "Created", "type": "integer" }, "errors": { "items": { "type": "string" }, "title": "Errors", "type": "array" }, "merged": { "default": 0, "title": "Merged", "type": "integer" }, "provider_connection_id": { "title": "Provider Connection Id", "type": "string" }, "skipped": { "default": 0, "title": "Skipped", "type": "integer" }, "success": { "title": "Success", "type": "boolean" }, "total_fetched": { "default": 0, "title": "Total Fetched", "type": "integer" } }, "required": [ "success", "provider_connection_id" ], "title": "CardDAVSyncResponse", "type": "object" }, "CardDAVTestRequest": { "properties": { "carddav_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Override CardDAV base URL", "title": "Carddav Url" }, "password": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Override app password", "title": "Password" } }, "title": "CardDAVTestRequest", "type": "object" }, "CardDAVTestResponse": { "properties": { "address_books": { "items": { "$ref": "#/components/schemas/CardDAVAddressBookSummary" }, "title": "Address Books", "type": "array" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error" }, "success": { "title": "Success", "type": "boolean" } }, "required": [ "success" ], "title": "CardDAVTestResponse", "type": "object" }, "CardDetailResponse": { "description": "Detailed card information for modal/detail views.\n\nReturns full content (not truncated) and any additional metadata\nthat might be useful for display in a detail modal.\n\nAttributes:\n card: The full feed card with complete content\n relatedCards: Optional list of related feed cards", "properties": { "card": { "$ref": "#/components/schemas/FeedCard", "description": "The feed card with full content (body not truncated)" }, "relatedCards": { "description": "Related cards (same source, category, or tags)", "items": { "$ref": "#/components/schemas/FeedCard" }, "title": "Relatedcards", "type": "array" } }, "required": [ "card" ], "title": "CardDetailResponse", "type": "object" }, "CatalogSource": { "description": "TIDY-19616 — another plugin in the set, delivered to a health check so\nthe workshop can list its models. ``unavailable`` says why it could not be.", "properties": { "credentials": { "items": { "$ref": "#/components/schemas/MaterializedCredential" }, "title": "Credentials", "type": "array" }, "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Label" }, "namespace": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Namespace" }, "unavailable": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Unavailable" } }, "title": "CatalogSource", "type": "object" }, "CatalogueVoice": { "properties": { "description": { "title": "Description", "type": "string" }, "gender": { "enum": [ "male", "female", "neutral" ], "title": "Gender", "type": "string" }, "id": { "title": "Id", "type": "string" }, "name": { "title": "Name", "type": "string" } }, "required": [ "id", "name", "gender", "description" ], "title": "CatalogueVoice", "type": "object" }, "CategoryCount": { "properties": { "count": { "title": "Count", "type": "integer" }, "name": { "title": "Name", "type": "string" } }, "required": [ "name", "count" ], "title": "CategoryCount", "type": "object" }, "CategoryUsage": { "properties": { "action_name": { "title": "Action Name", "type": "string" }, "credits_per_action": { "title": "Credits Per Action", "type": "number" }, "credits_used": { "title": "Credits Used", "type": "number" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" } }, "required": [ "action_name", "credits_per_action", "credits_used" ], "title": "CategoryUsage", "type": "object" }, "ChainAction": { "additionalProperties": false, "description": "One automation verb + params in an action chain (TIDY-14797 / D11).\n\nThe chain vocabulary mirrors the automation rule action shape 1:1\n(``mutate_property`` / ``archive`` / ``delete``). Shared by the authored\n``automation_chain`` descriptor and the invoke-wire ``chain`` payload.", "properties": { "params": { "additionalProperties": true, "title": "Chain Action Params", "type": "object" }, "verb": { "maxLength": 128, "minLength": 1, "title": "Verb", "type": "string" }, "when": { "anyOf": [ { "$ref": "#/components/schemas/ConditionGroup" }, { "type": "null" } ] } }, "required": [ "verb" ], "title": "ChainAction", "type": "object" }, "ChallengeRequest": { "properties": { "action": { "maxLength": 100, "minLength": 1, "title": "Action", "type": "string" }, "intent_handle": { "anyOf": [ { "maxLength": 128, "minLength": 1, "type": "string" }, { "type": "null" } ], "description": "Opaque, single-use handle from the action's step_up_required refusal. Required for request-bound actions; never send the approved values here.", "title": "Intent Handle" } }, "required": [ "action" ], "title": "ChallengeRequest", "type": "object" }, "ChallengeResponse": { "properties": { "challenge_id": { "format": "uuid", "title": "Challenge Id", "type": "string" }, "expires_at": { "format": "date-time", "title": "Expires At", "type": "string" }, "factors": { "items": { "enum": [ "password", "provider", "email_otp", "totp", "passkey" ], "type": "string" }, "title": "Factors", "type": "array" }, "providers": { "items": { "type": "string" }, "title": "Providers", "type": "array" } }, "required": [ "challenge_id", "factors", "providers", "expires_at" ], "title": "ChallengeResponse", "type": "object" }, "ChangePasswordRequest": { "description": "Request model for password change.", "properties": { "current_password": { "description": "Current password", "minLength": 8, "title": "Current Password", "type": "string" }, "new_password": { "description": "New password (min 8 chars)", "minLength": 8, "title": "New Password", "type": "string" } }, "required": [ "current_password", "new_password" ], "title": "ChangePasswordRequest", "type": "object" }, "ChangePasswordResponse": { "description": "Response model for password change.", "properties": { "message": { "title": "Message", "type": "string" }, "success": { "title": "Success", "type": "boolean" } }, "required": [ "success", "message" ], "title": "ChangePasswordResponse", "type": "object" }, "ChangePlanResponse": { "properties": { "billing_interval": { "title": "Billing Interval", "type": "string" }, "plan_id": { "title": "Plan Id", "type": "string" }, "price_cents": { "title": "Price Cents", "type": "integer" }, "status": { "title": "Status", "type": "string" }, "subscription_id": { "title": "Subscription Id", "type": "string" }, "takes_effect_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Takes Effect At" } }, "required": [ "subscription_id", "status", "plan_id", "billing_interval", "price_cents" ], "title": "ChangePlanResponse", "type": "object" }, "ChannelCanvasResponse": { "properties": { "canvas_note_id": { "title": "Canvas Note Id", "type": "string" }, "note_type": { "title": "Note Type", "type": "string" }, "room_id": { "title": "Room Id", "type": "string" }, "seeded": { "default": false, "title": "Seeded", "type": "boolean" } }, "required": [ "room_id", "canvas_note_id", "note_type" ], "title": "ChannelCanvasResponse", "type": "object" }, "ChannelHandoffRequest": { "properties": { "agent_account_id": { "title": "Agent Account Id", "type": "string" }, "tenant_id": { "title": "Tenant Id", "type": "string" } }, "required": [ "tenant_id", "agent_account_id" ], "title": "ChannelHandoffRequest", "type": "object" }, "ChannelHandoffResponse": { "properties": { "context": { "default": 0, "title": "Context", "type": "integer" }, "executable": { "default": 0, "title": "Executable", "type": "integer" } }, "title": "ChannelHandoffResponse", "type": "object" }, "ChannelHealth": { "properties": { "channel": { "description": "sms | email", "title": "Channel", "type": "string" }, "detail": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Detail" }, "detected_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Detected At" }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "hard_bounce | complaint | send_failed", "title": "Reason" }, "status": { "description": "healthy | unhealthy", "title": "Status", "type": "string" } }, "required": [ "channel", "status" ], "title": "ChannelHealth", "type": "object" }, "ChannelHealthResponse": { "properties": { "channels": { "items": { "$ref": "#/components/schemas/ChannelHealth" }, "title": "Channels", "type": "array" } }, "required": [ "channels" ], "title": "ChannelHealthResponse", "type": "object" }, "ChannelIngressRequest": { "properties": { "account_id": { "description": "The member the turn runs as.", "title": "Account Id", "type": "string" }, "body": { "maxLength": 10000, "minLength": 1, "title": "Body", "type": "string" }, "channel": { "enum": [ "sms", "web", "android", "whatsapp" ], "title": "Channel", "type": "string" }, "idempotency_key": { "description": "Provider message id (SMS) or client nonce (web/Android).", "maxLength": 200, "minLength": 1, "title": "Idempotency Key", "type": "string" }, "owner_account_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Routing owner: null for a tenant-shared channel. Omitted by legacy personal-channel adapters, which use account_id as the phone owner.", "title": "Owner Account Id" }, "sender_account_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Sender Account Id" }, "sender_ref": { "maxLength": 200, "minLength": 1, "title": "Sender Ref", "type": "string" }, "tenant_id": { "description": "Tenant UUID the message belongs to.", "title": "Tenant Id", "type": "string" } }, "required": [ "tenant_id", "account_id", "channel", "idempotency_key", "sender_ref", "body" ], "title": "ChannelIngressRequest", "type": "object" }, "ChannelIngressResponse": { "properties": { "deferred": { "default": false, "title": "Deferred", "type": "boolean" }, "duplicate": { "default": false, "title": "Duplicate", "type": "boolean" }, "employee_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Employee Id" }, "employee_kind": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Employee Kind" }, "employee_label": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Employee Label" }, "item_id": { "title": "Item Id", "type": "string" }, "outcome": { "title": "Outcome", "type": "string" }, "reply_text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Reply Text" }, "state": { "title": "State", "type": "string" } }, "required": [ "item_id", "state", "outcome" ], "title": "ChannelIngressResponse", "type": "object" }, "ChannelMemberRemovedResponse": { "properties": { "ok": { "default": true, "title": "Ok", "type": "boolean" }, "pending": { "default": false, "title": "Pending", "type": "boolean" } }, "title": "ChannelMemberRemovedResponse", "type": "object" }, "ChannelPatchRequest": { "properties": { "archived": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Archived" }, "description": { "anyOf": [ { "maxLength": 2000, "type": "string" }, { "type": "null" } ], "title": "Description" }, "name": { "anyOf": [ { "maxLength": 120, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Name" }, "topic": { "anyOf": [ { "maxLength": 500, "type": "string" }, { "type": "null" } ], "title": "Topic" }, "visibility": { "anyOf": [ { "enum": [ "public_in_workspace", "private", "restricted" ], "type": "string" }, { "type": "null" } ], "title": "Visibility" } }, "title": "ChannelPatchRequest", "type": "object" }, "ChannelPickupSetting": { "properties": { "channel": { "title": "Channel", "type": "string" }, "default_available": { "default": false, "title": "Default Available", "type": "boolean" }, "default_employee_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Default Employee Id" }, "default_employee_kind": { "title": "Default Employee Kind", "type": "string" }, "default_employee_label": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Default Employee Label" }, "failover_employee_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Failover Employee Id" }, "failover_employee_kind": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Failover Employee Kind" }, "failover_employee_label": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Failover Employee Label" }, "failover_fallback": { "title": "Failover Fallback", "type": "string" }, "is_default": { "default": true, "title": "Is Default", "type": "boolean" }, "offline_policy": { "title": "Offline Policy", "type": "string" }, "supported": { "title": "Supported", "type": "boolean" }, "unsupported_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Unsupported Reason" } }, "required": [ "channel", "default_employee_kind", "offline_policy", "failover_fallback", "supported" ], "title": "ChannelPickupSetting", "type": "object" }, "ChannelPickupSettings": { "properties": { "channels": { "items": { "$ref": "#/components/schemas/ChannelPickupSetting" }, "title": "Channels", "type": "array" } }, "title": "ChannelPickupSettings", "type": "object" }, "ChannelPickupUpdate": { "properties": { "ack_message": { "anyOf": [ { "maxLength": 600, "type": "string" }, { "type": "null" } ], "title": "Ack Message" }, "bounce_message": { "anyOf": [ { "maxLength": 600, "type": "string" }, { "type": "null" } ], "title": "Bounce Message" }, "default_employee_id": { "title": "Default Employee Id", "type": "string" }, "default_employee_kind": { "default": "hosted", "enum": [ "hosted", "workshop" ], "title": "Default Employee Kind", "type": "string" }, "failover_employee_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Failover Employee Id" }, "failover_employee_kind": { "anyOf": [ { "enum": [ "hosted", "workshop" ], "type": "string" }, { "type": "null" } ], "title": "Failover Employee Kind" }, "failover_fallback": { "default": "queue", "enum": [ "queue", "bounce" ], "title": "Failover Fallback", "type": "string" }, "offline_policy": { "default": "queue", "enum": [ "failover", "queue", "bounce" ], "title": "Offline Policy", "type": "string" } }, "required": [ "default_employee_id" ], "title": "ChannelPickupUpdate", "type": "object" }, "ChannelReplyRequest": { "properties": { "conversation_id": { "description": "The conversation the pickup wake opened.", "title": "Conversation Id", "type": "string" }, "reply_message_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Reply Message Id" }, "reply_text": { "maxLength": 10000, "minLength": 1, "title": "Reply Text", "type": "string" } }, "required": [ "conversation_id", "reply_text" ], "title": "ChannelReplyRequest", "type": "object" }, "ChannelReplyResponse": { "properties": { "claimed": { "title": "Claimed", "type": "boolean" }, "item_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Item Id" }, "state": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "State" } }, "required": [ "claimed" ], "title": "ChannelReplyResponse", "type": "object" }, "ChannelResult": { "properties": { "name": { "title": "Name", "type": "string" }, "room_id": { "title": "Room Id", "type": "string" }, "score": { "title": "Score", "type": "number" }, "visibility": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Visibility" } }, "required": [ "room_id", "name", "visibility", "score" ], "title": "ChannelResult", "type": "object" }, "ChannelTemplateTab": { "additionalProperties": true, "description": "One configured tab in a channel template's payload (S12).\n\nKept structurally compatible with the S5 workspace-template vocabulary: a\ndoc/embedded_facets tab is a note page (``body_markdown`` + ``facet_refs``);\na database_view tab is a room-scoped database view (``view_config``).", "properties": { "body_markdown": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Body Markdown" }, "facet_refs": { "items": { "type": "string" }, "title": "Facet Refs", "type": "array" }, "kind": { "default": "doc", "enum": [ "doc", "database_view", "drawing", "embedded_facets" ], "title": "Kind", "type": "string" }, "title": { "maxLength": 200, "minLength": 1, "title": "Title", "type": "string" }, "view_config": { "additionalProperties": true, "title": "View Config", "type": "object" } }, "required": [ "title" ], "title": "ChannelTemplateTab", "type": "object" }, "ChartCapabilities": { "description": "Chart kinds, aggregate vocabulary, and the field compatibility rules an\nagent needs to pick a legal (kind, dimension, measure) triple.", "properties": { "config_path": { "default": "", "title": "Config Path", "type": "string" }, "date_field_types": { "items": { "type": "string" }, "title": "Date Field Types", "type": "array" }, "dimension_field_types": { "default": "any", "title": "Dimension Field Types" }, "kinds": { "items": { "$ref": "#/components/schemas/ChartKindCapability" }, "title": "Kinds", "type": "array" }, "measures": { "items": { "$ref": "#/components/schemas/ChartMeasureCapability" }, "title": "Measures", "type": "array" }, "numeric_field_types": { "items": { "type": "string" }, "title": "Numeric Field Types", "type": "array" }, "ratio_formats": { "items": { "type": "string" }, "title": "Ratio Formats", "type": "array" }, "time_buckets": { "items": { "type": "string" }, "title": "Time Buckets", "type": "array" } }, "required": [ "kinds", "measures", "time_buckets" ], "title": "ChartCapabilities", "type": "object" }, "ChartKindCapability": { "properties": { "dimension": { "enum": [ "required", "optional", "unused" ], "title": "Dimension", "type": "string" }, "kind": { "title": "Kind", "type": "string" }, "label": { "title": "Label", "type": "string" }, "measure": { "enum": [ "required", "optional", "unused" ], "title": "Measure", "type": "string" }, "notes": { "default": "", "title": "Notes", "type": "string" }, "requires_ratio": { "title": "Requires Ratio", "type": "boolean" }, "supports_time_bucket": { "title": "Supports Time Bucket", "type": "boolean" } }, "required": [ "kind", "label", "dimension", "measure", "supports_time_bucket", "requires_ratio" ], "title": "ChartKindCapability", "type": "object" }, "ChartMeasureCapability": { "properties": { "field_required": { "title": "Field Required", "type": "boolean" }, "field_types": { "title": "Field Types" }, "fn": { "title": "Fn", "type": "string" }, "label": { "title": "Label", "type": "string" }, "notes": { "default": "", "title": "Notes", "type": "string" } }, "required": [ "fn", "label", "field_required", "field_types" ], "title": "ChartMeasureCapability", "type": "object" }, "ChatAuditEntryResponse": { "properties": { "action": { "title": "Action", "type": "string" }, "actor_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "default": null, "title": "Actor Id" }, "actor_type": { "title": "Actor Type", "type": "string" }, "args_hash": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Args Hash" }, "entry_hash": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Entry Hash" }, "error_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Error Code" }, "id": { "format": "uuid", "title": "Id", "type": "string" }, "outcome": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Outcome" }, "payload_summary": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "title": "Payload Summary" }, "prev_hash": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Prev Hash" }, "resource_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Resource Id" }, "resource_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Resource Type" }, "seq": { "title": "Seq", "type": "integer" }, "severity": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Severity" }, "tenant_id": { "format": "uuid", "title": "Tenant Id", "type": "string" }, "timestamp": { "format": "date-time", "title": "Timestamp", "type": "string" } }, "required": [ "id", "seq", "timestamp", "tenant_id", "actor_type", "action" ], "title": "ChatAuditEntryResponse", "type": "object" }, "ChatAuditListResponse": { "properties": { "items": { "items": { "$ref": "#/components/schemas/ChatAuditEntryResponse" }, "title": "Items", "type": "array" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Next Cursor" } }, "required": [ "items" ], "title": "ChatAuditListResponse", "type": "object" }, "ChatExportJobResponse": { "properties": { "archive_size_bytes": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Archive Size Bytes" }, "completed_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Completed At" }, "embed_count": { "title": "Embed Count", "type": "integer" }, "error_message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Error Message" }, "expires_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Expires At" }, "id": { "title": "Id", "type": "string" }, "message_count": { "title": "Message Count", "type": "integer" }, "requested_at": { "format": "date-time", "title": "Requested At", "type": "string" }, "room_id": { "title": "Room Id", "type": "string" }, "room_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Room Name" }, "since": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Since" }, "started_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Started At" }, "status": { "title": "Status", "type": "string" }, "tenant_id": { "title": "Tenant Id", "type": "string" }, "until": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Until" } }, "required": [ "id", "tenant_id", "room_id", "status", "message_count", "embed_count", "requested_at" ], "title": "ChatExportJobResponse", "type": "object" }, "ChatExportRequest": { "properties": { "room_id": { "maxLength": 255, "minLength": 1, "title": "Room Id", "type": "string" }, "since": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Since" }, "until": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Until" } }, "required": [ "room_id" ], "title": "ChatExportRequest", "type": "object" }, "ChatHistoryResponse": { "properties": { "conversation_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Conversation Id" }, "messages": { "items": { "$ref": "#/components/schemas/ChatMessageResponse" }, "title": "Messages", "type": "array" } }, "required": [ "messages" ], "title": "ChatHistoryResponse", "type": "object" }, "ChatKeywordRequest": { "description": "Request body for ``POST /api/v1/notifications/chat-keyword``.", "properties": { "author_display_name": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "title": "Author Display Name" }, "event_id": { "maxLength": 255, "minLength": 1, "title": "Event Id", "type": "string" }, "matched_keyword": { "maxLength": 100, "minLength": 1, "title": "Matched Keyword", "type": "string" }, "room_id": { "maxLength": 255, "minLength": 1, "title": "Room Id", "type": "string" }, "snippet": { "anyOf": [ { "maxLength": 1000, "type": "string" }, { "type": "null" } ], "title": "Snippet" } }, "required": [ "room_id", "event_id", "matched_keyword" ], "title": "ChatKeywordRequest", "type": "object" }, "ChatMentionRequest": { "description": "Request body for ``POST /api/v1/notifications/chat-mention``.\n\nThe frontend matrix highlight bridge posts one of these per highlight\nevent the matrix-js-sdk fires for the current user. The server\nvalidates that the caller's account has a linked Matrix MXID, then\nUPSERTs one ``user_notifications`` row keyed on\n``metadata.dedupe_key = \"chat:{event_id}\"``.\n\nRelated: TIDY-10166 (S6 of TIDY-6128)", "properties": { "author_display_name": { "maxLength": 255, "minLength": 1, "title": "Author Display Name", "type": "string" }, "event_id": { "maxLength": 255, "minLength": 1, "title": "Event Id", "type": "string" }, "room_id": { "maxLength": 255, "minLength": 1, "title": "Room Id", "type": "string" }, "room_name": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "title": "Room Name" }, "snippet": { "anyOf": [ { "maxLength": 1000, "type": "string" }, { "type": "null" } ], "title": "Snippet" } }, "required": [ "room_id", "event_id", "author_display_name" ], "title": "ChatMentionRequest", "type": "object" }, "ChatMentionResponse": { "description": "Response body for ``POST /api/v1/notifications/chat-mention``.\n\n``deduped=false`` -> 201 with a freshly inserted row id.\n``deduped=true`` -> 200 with the id of the pre-existing row that\nmatched ``metadata.dedupe_key=\"chat:{event_id}\"`` for this caller.", "properties": { "deduped": { "title": "Deduped", "type": "boolean" }, "notification_id": { "format": "uuid", "title": "Notification Id", "type": "string" } }, "required": [ "notification_id", "deduped" ], "title": "ChatMentionResponse", "type": "object" }, "ChatMessageEditResponse": { "properties": { "edited_at": { "format": "date-time", "title": "Edited At", "type": "string" }, "editor_account_id": { "title": "Editor Account Id", "type": "string" }, "editor_email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Editor Email" }, "id": { "title": "Id", "type": "string" }, "kind": { "enum": [ "edit", "delete" ], "title": "Kind", "type": "string" }, "new_body": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "New Body" }, "original_event_id": { "title": "Original Event Id", "type": "string" }, "previous_body": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Previous Body" }, "redaction_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Redaction Reason" }, "replacement_event_id": { "title": "Replacement Event Id", "type": "string" }, "room_id": { "title": "Room Id", "type": "string" } }, "required": [ "id", "room_id", "original_event_id", "replacement_event_id", "editor_account_id", "kind", "edited_at" ], "title": "ChatMessageEditResponse", "type": "object" }, "ChatMessageResponse": { "properties": { "citations": { "items": { "$ref": "#/components/schemas/CitationResponse" }, "title": "Citations", "type": "array" }, "content": { "title": "Content", "type": "string" }, "conversation_id": { "title": "Conversation Id", "type": "string" }, "created_at": { "title": "Created At", "type": "string" }, "id": { "title": "Id", "type": "string" }, "refused": { "title": "Refused", "type": "boolean" }, "role": { "title": "Role", "type": "string" } }, "required": [ "id", "conversation_id", "role", "content", "citations", "refused", "created_at" ], "title": "ChatMessageResponse", "type": "object" }, "ChatRequest": { "properties": { "conversation_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "description": "Continue an existing conversation; omit to start one", "title": "Conversation Id" }, "message": { "description": "The question to ask the bundle", "minLength": 1, "title": "Message", "type": "string" }, "request_id": { "description": "Stable client-generated id; retries return the completed turn", "format": "uuid", "title": "Request Id", "type": "string" } }, "required": [ "message" ], "title": "ChatRequest", "type": "object" }, "ChatResponse": { "properties": { "answer": { "title": "Answer", "type": "string" }, "citations": { "items": { "$ref": "#/components/schemas/CitationResponse" }, "title": "Citations", "type": "array" }, "conversation_id": { "title": "Conversation Id", "type": "string" }, "excluded_source_count": { "description": "Bundle items excluded from the context (deselected, unreadable, or no longer visible to the caller)", "title": "Excluded Source Count", "type": "integer" }, "message_id": { "title": "Message Id", "type": "string" }, "refusal_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Why the answer refused: not_in_sources, no_readable_sources, or citation_validation_failed", "title": "Refusal Reason" }, "refused": { "title": "Refused", "type": "boolean" }, "source_count": { "description": "Sources that contributed to this answer", "title": "Source Count", "type": "integer" } }, "required": [ "message_id", "conversation_id", "answer", "citations", "refused", "source_count", "excluded_source_count" ], "title": "ChatResponse", "type": "object" }, "ChatRetrieveRequest": { "properties": { "limit": { "default": 20, "maximum": 100.0, "minimum": 1.0, "title": "Limit", "type": "integer" }, "query": { "maxLength": 2000, "minLength": 1, "title": "Query", "type": "string" }, "room_ids": { "items": { "type": "string" }, "title": "Room Ids", "type": "array" }, "since": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Since" }, "tenant_id": { "title": "Tenant Id", "type": "string" }, "until": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Until" } }, "required": [ "query", "tenant_id" ], "title": "ChatRetrieveRequest", "type": "object" }, "ChatRetrieveResponse": { "properties": { "latency_ms": { "title": "Latency Ms", "type": "integer" }, "results": { "items": { "$ref": "#/components/schemas/ChatRetrieveResult" }, "title": "Results", "type": "array" } }, "required": [ "results", "latency_ms" ], "title": "ChatRetrieveResponse", "type": "object" }, "ChatRetrieveResult": { "properties": { "event_id": { "title": "Event Id", "type": "string" }, "room_id": { "title": "Room Id", "type": "string" }, "score": { "title": "Score", "type": "number" }, "sender_account_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Sender Account Id" }, "sender_matrix_id": { "title": "Sender Matrix Id", "type": "string" }, "snippet": { "title": "Snippet", "type": "string" }, "ts": { "format": "date-time", "title": "Ts", "type": "string" } }, "required": [ "event_id", "room_id", "sender_matrix_id", "sender_account_id", "ts", "snippet", "score" ], "title": "ChatRetrieveResult", "type": "object" }, "ChatSignInEmployee": { "properties": { "employee_account_id": { "title": "Employee Account Id", "type": "string" }, "employee_display_name": { "title": "Employee Display Name", "type": "string" } }, "required": [ "employee_account_id", "employee_display_name" ], "title": "ChatSignInEmployee", "type": "object" }, "ChatSignInEmployees": { "properties": { "employees": { "items": { "$ref": "#/components/schemas/ChatSignInEmployee" }, "title": "Employees", "type": "array" }, "runtime": { "title": "Runtime", "type": "string" }, "workshop_id": { "title": "Workshop Id", "type": "string" } }, "required": [ "workshop_id", "runtime" ], "title": "ChatSignInEmployees", "type": "object" }, "ChatSummaryResponse": { "properties": { "action_items": { "items": { "$ref": "#/components/schemas/ActionItem" }, "title": "Action Items", "type": "array" }, "cited_event_ids": { "items": { "type": "string" }, "title": "Cited Event Ids", "type": "array" }, "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "highlights": { "items": { "$ref": "#/components/schemas/Highlight" }, "title": "Highlights", "type": "array" }, "id": { "format": "uuid", "title": "Id", "type": "string" }, "message_count": { "title": "Message Count", "type": "integer" }, "promoted_note_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Promoted Note Id" }, "since_ts": { "format": "date-time", "title": "Since Ts", "type": "string" }, "summary_text": { "title": "Summary Text", "type": "string" }, "until_ts": { "format": "date-time", "title": "Until Ts", "type": "string" } }, "required": [ "id", "summary_text", "highlights", "action_items", "cited_event_ids", "promoted_note_id", "created_at", "message_count", "since_ts", "until_ts" ], "title": "ChatSummaryResponse", "type": "object" }, "ChatTrigger": { "description": "A single automation the caller may trigger from chat in a room.", "properties": { "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Description" }, "name": { "title": "Name", "type": "string" }, "params_schema": { "additionalProperties": true, "default": {}, "title": "Params Schema", "type": "object" }, "slug": { "title": "Slug", "type": "string" } }, "required": [ "slug", "name" ], "title": "ChatTrigger", "type": "object" }, "ChatTriggerRegistryResponse": { "properties": { "room_id": { "title": "Room Id", "type": "string" }, "surface": { "title": "Surface", "type": "string" }, "triggers": { "items": { "$ref": "#/components/schemas/ChatTrigger" }, "title": "Triggers", "type": "array" } }, "required": [ "surface", "room_id", "triggers" ], "title": "ChatTriggerRegistryResponse", "type": "object" }, "CheckDuplicateRequest": { "description": "Input for checking duplicate content.\n\nUsed in:\n - POST /api/v1/feed/check-duplicate\n\nAttributes:\n content_hash: SHA-256 hash of content\n\nRelated: migration 154_feed_cards_extensions.sql", "properties": { "content_hash": { "description": "SHA-256 hash of content", "pattern": "^[a-f0-9]{64}$", "title": "Content Hash", "type": "string" } }, "required": [ "content_hash" ], "title": "CheckDuplicateRequest", "type": "object" }, "CheckGrantRequest": { "properties": { "action": { "maxLength": 256, "title": "Action", "type": "string" }, "conversation_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Conversation Id" }, "exercise": { "default": true, "description": "Stamp the exercise when a grant covers the ask", "title": "Exercise", "type": "boolean" }, "member_account_id": { "title": "Member Account Id", "type": "string" }, "target": { "default": "", "maxLength": 256, "title": "Target", "type": "string" } }, "required": [ "action", "member_account_id" ], "title": "CheckGrantRequest", "type": "object" }, "CheckGrantResponse": { "properties": { "grant": { "anyOf": [ { "$ref": "#/components/schemas/ApprovalGrant" }, { "type": "null" } ], "default": null }, "granted": { "title": "Granted", "type": "boolean" } }, "required": [ "granted" ], "title": "CheckGrantResponse", "type": "object" }, "ChecklistItemState": { "properties": { "checked": { "title": "Checked", "type": "boolean" }, "index": { "title": "Index", "type": "integer" }, "text": { "title": "Text", "type": "string" } }, "required": [ "index", "text", "checked" ], "title": "ChecklistItemState", "type": "object" }, "CheckoutSessionRequest": { "properties": { "addon_inboxes": { "default": 0, "minimum": 0.0, "title": "Addon Inboxes", "type": "integer" }, "billing_interval": { "title": "Billing Interval", "type": "string" }, "flow": { "default": "settings", "enum": [ "settings", "onboarding" ], "title": "Flow", "type": "string" }, "plan_id": { "title": "Plan Id", "type": "string" }, "return_to": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Return To" }, "theme": { "default": "day", "title": "Theme", "type": "string" } }, "required": [ "plan_id", "billing_interval" ], "title": "CheckoutSessionRequest", "type": "object" }, "CheckoutSessionResponse": { "properties": { "session_id": { "title": "Session Id", "type": "string" }, "url": { "title": "Url", "type": "string" } }, "required": [ "url", "session_id" ], "title": "CheckoutSessionResponse", "type": "object" }, "ChoiceSettingEntry": { "properties": { "description": { "title": "Description", "type": "string" }, "key": { "title": "Key", "type": "string" }, "label": { "title": "Label", "type": "string" }, "options": { "items": { "type": "string" }, "title": "Options", "type": "array" }, "value": { "title": "Value", "type": "string" } }, "required": [ "key", "label", "description", "options", "value" ], "title": "ChoiceSettingEntry", "type": "object" }, "ChunkReceiptResponse": { "properties": { "chunk_index": { "title": "Chunk Index", "type": "integer" }, "chunks_received": { "title": "Chunks Received", "type": "integer" }, "duplicate": { "default": false, "description": "True when the chunk was a duplicate of one previously received.", "title": "Duplicate", "type": "boolean" }, "recording_id": { "title": "Recording Id", "type": "string" } }, "required": [ "recording_id", "chunk_index", "chunks_received" ], "title": "ChunkReceiptResponse", "type": "object" }, "CitationClickRequest": { "properties": { "marker": { "description": "Which citation of that message was opened", "minimum": 1.0, "title": "Marker", "type": "integer" } }, "required": [ "marker" ], "title": "CitationClickRequest", "type": "object" }, "CitationResponse": { "description": "One citation and what it opens.\n\nA bundle source is either a Tidy primitive or an external page, so a\ncitation carries either ``primitive_id`` or ``external_url`` (TIDY-15829).\n``external_url`` defaults to None so a message stored before this field\nexisted still reads back — those turns simply have no external target,\nwhich is what they had at the time.", "properties": { "bundle_item_id": { "title": "Bundle Item Id", "type": "string" }, "excerpt": { "title": "Excerpt", "type": "string" }, "external_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "For an external source, the page this citation opens", "title": "External Url" }, "marker": { "title": "Marker", "type": "integer" }, "primitive_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Primitive Id" }, "primitive_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Primitive Type" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Title" } }, "required": [ "marker", "bundle_item_id", "primitive_type", "primitive_id", "title", "excerpt" ], "title": "CitationResponse", "type": "object" }, "ClaimEntityRequest": { "description": "Optional overrides for the claimed contact (defaults from the entity).", "properties": { "contact_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Existing contact UUID to LINK instead of creating a new one", "title": "Contact Id" }, "display_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Override display name (defaults to entity canonical_name)", "title": "Display Name" } }, "title": "ClaimEntityRequest", "type": "object" }, "ClaimEntityResponse": { "properties": { "contact_id": { "title": "Contact Id", "type": "string" }, "created": { "description": "True when a new contact was created vs an existing link", "title": "Created", "type": "boolean" }, "entity_id": { "title": "Entity Id", "type": "string" } }, "required": [ "contact_id", "entity_id", "created" ], "title": "ClaimEntityResponse", "type": "object" }, "ClaimRequest": { "properties": { "agent_member_id": { "description": "agent_members.id of the claiming VE", "title": "Agent Member Id", "type": "string" }, "lease_seconds": { "default": 3600, "description": "Lease duration; expired leases are reclaimable.", "maximum": 14400.0, "minimum": 60.0, "title": "Lease Seconds", "type": "integer" }, "session_id": { "maxLength": 200, "minLength": 1, "title": "Session Id", "type": "string" } }, "required": [ "agent_member_id", "session_id" ], "title": "ClaimRequest", "type": "object" }, "ClaimResponse": { "properties": { "activity": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "title": "Activity" }, "claimed": { "title": "Claimed", "type": "boolean" }, "holder": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "title": "Holder" } }, "required": [ "claimed" ], "title": "ClaimResponse", "type": "object" }, "ClaimableResponse": { "properties": { "items": { "items": { "additionalProperties": true, "type": "object" }, "title": "Items", "type": "array" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Next Cursor" } }, "required": [ "items" ], "title": "ClaimableResponse", "type": "object" }, "ClassificationRulesUpdate": { "description": "Input for updating project classification rules.", "properties": { "rules": { "description": "Classification rules JSON array", "items": {}, "title": "Rules", "type": "array" } }, "required": [ "rules" ], "title": "ClassificationRulesUpdate", "type": "object" }, "CleanupResponse": { "properties": { "deleted": { "title": "Deleted", "type": "boolean" } }, "required": [ "deleted" ], "title": "CleanupResponse", "type": "object" }, "ClearBounceResponse": { "properties": { "cleared": { "title": "Cleared", "type": "boolean" }, "user_id": { "title": "User Id", "type": "string" } }, "required": [ "user_id", "cleared" ], "title": "ClearBounceResponse", "type": "object" }, "ClickAction": { "description": "Click action types for feed cards.\n\nDetermines what happens when a user taps on a card:\n - none: No action (content shown inline)\n - navigate: Navigate to a route (clickTarget = route path)\n - detail: Show generic detail modal (clickTarget = card ID for API fetch)\n - sheet: Open a bottom sheet (clickTarget = sheet type e.g., 'weather')\n - external: Open external app (clickTarget = deep link URL)", "enum": [ "none", "navigate", "detail", "sheet", "external" ], "title": "ClickAction", "type": "string" }, "ClickRequest": { "properties": { "clicked_event_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Clicked Event Id" }, "clicked_pg_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Clicked Pg Id" }, "group": { "enum": [ "messages", "embeds", "files", "people", "channels" ], "title": "Group", "type": "string" }, "position": { "minimum": 0.0, "title": "Position", "type": "integer" }, "query_id": { "format": "uuid", "title": "Query Id", "type": "string" }, "time_to_click_ms": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Time To Click Ms" } }, "required": [ "query_id", "group", "position" ], "title": "ClickRequest", "type": "object" }, "CloseNegotiationRequest": { "properties": { "note": { "anyOf": [ { "maxLength": 2000, "type": "string" }, { "type": "null" } ], "title": "Note" }, "outcome": { "description": "settled = calendar written from a clean acceptance; surfaced = recommendation handed to the member; closed = ended with a note (e.g. the member already resolved manually — no mutation).", "enum": [ "settled", "surfaced", "closed" ], "title": "Outcome", "type": "string" }, "target_event_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Target Event Id" } }, "required": [ "outcome" ], "title": "CloseNegotiationRequest", "type": "object" }, "ClusterDetectionRequest": { "description": "Request for POST /api/v1/contacts/merge/detect-clusters.\n\nAttributes:\n contact_ids: List of contact IDs to analyze for clustering\n scope: Candidate selection scope (TIDY-10524 / S11):\n - ``owner`` (default): today's per-owner behavior — the candidate\n query is restricted to contacts the caller may merge in their own\n scope (their own rows + ownerless + shared/tenant rows).\n - ``cross_member``: the deliberate cross-member manual tool — the\n candidate query spans other members' shared / account / global\n contacts. It NEVER returns another member's PRIVATE rows and is\n gated to the account owner / tenant admin (see router authz).", "properties": { "contact_ids": { "description": "Contact IDs to cluster", "items": { "type": "string" }, "minItems": 2, "title": "Contact Ids", "type": "array" }, "scope": { "default": "owner", "description": "Candidate scope: 'owner' (per-owner, default) or 'cross_member' (spans shared/account/global rows across members — owner/admin only).", "enum": [ "owner", "cross_member" ], "title": "Scope", "type": "string" } }, "required": [ "contact_ids" ], "title": "ClusterDetectionRequest", "type": "object" }, "ClusterDetectionResponse": { "description": "Response from POST /api/v1/contacts/merge/detect-clusters.\n\nAttributes:\n clusters: List of detected clusters\n unclustered: Contacts that don't match any cluster\n total_contacts: Total contacts analyzed", "properties": { "clusters": { "default": [], "description": "Detected clusters", "items": { "$ref": "#/components/schemas/ContactCluster" }, "title": "Clusters", "type": "array" }, "total_contacts": { "description": "Total contacts analyzed", "title": "Total Contacts", "type": "integer" }, "unclustered": { "default": [], "description": "Contacts not in any cluster", "items": { "$ref": "#/components/schemas/api_service__models__contact_merge__ContactSummary" }, "title": "Unclustered", "type": "array" } }, "required": [ "total_contacts" ], "title": "ClusterDetectionResponse", "type": "object" }, "ClusterSuggestion": { "properties": { "contact_id": { "format": "uuid", "title": "Contact Id", "type": "string" }, "display_name": { "title": "Display Name", "type": "string" }, "similarity": { "title": "Similarity", "type": "number" } }, "required": [ "contact_id", "display_name", "similarity" ], "title": "ClusterSuggestion", "type": "object" }, "CoRequester": { "properties": { "account_id": { "format": "uuid", "title": "Account Id", "type": "string" }, "co_requester_order": { "title": "Co Requester Order", "type": "integer" }, "requested_at": { "title": "Requested At" } }, "required": [ "account_id", "co_requester_order", "requested_at" ], "title": "CoRequester", "type": "object" }, "CoachingCard": { "properties": { "action": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Action" }, "dismissible": { "default": true, "title": "Dismissible", "type": "boolean" }, "impact": { "title": "Impact", "type": "string" }, "observation": { "title": "Observation", "type": "string" }, "rule_id": { "title": "Rule Id", "type": "string" }, "severity": { "title": "Severity", "type": "string" }, "technique": { "title": "Technique", "type": "string" } }, "required": [ "rule_id", "severity", "observation", "impact", "technique" ], "title": "CoachingCard", "type": "object" }, "CoachingChunkRow": { "properties": { "chunk_index": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Chunk Index" }, "content": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Content" }, "created_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Created At" }, "header_context": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Header Context" }, "id": { "title": "Id", "type": "string" }, "keywords": { "default": [], "items": { "type": "string" }, "title": "Keywords", "type": "array" }, "metadata": { "additionalProperties": true, "default": {}, "title": "Metadata", "type": "object" }, "module": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Module" }, "source_document": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Source Document" } }, "required": [ "id" ], "title": "CoachingChunkRow", "type": "object" }, "CoachingDocumentRow": { "properties": { "chunk_count": { "default": 0, "title": "Chunk Count", "type": "integer" }, "created_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Created At" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Description" }, "error_message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Error Message" }, "file_size_bytes": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "File Size Bytes" }, "filename": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Filename" }, "id": { "title": "Id", "type": "string" }, "module": { "title": "Module", "type": "string" }, "processed_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Processed At" }, "status": { "default": "processed", "title": "Status", "type": "string" }, "storage_path": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Storage Path" }, "tags": { "default": [], "items": { "type": "string" }, "title": "Tags", "type": "array" } }, "required": [ "id", "module" ], "title": "CoachingDocumentRow", "type": "object" }, "CoachingEvaluateRequest": { "properties": { "metrics": { "additionalProperties": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "title": "Metrics", "type": "object" } }, "required": [ "metrics" ], "title": "CoachingEvaluateRequest", "type": "object" }, "CoachingEvaluateResponse": { "properties": { "benchmarks_applied": { "additionalProperties": { "$ref": "#/components/schemas/BenchmarkComparison" }, "title": "Benchmarks Applied", "type": "object" }, "cards": { "items": { "$ref": "#/components/schemas/CoachingCard" }, "title": "Cards", "type": "array" } }, "required": [ "cards", "benchmarks_applied" ], "title": "CoachingEvaluateResponse", "type": "object" }, "CoachingGoals": { "description": "User-defined goals for each coaching domain.", "properties": { "emotional": { "anyOf": [ { "maxLength": 500, "type": "string" }, { "type": "null" } ], "description": "Emotional/wellness goals", "title": "Emotional" }, "professional": { "anyOf": [ { "maxLength": 500, "type": "string" }, { "type": "null" } ], "description": "Professional/productivity goals", "title": "Professional" }, "relationships": { "anyOf": [ { "maxLength": 500, "type": "string" }, { "type": "null" } ], "description": "Relationship improvement goals", "title": "Relationships" } }, "title": "CoachingGoals", "type": "object" }, "CoachingKnowledgePageResponse": { "properties": { "chunks": { "items": { "$ref": "#/components/schemas/CoachingChunkRow" }, "title": "Chunks", "type": "array" }, "documents": { "items": { "$ref": "#/components/schemas/CoachingDocumentRow" }, "title": "Documents", "type": "array" }, "totalChunks": { "title": "Totalchunks", "type": "integer" }, "totalCount": { "title": "Totalcount", "type": "integer" } }, "required": [ "documents", "chunks", "totalCount", "totalChunks" ], "title": "CoachingKnowledgePageResponse", "type": "object" }, "CoachingModule": { "description": "Available coaching modules.", "enum": [ "wellness", "productivity", "relationships", "parenting" ], "title": "CoachingModule", "type": "string" }, "CoachingPreferencesResponse": { "description": "Response model for coaching preferences.\n\n``datetime`` fields serialize as canonical Tidy Time Standard ISO UTC\n(``YYYY-MM-DDTHH:MM:SS.sssZ``) via :class:`TidyResponseModel`.", "properties": { "coaching_enabled": { "default": false, "description": "Whether coaching features are enabled", "title": "Coaching Enabled", "type": "boolean" }, "coaching_goals": { "anyOf": [ { "$ref": "#/components/schemas/CoachingGoals" }, { "type": "null" } ], "default": null, "description": "Goals for each coaching domain" }, "coaching_modules": { "description": "List of enabled coaching modules", "items": { "type": "string" }, "title": "Coaching Modules", "type": "array" }, "privacy_accepted_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "description": "Timestamp when user accepted privacy disclosure", "title": "Privacy Accepted At" }, "updated_at": { "description": "Last update timestamp", "format": "date-time", "title": "Updated At", "type": "string" } }, "required": [ "updated_at" ], "title": "CoachingPreferencesResponse", "type": "object" }, "CoachingPreferencesUpdate": { "description": "Request model for updating coaching preferences.", "properties": { "accept_privacy": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Set to true to accept the coaching privacy disclosure. Required before coaching can be enabled. Once accepted, cannot be revoked.", "title": "Accept Privacy" }, "coaching_enabled": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Enable/disable coaching features", "title": "Coaching Enabled" }, "coaching_goals": { "anyOf": [ { "$ref": "#/components/schemas/CoachingGoals" }, { "type": "null" } ], "description": "Goals for each coaching domain" }, "coaching_modules": { "anyOf": [ { "items": { "$ref": "#/components/schemas/CoachingModule" }, "type": "array" }, { "type": "null" } ], "description": "List of coaching modules to enable", "title": "Coaching Modules" } }, "title": "CoachingPreferencesUpdate", "type": "object" }, "CohortEvent": { "description": "One ranking outcome. Carries no query text — by construction.", "properties": { "bucket": { "maximum": 99.0, "minimum": 0.0, "title": "Bucket", "type": "integer" }, "cohort": { "maxLength": 64, "title": "Cohort", "type": "string" }, "config_version_id": { "format": "uuid", "title": "Config Version Id", "type": "string" }, "event_type": { "description": "One of the seven ranking outcome events.", "title": "Event Type", "type": "string" }, "experiment_id": { "format": "uuid", "title": "Experiment Id", "type": "string" }, "idempotency_key": { "maxLength": 200, "title": "Idempotency Key", "type": "string" }, "latency_ms": { "anyOf": [ { "minimum": 0.0, "type": "integer" }, { "type": "null" } ], "title": "Latency Ms" }, "occurred_at": { "format": "date-time", "title": "Occurred At", "type": "string" }, "rank": { "anyOf": [ { "minimum": 0.0, "type": "integer" }, { "type": "null" } ], "title": "Rank" }, "session_id": { "format": "uuid", "title": "Session Id", "type": "string" }, "surface": { "title": "Surface", "type": "string" } }, "required": [ "event_type", "surface", "experiment_id", "cohort", "config_version_id", "bucket", "session_id", "occurred_at", "idempotency_key" ], "title": "CohortEvent", "type": "object" }, "CohortEventBatch": { "properties": { "events": { "items": { "$ref": "#/components/schemas/CohortEvent" }, "minItems": 1, "title": "Events", "type": "array" } }, "required": [ "events" ], "title": "CohortEventBatch", "type": "object" }, "CohortEventBatchResult": { "properties": { "accepted": { "title": "Accepted", "type": "integer" }, "duplicates": { "title": "Duplicates", "type": "integer" }, "guardrail_raised": { "default": false, "title": "Guardrail Raised", "type": "boolean" }, "rejected": { "items": { "$ref": "#/components/schemas/RejectedEvent" }, "title": "Rejected", "type": "array" } }, "required": [ "accepted", "duplicates", "rejected" ], "title": "CohortEventBatchResult", "type": "object" }, "ColorPaletteEntry": { "description": "A single color option.", "properties": { "background_color": { "title": "Background Color", "type": "string" }, "id": { "title": "Id", "type": "string" }, "name": { "title": "Name", "type": "string" }, "text_color": { "title": "Text Color", "type": "string" } }, "required": [ "id", "name", "background_color", "text_color" ], "title": "ColorPaletteEntry", "type": "object" }, "ColorPaletteResponse": { "description": "Response with available color palette.", "properties": { "colors": { "items": { "$ref": "#/components/schemas/ColorPaletteEntry" }, "title": "Colors", "type": "array" } }, "required": [ "colors" ], "title": "ColorPaletteResponse", "type": "object" }, "CommandPolicyLayers": { "properties": { "builtin": { "items": { "$ref": "#/components/schemas/CommandPolicyRule" }, "title": "Builtin", "type": "array" }, "employee": { "items": { "$ref": "#/components/schemas/CommandPolicyRule" }, "title": "Employee", "type": "array" }, "org": { "items": { "$ref": "#/components/schemas/CommandPolicyRule" }, "title": "Org", "type": "array" }, "session": { "items": { "$ref": "#/components/schemas/CommandPolicyRule" }, "title": "Session", "type": "array" } }, "title": "CommandPolicyLayers", "type": "object" }, "CommandPolicyResponse": { "properties": { "can_edit_employee": { "default": false, "description": "True when the caller may add/remove rules for the employee named in `agent_account_id` (its owner, or a tenant Owner/Admin). False when no employee was named.", "title": "Can Edit Employee", "type": "boolean" }, "can_edit_org": { "default": false, "description": "True when the caller may add/remove ORG-floor rules (tenant Owner/Admin). The builtin floor is never editable by anyone.", "title": "Can Edit Org", "type": "boolean" }, "floor_version": { "title": "Floor Version", "type": "integer" }, "layers": { "$ref": "#/components/schemas/CommandPolicyLayers" }, "rules": { "items": { "$ref": "#/components/schemas/CommandPolicyRule" }, "title": "Rules", "type": "array" } }, "required": [ "floor_version", "layers" ], "title": "CommandPolicyResponse", "type": "object" }, "CommandPolicyRule": { "properties": { "agent_account_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Agent Account Id" }, "builtin": { "default": false, "title": "Builtin", "type": "boolean" }, "conversation_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Conversation Id" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Description" }, "effect": { "description": "deny | require_approval", "title": "Effect", "type": "string" }, "id": { "description": "Stable rule id — named in prompts and audit rows", "title": "Id", "type": "string" }, "layer": { "title": "Layer", "type": "string" }, "pattern": { "title": "Pattern", "type": "string" }, "row_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Row Id" } }, "required": [ "id", "layer", "effect", "pattern" ], "title": "CommandPolicyRule", "type": "object" }, "CommandPolicyRuleDeleteResponse": { "properties": { "deleted": { "title": "Deleted", "type": "boolean" }, "row_id": { "title": "Row Id", "type": "string" } }, "required": [ "row_id", "deleted" ], "title": "CommandPolicyRuleDeleteResponse", "type": "object" }, "CommandPolicyRuleRequest": { "properties": { "conversation_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Required for a conversation-layer rule", "title": "Conversation Id" }, "description": { "anyOf": [ { "maxLength": 512, "type": "string" }, { "type": "null" } ], "title": "Description" }, "effect": { "description": "deny | require_approval", "title": "Effect", "type": "string" }, "pattern": { "description": "Glob over the normalized command", "maxLength": 512, "title": "Pattern", "type": "string" }, "rule_key": { "description": "Stable id within the layer", "maxLength": 128, "title": "Rule Key", "type": "string" } }, "required": [ "rule_key", "pattern", "effect" ], "title": "CommandPolicyRuleRequest", "type": "object" }, "CommentCreate": { "description": "Request body for creating a comment.\n\nDuring the typed-ID deprecation window, ``parent_id`` and\n``thread_root_id`` accept either a typed ID (e.g. ``J-``,\n``M-``) or a bare UUID. The router unwraps to canonical UUID\nbefore storage.", "properties": { "anchor_block_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Anchor Block Id" }, "anchor_text": { "anyOf": [ { "maxLength": 2000, "type": "string" }, { "type": "null" } ], "description": "Highlighted text snippet the comment is anchored to. Deliberate 2000-char cap (a long paragraph): the highlight is an @mentioned agent's primary instruction source (TIDY-11594). Mirror the router constant _ANCHOR_TEXT_MAX_CHARS.", "title": "Anchor Text" }, "content": { "additionalProperties": true, "description": "ProseMirror JSON document", "title": "Content", "type": "object" }, "facet_data": { "additionalProperties": true, "title": "Facet Data", "type": "object" }, "facets": { "items": { "type": "string" }, "title": "Facets", "type": "array" }, "id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "description": "Client-specified UUID (used to match TipTap comment marks)", "title": "Id" }, "parent_id": { "title": "Parent Id", "type": "string" }, "parent_type": { "enum": [ "note", "journal", "activity", "event", "project", "contact", "organization", "record", "email", "comment" ], "title": "Parent Type", "type": "string" }, "placement": { "anyOf": [ { "discriminator": { "mapping": { "after_span": "#/components/schemas/AfterSpanPlacement", "append": "#/components/schemas/AppendPlacement", "before_span": "#/components/schemas/BeforeSpanPlacement", "none": "#/components/schemas/NoPlacement", "prepend": "#/components/schemas/PrependPlacement", "under_heading": "#/components/schemas/UnderHeadingPlacement" }, "propertyName": "mode" }, "oneOf": [ { "$ref": "#/components/schemas/NoPlacement" }, { "$ref": "#/components/schemas/AppendPlacement" }, { "$ref": "#/components/schemas/PrependPlacement" }, { "$ref": "#/components/schemas/AfterSpanPlacement" }, { "$ref": "#/components/schemas/BeforeSpanPlacement" }, { "$ref": "#/components/schemas/UnderHeadingPlacement" } ] }, { "type": "null" } ], "description": "Where the comment is embedded in the parent's body (TIDY-18990). Omit for the default: `append` at the end of the body when the parent has a collaborative prose body and this comment is not anchored to a block, `none` otherwise. Pass `{\"mode\": \"none\"}` to create the row and its link without touching the body. An explicit non-`none` placement on a parent with no prose body is a 422.", "title": "Placement" }, "template": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "A content template to start this comment's body from — its id, its name, or the slugified name (`progress_update` for \"Progress update\"). TIDY-18992. Resolved against the templates bound to this comment's leaf facet and to the base `comment` facet, with `{{context.creator}}` and `{{context.created_at}}` substituted before the row is written. An unknown name is a 422 and persists nothing. Ignored when `content` is not empty — a caller that sent both meant the text they wrote.", "title": "Template" }, "thread_root_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Thread Root Id" }, "visibility": { "default": "private", "title": "Visibility", "type": "string" } }, "required": [ "parent_type", "parent_id" ], "title": "CommentCreate", "type": "object" }, "CommentId": { "description": "Typed primitive ID for comments (prefix 'M').", "examples": [ "M-550e8400-e29b-41d4-a716-446655440000" ], "pattern": "^M-[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "title": "CommentId", "type": "string", "x-tidy-typed-id-prefix": "M", "x-tidy-typed-id-table": "comments" }, "CommentReplyResponse": { "description": "Response model for a reply nested under a root comment.\n\nTyped-ID emit (TIDY-8940): primary id M-; ``parent_id`` is\npolymorphic (lookup via ``parent_type``) so it stays bare —\nconsumers can prefix from ``parent_type``. ``thread_root_id``\npoints at another comment so it's M-.\n\nKeep this non-recursive. ``openapi-typescript`` rejects a component that\nresolves to ``#/components/schemas/``.", "properties": { "anchor_block_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "default": null, "title": "Anchor Block Id" }, "anchor_text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Anchor Text" }, "author_email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Author Email" }, "author_id": { "format": "uuid", "title": "Author Id", "type": "string" }, "author_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Author Name" }, "content": { "additionalProperties": true, "title": "Content", "type": "object" }, "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "deleted_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Deleted At" }, "facet_data": { "additionalProperties": true, "title": "Facet Data", "type": "object" }, "facets": { "items": { "type": "string" }, "title": "Facets", "type": "array" }, "id": { "format": "uuid", "title": "Id", "type": "string" }, "parent_id": { "format": "uuid", "title": "Parent Id", "type": "string" }, "parent_type": { "title": "Parent Type", "type": "string" }, "plain_text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Plain Text" }, "reopened_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Reopened At" }, "reopened_by": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Reopened By" }, "resolution_history": { "description": "Append-only resolution trail, oldest first. Each entry is `{action, at, by}` with action one of `resolved` / `reopened` / `cleared`.", "items": { "additionalProperties": true, "type": "object" }, "title": "Resolution History", "type": "array" }, "resolved_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Resolved At" }, "resolved_by": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Resolved By" }, "status": { "title": "Status", "type": "string" }, "tenant_id": { "format": "uuid", "title": "Tenant Id", "type": "string" }, "thread_root_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "default": null, "title": "Thread Root Id" }, "updated_at": { "format": "date-time", "title": "Updated At", "type": "string" }, "visibility": { "title": "Visibility", "type": "string" } }, "required": [ "id", "tenant_id", "parent_type", "parent_id", "content", "author_id", "facets", "facet_data", "status", "visibility", "created_at", "updated_at" ], "title": "CommentReplyResponse", "type": "object" }, "CommentResolutionResponse": { "description": "Lifecycle state after a resolve/reopen transition.", "properties": { "changed": { "title": "Changed", "type": "boolean" }, "id": { "title": "Id", "type": "string" }, "reopened_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Reopened At" }, "reopened_by": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Reopened By" }, "resolution_history": { "description": "Tail of the append-only resolution trail (last 10 entries, oldest first). Each entry is `{action, at, by}`. Lets a caller verify WHO resolved or reopened without a second read.", "items": { "additionalProperties": true, "type": "object" }, "title": "Resolution History", "type": "array" }, "resolved_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Resolved At" }, "resolved_by": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Resolved By" }, "status": { "title": "Status", "type": "string" } }, "required": [ "id", "status", "changed" ], "title": "CommentResolutionResponse", "type": "object" }, "CommentResolveBulkItem": { "properties": { "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Error" }, "id": { "title": "Id", "type": "string" }, "ok": { "title": "Ok", "type": "boolean" } }, "required": [ "id", "ok" ], "title": "CommentResolveBulkItem", "type": "object" }, "CommentResolveBulkRequest": { "properties": { "ids": { "items": { "type": "string" }, "maxItems": 200, "minItems": 1, "title": "Ids", "type": "array" } }, "required": [ "ids" ], "title": "CommentResolveBulkRequest", "type": "object" }, "CommentResolveBulkResponse": { "properties": { "failed_count": { "title": "Failed Count", "type": "integer" }, "resolved_count": { "title": "Resolved Count", "type": "integer" }, "results": { "items": { "$ref": "#/components/schemas/CommentResolveBulkItem" }, "title": "Results", "type": "array" } }, "required": [ "results", "resolved_count", "failed_count" ], "title": "CommentResolveBulkResponse", "type": "object" }, "CommentResponse": { "description": "Response model for a single root comment with immediate replies.", "properties": { "anchor_block_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "default": null, "title": "Anchor Block Id" }, "anchor_text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Anchor Text" }, "author_email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Author Email" }, "author_id": { "format": "uuid", "title": "Author Id", "type": "string" }, "author_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Author Name" }, "content": { "additionalProperties": true, "title": "Content", "type": "object" }, "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "deleted_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Deleted At" }, "facet_data": { "additionalProperties": true, "title": "Facet Data", "type": "object" }, "facets": { "items": { "type": "string" }, "title": "Facets", "type": "array" }, "id": { "format": "uuid", "title": "Id", "type": "string" }, "parent_id": { "format": "uuid", "title": "Parent Id", "type": "string" }, "parent_type": { "title": "Parent Type", "type": "string" }, "plain_text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Plain Text" }, "reopened_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Reopened At" }, "reopened_by": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Reopened By" }, "replies": { "items": { "$ref": "#/components/schemas/CommentReplyResponse" }, "title": "Replies", "type": "array" }, "resolution_history": { "description": "Append-only resolution trail, oldest first. Each entry is `{action, at, by}` with action one of `resolved` / `reopened` / `cleared`.", "items": { "additionalProperties": true, "type": "object" }, "title": "Resolution History", "type": "array" }, "resolved_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Resolved At" }, "resolved_by": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Resolved By" }, "status": { "title": "Status", "type": "string" }, "tenant_id": { "format": "uuid", "title": "Tenant Id", "type": "string" }, "thread_root_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "default": null, "title": "Thread Root Id" }, "updated_at": { "format": "date-time", "title": "Updated At", "type": "string" }, "visibility": { "title": "Visibility", "type": "string" } }, "required": [ "id", "tenant_id", "parent_type", "parent_id", "content", "author_id", "facets", "facet_data", "status", "visibility", "created_at", "updated_at" ], "title": "CommentResponse", "type": "object" }, "CommentThreadResponse": { "description": "Response for ``GET /comments/{id}`` (mention-grant single-comment read).\n\nReturns the requested comment + its thread siblings + the anchor metadata,\nand NEVER the parent primitive's body. ``mention_grant`` records whether\naccess was granted via @mention (vs parent access) for observability.", "properties": { "anchor_block_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Anchor Block Id" }, "anchor_text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Anchor Text" }, "comment": { "$ref": "#/components/schemas/CommentResponse" }, "mention_grant": { "default": false, "title": "Mention Grant", "type": "boolean" }, "parent_route": { "title": "Parent Route", "type": "string" }, "parent_type": { "title": "Parent Type", "type": "string" }, "thread": { "items": { "$ref": "#/components/schemas/CommentResponse" }, "title": "Thread", "type": "array" } }, "required": [ "comment", "parent_type", "parent_route" ], "title": "CommentThreadResponse", "type": "object" }, "CommentUpdate": { "description": "Request body for updating a comment.", "properties": { "content": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Content" }, "facet_data": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Facet Data" }, "facet_data_patch": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "Atomically merge these top-level comment fields into the current facet_data object, preserving other keys and facet identity. Comment fields are flat (for example {\"type\": \"question\"}), including on derived facets. Mutually exclusive with facet_data replacement.", "title": "Facet Data Patch" }, "facets": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Facets" }, "resolution_action": { "anyOf": [ { "enum": [ "resolved", "reopened", "cleared" ], "type": "string" }, { "type": "null" } ], "description": "Which entry this transition records in the append-only `resolution_history` trail (TIDY-18987). The caller states the INTENT only — `at` and `by` are stamped server-side against the authenticated account, so a client cannot author an audit entry about anyone. Omitted, a status flip records the obvious one (`resolved` / `reopened`) and a write that does not change status records nothing. `cleared` requires `status: resolved` and always records, so that 'Clear all comments' can lift an already-resolved thread out of a document's margin.", "title": "Resolution Action" }, "status": { "anyOf": [ { "enum": [ "open", "resolved" ], "type": "string" }, { "type": "null" } ], "title": "Status" } }, "title": "CommentUpdate", "type": "object" }, "CommitIngest": { "properties": { "author": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Author" }, "authored_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Authored At" }, "links": { "default": [], "items": { "$ref": "#/components/schemas/EvidenceLinkIn" }, "title": "Links", "type": "array" }, "message_subject": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Message Subject" }, "provider": { "default": "github", "title": "Provider", "type": "string" }, "repository": { "minLength": 1, "title": "Repository", "type": "string" }, "sha": { "minLength": 4, "title": "Sha", "type": "string" }, "source_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Source Url" } }, "required": [ "repository", "sha" ], "title": "CommitIngest", "type": "object" }, "CommitProvenanceResponse": { "description": "Commit → the exact sessions/turns that authored it (R17).", "properties": { "evidence": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "title": "Evidence" }, "file_versions": { "default": [], "items": { "$ref": "#/components/schemas/ProvenanceFileVersion" }, "title": "File Versions", "type": "array" }, "links": { "default": [], "items": { "$ref": "#/components/schemas/ProvenanceLink" }, "title": "Links", "type": "array" }, "repository": { "default": "", "title": "Repository", "type": "string" }, "run_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Run Id" }, "sha": { "title": "Sha", "type": "string" }, "tools": { "default": [], "items": { "$ref": "#/components/schemas/ProvenanceToolCall" }, "title": "Tools", "type": "array" } }, "required": [ "sha" ], "title": "CommitProvenanceResponse", "type": "object" }, "CommitmentDashboardItem": { "description": "A single commitment-flavored activity for dashboard rendering.\n\n`id` is the typed id (`A-`) so the widget can hand it straight\nto `getPrimitiveUrl()` without re-stringifying.", "properties": { "counterparty_email": { "title": "Counterparty Email", "type": "string" }, "counterparty_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Counterparty Name" }, "created_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Created At" }, "description": { "title": "Description", "type": "string" }, "direction": { "title": "Direction", "type": "string" }, "due_date": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Due Date" }, "email_subject": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Email Subject" }, "id": { "title": "Id", "type": "string" }, "is_overdue": { "default": false, "title": "Is Overdue", "type": "boolean" }, "source_email_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Source Email Id" }, "source_thread_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Source Thread Id" }, "status": { "title": "Status", "type": "string" } }, "required": [ "id", "direction", "counterparty_email", "description", "status" ], "title": "CommitmentDashboardItem", "type": "object" }, "CommitmentDashboardResponse": { "properties": { "overdue_count": { "title": "Overdue Count", "type": "integer" }, "owed_count": { "title": "Owed Count", "type": "integer" }, "owing_count": { "title": "Owing Count", "type": "integer" }, "top_owed": { "items": { "$ref": "#/components/schemas/CommitmentDashboardItem" }, "title": "Top Owed", "type": "array" }, "top_owing": { "items": { "$ref": "#/components/schemas/CommitmentDashboardItem" }, "title": "Top Owing", "type": "array" } }, "required": [ "owed_count", "owing_count", "overdue_count", "top_owed", "top_owing" ], "title": "CommitmentDashboardResponse", "type": "object" }, "CompactionConfigListResponse": { "properties": { "compactionConfigs": { "items": { "$ref": "#/components/schemas/CompactionConfigRow" }, "title": "Compactionconfigs", "type": "array" } }, "required": [ "compactionConfigs" ], "title": "CompactionConfigListResponse", "type": "object" }, "CompactionConfigRow": { "properties": { "compact_after_pairs": { "title": "Compact After Pairs", "type": "integer" }, "conversation_type": { "title": "Conversation Type", "type": "string" }, "keep_intact_pairs": { "title": "Keep Intact Pairs", "type": "integer" }, "meta_compact_after_summaries": { "title": "Meta Compact After Summaries", "type": "integer" }, "token_threshold": { "title": "Token Threshold", "type": "integer" } }, "required": [ "conversation_type", "token_threshold", "keep_intact_pairs", "compact_after_pairs", "meta_compact_after_summaries" ], "title": "CompactionConfigRow", "type": "object" }, "CompareRequest": { "properties": { "entries": { "items": { "$ref": "#/components/schemas/StateVectorEntry" }, "title": "Entries", "type": "array" } }, "required": [ "entries" ], "title": "CompareRequest", "type": "object" }, "CompareResponse": { "properties": { "needs_upload": { "items": { "type": "string" }, "title": "Needs Upload", "type": "array" }, "not_found": { "default": [], "items": { "type": "string" }, "title": "Not Found", "type": "array" } }, "required": [ "needs_upload" ], "title": "CompareResponse", "type": "object" }, "CompileFormBundleRequest": { "properties": { "publication_config": { "$ref": "#/components/schemas/FormPublicationConfig" } }, "required": [ "publication_config" ], "title": "CompileFormBundleRequest", "type": "object" }, "CompileFormBundleResponse": { "properties": { "bundle": { "$ref": "#/components/schemas/FormBundle" }, "warnings": { "items": { "$ref": "#/components/schemas/CompileWarning" }, "title": "Warnings", "type": "array" } }, "required": [ "bundle" ], "title": "CompileFormBundleResponse", "type": "object" }, "CompileWarning": { "properties": { "code": { "title": "Code", "type": "string" }, "node_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Node Id" } }, "required": [ "code" ], "title": "CompileWarning", "type": "object" }, "CompleteBulkItemResult": { "properties": { "conflict": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "title": "Conflict" }, "error_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Error Code" }, "id": { "title": "Id", "type": "string" }, "ok": { "title": "Ok", "type": "boolean" }, "result": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "title": "Result" } }, "required": [ "id", "ok" ], "title": "CompleteBulkItemResult", "type": "object" }, "CompleteBulkRequest": { "properties": { "descendant_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Descendant Status" }, "ids": { "items": { "type": "string" }, "maxItems": 200, "minItems": 1, "title": "Ids", "type": "array" }, "mode": { "default": "check", "enum": [ "check", "cascade", "exception" ], "title": "Mode", "type": "string" }, "target_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Target Status" } }, "required": [ "ids" ], "title": "CompleteBulkRequest", "type": "object" }, "CompleteBulkResponse": { "properties": { "results": { "items": { "$ref": "#/components/schemas/CompleteBulkItemResult" }, "title": "Results", "type": "array" } }, "required": [ "results" ], "title": "CompleteBulkResponse", "type": "object" }, "CompleteInstallRequest": { "properties": { "categories": { "items": { "type": "string" }, "title": "Categories", "type": "array" }, "state": { "title": "State", "type": "string" }, "tenant_id": { "title": "Tenant Id", "type": "string" } }, "required": [ "state", "tenant_id" ], "title": "CompleteInstallRequest", "type": "object" }, "CompleteInstallResponse": { "properties": { "redirect_to": { "title": "Redirect To", "type": "string" } }, "required": [ "redirect_to" ], "title": "CompleteInstallResponse", "type": "object" }, "CompleteRequest": { "description": "Completion request. ``check`` is the default (conflict-detecting) mode.", "properties": { "descendant_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Done-category status for descendants (each facet's done default otherwise).", "title": "Descendant Status" }, "mode": { "default": "check", "description": "check: 409 with unfinished descendants (or complete when none); cascade: complete parent + all descendants in one transaction; exception: complete only the parent, recording the open descendants.", "enum": [ "check", "cascade", "exception" ], "title": "Mode", "type": "string" }, "target_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Done-category status for the parent (facet's done default otherwise).", "title": "Target Status" } }, "title": "CompleteRequest", "type": "object" }, "CompleteResponse": { "description": "Result of a completion action.", "properties": { "ancestors_eligible": { "description": "Ancestors whose children are now all finished — offered, never auto-cascaded.", "items": { "additionalProperties": true, "type": "object" }, "title": "Ancestors Eligible", "type": "array" }, "completed": { "description": "Typed ids completed", "items": { "type": "string" }, "title": "Completed", "type": "array" }, "completion_exception": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "title": "Completion Exception" }, "mode": { "title": "Mode", "type": "string" } }, "required": [ "mode" ], "title": "CompleteResponse", "type": "object" }, "CompletedLedgerItemRow": { "description": "One COMPLETED priority-request ledger item (TIDY-11726).\n\nCarries the episode-identity key ``(rss_feed_url, guid)`` so the admin\ntranscript viewer can resolve THIS env's transcript — opened by clicking the\nrow. ``rss_feed_url`` comes from the requesting tenant's subscription; the\ntranscript itself is global and resolved through the corpus ingest log.", "properties": { "completed_at": { "anyOf": [ {}, { "type": "null" } ], "title": "Completed At" }, "created_at": { "title": "Created At" }, "guid": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Guid" }, "request_ref": { "format": "uuid", "title": "Request Ref", "type": "string" }, "rss_feed_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Rss Feed Url" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Title" } }, "required": [ "request_ref", "title", "rss_feed_url", "guid", "completed_at", "created_at" ], "title": "CompletedLedgerItemRow", "type": "object" }, "CompletionAgent": { "properties": { "harness": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Harness" }, "model": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Model" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name" }, "subagent": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Subagent" } }, "title": "CompletionAgent", "type": "object" }, "CompletionCriterion": { "properties": { "status": { "default": "pass", "enum": [ "pass", "fail", "skipped" ], "title": "Status", "type": "string" }, "text": { "title": "Text", "type": "string" } }, "required": [ "text" ], "title": "CompletionCriterion", "type": "object" }, "CompletionReportEntry": { "properties": { "created_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Created At" }, "created_by": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Created By" }, "execution_id": { "title": "Execution Id", "type": "string" }, "report": { "additionalProperties": true, "title": "Report", "type": "object" }, "superseded_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Superseded At" }, "updated_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Updated At" } }, "required": [ "execution_id", "report" ], "title": "CompletionReportEntry", "type": "object" }, "CompletionReportGetResponse": { "properties": { "current": { "anyOf": [ { "$ref": "#/components/schemas/CompletionReportEntry" }, { "type": "null" } ], "default": null }, "history": { "items": { "$ref": "#/components/schemas/CompletionReportEntry" }, "title": "History", "type": "array" }, "id": { "title": "Id", "type": "string" } }, "required": [ "id" ], "title": "CompletionReportGetResponse", "type": "object" }, "CompletionReportPut": { "description": "The report payload. Only execution_id/result/summary are mandatory.", "properties": { "acceptance_criteria": { "items": { "$ref": "#/components/schemas/CompletionCriterion" }, "title": "Acceptance Criteria", "type": "array" }, "agent": { "anyOf": [ { "$ref": "#/components/schemas/CompletionAgent" }, { "type": "null" } ] }, "blockers_deviations": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Blockers Deviations" }, "changed_files": { "items": { "type": "string" }, "title": "Changed Files", "type": "array" }, "commits": { "items": { "type": "string" }, "title": "Commits", "type": "array" }, "ended_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Ended At" }, "execution_id": { "maxLength": 200, "minLength": 1, "title": "Execution Id", "type": "string" }, "requirements": { "items": { "type": "string" }, "title": "Requirements", "type": "array" }, "result": { "enum": [ "success", "failure", "partial" ], "title": "Result", "type": "string" }, "started_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Started At" }, "summary": { "minLength": 1, "title": "Summary", "type": "string" }, "tests": { "anyOf": [ { "$ref": "#/components/schemas/CompletionTests" }, { "type": "null" } ] }, "token_usage": { "anyOf": [ { "$ref": "#/components/schemas/CompletionTokenUsage" }, { "type": "null" } ] } }, "required": [ "execution_id", "result", "summary" ], "title": "CompletionReportPut", "type": "object" }, "CompletionReportPutResponse": { "properties": { "execution_id": { "title": "Execution Id", "type": "string" }, "id": { "title": "Id", "type": "string" }, "superseded_execution_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Superseded Execution Id" } }, "required": [ "id", "execution_id" ], "title": "CompletionReportPutResponse", "type": "object" }, "CompletionTests": { "properties": { "failed": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Failed" }, "passed": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Passed" }, "summary": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Summary" } }, "title": "CompletionTests", "type": "object" }, "CompletionTokenUsage": { "properties": { "input": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Input" }, "output": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Output" } }, "title": "CompletionTokenUsage", "type": "object" }, "ComplianceInfo": { "properties": { "current_streak": { "title": "Current Streak", "type": "integer" }, "days_since_last_contact": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Days Since Last Contact" }, "last_interaction_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Interaction At" }, "periods_checked": { "title": "Periods Checked", "type": "integer" }, "periods_met": { "title": "Periods Met", "type": "integer" }, "status": { "title": "Status", "type": "string" } }, "required": [ "periods_checked", "periods_met", "current_streak", "last_interaction_at", "days_since_last_contact", "status" ], "title": "ComplianceInfo", "type": "object" }, "ComposeAssistRequest": { "properties": { "ai_employee_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Ai Employee Id" }, "draft": { "default": "", "maxLength": 8000, "title": "Draft", "type": "string" }, "instruction": { "maxLength": 1000, "minLength": 1, "title": "Instruction", "type": "string" }, "room_id": { "minLength": 1, "title": "Room Id", "type": "string" } }, "required": [ "room_id", "instruction" ], "title": "ComposeAssistRequest", "type": "object" }, "ComposeAssistResponse": { "properties": { "elapsed_ms": { "title": "Elapsed Ms", "type": "integer" }, "suggestion": { "title": "Suggestion", "type": "string" } }, "required": [ "suggestion", "elapsed_ms" ], "title": "ComposeAssistResponse", "type": "object" }, "ComputeDailyResponse": { "properties": { "badges_checked": { "title": "Badges Checked", "type": "integer" }, "badges_earned": { "title": "Badges Earned", "type": "integer" }, "streaks_evaluated": { "title": "Streaks Evaluated", "type": "integer" } }, "required": [ "streaks_evaluated", "badges_earned", "badges_checked" ], "title": "ComputeDailyResponse", "type": "object" }, "ConditionClause": { "additionalProperties": false, "description": "One field comparison. ``field`` is a trigger-context path: an item\nfield name (or ``item.``), ``old_value`` / ``new_value``, or a\none-hop link-neighborhood path ``item.[.]``.", "properties": { "field": { "minLength": 1, "title": "Field", "type": "string" }, "operator": { "enum": [ "equals", "not_equals", "contains", "is_empty", "not_empty", "gt", "lt", "email_equals", "is_role_mailbox", "not_role_mailbox", "is_freemail", "not_freemail", "is_tenant_owned_domain", "not_tenant_owned_domain" ], "title": "Operator", "type": "string" }, "value": { "anyOf": [ {}, { "type": "null" } ], "title": "Value" } }, "required": [ "field", "operator" ], "title": "ConditionClause", "type": "object" }, "ConditionGroup": { "additionalProperties": false, "description": "Flat and/or group. Deeper nesting is rejected in v1 (D11) — ``clauses``\nholds clauses only, never groups.", "properties": { "clauses": { "items": { "$ref": "#/components/schemas/ConditionClause" }, "title": "Clauses", "type": "array" }, "op": { "default": "and", "enum": [ "and", "or" ], "title": "Op", "type": "string" } }, "title": "ConditionGroup", "type": "object" }, "ConfigurableEmployee": { "description": "An employee the caller may configure — identity only (TIDY-19569 R5d).", "properties": { "agent_account_id": { "title": "Agent Account Id", "type": "string" }, "display_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Display Name" }, "mention_handle": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Mention Handle" }, "slug": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Slug" } }, "required": [ "agent_account_id" ], "title": "ConfigurableEmployee", "type": "object" }, "ConfigurableEmployeeList": { "properties": { "employees": { "items": { "$ref": "#/components/schemas/ConfigurableEmployee" }, "title": "Employees", "type": "array" } }, "required": [ "employees" ], "title": "ConfigurableEmployeeList", "type": "object" }, "ConfigurationChange": { "description": "Who last changed one of an employee's settings (TIDY-20154).", "properties": { "at": { "format": "date-time", "title": "At", "type": "string" }, "by_account_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "By Account Id" }, "by_name": { "description": "The person or employee who changed it.", "title": "By Name", "type": "string" } }, "required": [ "by_name", "at" ], "title": "ConfigurationChange", "type": "object" }, "ConflictAcknowledgeRequest": { "description": "Record \"Conflict's OK\" — the member looked at the overlap and it is fine.", "properties": { "expected_version": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "The version the client rendered. A card that moved underneath the member refuses rather than recording a decision about something they never saw.", "title": "Expected Version" }, "source_proposal_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Narrow to one entry. Omitted acknowledges every entry the card currently carries, which is what the card's own action means.", "title": "Source Proposal Id" } }, "title": "ConflictAcknowledgeRequest", "type": "object" }, "ConflictAcknowledgeResponse": { "properties": { "acknowledged": { "title": "Acknowledged", "type": "boolean" }, "card_id": { "title": "Card Id", "type": "string" }, "version": { "title": "Version", "type": "integer" } }, "required": [ "card_id", "acknowledged", "version" ], "title": "ConflictAcknowledgeResponse", "type": "object" }, "ConflictCard": { "description": "One card: everything blocking one change, plus how to resolve it.", "properties": { "created_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "When this card was created (blocked creates only). The anchor the assistant's member-message attestation is checked against.", "title": "Created At" }, "entries": { "items": { "$ref": "#/components/schemas/ConflictCardEntry" }, "title": "Entries", "type": "array" }, "event_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The blocked event; null for a blocked create.", "title": "Event Id" }, "id": { "description": "The event id, or the pending-create row id.", "title": "Id", "type": "string" }, "multiple_conflicts": { "default": false, "description": "The annotation evicted entries past its ten-entry cap.", "title": "Multiple Conflicts", "type": "boolean" }, "origin": { "enum": [ "event", "pending_create" ], "title": "Origin", "type": "string" }, "pending_create_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Pending Create Id" }, "proposed_event": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "What the blocked CREATE asked for.", "title": "Proposed Event" }, "requested_end": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Requested End" }, "requested_start": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Requested Start" }, "timezone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Timezone" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Title" }, "total_conflict_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Total Conflict Count" }, "version": { "description": "The compare-and-swap version this card was read at — pass it as `expected_version` so an apply refuses a card that has moved.", "title": "Version", "type": "integer" } }, "required": [ "id", "origin", "version" ], "title": "ConflictCard", "type": "object" }, "ConflictCardEntry": { "description": "One persisted conflict entry, verbatim.", "properties": { "acknowledged": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "The member's acknowledgment of THIS conflict ({account_id, at, via}), verbatim as persisted. Null means the entry is still unanswered and blocks.", "title": "Acknowledged" }, "availability_truncated": { "default": false, "title": "Availability Truncated", "type": "boolean" }, "conflict_kind": { "title": "Conflict Kind", "type": "string" }, "conflicting_event_ids": { "items": { "type": "string" }, "title": "Conflicting Event Ids", "type": "array" }, "detected_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Detected At" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error" }, "evaluated_through": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Evaluated Through" }, "input_watermark": { "title": "Input Watermark", "type": "string" }, "not_evaluated_beyond": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The horizon the proposals were NOT evaluated past. A client MUST render this rather than implying the whole range was checked.", "title": "Not Evaluated Beyond" }, "provider": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Provider" }, "resolution_proposals": { "description": "TIDY-15404 proposals as persisted. `provider_action` decides whether a proposal may be applied locally or only countered. `kind` is `alternative` (a different time) or `admit_as_requested` (the original time and recurrence, confirming that occurrences beyond the evaluation horizon are unevaluated); absent means `alternative`.", "items": { "additionalProperties": true, "type": "object" }, "title": "Resolution Proposals", "type": "array" }, "source_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Source Id" }, "source_kind": { "title": "Source Kind", "type": "string" }, "source_proposal_id": { "title": "Source Proposal Id", "type": "string" }, "status": { "title": "Status", "type": "string" } }, "required": [ "source_proposal_id", "source_kind", "conflict_kind", "input_watermark", "status" ], "title": "ConflictCardEntry", "type": "object" }, "ConflictCardListResponse": { "properties": { "cards": { "items": { "$ref": "#/components/schemas/ConflictCard" }, "title": "Cards", "type": "array" }, "truncated": { "default": false, "description": "More than 50 cards exist; these are the oldest.", "title": "Truncated", "type": "boolean" } }, "title": "ConflictCardListResponse", "type": "object" }, "ConflictCheckRequest": { "description": "Request model for conflict detection.", "properties": { "all_day": { "default": false, "description": "Treat the range as an all-day date range", "title": "All Day", "type": "boolean" }, "end_time": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "End Time" }, "exclude_event_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Event ID to exclude from conflict check (for updates)", "title": "Exclude Event Id" }, "ical_uid": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Normalized iCalUID. The only identity used for double-booking and provider-divergence detection; without it neither is inferred from title or proximity.", "title": "Ical Uid" }, "recurrence_rule": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Bare RRULE value, e.g. FREQ=WEEKLY;BYDAY=MO", "title": "Recurrence Rule" }, "recurrence_scope": { "default": "this_occurrence", "description": "Which occurrences the mutation affects: this_occurrence | future | series", "title": "Recurrence Scope", "type": "string" }, "resource_ids": { "description": "Room/resource identifiers the event claims", "items": { "type": "string" }, "title": "Resource Ids", "type": "array" }, "start_time": { "format": "date-time", "title": "Start Time", "type": "string" }, "timezone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "IANA timezone for all-day and floating values. Required when all_day is true — an all-day range is anchored to local midnight, never UTC midnight, and no timezone is ever assumed.", "title": "Timezone" }, "travel_buffer_after_minutes": { "default": 0, "description": "Travel time needed after the event; participates in detection", "minimum": 0.0, "title": "Travel Buffer After Minutes", "type": "integer" }, "travel_buffer_before_minutes": { "default": 0, "description": "Travel time needed before the event; participates in detection", "minimum": 0.0, "title": "Travel Buffer Before Minutes", "type": "integer" } }, "required": [ "start_time" ], "title": "ConflictCheckRequest", "type": "object" }, "ConflictCheckResponse": { "description": "Response model for conflict detection.\n\n``has_conflicts`` keeps its original meaning. ``truncated`` is the field that\nmatters for correctness: when it is true the evaluation did NOT cover the\nwhole series or the whole availability set, so an empty ``conflicts`` list\nmust never be presented as \"no conflicts\" — surface the warning instead.", "properties": { "conflicts": { "items": { "$ref": "#/components/schemas/ConflictDetails" }, "title": "Conflicts", "type": "array" }, "evaluated_occurrence_count": { "default": 0, "description": "Occurrences expanded and checked", "title": "Evaluated Occurrence Count", "type": "integer" }, "evaluated_through": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "description": "Last instant actually covered by the evaluation", "title": "Evaluated Through" }, "has_conflicts": { "title": "Has Conflicts", "type": "boolean" }, "truncated": { "default": false, "description": "The evaluation was bounded (series past the 180-day/1,000-occurrence horizon, or availability past the 500-interval cap). Callers must not claim globally conflict-free when this is true.", "title": "Truncated", "type": "boolean" }, "warnings": { "description": "Typed warnings, e.g. truncated_beyond_horizon, availability_unknown:", "items": { "type": "string" }, "title": "Warnings", "type": "array" } }, "required": [ "has_conflicts" ], "title": "ConflictCheckResponse", "type": "object" }, "ConflictDetails": { "description": "Details of a conflicting event.\n\nThe original four fields are unchanged; everything below them is additive so\na client that predates TIDY-15403 keeps working against the same payload.", "properties": { "conflict_kind": { "default": "overlap", "description": "overlap | double_booking | focus_block | attendee_unavailable | resource_unavailable | provider_divergence", "title": "Conflict Kind", "type": "string" }, "end_time": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "End Time" }, "id": { "title": "Id", "type": "string" }, "overlap_minutes": { "description": "Number of minutes of overlap", "title": "Overlap Minutes", "type": "integer" }, "provider": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Provider that reported the conflict, when it came from free/busy", "title": "Provider" }, "source_event_ids": { "description": "Canonical event ids this conflict refers to", "items": { "type": "string" }, "title": "Source Event Ids", "type": "array" }, "start_time": { "format": "date-time", "title": "Start Time", "type": "string" }, "title": { "title": "Title", "type": "string" } }, "required": [ "id", "title", "start_time", "end_time", "overlap_minutes" ], "title": "ConflictDetails", "type": "object" }, "ConflictDismissRequest": { "description": "Withdraw one conflict entry without applying anything.", "properties": { "event_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The event the entry is annotated on. Omit for a blocked create, whose row is found by source_proposal_id alone.", "title": "Event Id" }, "expected_version": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "The version the client rendered. Omitted means 'whatever is stored now', which is only safe for an unattended cleanup.", "title": "Expected Version" } }, "title": "ConflictDismissRequest", "type": "object" }, "ConflictDismissResponse": { "properties": { "dismissed": { "title": "Dismissed", "type": "boolean" }, "source_proposal_id": { "title": "Source Proposal Id", "type": "string" }, "version": { "title": "Version", "type": "integer" } }, "required": [ "source_proposal_id", "dismissed", "version" ], "title": "ConflictDismissResponse", "type": "object" }, "ConflictPriorityComparison": { "description": "The comparator's verdict for the subject vs ONE conflicting event.", "properties": { "explanation": { "title": "Explanation", "type": "string" }, "other_event_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Other Event Id" }, "other_vector": { "anyOf": [ { "items": { "type": "integer" }, "type": "array" }, { "type": "null" } ], "title": "Other Vector" }, "outcome": { "enum": [ "decisive", "tie", "insufficient_evidence" ], "title": "Outcome", "type": "string" }, "resolution_mode": { "anyOf": [ { "enum": [ "move", "move_with_confirmation", "propose_or_surface" ], "type": "string" }, { "type": "null" } ], "title": "Resolution Mode" }, "subject_event_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Subject Event Id" }, "subject_vector": { "anyOf": [ { "items": { "type": "integer" }, "type": "array" }, { "type": "null" } ], "title": "Subject Vector" }, "veto_applied": { "default": false, "description": "The yielding event starts within 48h and is therefore never moved — the plan must propose or surface instead (R4.2 veto).", "title": "Veto Applied", "type": "boolean" }, "yielding_event_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Yielding Event Id" } }, "required": [ "outcome", "explanation" ], "title": "ConflictPriorityComparison", "type": "object" }, "ConflictPriorityEventFeatures": { "description": "Deterministic evidence for one event involved in a conflict (TIDY-16596).\n\nAssembled server-side from persisted rows — no LLM. The\ncalendar-conflict-manager skill consumes this instead of re-deriving\nfacts, which is the hallucination guard (D-features-server-side).", "properties": { "auto_created": { "default": false, "description": "True when this is a still-pending item Tidy created itself (event_status pending/pending_review AND source_type email or agent) — the ONLY target a reject_pending resolution may act on.", "title": "Auto Created", "type": "boolean" }, "confirmed": { "default": false, "description": "A real, confirmed calendar item (approved + CONFIRMED) — the counterpart that makes a pending auto-created duplicate safe to auto-reject.", "title": "Confirmed", "type": "boolean" }, "end_time": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "End Time" }, "event_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Null for a blocked create's requested event.", "title": "Event Id" }, "event_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The review lifecycle state (pending | approved | rejected | cancelled | pending_review); null when not visible or for a blocked create's requested event.", "title": "Event Status" }, "ical_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The iCal status (CONFIRMED | TENTATIVE | CANCELLED).", "title": "Ical Status" }, "imminence_hours": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Hours until the event starts (negative if started).", "title": "Imminence Hours" }, "move_vetoed": { "default": false, "description": "This event starts within 48 hours: an own (organized/solo) event moves only with the member's explicit confirmation given in the conversation after the preview; an attendee (someone else's) event is never moved at all (R4.2 veto, stated per event — moving the OTHER event instead does not avoid it when that one is vetoed too).", "title": "Move Vetoed", "type": "boolean" }, "other_attendee_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Other Attendee Count" }, "role": { "anyOf": [ { "enum": [ "organizer", "attendee", "solo" ], "type": "string" }, { "type": "null" } ], "title": "Role" }, "severity": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Worst severity among the entries naming this event.", "title": "Severity" }, "source_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Row provenance (manual | email | calendar_sync | agent); email and agent rows are machine-derived.", "title": "Source Type" }, "standing": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Part of a recurring/standing series.", "title": "Standing" }, "start_time": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Start Time" }, "subject": { "description": "True for the card's own event (or requested create).", "title": "Subject", "type": "boolean" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Title" }, "visible": { "description": "False when the event is outside the member's visibility; every feature field is then null rather than guessed at.", "title": "Visible", "type": "boolean" } }, "required": [ "subject", "visible" ], "title": "ConflictPriorityEventFeatures", "type": "object" }, "ConflictPriorityFeaturesResponse": { "description": "GET /conflicts/{card_id}/priority-features (TIDY-16596).", "properties": { "card_id": { "title": "Card Id", "type": "string" }, "comparisons": { "items": { "$ref": "#/components/schemas/ConflictPriorityComparison" }, "title": "Comparisons", "type": "array" }, "created_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Created At" }, "entries": { "description": "The card's conflict entries, verbatim as persisted.", "items": { "$ref": "#/components/schemas/ConflictCardEntry" }, "title": "Entries", "type": "array" }, "evaluated_at": { "format": "date-time", "title": "Evaluated At", "type": "string" }, "events": { "items": { "$ref": "#/components/schemas/ConflictPriorityEventFeatures" }, "title": "Events", "type": "array" }, "origin": { "enum": [ "event", "pending_create" ], "title": "Origin", "type": "string" }, "plan_constraints": { "description": "Binding, deterministically-assembled constraints on any resolution plan (per-event 48h move-vetoes; the no-inferred-direction rule). A consumer that plans against this payload honors every line.", "items": { "type": "string" }, "title": "Plan Constraints", "type": "array" }, "version": { "title": "Version", "type": "integer" } }, "required": [ "card_id", "origin", "version", "evaluated_at" ], "title": "ConflictPriorityFeaturesResponse", "type": "object" }, "ConflictResolutionApplyRequest": { "description": "One proposal, chosen off one conflict entry.", "properties": { "expected_version": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "The change_pending version the client rendered. When supplied, an annotation that moved under the caller refuses with 409 rather than applying against a card the user never saw.", "title": "Expected Version" }, "proposal_id": { "description": "The proposal_id carried in the entry's resolution_proposals. Deterministic, so re-reading the card and picking the same slot yields the same id.", "title": "Proposal Id", "type": "string" } }, "required": [ "proposal_id" ], "title": "ConflictResolutionApplyRequest", "type": "object" }, "ConflictResolutionApplyResponse": { "description": "The outcome of an apply — including the two idempotent no-ops.", "properties": { "already_resolved": { "default": false, "description": "The entry was already withdrawn — a replayed apply, not a failure. Nothing was written and nothing is owed.", "title": "Already Resolved", "type": "boolean" }, "applied": { "description": "Whether this call moved the event.", "title": "Applied", "type": "boolean" }, "end_time": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "End Time" }, "event_id": { "title": "Event Id", "type": "string" }, "start_time": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Start Time" }, "version": { "description": "The change_pending version now stored.", "title": "Version", "type": "integer" }, "warnings": { "items": { "type": "string" }, "title": "Warnings", "type": "array" } }, "required": [ "event_id", "applied", "version" ], "title": "ConflictResolutionApplyResponse", "type": "object" }, "ConnectedAgentItem": { "properties": { "active_token_count": { "title": "Active Token Count", "type": "integer" }, "client_id": { "title": "Client Id", "type": "string" }, "client_pk_id": { "title": "Client Pk Id", "type": "string" }, "client_type": { "title": "Client Type", "type": "string" }, "first_bound_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "First Bound At" }, "homepage_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Homepage Url" }, "last_used_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Last Used At" }, "logo_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Logo Url" }, "name": { "title": "Name", "type": "string" }, "review_status": { "title": "Review Status", "type": "string" }, "scopes": { "items": { "type": "string" }, "title": "Scopes", "type": "array" }, "software_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Software Id" } }, "required": [ "client_pk_id", "client_id", "name", "client_type", "review_status", "scopes", "active_token_count" ], "title": "ConnectedAgentItem", "type": "object" }, "ConnectedAppItem": { "properties": { "app_id": { "title": "App Id", "type": "string" }, "authorized_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Authorized At" }, "client_id": { "title": "Client Id", "type": "string" }, "granted_scopes": { "items": { "type": "string" }, "title": "Granted Scopes", "type": "array" }, "homepage_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Homepage Url" }, "last_used_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Last Used At" }, "logo_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Logo Url" }, "name": { "title": "Name", "type": "string" } }, "required": [ "app_id", "client_id", "name", "granted_scopes" ], "title": "ConnectedAppItem", "type": "object" }, "ConnectionCreate": { "additionalProperties": false, "properties": { "authorization": { "$ref": "#/components/schemas/ProviderAuthorization" }, "label": { "maxLength": 200, "minLength": 1, "title": "Label", "type": "string" }, "provider": { "enum": [ "digitalocean", "hetzner", "lightsail", "ovh" ], "title": "Provider", "type": "string" }, "request_key": { "anyOf": [ { "maxLength": 128, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Request Key" } }, "required": [ "provider", "label", "authorization" ], "title": "ConnectionCreate", "type": "object" }, "ConnectionList": { "properties": { "connections": { "items": { "$ref": "#/components/schemas/ConnectionResponse" }, "title": "Connections", "type": "array" } }, "required": [ "connections" ], "title": "ConnectionList", "type": "object" }, "ConnectionPolicyResponse": { "description": "Response for GET /api/v1/account/connection-policy.", "properties": { "account_id": { "title": "Account Id", "type": "string" }, "allowed_domains": { "default": [], "items": { "type": "string" }, "title": "Allowed Domains", "type": "array" }, "policy": { "enum": [ "unrestricted", "domain_restricted", "admin_provisioned" ], "title": "Policy", "type": "string" }, "updated_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Updated At" }, "updated_by": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Updated By" } }, "required": [ "account_id", "policy" ], "title": "ConnectionPolicyResponse", "type": "object" }, "ConnectionPolicyUpdateRequest": { "description": "Request for PUT /api/v1/account/connection-policy.", "properties": { "allowed_domains": { "default": [], "description": "Allowed email domains (required when policy is domain_restricted)", "items": { "type": "string" }, "title": "Allowed Domains", "type": "array" }, "policy": { "description": "One of: unrestricted, domain_restricted, admin_provisioned", "title": "Policy", "type": "string" } }, "required": [ "policy" ], "title": "ConnectionPolicyUpdateRequest", "type": "object" }, "ConnectionResponse": { "properties": { "auth_generation": { "title": "Auth Generation", "type": "integer" }, "authorization_setup": { "anyOf": [ { "$ref": "#/components/schemas/LightsailRoleSetup" }, { "type": "null" } ], "default": null }, "connection_id": { "format": "uuid", "title": "Connection Id", "type": "string" }, "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "external_account_ref": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "External Account Ref" }, "label": { "title": "Label", "type": "string" }, "provider": { "enum": [ "digitalocean", "hetzner", "lightsail", "ovh" ], "title": "Provider", "type": "string" }, "record_id": { "format": "uuid", "title": "Record Id", "type": "string" }, "status": { "enum": [ "pending", "working", "needs_reauth", "disconnected" ], "title": "Status", "type": "string" }, "updated_at": { "format": "date-time", "title": "Updated At", "type": "string" } }, "required": [ "connection_id", "record_id", "provider", "label", "status", "auth_generation", "created_at", "updated_at" ], "title": "ConnectionResponse", "type": "object" }, "ConnectionStatus": { "description": "Mail plugin status — the one vocabulary every plugin row carries (TIDY-18240).\n\nA transient sync problem is ``sync_error`` on a ``working`` plugin, not a\nstatus of its own.", "enum": [ "pending", "working", "needs_reauth", "disconnected" ], "title": "ConnectionStatus", "type": "string" }, "ConnectorBundleV2": { "properties": { "agent_account_id": { "format": "uuid", "title": "Agent Account Id", "type": "string" }, "agent_member_id": { "format": "uuid", "title": "Agent Member Id", "type": "string" }, "api_base_url": { "title": "Api Base Url", "type": "string" }, "display_name": { "title": "Display Name", "type": "string" }, "matrix_allowed_users": { "items": { "type": "string" }, "title": "Matrix Allowed Users", "type": "array" }, "matrix_bootstrap_access_token": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Matrix Bootstrap Access Token" }, "matrix_bootstrap_device_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Matrix Bootstrap Device Id" }, "matrix_home_room_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Matrix Home Room Id" }, "matrix_homeserver_url": { "title": "Matrix Homeserver Url", "type": "string" }, "matrix_user_id": { "title": "Matrix User Id", "type": "string" }, "runtime_bearer_token": { "title": "Runtime Bearer Token", "type": "string" }, "runtime_token_expires_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Runtime Token Expires At" }, "runtime_token_id": { "format": "uuid", "title": "Runtime Token Id", "type": "string" }, "schema_version": { "const": 2, "default": 2, "title": "Schema Version", "type": "integer" }, "slug": { "title": "Slug", "type": "string" }, "tenant_id": { "format": "uuid", "title": "Tenant Id", "type": "string" } }, "required": [ "agent_account_id", "agent_member_id", "display_name", "slug", "tenant_id", "api_base_url", "runtime_bearer_token", "runtime_token_id", "matrix_homeserver_url", "matrix_user_id" ], "title": "ConnectorBundleV2", "type": "object" }, "ConsentDecisionBody": { "properties": { "decision": { "description": "`accept` or `decline`.", "title": "Decision", "type": "string" } }, "required": [ "decision" ], "title": "ConsentDecisionBody", "type": "object" }, "ConsentListResponse": { "description": "Response for consent list.", "properties": { "consents": { "items": { "$ref": "#/components/schemas/ParentalConsentResponse" }, "title": "Consents", "type": "array" }, "total": { "title": "Total", "type": "integer" } }, "required": [ "consents", "total" ], "title": "ConsentListResponse", "type": "object" }, "ConsentRecorded": { "properties": { "consent_state": { "title": "Consent State", "type": "string" }, "id": { "title": "Id", "type": "string" } }, "required": [ "id", "consent_state" ], "title": "ConsentRecorded", "type": "object" }, "ConsentScope": { "description": "What the parent consented to.", "properties": { "data_collection": { "default": true, "description": "Collect child's data", "title": "Data Collection", "type": "boolean" }, "email_processing": { "default": true, "description": "Process child-related emails", "title": "Email Processing", "type": "boolean" }, "event_extraction": { "default": true, "description": "Extract events/tasks", "title": "Event Extraction", "type": "boolean" }, "third_party_sharing": { "default": false, "description": "Share with third parties", "title": "Third Party Sharing", "type": "boolean" } }, "title": "ConsentScope", "type": "object" }, "ConsentStatus": { "description": "Parental consent status.", "enum": [ "pending", "granted", "revoked", "expired" ], "title": "ConsentStatus", "type": "string" }, "ConsumerLeaseAcquireRequest": { "properties": { "boot_id": { "format": "uuid", "title": "Boot Id", "type": "string" }, "crypto_store_device_id": { "anyOf": [ { "maxLength": 255, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Crypto Store Device Id" }, "host_continuity_token": { "maxLength": 512, "minLength": 32, "title": "Host Continuity Token", "type": "string" }, "host_instance_id": { "format": "uuid", "title": "Host Instance Id", "type": "string" }, "idempotency_key": { "format": "uuid", "title": "Idempotency Key", "type": "string" }, "installation_id": { "format": "uuid", "title": "Installation Id", "type": "string" }, "machine_fingerprint": { "maxLength": 512, "minLength": 16, "title": "Machine Fingerprint", "type": "string" }, "mode": { "enum": [ "fresh", "restart", "legacy_migration", "stale_takeover", "forced_takeover" ], "title": "Mode", "type": "string" }, "runtime_host": { "maxLength": 255, "minLength": 1, "title": "Runtime Host", "type": "string" }, "ttl_seconds": { "const": 120, "default": 120, "title": "Ttl Seconds", "type": "integer" } }, "required": [ "installation_id", "boot_id", "host_instance_id", "machine_fingerprint", "host_continuity_token", "idempotency_key", "runtime_host", "mode" ], "title": "ConsumerLeaseAcquireRequest", "type": "object" }, "ConsumerLeaseAcquireResponse": { "properties": { "boot_id": { "format": "uuid", "title": "Boot Id", "type": "string" }, "expires_at": { "format": "date-time", "title": "Expires At", "type": "string" }, "generation": { "title": "Generation", "type": "integer" }, "host_continuity_token": { "title": "Host Continuity Token", "type": "string" }, "installation_id": { "format": "uuid", "title": "Installation Id", "type": "string" }, "matrix_access_token": { "title": "Matrix Access Token", "type": "string" }, "matrix_allowed_users": { "items": { "type": "string" }, "title": "Matrix Allowed Users", "type": "array" }, "matrix_device_id": { "title": "Matrix Device Id", "type": "string" }, "migration_rollback_receipt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Migration Rollback Receipt" }, "receipt_id": { "format": "uuid", "title": "Receipt Id", "type": "string" }, "status": { "const": "active", "title": "Status", "type": "string" } }, "required": [ "status", "receipt_id", "installation_id", "boot_id", "generation", "expires_at", "host_continuity_token", "matrix_access_token", "matrix_device_id" ], "title": "ConsumerLeaseAcquireResponse", "type": "object" }, "ConsumerLeaseKnownLists": { "description": "The revisions of the lists a renewing box holds from earlier renewals.", "properties": { "allowlist": { "anyOf": [ { "pattern": "^[0-9a-f]{32}$", "type": "string" }, { "type": "null" } ], "title": "Allowlist" }, "colleagues": { "anyOf": [ { "pattern": "^[0-9a-f]{32}$", "type": "string" }, { "type": "null" } ], "title": "Colleagues" } }, "title": "ConsumerLeaseKnownLists", "type": "object" }, "ConsumerLeaseListRevisions": { "description": "The revision of each list a renewal answer carries.", "properties": { "allowlist": { "anyOf": [ { "pattern": "^[0-9a-f]{32}$", "type": "string" }, { "type": "null" } ], "default": null, "title": "Allowlist" }, "colleagues": { "anyOf": [ { "pattern": "^[0-9a-f]{32}$", "type": "string" }, { "type": "null" } ], "default": null, "title": "Colleagues" } }, "title": "ConsumerLeaseListRevisions", "type": "object" }, "ConsumerLeaseMaterialization": { "description": "TIDY-19869 F7: whether what the employee's box materializes moved.", "properties": { "pending": { "title": "Pending", "type": "boolean" }, "stamp": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Stamp" } }, "required": [ "stamp", "pending" ], "title": "ConsumerLeaseMaterialization", "type": "object" }, "ConsumerLeaseReleaseRequest": { "properties": { "boot_id": { "format": "uuid", "title": "Boot Id", "type": "string" }, "generation": { "minimum": 1.0, "title": "Generation", "type": "integer" }, "installation_id": { "format": "uuid", "title": "Installation Id", "type": "string" }, "request_id": { "format": "uuid", "title": "Request Id", "type": "string" } }, "required": [ "installation_id", "boot_id", "generation", "request_id" ], "title": "ConsumerLeaseReleaseRequest", "type": "object" }, "ConsumerLeaseRenewRequest": { "properties": { "boot_id": { "format": "uuid", "title": "Boot Id", "type": "string" }, "generation": { "minimum": 1.0, "title": "Generation", "type": "integer" }, "installation_id": { "format": "uuid", "title": "Installation Id", "type": "string" }, "known": { "anyOf": [ { "$ref": "#/components/schemas/ConsumerLeaseKnownLists" }, { "type": "null" } ] } }, "required": [ "installation_id", "boot_id", "generation" ], "title": "ConsumerLeaseRenewRequest", "type": "object" }, "ConsumerLeaseStatusResponse": { "properties": { "active_budgets": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "title": "Active Budgets" }, "expires_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Expires At" }, "generation": { "default": 0, "title": "Generation", "type": "integer" }, "installation_host_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "default": null, "title": "Installation Host Id" }, "last_renewed_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Last Renewed At" }, "lifecycle_state": { "anyOf": [ { "enum": [ "provisioned", "active", "paused", "retired" ], "type": "string" }, { "type": "null" } ], "default": null, "title": "Lifecycle State" }, "materialization": { "anyOf": [ { "$ref": "#/components/schemas/ConsumerLeaseMaterialization" }, { "type": "null" } ], "default": null }, "matrix_allowed_users": { "items": { "type": "string" }, "title": "Matrix Allowed Users", "type": "array" }, "matrix_colleague_users": { "items": { "type": "string" }, "title": "Matrix Colleague Users", "type": "array" }, "portable_owned": { "default": false, "title": "Portable Owned", "type": "boolean" }, "revisions": { "anyOf": [ { "$ref": "#/components/schemas/ConsumerLeaseListRevisions" }, { "type": "null" } ], "default": null }, "runtime_host": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Runtime Host" }, "server_time": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Server Time" }, "state": { "title": "State", "type": "string" }, "takeover_eligible": { "default": false, "title": "Takeover Eligible", "type": "boolean" }, "unchanged": { "anyOf": [ { "items": { "enum": [ "allowlist", "colleagues" ], "type": "string" }, "type": "array" }, { "type": "null" } ], "default": null, "title": "Unchanged" } }, "required": [ "state" ], "title": "ConsumerLeaseStatusResponse", "type": "object" }, "ContactAliasCreate": { "description": "Body for POST /api/v1/contacts/{contact_id}/aliases (manual create).", "properties": { "alias_name": { "description": "Free-form alias as the user types it (preserved verbatim).", "examples": [ "Miss Shari" ], "maxLength": 200, "minLength": 1, "title": "Alias Name", "type": "string" }, "alias_type": { "default": "other", "description": "Categorization hint: honorific (Miss/Dr.), nickname (Bobby), maiden_name, alternate_spelling, transliteration, extracted (LLM-derived), or other.", "enum": [ "honorific", "nickname", "maiden_name", "alternate_spelling", "transliteration", "extracted", "other" ], "title": "Alias Type", "type": "string" } }, "required": [ "alias_name" ], "title": "ContactAliasCreate", "type": "object" }, "ContactAliasResponse": { "description": "Single alias row as returned by the API.", "properties": { "alias_name": { "description": "As stored — preserves original casing.", "title": "Alias Name", "type": "string" }, "alias_normalized": { "description": "Normalized form used by the matcher (lowercase, NFKD, no diacritics).", "title": "Alias Normalized", "type": "string" }, "alias_type": { "description": "Alias category.", "enum": [ "honorific", "nickname", "maiden_name", "alternate_spelling", "transliteration", "extracted", "other" ], "title": "Alias Type", "type": "string" }, "contact_id": { "description": "Owning contact UUID.", "title": "Contact Id", "type": "string" }, "created_at": { "description": "Insertion timestamp (ISO UTC).", "format": "date-time", "title": "Created At", "type": "string" }, "created_by": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "account_id of the manual creator; NULL for merge/extraction sources.", "title": "Created By" }, "id": { "description": "Alias UUID.", "title": "Id", "type": "string" }, "source": { "description": "Provenance: extraction (LLM-derived), merge (auto-generated when a pending contact was absorbed), or manual (user added).", "enum": [ "extraction", "merge", "manual" ], "title": "Source", "type": "string" }, "source_contact_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "When source='merge': the secondary contact whose name became this alias. NULL after that secondary is deleted (ON DELETE SET NULL).", "title": "Source Contact Id" }, "tenant_id": { "description": "Tenant UUID.", "title": "Tenant Id", "type": "string" } }, "required": [ "id", "contact_id", "tenant_id", "alias_name", "alias_normalized", "alias_type", "source", "created_at" ], "title": "ContactAliasResponse", "type": "object" }, "ContactAnalyticsResponse": { "properties": { "avg_response_time_theirs": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Avg Response Time Theirs" }, "avg_response_time_yours": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Avg Response Time Yours" }, "by_period": { "items": { "$ref": "#/components/schemas/VolumePeriod" }, "title": "By Period", "type": "array" }, "categories": { "additionalProperties": { "type": "integer" }, "title": "Categories", "type": "object" }, "contact_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Contact Id" }, "data_quality": { "enum": [ "good", "limited" ], "title": "Data Quality", "type": "string" }, "email_addresses": { "items": { "type": "string" }, "title": "Email Addresses", "type": "array" }, "engagement": { "anyOf": [ { "$ref": "#/components/schemas/SenderEngagementMetrics" }, { "type": "null" } ] }, "first_contact": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "First Contact" }, "last_contact": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Contact" }, "thread_count": { "title": "Thread Count", "type": "integer" }, "top_threads": { "items": { "$ref": "#/components/schemas/TopThread" }, "title": "Top Threads", "type": "array" }, "total_received": { "title": "Total Received", "type": "integer" }, "total_sent": { "title": "Total Sent", "type": "integer" }, "trend": { "title": "Trend", "type": "string" } }, "required": [ "email_addresses", "total_received", "total_sent", "thread_count", "avg_response_time_yours", "avg_response_time_theirs", "by_period", "top_threads", "categories", "trend", "first_contact", "last_contact", "data_quality" ], "title": "ContactAnalyticsResponse", "type": "object" }, "ContactApprovalDestination": { "description": "Where to route an approved contact.\n\n`keep_private` (default): contact stays at its current owner/visibility.\n`share_to_container`: link the contact to a project/notebook the user\n has can_edit on; contact owner is unchanged.\n`promote_global`: tenant-wide contact (owner_type='account', visibility='shared').\n`merge_into_contact` (TIDY-8666): absorb the pending contact into an\n existing approved one. The pending row is consumed by the merge;\n its name becomes an alias on the target; the source email's match\n keys land in resolution memory; the merge is queued for graph sync.", "properties": { "container_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Container Id" }, "container_type": { "anyOf": [ { "enum": [ "project", "notebook" ], "type": "string" }, { "type": "null" } ], "title": "Container Type" }, "kind": { "default": "keep_private", "enum": [ "keep_private", "share_to_container", "promote_global", "merge_into_contact" ], "title": "Kind", "type": "string" }, "target_contact_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Target Contact Id" } }, "title": "ContactApprovalDestination", "type": "object" }, "ContactApprovalRequest": { "description": "POST /api/v1/review/contacts/{id}/approve body.", "properties": { "destination": { "anyOf": [ { "$ref": "#/components/schemas/ContactApprovalDestination" }, { "type": "null" } ] }, "thumb": { "anyOf": [ { "enum": [ "up", "down" ], "type": "string" }, { "type": "null" } ], "title": "Thumb" } }, "title": "ContactApprovalRequest", "type": "object" }, "ContactApprovalResponse": { "properties": { "approval_status": { "title": "Approval Status", "type": "string" }, "contact_id": { "title": "Contact Id", "type": "string" }, "linked_to": { "items": { "$ref": "#/components/schemas/ContactLinkedContainer" }, "title": "Linked To", "type": "array" }, "owner_id": { "title": "Owner Id", "type": "string" }, "owner_type": { "title": "Owner Type", "type": "string" }, "visibility": { "title": "Visibility", "type": "string" } }, "required": [ "contact_id", "owner_id", "owner_type", "visibility", "approval_status" ], "title": "ContactApprovalResponse", "type": "object" }, "ContactBulkItemResult": { "properties": { "contact_id": { "title": "Contact Id", "type": "string" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error" } }, "required": [ "contact_id" ], "title": "ContactBulkItemResult", "type": "object" }, "ContactBulkRequest": { "properties": { "action": { "enum": [ "approve", "dismiss" ], "title": "Action", "type": "string" }, "contact_ids": { "items": { "type": "string" }, "minItems": 1, "title": "Contact Ids", "type": "array" }, "destination": { "anyOf": [ { "$ref": "#/components/schemas/ContactApprovalDestination" }, { "type": "null" } ] }, "thumb": { "anyOf": [ { "enum": [ "up", "down" ], "type": "string" }, { "type": "null" } ], "title": "Thumb" } }, "required": [ "action", "contact_ids" ], "title": "ContactBulkRequest", "type": "object" }, "ContactBulkResponse": { "properties": { "failed": { "items": { "$ref": "#/components/schemas/ContactBulkItemResult" }, "title": "Failed", "type": "array" }, "succeeded": { "items": { "type": "string" }, "title": "Succeeded", "type": "array" } }, "title": "ContactBulkResponse", "type": "object" }, "ContactCluster": { "description": "A cluster of contacts that likely represent the same person.\n\nUsed in ClusterDetectionResponse for multi-select merge.\n\nAttributes:\n cluster_id: Unique identifier for this cluster\n contacts: List of contacts in this cluster\n suggested_primary_id: ID of contact suggested as primary\n confidence_score: Overall cluster confidence\n match_reasons: Reasons why contacts were grouped\n merged_preview: Preview of merged result", "properties": { "cluster_id": { "description": "Unique cluster identifier", "title": "Cluster Id", "type": "string" }, "confidence_score": { "description": "Cluster confidence score 0.0-1.0", "maximum": 1.0, "minimum": 0.0, "title": "Confidence Score", "type": "number" }, "contacts": { "description": "Contacts in this cluster", "items": { "$ref": "#/components/schemas/api_service__models__contact_merge__ContactSummary" }, "title": "Contacts", "type": "array" }, "match_reasons": { "default": [], "description": "Match reasons for this cluster", "items": { "$ref": "#/components/schemas/MatchReason" }, "title": "Match Reasons", "type": "array" }, "merged_preview": { "additionalProperties": true, "default": {}, "description": "Preview of merged result", "title": "Merged Preview", "type": "object" }, "suggested_primary_id": { "description": "Suggested primary contact ID — a Shared contact whenever the cluster mixes Shared and Private ones, since the merge keeps it (TIDY-19981).", "title": "Suggested Primary Id", "type": "string" } }, "required": [ "cluster_id", "contacts", "suggested_primary_id", "confidence_score" ], "title": "ContactCluster", "type": "object" }, "ContactCreate": { "description": "Input model for creating new contacts via POST /api/v1/contacts.", "properties": { "addresses": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "default": [], "description": "Array of addresses [{street, city, state, zip, type}]", "title": "Addresses" }, "child_associations": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "default": [], "description": "List of child associations", "title": "Child Associations" }, "confidence_score": { "anyOf": [ { "maximum": 1.0, "minimum": 0.0, "type": "number" }, { "type": "null" } ], "description": "AI confidence score 0.0-1.0", "title": "Confidence Score" }, "custom_properties": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "TIDY-14195: story/extension fields for a contact-derivative create (a fictional Character). `metadata` is the canonical carrier and wins on any key conflict; `custom_properties` is accepted as an alias so a payload naming the target column directly is NOT silently dropped. Ignored for a non-derivative create.", "title": "Custom Properties" }, "duplicate_resolution": { "anyOf": [ { "$ref": "#/components/schemas/ContactDuplicateResolution" }, { "type": "null" } ], "description": "Explicit duplicate-resolution choice for matching name/email/phone data" }, "email_addresses": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "default": [], "description": "Array of email addresses [{address, type, primary, label}]", "title": "Email Addresses" }, "facet_data": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "Per-facet scoped custom fields for contact-inheriting facets ({ slug: { field_key: value } }). Deep-merged per slug on later updates: an existing non-null field is never clobbered by an absent/null incoming value; explicit non-null values win.", "title": "Facet Data" }, "facet_slug": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "TIDY-14195: facet this contact is created under (e.g. 'character'). When it resolves SERVER-SIDE to a facet whose derivative_of='contacts', the create routes to the contact-derivative branch (fictional Character): story fields land flat in custom_properties, native comms columns stay empty, dedup is skipped, and contacts.facet_derivative is stamped. A client can NEVER stamp facet_derivative directly — it is derived only from this slug. Absent or non-derivative slug ⇒ an ordinary contact create, byte-for-byte unchanged.", "title": "Facet Slug" }, "first_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "First name", "title": "First Name" }, "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Client-provided UUID for idempotent creates (PowerSync offline sync)", "title": "Id" }, "last_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Last name", "title": "Last Name" }, "metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": {}, "description": "Extensible metadata. Canonical carrier for a contact-derivative create's story fields (role, arc, …) — see custom_properties.", "title": "Metadata" }, "middle_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Middle name", "title": "Middle Name" }, "name": { "description": "Contact name (1-255 characters)", "examples": [ "Jane Smith" ], "maxLength": 255, "minLength": 1, "title": "Name", "type": "string" }, "nickname": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Informal name", "title": "Nickname" }, "notes_history": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "default": [], "description": "DEPRECATED: Use /api/v1/notes endpoints. Ignored on create.", "title": "Notes History" }, "organization": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "DEPRECATED (TIDY-7636): free-text organization name. The value is no longer written to contacts.organization — instead, callers must pass organization_ids referencing rows in the organizations table. This field is kept for backward-compat parsing but is IGNORED.", "examples": [ "Lincoln Elementary" ], "title": "Organization" }, "organization_ids": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "description": "Organization UUIDs to link to the new contact. Each ID must reference an organizations.id row in the same tenant; first ID becomes the primary org. Replaces the legacy free-text organization field per TIDY-7636.", "title": "Organization Ids" }, "phone_numbers": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "default": [], "description": "Array of phone numbers [{number, type, primary, label}]", "title": "Phone Numbers" }, "project_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Project to link the new contact into (P-). Omitted: the project of the assistant or employee turn creating it, else none. Null: no project.", "title": "Project Id" }, "relation_type": { "anyOf": [ { "pattern": "^(child|relation|acquaintance)?$", "type": "string" }, { "type": "null" } ], "default": "acquaintance", "description": "Relationship classification (child|relation|acquaintance)", "title": "Relation Type" }, "role": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Contact role", "examples": [ "Teacher", "Coach" ], "title": "Role" }, "source_context": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "Internal-only audit/source attribution metadata", "title": "Source Context" }, "source_type": { "anyOf": [ { "pattern": "^(extracted|manual|imported|booking)?$", "type": "string" }, { "type": "null" } ], "default": "manual", "description": "Where contact came from", "title": "Source Type" }, "tags": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "description": "Tag slugs to apply to this contact", "title": "Tags" }, "template_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "TIDY-14195: content template (templates.id) to apply on a derivative create — its body seeds the new Character's own yjs document. Ignored for a non-derivative create.", "title": "Template Id" }, "visibility": { "anyOf": [ { "enum": [ "private", "shared", "tenant" ], "type": "string" }, { "type": "null" } ], "description": "Omitted manual create: shared with everyone; choose private when needed.", "title": "Visibility" } }, "required": [ "name" ], "title": "ContactCreate", "type": "object" }, "ContactDismissRequest": { "description": "POST /api/v1/review/contacts/{id}/dismiss body (TIDY-8071).\n\nBody is optional; legacy callers may post without one. When `thumb` is\nsupplied the dismissal records the negative signal in `pending_feedback`\nin the same operation.", "properties": { "thumb": { "anyOf": [ { "enum": [ "up", "down" ], "type": "string" }, { "type": "null" } ], "title": "Thumb" } }, "title": "ContactDismissRequest", "type": "object" }, "ContactDismissResponse": { "properties": { "approval_status": { "title": "Approval Status", "type": "string" }, "contact_id": { "title": "Contact Id", "type": "string" }, "dismissed_keys": { "items": { "type": "string" }, "title": "Dismissed Keys", "type": "array" }, "rejected_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Rejected At" } }, "required": [ "contact_id", "approval_status" ], "title": "ContactDismissResponse", "type": "object" }, "ContactDuplicateResolution": { "description": "Explicit user choice when create/update matches an existing contact.", "properties": { "action": { "description": "Duplicate-resolution action chosen by the user", "enum": [ "create_anyway", "approve_duplicate", "update_existing", "merge_into_existing" ], "title": "Action", "type": "string" }, "target_contact_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Existing contact selected for update/merge actions", "title": "Target Contact Id" } }, "required": [ "action" ], "title": "ContactDuplicateResolution", "type": "object" }, "ContactEditHistoryEntry": { "description": "Single contact field edit record.", "properties": { "change_set_id": { "description": "Edit batch UUID", "title": "Change Set Id", "type": "string" }, "changed_at": { "description": "ISO 8601 timestamp of the change", "format": "date-time", "title": "Changed At", "type": "string" }, "changed_by": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Account UUID that made the change", "title": "Changed By" }, "contact_id": { "description": "Contact UUID", "title": "Contact Id", "type": "string" }, "edit_source": { "description": "Source of the change (user, assistant, restore)", "title": "Edit Source", "type": "string" }, "field_name": { "description": "Changed field name", "title": "Field Name", "type": "string" }, "id": { "description": "Edit history UUID", "title": "Id", "type": "string" }, "new_value": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "New stored value", "title": "New Value" }, "old_value": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Previous stored value", "title": "Old Value" }, "source_context": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "description": "Captured source attribution for the change", "title": "Source Context" } }, "required": [ "id", "change_set_id", "contact_id", "field_name", "edit_source", "changed_at" ], "title": "ContactEditHistoryEntry", "type": "object" }, "ContactEditHistoryResponse": { "description": "Response payload for contact edit history queries.", "properties": { "entries": { "description": "Most recent edit history entries for the contact", "items": { "$ref": "#/components/schemas/ContactEditHistoryEntry" }, "title": "Entries", "type": "array" } }, "title": "ContactEditHistoryResponse", "type": "object" }, "ContactFeedbackRequest": { "properties": { "thumb": { "enum": [ "up", "down" ], "title": "Thumb", "type": "string" } }, "required": [ "thumb" ], "title": "ContactFeedbackRequest", "type": "object" }, "ContactFeedbackResponse": { "properties": { "contact_id": { "title": "Contact Id", "type": "string" }, "feedback_id": { "title": "Feedback Id", "type": "string" }, "thumb": { "enum": [ "up", "down" ], "title": "Thumb", "type": "string" } }, "required": [ "feedback_id", "contact_id", "thumb" ], "title": "ContactFeedbackResponse", "type": "object" }, "ContactFile": { "description": "A single attachment exchanged with the contact.", "properties": { "bucket": { "title": "Bucket", "type": "string" }, "content_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Content Type" }, "disposition": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Disposition" }, "email_canonical_id": { "title": "Email Canonical Id", "type": "string" }, "filename": { "title": "Filename", "type": "string" }, "from_address": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "From Address" }, "id": { "title": "Id", "type": "string" }, "locator": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "title": "Locator" }, "scan_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Scan Status" }, "sent_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Sent At" }, "size_bytes": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Size Bytes" }, "source": { "default": "processed", "title": "Source", "type": "string" }, "storage_path": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Storage Path" }, "subject": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Subject" } }, "required": [ "id", "email_canonical_id", "filename", "bucket" ], "title": "ContactFile", "type": "object" }, "ContactFilesResponse": { "description": "Envelope for the contact files aggregation.", "properties": { "received": { "items": { "$ref": "#/components/schemas/ContactFile" }, "title": "Received", "type": "array" }, "sent": { "items": { "$ref": "#/components/schemas/ContactFile" }, "title": "Sent", "type": "array" } }, "required": [ "received", "sent" ], "title": "ContactFilesResponse", "type": "object" }, "ContactFollowUpItem": { "properties": { "display_text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Display Text" }, "email_id": { "format": "uuid", "title": "Email Id", "type": "string" }, "flagged_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Flagged At" }, "link_id": { "title": "Link Id", "type": "string" }, "sent_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Sent At" }, "subject": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Subject" } }, "required": [ "link_id", "email_id" ], "title": "ContactFollowUpItem", "type": "object" }, "ContactFollowUpsResponse": { "properties": { "contact_id": { "format": "uuid", "title": "Contact Id", "type": "string" }, "follow_ups": { "items": { "$ref": "#/components/schemas/ContactFollowUpItem" }, "title": "Follow Ups", "type": "array" } }, "required": [ "contact_id", "follow_ups" ], "title": "ContactFollowUpsResponse", "type": "object" }, "ContactId": { "description": "Typed primitive ID for contacts (prefix 'C').", "examples": [ "C-550e8400-e29b-41d4-a716-446655440000" ], "pattern": "^C-[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "title": "ContactId", "type": "string", "x-tidy-typed-id-prefix": "C", "x-tidy-typed-id-table": "contacts" }, "ContactIntelligenceFieldChange": { "description": "Field-level preview describing how a record would change.", "properties": { "changed": { "description": "Whether the field would change", "title": "Changed", "type": "boolean" }, "current_value": { "description": "Existing persisted value", "title": "Current Value" }, "field": { "description": "Field name", "title": "Field", "type": "string" }, "proposed_value": { "description": "Proposed value after apply", "title": "Proposed Value" } }, "required": [ "field", "changed" ], "title": "ContactIntelligenceFieldChange", "type": "object" }, "ContactIntelligenceProvenance": { "description": "Source metadata captured for contact-intelligence review flows.", "properties": { "context_after": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Text after selection", "title": "Context After" }, "context_before": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Text before selection", "title": "Context Before" }, "email_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Backing email identifier", "title": "Email Id" }, "selected_html": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Selected HTML when available", "title": "Selected Html" }, "source_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Source entity identifier", "title": "Source Id" }, "source_surface": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Surface where text was selected", "title": "Source Surface" }, "source_title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Source entity title", "title": "Source Title" }, "source_type": { "description": "Origin channel, e.g. selection or email", "title": "Source Type", "type": "string" }, "thread_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Backing email thread identifier", "title": "Thread Id" } }, "required": [ "source_type" ], "title": "ContactIntelligenceProvenance", "type": "object" }, "ContactIntelligenceRecommendation": { "description": "Recommended action for an extracted contact or organization candidate.", "properties": { "action": { "description": "Recommended next step", "enum": [ "update_existing", "create_new", "require_human_review" ], "title": "Action", "type": "string" }, "confidence": { "description": "Recommendation confidence", "maximum": 1.0, "minimum": 0.0, "title": "Confidence", "type": "number" }, "field_changes": { "description": "Field-level preview of what would change", "items": { "$ref": "#/components/schemas/ContactIntelligenceFieldChange" }, "title": "Field Changes", "type": "array" }, "match_signals": { "description": "Signals that contributed to the recommendation", "items": { "type": "string" }, "title": "Match Signals", "type": "array" }, "merge_conflicts": { "description": "Conflicts that require explicit human review", "items": { "additionalProperties": true, "type": "object" }, "title": "Merge Conflicts", "type": "array" }, "proposed_record": { "additionalProperties": true, "description": "Normalized record payload to show or apply after confirmation", "title": "Proposed Record", "type": "object" }, "reason": { "description": "Human-readable explanation", "title": "Reason", "type": "string" }, "target_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Existing entity identifier", "title": "Target Id" }, "target_label": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Existing entity display label", "title": "Target Label" }, "target_type": { "description": "Target entity type", "enum": [ "contact", "organization" ], "title": "Target Type", "type": "string" } }, "required": [ "target_type", "action", "confidence", "reason" ], "title": "ContactIntelligenceRecommendation", "type": "object" }, "ContactIntelligenceResolveRequest": { "description": "Input payload for POST /api/v1/contact-intelligence/resolve.", "properties": { "context_after": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Nearby text after selection", "title": "Context After" }, "context_before": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Nearby text before selection", "title": "Context Before" }, "email_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Email identifier when applicable", "title": "Email Id" }, "selected_html": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Selected HTML when available", "title": "Selected Html" }, "source_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Source entity identifier", "title": "Source Id" }, "source_surface": { "anyOf": [ { "enum": [ "editor", "dom", "iframe" ], "type": "string" }, { "type": "null" } ], "description": "Surface the user selected text from", "title": "Source Surface" }, "source_title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Source title or label", "title": "Source Title" }, "source_type": { "default": "selection", "description": "Origin channel for the extracted text", "enum": [ "selection", "email", "assistant" ], "title": "Source Type", "type": "string" }, "text": { "description": "Selected or email-derived text to analyze", "minLength": 1, "title": "Text", "type": "string" }, "thread_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Email thread identifier when applicable", "title": "Thread Id" }, "user_request": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional user instruction describing the desired contact or organization change", "title": "User Request" } }, "required": [ "text" ], "title": "ContactIntelligenceResolveRequest", "type": "object" }, "ContactIntelligenceResolveResponse": { "description": "Response payload for the contact intelligence resolve endpoint.", "properties": { "extracted_contact": { "anyOf": [ { "$ref": "#/components/schemas/ExtractedContactCandidate" }, { "type": "null" } ], "description": "Extracted contact candidate when detected" }, "extracted_organization": { "anyOf": [ { "$ref": "#/components/schemas/ExtractedOrganizationCandidate" }, { "type": "null" } ], "description": "Extracted organization candidate when detected" }, "provenance": { "$ref": "#/components/schemas/ContactIntelligenceProvenance", "description": "Source metadata captured for audit and UI review" }, "recommendations": { "description": "Recommended actions with field-level previews", "items": { "$ref": "#/components/schemas/ContactIntelligenceRecommendation" }, "title": "Recommendations", "type": "array" } }, "required": [ "provenance" ], "title": "ContactIntelligenceResolveResponse", "type": "object" }, "ContactLinkedContainer": { "properties": { "container_id": { "title": "Container Id", "type": "string" }, "container_type": { "title": "Container Type", "type": "string" } }, "required": [ "container_type", "container_id" ], "title": "ContactLinkedContainer", "type": "object" }, "ContactOrganizationLink": { "description": "Link between a contact and an organization.\n\nUsed in organization detail responses to show linked contacts.\n\nAttributes:\n contact_id: Contact UUID\n contact_name: Contact display name\n relationship_type: Type of relationship (works_at, member_of, etc.)\n role: Contact's role at the organization\n is_primary: Whether this is the contact's primary organization", "properties": { "contact_id": { "description": "Contact UUID", "title": "Contact Id", "type": "string" }, "contact_name": { "description": "Contact display name", "title": "Contact Name", "type": "string" }, "is_primary": { "default": false, "description": "Whether this is the contact's primary organization", "title": "Is Primary", "type": "boolean" }, "relationship_type": { "default": "affiliated_with", "description": "Type of relationship (works_at, member_of, attends, affiliated_with)", "title": "Relationship Type", "type": "string" }, "role": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Contact's role at the organization", "title": "Role" } }, "required": [ "contact_id", "contact_name" ], "title": "ContactOrganizationLink", "type": "object" }, "ContactReportsToResponse": { "description": "Where the reporting line now lives.", "properties": { "contact_id": { "description": "The person placed (their existing membership's contact, or the canonical member card for new enrolment)", "examples": [ "C-550e8400-e29b-41d4-a716-446655440000" ], "pattern": "^C-[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "title": "ContactId", "type": "string", "x-tidy-typed-id-prefix": "C", "x-tidy-typed-id-table": "contacts" }, "manager_contact_id": { "anyOf": [ { "description": "Typed primitive ID for contacts (prefix 'C').", "examples": [ "C-550e8400-e29b-41d4-a716-446655440000" ], "pattern": "^C-[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "title": "ContactId", "type": "string", "x-tidy-typed-id-prefix": "C", "x-tidy-typed-id-table": "contacts" }, { "type": "null" } ], "default": null, "description": "Who they report to now, or null (top of the chart)", "title": "Manager Contact Id" }, "manager_private_on_team_chart": { "default": false, "description": "The manager is a private card: only you see them on the team's org chart, and the rest of the workspace sees this person at the top", "title": "Manager Private On Team Chart", "type": "boolean" }, "membership_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "The person's membership there (UUID)", "title": "Membership Id" }, "organization_id": { "anyOf": [ { "description": "Typed primitive ID for organizations (prefix 'O').", "examples": [ "O-550e8400-e29b-41d4-a716-446655440000" ], "pattern": "^O-[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "title": "OrganizationId", "type": "string", "x-tidy-typed-id-prefix": "O", "x-tidy-typed-id-table": "organizations" }, { "type": "null" } ], "default": null, "description": "The selected organization holding the line; all other organizations' lines are unchanged", "title": "Organization Id" }, "private_on_team_chart": { "default": false, "description": "The person is a private card: on the team's org chart only you see them, and the rest of the workspace sees their reports at the top", "title": "Private On Team Chart", "type": "boolean" } }, "required": [ "contact_id" ], "title": "ContactReportsToResponse", "type": "object" }, "ContactReportsToUpdate": { "description": "Input for PUT /api/v1/contacts/{contact_id}/reports-to (TIDY-18958).", "properties": { "manager_contact_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The contact this person reports to (typed C-id or UUID), or null to move them to the top of the org chart", "title": "Manager Contact Id" }, "organization_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Organization whose line is being edited; other organizations are unchanged", "title": "Organization Id" }, "team_organization": { "default": false, "description": "Use the workspace's team organization rather than an inferred shared organization", "title": "Team Organization", "type": "boolean" } }, "required": [ "manager_contact_id" ], "title": "ContactReportsToUpdate", "type": "object" }, "ContactResponse": { "description": "Complete contact object returned by API endpoints.\n\nUsed in GET/POST/PUT /api/v1/contacts endpoints.", "properties": { "addresses": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "default": [], "description": "Array of addresses [{street, city, state, zip, type}]", "title": "Addresses" }, "aliases": { "description": "Aliases (honorifics, nicknames, alternate spellings) recognized by the matcher.", "items": { "$ref": "#/components/schemas/ContactAliasResponse" }, "title": "Aliases", "type": "array" }, "approval_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Lifecycle state: 'pending_review' | 'approved' | 'rejected'.", "title": "Approval Status" }, "audit_recent": { "anyOf": [ { "items": { "$ref": "#/components/schemas/AuditLogSummary" }, "type": "array" }, { "type": "null" } ], "default": null, "description": "Last 10 audit_log entries for this contact, newest first.", "title": "Audit Recent" }, "audit_recent_error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Set when the audit_log sub-fetch failed; isolated from core response.", "title": "Audit Recent Error" }, "child_associations": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "default": [], "description": "List of child associations [{child_name, relationship}]", "examples": [ [ { "child_name": "Emma", "relationship": "teacher" } ] ], "title": "Child Associations" }, "confidence_score": { "anyOf": [ { "maximum": 1.0, "minimum": 0.0, "type": "number" }, { "type": "null" } ], "default": null, "description": "AI confidence score 0.0-1.0", "examples": [ 0.85 ], "title": "Confidence Score" }, "created_at": { "description": "ISO 8601 timestamp of contact creation", "format": "date-time", "title": "Created At", "type": "string" }, "display_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Generated display name", "examples": [ "Jane Marie Smith" ], "title": "Display Name" }, "email_addresses": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "default": [], "description": "Array of email addresses [{address, type, primary, label}]", "title": "Email Addresses" }, "facet_data": { "additionalProperties": true, "description": "Per-facet scoped custom fields for contact-inheriting facets ({ slug: { field_key: value } }).", "title": "Facet Data", "type": "object" }, "first_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "First name", "examples": [ "Jane" ], "title": "First Name" }, "graph_facts": { "anyOf": [ { "items": { "$ref": "#/components/schemas/GraphFact" }, "type": "array" }, { "type": "null" } ], "default": null, "description": "Recent KG facts about this entity (most recent 50). NULL when not pending or no entity.", "title": "Graph Facts" }, "graph_facts_error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Set when the KG sub-fetch failed; isolated from core response.", "title": "Graph Facts Error" }, "graph_sync_summary": { "anyOf": [ { "$ref": "#/components/schemas/GraphSyncSummary" }, { "type": "null" } ], "default": null, "description": "Most-recent merge's graph_sync summary; NULL when no recent merge." }, "id": { "description": "Unique contact identifier (UUID)", "examples": [ "a1b2c3d4-..." ], "title": "Id", "type": "string" }, "is_self": { "default": false, "description": "True when this contact IS the signed-in account in this tenant.", "title": "Is Self", "type": "boolean" }, "is_starred": { "default": false, "description": "VIP/starred status. VIP = is_starred=TRUE OR source_type=imported", "title": "Is Starred", "type": "boolean" }, "last_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Last name", "examples": [ "Smith" ], "title": "Last Name" }, "metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": {}, "description": "Extensible metadata", "title": "Metadata" }, "middle_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Middle name", "examples": [ "Marie" ], "title": "Middle Name" }, "name": { "description": "Contact name (legacy)", "examples": [ "Jane Smith" ], "title": "Name", "type": "string" }, "nickname": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Informal name", "examples": [ "Coach Mike" ], "title": "Nickname" }, "notes_history": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "default": [], "description": "DEPRECATED: Use /api/v1/notes endpoints. Always returns empty array.", "title": "Notes History" }, "organization": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "[DEPRECATED] Use 'organizations' field instead.", "examples": [ "Lincoln Elementary", "Youth Soccer League" ], "title": "Organization" }, "organizations": { "default": [], "description": "List of organizations this contact is affiliated with", "items": { "$ref": "#/components/schemas/OrganizationSummary" }, "title": "Organizations", "type": "array" }, "phone_numbers": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "default": [], "description": "Array of phone numbers [{number, type, primary, label}]", "title": "Phone Numbers" }, "photo_source": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Source of photo (manual|device_sync|google_people|generated)", "examples": [ "google_people" ], "title": "Photo Source" }, "photo_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "URL to contact's primary photo (priority: manual > device > google > generated)", "examples": [ "tenant-id/contacts/contact-id/photos/manual/2026-01-12.jpg" ], "title": "Photo Url" }, "potential_matches": { "anyOf": [ { "items": { "$ref": "#/components/schemas/PotentialMatch" }, "type": "array" }, { "type": "null" } ], "default": null, "description": "Existing contacts the matcher proposes as merge targets. NULL when not pending.", "title": "Potential Matches" }, "potential_matches_error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Set when the duplicate-detection sub-fetch failed; isolated from core response.", "title": "Potential Matches Error" }, "provenance": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "description": "Provenance metadata: who created this contact and how (D29).", "title": "Provenance" }, "relation_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": "acquaintance", "description": "Relationship classification (child|relation|acquaintance)", "examples": [ "child", "relation", "acquaintance" ], "title": "Relation Type" }, "requires_review": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "description": "Mirror of contacts.requires_review — server-asserted review flag.", "title": "Requires Review" }, "role": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Contact role (Teacher, Coach, Parent, etc.)", "examples": [ "Teacher", "Coach" ], "title": "Role" }, "source_email_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Email this contact was extracted from (extraction-source contacts only).", "title": "Source Email Id" }, "source_evidence": { "anyOf": [ { "items": { "$ref": "#/components/schemas/SourceEvidence" }, "type": "array" }, { "type": "null" } ], "default": null, "description": "Source records that produced this contact (email/note/calendar/extracted).", "title": "Source Evidence" }, "source_evidence_error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Set when the source-evidence sub-fetch failed; isolated from core response.", "title": "Source Evidence Error" }, "source_type": { "default": "manual", "description": "Where contact came from (extracted|manual|imported|booking)", "examples": [ "manual", "extracted" ], "pattern": "^(extracted|manual|imported|booking)$", "title": "Source Type", "type": "string" }, "source_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Supabase Storage URL to the original source document", "examples": [ "tenant-id/raw_emails/2025/12/18/email.eml" ], "title": "Source Url" }, "tags": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "default": null, "description": "Tag slugs applied to this contact", "title": "Tags" }, "tenant_id": { "description": "Associated tenant identifier (UUID)", "examples": [ "a1b2c3d4-..." ], "title": "Tenant Id", "type": "string" }, "updated_at": { "description": "ISO 8601 timestamp of last modification", "format": "date-time", "title": "Updated At", "type": "string" } }, "required": [ "id", "tenant_id", "name", "created_at", "updated_at" ], "title": "ContactResponse", "type": "object" }, "ContactSettingsPayload": { "description": "Contact module settings per user (partial update).", "properties": { "auto_extract_contacts": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Automatically extract contacts from emails", "title": "Auto Extract Contacts" }, "avatar_source_priority": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "description": "Ordered list of avatar sources", "examples": [ [ "manual", "device_sync", "google_people", "generated" ] ], "title": "Avatar Source Priority" }, "default_view": { "anyOf": [ { "pattern": "^(grid|list)$", "type": "string" }, { "type": "null" } ], "description": "Default contact list view", "title": "Default View" }, "enrichment_enabled": { "anyOf": [ { "additionalProperties": { "type": "boolean" }, "type": "object" }, { "type": "null" } ], "description": "Per-source enrichment toggles", "examples": [ { "google_people": true, "linkedin": false } ], "title": "Enrichment Enabled" } }, "title": "ContactSettingsPayload", "type": "object" }, "ContactSettingsResponse": { "description": "Full contact settings response with defaults applied.", "properties": { "auto_extract_contacts": { "default": true, "title": "Auto Extract Contacts", "type": "boolean" }, "avatar_source_priority": { "items": { "type": "string" }, "title": "Avatar Source Priority", "type": "array" }, "default_view": { "default": "list", "title": "Default View", "type": "string" }, "enrichment_enabled": { "additionalProperties": { "type": "boolean" }, "title": "Enrichment Enabled", "type": "object" } }, "title": "ContactSettingsResponse", "type": "object" }, "ContactSuggestion": { "description": "Contact or group suggestion for recipient autocomplete.", "properties": { "avatar_schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Custom vector avatar schema (JSON string)", "title": "Avatar Schema" }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Email address (null for groups)", "title": "Email" }, "icon": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "User-set unified icon value", "title": "Icon" }, "id": { "description": "Contact or group UUID", "format": "uuid", "title": "Id", "type": "string" }, "member_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Member count (groups only)", "title": "Member Count" }, "name": { "description": "Display name", "title": "Name", "type": "string" }, "photo_source": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Photo provenance discriminator (custom_avatar/gravatar/...)", "title": "Photo Source" }, "photo_thumbnail": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Inline photo thumbnail (data URL) for instant paint", "title": "Photo Thumbnail" }, "photo_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Contact photo URL", "title": "Photo Url" }, "type": { "default": "contact", "description": "'contact' or 'group'", "title": "Type", "type": "string" } }, "required": [ "id", "name" ], "title": "ContactSuggestion", "type": "object" }, "ContactSuggestionsResponse": { "description": "Response for contact autocomplete.", "properties": { "suggestions": { "description": "Matching contacts", "items": { "$ref": "#/components/schemas/ContactSuggestion" }, "title": "Suggestions", "type": "array" } }, "required": [ "suggestions" ], "title": "ContactSuggestionsResponse", "type": "object" }, "ContactSummary": { "description": "Lightweight contact view for duplicate detection results.\n\nUsed in DuplicatePair to show two contacts side-by-side\nwithout full contact detail overhead.\n\nAttributes:\n id: Contact UUID\n display_name: Full display name\n first_name: First name component (optional)\n last_name: Last name component (optional)\n organization: Organization/school name (optional)\n email_addresses: List of email addresses\n phone_numbers: List of phone numbers\n tags: List of contact tags\n has_mobile_link: Whether contact is linked to a mobile device contact\n created_at: When contact was created\n\nRelated: apps/mobile/src/lib/components/contacts/DuplicatePairCard.svelte", "properties": { "created_at": { "description": "When contact was created", "format": "date-time", "title": "Created At", "type": "string" }, "display_name": { "description": "Full display name", "title": "Display Name", "type": "string" }, "email_addresses": { "default": [], "description": "Array of email addresses [{address, type, primary}]", "items": { "additionalProperties": true, "type": "object" }, "title": "Email Addresses", "type": "array" }, "first_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "First name", "title": "First Name" }, "has_mobile_link": { "default": false, "description": "Whether contact is linked to mobile device", "title": "Has Mobile Link", "type": "boolean" }, "id": { "description": "Contact UUID", "title": "Id", "type": "string" }, "last_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Last name", "title": "Last Name" }, "organization": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Legacy free-text organization name (TIDY-7640 / S7 cleanup). Use `organizations` for link-first display.", "title": "Organization" }, "organizations": { "default": [], "description": "Linked organizations [{id, name, type}] from contact_organizations.", "items": { "additionalProperties": true, "type": "object" }, "title": "Organizations", "type": "array" }, "phone_numbers": { "default": [], "description": "Array of phone numbers [{number, type, primary}]", "items": { "additionalProperties": true, "type": "object" }, "title": "Phone Numbers", "type": "array" }, "tags": { "default": [], "description": "Contact tags", "items": { "type": "string" }, "title": "Tags", "type": "array" }, "workspace_shared": { "description": "True when every member of the workspace sees this contact (Shared), False when only its owner does (Private). A merge mixing the two keeps the shared contact (TIDY-19981).", "title": "Workspace Shared", "type": "boolean" } }, "required": [ "id", "display_name", "workspace_shared", "created_at" ], "title": "ContactSummary", "type": "object" }, "ContactSyncRequest": { "description": "Request body for POST /api/v1/contacts/sync endpoint.", "properties": { "contacts": { "description": "List of device contacts to sync", "items": { "$ref": "#/components/schemas/DeviceContact" }, "title": "Contacts", "type": "array" }, "device_id": { "description": "Stable sync namespace for this contact set. For os_contacts this MUST be account-namespaced (e.g. 'os:') so the provider_record_id survives a reinstall. For legacy device_sync it is the physical device id.", "examples": [ "os:cbc81958-7e96-469e-9443-2f0a005497e8", "android-12345-abcde" ], "title": "Device Id", "type": "string" }, "full_sync": { "default": false, "description": "True = replace all device-linked contacts, False = merge", "title": "Full Sync", "type": "boolean" }, "source": { "default": "device_sync", "description": "Provider source key for the external_contacts cache. 'os_contacts' (native Android), 'device_sync' (legacy Tauri). Must be one of DEVICE_SYNC_SOURCES.", "examples": [ "os_contacts" ], "title": "Source", "type": "string" } }, "required": [ "device_id", "contacts" ], "title": "ContactSyncRequest", "type": "object" }, "ContactSyncResponse": { "description": "Response for POST /api/v1/contacts/sync endpoint.", "properties": { "errors": { "default": [], "description": "List of error messages for failed contacts", "items": { "type": "string" }, "title": "Errors", "type": "array" }, "stats": { "$ref": "#/components/schemas/ContactSyncStats", "description": "Sync statistics" }, "success": { "description": "Whether sync completed successfully", "title": "Success", "type": "boolean" }, "synced_at": { "description": "Timestamp of sync completion", "format": "date-time", "title": "Synced At", "type": "string" } }, "required": [ "success", "stats", "synced_at" ], "title": "ContactSyncResponse", "type": "object" }, "ContactSyncStats": { "description": "Statistics for a contact sync operation.", "properties": { "created": { "default": 0, "description": "New contacts created", "title": "Created", "type": "integer" }, "matched": { "default": 0, "description": "Contacts matched to existing", "title": "Matched", "type": "integer" }, "skipped": { "default": 0, "description": "Contacts skipped", "title": "Skipped", "type": "integer" }, "total_processed": { "default": 0, "description": "Total contacts processed", "title": "Total Processed", "type": "integer" }, "updated": { "default": 0, "description": "Existing contacts updated", "title": "Updated", "type": "integer" } }, "title": "ContactSyncStats", "type": "object" }, "ContactUndoDismissResponse": { "properties": { "approval_status": { "title": "Approval Status", "type": "string" }, "contact_id": { "title": "Contact Id", "type": "string" } }, "required": [ "contact_id", "approval_status" ], "title": "ContactUndoDismissResponse", "type": "object" }, "ContactUpdate": { "description": "Input model for updating contacts via PUT/PATCH /api/v1/contacts/{id}.", "properties": { "addresses": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "description": "Array of addresses [{street, city, state, zip, type}]", "title": "Addresses" }, "base_values": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "Internal-only autosave base values for field conflict detection", "title": "Base Values" }, "child_associations": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "description": "List of child associations", "title": "Child Associations" }, "custom_properties": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "Facet field values to merge per-key into custom_properties (a provided key overwrites, null clears the key, unprovided keys survive).", "title": "Custom Properties" }, "display_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Override display name", "title": "Display Name" }, "duplicate_resolution": { "anyOf": [ { "$ref": "#/components/schemas/ContactDuplicateResolution" }, { "type": "null" } ], "description": "Explicit duplicate-resolution choice for matching name/email/phone data" }, "email_addresses": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "description": "Array of email addresses [{address, type, primary, label}]", "title": "Email Addresses" }, "facet_data": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "Per-facet scoped custom fields for contact-inheriting facets ({ slug: { field_key: value } }). Deep-merged per slug: an existing non-null field is never clobbered by an absent/null incoming value; explicit non-null values win.", "title": "Facet Data" }, "first_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "First name", "title": "First Name" }, "icon": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Serialized unified icon ({kind,value}); photo-less identity affordance. Null clears it.", "title": "Icon" }, "is_starred": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "VIP/starred status", "title": "Is Starred" }, "last_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Last name", "title": "Last Name" }, "metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "Extensible metadata", "title": "Metadata" }, "middle_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Middle name", "title": "Middle Name" }, "name": { "anyOf": [ { "maxLength": 255, "minLength": 1, "type": "string" }, { "type": "null" } ], "description": "Contact name (1-255 characters)", "title": "Name" }, "nickname": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Informal name", "title": "Nickname" }, "notes_history": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "description": "DEPRECATED: Use /api/v1/notes endpoints. Ignored on update.", "title": "Notes History" }, "organization": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Organization name (legacy)", "title": "Organization" }, "organization_ids": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "description": "Organization UUIDs to link (replaces existing)", "title": "Organization Ids" }, "phone_numbers": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "description": "Array of phone numbers [{number, type, primary, label}]", "title": "Phone Numbers" }, "relation_type": { "anyOf": [ { "pattern": "^(child|relation|acquaintance)?$", "type": "string" }, { "type": "null" } ], "description": "Relationship classification (child|relation|acquaintance)", "title": "Relation Type" }, "role": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Contact role", "title": "Role" }, "source_context": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "Internal-only audit/source attribution metadata", "title": "Source Context" }, "tags": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "description": "Tag slugs to apply to this contact", "title": "Tags" }, "visibility": { "anyOf": [ { "enum": [ "private", "shared", "tenant" ], "type": "string" }, { "type": "null" } ], "description": "Per-row visibility. Only the row owner may change this.", "title": "Visibility" } }, "title": "ContactUpdate", "type": "object" }, "ContainerCapability": { "description": "A host an agent may put a view in — ephemeral preview or persisted.", "properties": { "accepts_layouts": { "default": "all", "title": "Accepts Layouts" }, "container": { "title": "Container", "type": "string" }, "container_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Container Type" }, "label": { "title": "Label", "type": "string" }, "notes": { "default": "", "title": "Notes", "type": "string" }, "persistence": { "enum": [ "ephemeral", "persisted" ], "title": "Persistence", "type": "string" }, "requires_container_id": { "title": "Requires Container Id", "type": "boolean" } }, "required": [ "container", "label", "persistence", "requires_container_id" ], "title": "ContainerCapability", "type": "object" }, "ContentItem": { "description": "A single content item for bulk assign/unassign.", "properties": { "id": { "description": "UUID of the content item", "title": "Id", "type": "string" }, "type": { "description": "Content type (email|task|calendar_event|contact|note)", "pattern": "^(email|task|calendar_event|contact|note)$", "title": "Type", "type": "string" } }, "required": [ "type", "id" ], "title": "ContentItem", "type": "object" }, "ContentProducerOption": { "description": "One registered body producer a `primitive_content` field may declare.\n\nTIDY-19091 (S4): the facet editor's Content producer select is fed from\nthis list — the registry (`content_producers.py`) is the compatibility\nsource of truth, never a client-mirrored array. `hostable_primitives`\nnames the storage tables that can host the producer's content kind, so\nthe editor filters by the facet's resolved primitive.", "properties": { "content_kind": { "title": "Content Kind", "type": "string" }, "hostable_primitives": { "items": { "type": "string" }, "title": "Hostable Primitives", "type": "array" }, "label": { "title": "Label", "type": "string" }, "name": { "title": "Name", "type": "string" } }, "required": [ "name", "label", "content_kind", "hostable_primitives" ], "title": "ContentProducerOption", "type": "object" }, "ContentSaveRequest": { "description": "Request for PUT /api/v1/notes/{id}/content with optimistic locking.", "properties": { "content": { "description": "Updated markdown content", "title": "Content", "type": "string" }, "expected_version": { "description": "Version expected by client", "minimum": 0.0, "title": "Expected Version", "type": "integer" } }, "required": [ "content", "expected_version" ], "title": "ContentSaveRequest", "type": "object" }, "ContentSaveResponse": { "description": "Response for content save with new version.", "properties": { "drawing_version": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Drawing Version" }, "id": { "title": "Id", "type": "string" }, "updated_at": { "format": "date-time", "title": "Updated At", "type": "string" }, "version": { "title": "Version", "type": "integer" } }, "required": [ "id", "version", "updated_at" ], "title": "ContentSaveResponse", "type": "object" }, "ContextRequest": { "description": "Request model for /onboarding/context — first-step context picker (TIDY-7079, TIDY-9377).", "properties": { "account_type": { "description": "Account type: 'personal', 'household', or 'business'", "pattern": "^(personal|household|business)$", "title": "Account Type", "type": "string" }, "marketing_consent": { "default": false, "description": "Opt-in for marketing communications. When true, tenants.marketing_consent_at is stamped on first grant. Explicit false revokes; omission preserves prior consent. Default false for new accounts (opt-in, never opt-out). TIDY-18851.", "title": "Marketing Consent", "type": "boolean" } }, "required": [ "account_type" ], "title": "ContextRequest", "type": "object" }, "ContextResponse": { "description": "Response model for /onboarding/context.", "properties": { "account_type": { "description": "Stored account_type", "title": "Account Type", "type": "string" }, "next_step": { "description": "Current step after saving; plan for the initial selection", "title": "Next Step", "type": "string" }, "next_url": { "description": "Current onboarding URL, or workspace when complete", "title": "Next Url", "type": "string" }, "success": { "description": "Always true on success", "title": "Success", "type": "boolean" } }, "required": [ "success", "account_type", "next_step", "next_url" ], "title": "ContextResponse", "type": "object" }, "ContinueHeaderBackfillResponse": { "properties": { "connection_id": { "title": "Connection Id", "type": "string" }, "status": { "title": "Status", "type": "string" } }, "required": [ "connection_id", "status" ], "title": "ContinueHeaderBackfillResponse", "type": "object" }, "ControllerActionAuthorize": { "additionalProperties": false, "description": "An exact action described and signed by the protected controller.", "properties": { "approval_request_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Approval Request Id" }, "authorization": { "maxLength": 8192, "minLength": 1, "title": "Authorization", "type": "string" }, "browser": { "$ref": "#/components/schemas/BrowserJudgmentAction" }, "conversation_id": { "format": "uuid", "title": "Conversation Id", "type": "string" }, "operation_id": { "format": "uuid", "title": "Operation Id", "type": "string" }, "turn_ref": { "maxLength": 512, "minLength": 1, "title": "Turn Ref", "type": "string" } }, "required": [ "authorization", "conversation_id", "turn_ref", "operation_id", "approval_request_id", "browser" ], "title": "ControllerActionAuthorize", "type": "object" }, "ControllerActionDecision": { "properties": { "decision": { "enum": [ "allow", "escalate" ], "title": "Decision", "type": "string" }, "purchase": { "anyOf": [ { "enum": [ "order", "payment", "uncertain" ], "type": "string" }, { "type": "null" } ], "default": null, "title": "Purchase" }, "reason": { "enum": [ "browser_action_allowed", "browser_action_requires_approval", "browser_action_low_confidence", "browser_classifier_unavailable", "browser_target_ambiguous", "browser_human_approved", "browser_posture_bypass", "browser_purchase_requires_approval" ], "title": "Reason", "type": "string" }, "request_digest": { "pattern": "^[0-9a-f]{64}$", "title": "Request Digest", "type": "string" } }, "required": [ "decision", "request_digest", "reason" ], "title": "ControllerActionDecision", "type": "object" }, "ControllerClaimProof": { "additionalProperties": false, "properties": { "challenge": { "pattern": "^[0-9a-f]{64}$", "title": "Challenge", "type": "string" }, "public_key": { "maxLength": 128, "minLength": 40, "title": "Public Key", "type": "string" } }, "required": [ "challenge", "public_key" ], "title": "ControllerClaimProof", "type": "object" }, "ControllerDemonstrationSave": { "additionalProperties": false, "description": "Additive (TIDY-18934 F10): Save files a demonstration for the employee.\n\n``name`` is the person's one line on what the routine is for; each step of\n``capture`` carries its page, what was acted on and the example value; and\n``screenshots`` are the JPEG frames the person was shown, base64, which the\nsteps point at by index. Signed as sent, like the readiness subclasses.", "properties": { "capture": { "additionalProperties": true, "title": "ControllerDemonstrationSaveCapture", "type": "object" }, "name": { "maxLength": 128, "minLength": 1, "title": "Name", "type": "string" }, "request_key": { "format": "uuid", "title": "Request Key", "type": "string" }, "screenshots": { "items": { "maxLength": 700000, "type": "string" }, "maxItems": 8, "title": "Screenshots", "type": "array" } }, "required": [ "name", "request_key", "capture", "screenshots" ], "title": "ControllerDemonstrationSave", "type": "object" }, "ControllerEgressRead": { "additionalProperties": false, "description": "TIDY-18940: a session's controller asking for its account egress URL.", "properties": {}, "title": "ControllerEgressRead", "type": "object" }, "ControllerEnrollmentRequest": { "additionalProperties": false, "properties": { "expected_key_generation": { "minimum": 0.0, "title": "Expected Key Generation", "type": "integer" } }, "required": [ "expected_key_generation" ], "title": "ControllerEnrollmentRequest", "type": "object" }, "ControllerEnrollmentResponse": { "properties": { "controller_id": { "format": "uuid", "title": "Controller Id", "type": "string" }, "enrollment_token": { "title": "Enrollment Token", "type": "string" }, "expires_at": { "format": "date-time", "title": "Expires At", "type": "string" }, "host_instance_id": { "format": "uuid", "title": "Host Instance Id", "type": "string" }, "key_generation": { "title": "Key Generation", "type": "integer" }, "workshop_id": { "format": "uuid", "title": "Workshop Id", "type": "string" } }, "required": [ "controller_id", "workshop_id", "host_instance_id", "key_generation", "enrollment_token", "expires_at" ], "title": "ControllerEnrollmentResponse", "type": "object" }, "ControllerEnvelope": { "additionalProperties": false, "properties": { "controller_epoch": { "anyOf": [ { "minimum": 0.0, "type": "integer" }, { "type": "null" } ], "title": "Controller Epoch" }, "controller_id": { "format": "uuid", "title": "Controller Id", "type": "string" }, "host_instance_id": { "format": "uuid", "title": "Host Instance Id", "type": "string" }, "issued_at": { "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$", "title": "Issued At", "type": "string" }, "key_generation": { "minimum": 1.0, "title": "Key Generation", "type": "integer" }, "kind": { "enum": [ "enrollment.claim", "readiness", "mode.applied", "relay.attach", "transport.paused", "file.read", "file.save", "action.authorize", "teach.save", "egress.read" ], "title": "Kind", "type": "string" }, "nonce": { "format": "uuid", "title": "Nonce", "type": "string" }, "payload": { "anyOf": [ { "$ref": "#/components/schemas/ControllerClaimProof" }, { "$ref": "#/components/schemas/ControllerRelayProfilePurgeReadiness" }, { "$ref": "#/components/schemas/ControllerRelayReadiness" }, { "$ref": "#/components/schemas/ControllerProfilePurgeReadiness" }, { "$ref": "#/components/schemas/ControllerPresentationReadiness" }, { "$ref": "#/components/schemas/ControllerPolicyReadiness" }, { "$ref": "#/components/schemas/ControllerRuntimeReadiness" }, { "$ref": "#/components/schemas/ControllerReadiness" }, { "$ref": "#/components/schemas/ControllerModeApplied" }, { "$ref": "#/components/schemas/ControllerRelayAttach" }, { "$ref": "#/components/schemas/ControllerTransportPaused" }, { "$ref": "#/components/schemas/ControllerFileRead" }, { "$ref": "#/components/schemas/ControllerFileSave" }, { "$ref": "#/components/schemas/ControllerActionAuthorize" }, { "$ref": "#/components/schemas/ControllerDemonstrationSave" }, { "$ref": "#/components/schemas/ControllerTeachSave" }, { "$ref": "#/components/schemas/ControllerEgressRead" } ], "title": "Payload" }, "session_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Session Id" }, "tenant_id": { "format": "uuid", "title": "Tenant Id", "type": "string" }, "version": { "const": 1, "title": "Version", "type": "integer" }, "workshop_id": { "format": "uuid", "title": "Workshop Id", "type": "string" } }, "required": [ "version", "kind", "tenant_id", "controller_id", "workshop_id", "host_instance_id", "key_generation", "session_id", "controller_epoch", "issued_at", "nonce", "payload" ], "title": "ControllerEnvelope", "type": "object" }, "ControllerFileRead": { "additionalProperties": false, "properties": { "file_id": { "format": "uuid", "title": "File Id", "type": "string" } }, "required": [ "file_id" ], "title": "ControllerFileRead", "type": "object" }, "ControllerFileSave": { "additionalProperties": false, "properties": { "download_id": { "format": "uuid", "title": "Download Id", "type": "string" }, "filename": { "maxLength": 255, "minLength": 1, "pattern": "^[^/\\\\\\x00-\\x1f\\x7f]+$", "title": "Filename", "type": "string" }, "mime_type": { "maxLength": 128, "pattern": "^[a-zA-Z0-9!#$&^_.+-]+/[a-zA-Z0-9!#$&^_.+-]+$", "title": "Mime Type", "type": "string" }, "sha256": { "pattern": "^[0-9a-f]{64}$", "title": "Sha256", "type": "string" }, "size_bytes": { "maximum": 26214400.0, "minimum": 1.0, "title": "Size Bytes", "type": "integer" } }, "required": [ "download_id", "filename", "mime_type", "size_bytes", "sha256" ], "title": "ControllerFileSave", "type": "object" }, "ControllerModeApplied": { "additionalProperties": false, "properties": { "isolation_enforced": { "title": "Isolation Enforced", "type": "boolean" }, "mode": { "enum": [ "paused", "agent", "private", "teach", "shared" ], "title": "Mode", "type": "string" }, "transition_id": { "format": "uuid", "title": "Transition Id", "type": "string" } }, "required": [ "transition_id", "mode", "isolation_enforced" ], "title": "ControllerModeApplied", "type": "object" }, "ControllerModeAppliedResponse": { "properties": { "controller_epoch": { "title": "Controller Epoch", "type": "integer" }, "mode": { "enum": [ "paused", "agent", "private", "teach", "shared", "unavailable", "closed" ], "title": "Mode", "type": "string" }, "session_id": { "format": "uuid", "title": "Session Id", "type": "string" } }, "required": [ "session_id", "mode", "controller_epoch" ], "title": "ControllerModeAppliedResponse", "type": "object" }, "ControllerPolicyReadiness": { "additionalProperties": false, "description": "Additive again (TIDY-18715 / D18): what this controller build enforces.\n\n``origin_policy`` says sessions are bounded by the account's origin policy\nrather than one pinned ``site_origin``; the API refuses\n``controller_outdated`` for an account a pinned controller cannot express\nuntil readiness carries it. A controller that omits ``capabilities`` still\nmatches ``ControllerRuntimeReadiness`` and keeps its exact signed bytes —\nthe signature is verified over exactly the fields the controller sent.", "properties": { "browser_sha256": { "pattern": "^[0-9a-f]{64}$", "title": "Browser Sha256", "type": "string" }, "capabilities": { "items": { "pattern": "^[a-z][a-z0-9_]{0,63}$", "type": "string" }, "maxItems": 16, "minItems": 1, "title": "Capabilities", "type": "array" }, "isolation_enforced": { "title": "Isolation Enforced", "type": "boolean" }, "platform_baseline_version": { "pattern": "^[A-Za-z0-9][A-Za-z0-9._+-]{0,63}$", "title": "Platform Baseline Version", "type": "string" }, "platform_target": { "pattern": "^[a-z0-9][a-z0-9._-]{0,63}$", "title": "Platform Target", "type": "string" } }, "required": [ "isolation_enforced", "platform_baseline_version", "platform_target", "browser_sha256", "capabilities" ], "title": "ControllerPolicyReadiness", "type": "object" }, "ControllerPresentationReadiness": { "additionalProperties": false, "description": "Additive again (TIDY-18717 / D21): how the person-driven browser presents.\n\n``presentation`` is ``headed`` (a Linux workshop with a healthy private\ndisplay) or ``headless_relaxed``; ``display`` says WHY —\n``ready`` / ``unavailable`` (Linux, no reachable display socket) /\n``unsupported`` (macOS / Windows have no display session by design) — so a\nmissing display is reported on the controller card, never a silent\ndowngrade. The two travel together and are signed as sent: a controller\nthat omits both still matches ``ControllerPolicyReadiness`` and keeps its\nexact signed bytes, so a 1.1.152/1.1.153 report verifies unchanged.", "properties": { "browser_sha256": { "pattern": "^[0-9a-f]{64}$", "title": "Browser Sha256", "type": "string" }, "capabilities": { "items": { "pattern": "^[a-z][a-z0-9_]{0,63}$", "type": "string" }, "maxItems": 16, "minItems": 1, "title": "Capabilities", "type": "array" }, "display": { "enum": [ "ready", "unavailable", "unsupported" ], "title": "Display", "type": "string" }, "isolation_enforced": { "title": "Isolation Enforced", "type": "boolean" }, "platform_baseline_version": { "pattern": "^[A-Za-z0-9][A-Za-z0-9._+-]{0,63}$", "title": "Platform Baseline Version", "type": "string" }, "platform_target": { "pattern": "^[a-z0-9][a-z0-9._-]{0,63}$", "title": "Platform Target", "type": "string" }, "presentation": { "enum": [ "headed", "headless_relaxed" ], "title": "Presentation", "type": "string" } }, "required": [ "isolation_enforced", "platform_baseline_version", "platform_target", "browser_sha256", "capabilities", "presentation", "display" ], "title": "ControllerPresentationReadiness", "type": "object" }, "ControllerProfilePurgeReadiness": { "additionalProperties": false, "description": "Additive again (TIDY-19814): the deleted accounts' profiles it removed.\n\nThe API answers readiness with ``retired_profiles`` — browsing accounts\ndeleted on this workshop whose profile directory may still hold their\ncookies and sign-ins. The controller removes each and confirms them here,\nsigned; sent only when there is something to confirm, so every other\nreport keeps the exact bytes ``ControllerPresentationReadiness`` signs.", "properties": { "browser_sha256": { "pattern": "^[0-9a-f]{64}$", "title": "Browser Sha256", "type": "string" }, "capabilities": { "items": { "pattern": "^[a-z][a-z0-9_]{0,63}$", "type": "string" }, "maxItems": 16, "minItems": 1, "title": "Capabilities", "type": "array" }, "display": { "enum": [ "ready", "unavailable", "unsupported" ], "title": "Display", "type": "string" }, "isolation_enforced": { "title": "Isolation Enforced", "type": "boolean" }, "platform_baseline_version": { "pattern": "^[A-Za-z0-9][A-Za-z0-9._+-]{0,63}$", "title": "Platform Baseline Version", "type": "string" }, "platform_target": { "pattern": "^[a-z0-9][a-z0-9._-]{0,63}$", "title": "Platform Target", "type": "string" }, "presentation": { "enum": [ "headed", "headless_relaxed" ], "title": "Presentation", "type": "string" }, "purged_profiles": { "items": { "format": "uuid", "type": "string" }, "maxItems": 64, "minItems": 1, "title": "Purged Profiles", "type": "array" } }, "required": [ "isolation_enforced", "platform_baseline_version", "platform_target", "browser_sha256", "capabilities", "presentation", "display", "purged_profiles" ], "title": "ControllerProfilePurgeReadiness", "type": "object" }, "ControllerReadiness": { "additionalProperties": false, "properties": { "isolation_enforced": { "title": "Isolation Enforced", "type": "boolean" }, "platform_baseline_version": { "pattern": "^[A-Za-z0-9][A-Za-z0-9._+-]{0,63}$", "title": "Platform Baseline Version", "type": "string" } }, "required": [ "isolation_enforced", "platform_baseline_version" ], "title": "ControllerReadiness", "type": "object" }, "ControllerRelayAttach": { "additionalProperties": false, "properties": { "challenge": { "maxLength": 128, "minLength": 43, "pattern": "^[A-Za-z0-9_-]+$", "title": "Challenge", "type": "string" } }, "required": [ "challenge" ], "title": "ControllerRelayAttach", "type": "object" }, "ControllerRelayProfilePurgeReadiness": { "additionalProperties": false, "description": "A link report that also acknowledges deleted profiles.", "properties": { "browser_sha256": { "pattern": "^[0-9a-f]{64}$", "title": "Browser Sha256", "type": "string" }, "capabilities": { "items": { "pattern": "^[a-z][a-z0-9_]{0,63}$", "type": "string" }, "maxItems": 16, "minItems": 1, "title": "Capabilities", "type": "array" }, "display": { "enum": [ "ready", "unavailable", "unsupported" ], "title": "Display", "type": "string" }, "isolation_enforced": { "title": "Isolation Enforced", "type": "boolean" }, "platform_baseline_version": { "pattern": "^[A-Za-z0-9][A-Za-z0-9._+-]{0,63}$", "title": "Platform Baseline Version", "type": "string" }, "platform_target": { "pattern": "^[a-z0-9][a-z0-9._-]{0,63}$", "title": "Platform Target", "type": "string" }, "presentation": { "enum": [ "headed", "headless_relaxed" ], "title": "Presentation", "type": "string" }, "purged_profiles": { "items": { "format": "uuid", "type": "string" }, "maxItems": 64, "minItems": 1, "title": "Purged Profiles", "type": "array" }, "relay_connected": { "title": "Relay Connected", "type": "boolean" } }, "required": [ "isolation_enforced", "platform_baseline_version", "platform_target", "browser_sha256", "capabilities", "presentation", "display", "relay_connected", "purged_profiles" ], "title": "ControllerRelayProfilePurgeReadiness", "type": "object" }, "ControllerRelayReadiness": { "additionalProperties": false, "description": "Additive link availability, distinct from the OS isolation proof.\n\nThe earlier variants keep their exact signed bytes while a connector lags.", "properties": { "browser_sha256": { "pattern": "^[0-9a-f]{64}$", "title": "Browser Sha256", "type": "string" }, "capabilities": { "items": { "pattern": "^[a-z][a-z0-9_]{0,63}$", "type": "string" }, "maxItems": 16, "minItems": 1, "title": "Capabilities", "type": "array" }, "display": { "enum": [ "ready", "unavailable", "unsupported" ], "title": "Display", "type": "string" }, "isolation_enforced": { "title": "Isolation Enforced", "type": "boolean" }, "platform_baseline_version": { "pattern": "^[A-Za-z0-9][A-Za-z0-9._+-]{0,63}$", "title": "Platform Baseline Version", "type": "string" }, "platform_target": { "pattern": "^[a-z0-9][a-z0-9._-]{0,63}$", "title": "Platform Target", "type": "string" }, "presentation": { "enum": [ "headed", "headless_relaxed" ], "title": "Presentation", "type": "string" }, "relay_connected": { "title": "Relay Connected", "type": "boolean" } }, "required": [ "isolation_enforced", "platform_baseline_version", "platform_target", "browser_sha256", "capabilities", "presentation", "display", "relay_connected" ], "title": "ControllerRelayReadiness", "type": "object" }, "ControllerRuntimeReadiness": { "additionalProperties": false, "description": "Additive runtime proof; the earlier signed payload keeps its exact bytes.", "properties": { "browser_sha256": { "pattern": "^[0-9a-f]{64}$", "title": "Browser Sha256", "type": "string" }, "isolation_enforced": { "title": "Isolation Enforced", "type": "boolean" }, "platform_baseline_version": { "pattern": "^[A-Za-z0-9][A-Za-z0-9._+-]{0,63}$", "title": "Platform Baseline Version", "type": "string" }, "platform_target": { "pattern": "^[a-z0-9][a-z0-9._-]{0,63}$", "title": "Platform Target", "type": "string" } }, "required": [ "isolation_enforced", "platform_baseline_version", "platform_target", "browser_sha256" ], "title": "ControllerRuntimeReadiness", "type": "object" }, "ControllerSignedRequest": { "additionalProperties": false, "properties": { "message": { "$ref": "#/components/schemas/ControllerEnvelope" }, "signature": { "format": "password", "maxLength": 128, "minLength": 80, "title": "Signature", "type": "string", "writeOnly": true } }, "required": [ "message", "signature" ], "title": "ControllerSignedRequest", "type": "object" }, "ControllerStatusResponse": { "properties": { "accepts": { "items": { "type": "string" }, "maxItems": 16, "title": "Accepts", "type": "array" }, "controller_id": { "format": "uuid", "title": "Controller Id", "type": "string" }, "host_instance_id": { "format": "uuid", "title": "Host Instance Id", "type": "string" }, "key_generation": { "title": "Key Generation", "type": "integer" }, "retired_profiles": { "items": { "format": "uuid", "type": "string" }, "title": "Retired Profiles", "type": "array" }, "status": { "enum": [ "enrolled", "ready" ], "title": "Status", "type": "string" } }, "required": [ "controller_id", "host_instance_id", "key_generation", "status" ], "title": "ControllerStatusResponse", "type": "object" }, "ControllerTeachSave": { "additionalProperties": false, "description": "An explicit Save and its recording, signed by the protected controller.\n\nThis exact shape is an older controller's: its bare structural recording is\nrefused ``controller_outdated`` (TIDY-18934 F10). It still parses, so the\nrefusal is named rather than a validation error.", "properties": { "capture": { "additionalProperties": true, "title": "Capture", "type": "object" }, "name": { "maxLength": 128, "minLength": 1, "title": "Name", "type": "string" }, "request_key": { "format": "uuid", "title": "Request Key", "type": "string" } }, "required": [ "name", "request_key", "capture" ], "title": "ControllerTeachSave", "type": "object" }, "ControllerTransportPaused": { "additionalProperties": false, "properties": { "client_id": { "maxLength": 128, "minLength": 1, "title": "Client Id", "type": "string" }, "reason": { "enum": [ "disconnect", "heartbeat_timeout", "relay_lost", "transition_timeout", "authority_expired" ], "title": "Reason", "type": "string" } }, "required": [ "client_id", "reason" ], "title": "ControllerTransportPaused", "type": "object" }, "ConversationBadges": { "description": "Badge counts for a conversation/thread.", "properties": { "attachment_count": { "default": 0, "description": "Total attachments across thread", "title": "Attachment Count", "type": "integer" }, "email_count": { "default": 0, "description": "Number of emails in thread", "title": "Email Count", "type": "integer" }, "has_attachments": { "default": false, "description": "Whether thread has any attachments", "title": "Has Attachments", "type": "boolean" }, "note_count": { "default": 0, "description": "Number of user notes in thread", "title": "Note Count", "type": "integer" }, "participant_count": { "default": 0, "description": "Unique participants in thread", "title": "Participant Count", "type": "integer" }, "task_count": { "default": 0, "description": "Total tasks extracted from thread", "title": "Task Count", "type": "integer" }, "tasks_completed": { "default": 0, "description": "Completed tasks count", "title": "Tasks Completed", "type": "integer" }, "tasks_overdue": { "default": 0, "description": "Overdue tasks count", "title": "Tasks Overdue", "type": "integer" }, "unread_count": { "default": 0, "description": "Unread emails in thread", "title": "Unread Count", "type": "integer" } }, "title": "ConversationBadges", "type": "object" }, "ConversationChannelDepartureResponse": { "properties": { "channel_name": { "title": "Channel Name", "type": "string" }, "continued_conversation_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Continued Conversation Id" }, "continues_with": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Continues With" }, "continues_with_account_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Continues With Account Id" }, "pending": { "title": "Pending", "type": "boolean" }, "room_id": { "title": "Room Id", "type": "string" } }, "required": [ "room_id", "channel_name", "pending" ], "title": "ConversationChannelDepartureResponse", "type": "object" }, "ConversationChannelResponse": { "properties": { "carried": { "default": false, "title": "Carried", "type": "boolean" }, "conversation_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Conversation Id" }, "event_id": { "title": "Event Id", "type": "string" }, "invited_account_ids": { "items": { "type": "string" }, "title": "Invited Account Ids", "type": "array" }, "name": { "title": "Name", "type": "string" }, "room_id": { "title": "Room Id", "type": "string" } }, "required": [ "room_id", "name", "event_id" ], "title": "ConversationChannelResponse", "type": "object" }, "ConversationItemBinding": { "properties": { "active": { "title": "Active", "type": "boolean" }, "primitive_id": { "title": "Primitive Id", "type": "string" }, "primitive_type": { "title": "Primitive Type", "type": "string" }, "role": { "title": "Role", "type": "string" } }, "required": [ "primitive_type", "primitive_id", "role", "active" ], "title": "ConversationItemBinding", "type": "object" }, "ConversationModel": { "properties": { "is_assistant": { "default": false, "title": "Is Assistant", "type": "boolean" }, "is_dm": { "title": "Is Dm", "type": "boolean" }, "last_message": { "anyOf": [ { "$ref": "#/components/schemas/LastMessageModel" }, { "type": "null" } ], "default": null }, "managed_crypto": { "anyOf": [ { "enum": [ "available", "unavailable", "unknown" ], "type": "string" }, { "type": "null" } ], "default": null, "title": "Managed Crypto" }, "member_display_names": { "items": { "type": "string" }, "title": "Member Display Names", "type": "array" }, "name": { "title": "Name", "type": "string" }, "room_id": { "title": "Room Id", "type": "string" }, "unread_count": { "default": 0, "title": "Unread Count", "type": "integer" } }, "required": [ "room_id", "name", "is_dm" ], "title": "ConversationModel", "type": "object" }, "ConversationSearchHit": { "properties": { "agent_member_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Agent Member Id" }, "agent_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Agent Name" }, "conversation_id": { "title": "Conversation Id", "type": "string" }, "last_active_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Active At" }, "linked_items": { "items": { "$ref": "#/components/schemas/ConversationItemBinding" }, "title": "Linked Items", "type": "array" }, "matched_in": { "description": "Which index leg produced the hit: message | title | chat | item_link.", "title": "Matched In", "type": "string" }, "matrix_room_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Matrix Room Id" }, "matrix_thread_root_event_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Matrix Thread Root Event Id" }, "origin": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Origin" }, "rank": { "title": "Rank", "type": "number" }, "settled": { "title": "Settled", "type": "boolean" }, "snippet": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Snippet" }, "status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Status" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Title" } }, "required": [ "conversation_id", "settled", "rank", "matched_in" ], "title": "ConversationSearchHit", "type": "object" }, "ConversationSearchResponse": { "properties": { "encrypted_content_excluded": { "description": "True when the caller's scope holds end-to-end-encrypted chat the server index cannot search — only a client's local lane covers that content.", "title": "Encrypted Content Excluded", "type": "boolean" }, "lane": { "default": "server", "title": "Lane", "type": "string" }, "results": { "items": { "$ref": "#/components/schemas/ConversationSearchHit" }, "title": "Results", "type": "array" } }, "required": [ "results", "encrypted_content_excluded" ], "title": "ConversationSearchResponse", "type": "object" }, "ConversationSummaryResponse": { "description": "Response for conversation summary with badges.", "properties": { "badges": { "$ref": "#/components/schemas/ConversationBadges", "description": "Conversation badges" }, "conversation_summary": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Paragraph summary of entire conversation", "title": "Conversation Summary" }, "subject": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Thread subject from first email", "title": "Subject" }, "summary_quality_score": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "description": "Aggregated quality score from feedback", "title": "Summary Quality Score" }, "summary_updated_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "description": "When summary was last updated", "title": "Summary Updated At" }, "thread_id": { "description": "Thread UUID", "format": "uuid", "title": "Thread Id", "type": "string" } }, "required": [ "thread_id" ], "title": "ConversationSummaryResponse", "type": "object" }, "ConversationWorktreeProject": { "properties": { "choice": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "This project's own choice; null when it follows the default.", "title": "Choice" }, "folder_ready": { "default": false, "description": "The linked repository's managed folder is ready on its workshop.", "title": "Folder Ready", "type": "boolean" }, "name": { "title": "Name", "type": "string" }, "project_id": { "title": "Project Id", "type": "string" }, "separate_copy": { "description": "What a new conversation in it gets: its own working copy of the project's repository (true), or the project's folder (false).", "title": "Separate Copy", "type": "boolean" } }, "required": [ "project_id", "name", "choice", "separate_copy" ], "title": "ConversationWorktreeProject", "type": "object" }, "ConversationWorktreesChange": { "additionalProperties": false, "description": "Only what is named changes; it applies to new conversations only.", "properties": { "default": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "The default for its projects.", "title": "Default" }, "projects": { "additionalProperties": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "description": "Per project id: true or false is that project's own choice, null returns it to the default. A project not named keeps its choice.", "title": "ConversationWorktreeChoices", "type": "object" } }, "title": "ConversationWorktreesChange", "type": "object" }, "ConversationsResponse": { "properties": { "conversations": { "items": { "$ref": "#/components/schemas/ConversationModel" }, "title": "Conversations", "type": "array" } }, "title": "ConversationsResponse", "type": "object" }, "ConvertCheckDuplicateRequest": { "properties": { "fileHash": { "title": "Filehash", "type": "string" } }, "required": [ "fileHash" ], "title": "ConvertCheckDuplicateRequest", "type": "object" }, "ConvertCheckDuplicateResponse": { "properties": { "exists": { "title": "Exists", "type": "boolean" }, "noteId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Noteid" }, "noteTitle": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Notetitle" } }, "required": [ "exists" ], "title": "ConvertCheckDuplicateResponse", "type": "object" }, "ConvertDocxResponse": { "properties": { "imageCount": { "title": "Imagecount", "type": "integer" }, "imagesUploaded": { "title": "Imagesuploaded", "type": "integer" }, "importSourceType": { "title": "Importsourcetype", "type": "string" }, "noteId": { "title": "Noteid", "type": "string" }, "originalFilename": { "title": "Originalfilename", "type": "string" }, "title": { "title": "Title", "type": "string" } }, "required": [ "noteId", "title", "originalFilename", "importSourceType", "imageCount", "imagesUploaded" ], "title": "ConvertDocxResponse", "type": "object" }, "ConvertHealthResponse": { "properties": { "echoTest": { "additionalProperties": true, "title": "Echotest", "type": "object" }, "pool": { "additionalProperties": true, "title": "Pool", "type": "object" }, "status": { "title": "Status", "type": "string" } }, "required": [ "status", "pool", "echoTest" ], "title": "ConvertHealthResponse", "type": "object" }, "ConvertPptxResponse": { "properties": { "importSourceType": { "title": "Importsourcetype", "type": "string" }, "noteId": { "title": "Noteid", "type": "string" }, "originalFilename": { "title": "Originalfilename", "type": "string" }, "slideCount": { "title": "Slidecount", "type": "integer" }, "title": { "title": "Title", "type": "string" } }, "required": [ "noteId", "title", "originalFilename", "importSourceType", "slideCount" ], "title": "ConvertPptxResponse", "type": "object" }, "ConvertXlsxResponse": { "properties": { "cellCount": { "title": "Cellcount", "type": "integer" }, "importSourceType": { "title": "Importsourcetype", "type": "string" }, "noteId": { "title": "Noteid", "type": "string" }, "originalFilename": { "title": "Originalfilename", "type": "string" }, "sheetCount": { "title": "Sheetcount", "type": "integer" }, "title": { "title": "Title", "type": "string" } }, "required": [ "noteId", "title", "originalFilename", "importSourceType", "sheetCount", "cellCount" ], "title": "ConvertXlsxResponse", "type": "object" }, "CorpusContractResponse": { "additionalProperties": false, "description": "The record schema version this environment's ingest accepts.", "properties": { "schema_version": { "title": "Schema Version", "type": "string" } }, "required": [ "schema_version" ], "title": "CorpusContractResponse", "type": "object" }, "CorpusEntityTypeCount": { "properties": { "count": { "title": "Count", "type": "integer" }, "type": { "enum": [ "person", "organization", "product", "book" ], "title": "Type", "type": "string" } }, "required": [ "type", "count" ], "title": "CorpusEntityTypeCount", "type": "object" }, "CorpusIngestRequest": { "additionalProperties": false, "description": "Writeback/seed ingest envelope.\n\n``record`` is the full tidy.podcast.global/v1 record JSON; ``vectors``\ninlines the parquet-sidecar embeddings (the record's JSONL form references\nthem by parquet_ref). ``source`` distinguishes continuous writeback from\nbulk seed replay.", "properties": { "dai_fingerprint_b64": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Dai Fingerprint B64" }, "record": { "additionalProperties": true, "title": "Record", "type": "object" }, "source": { "default": "writeback", "title": "Source", "type": "string" }, "vectors": { "items": { "$ref": "#/components/schemas/CorpusIngestVector" }, "title": "Vectors", "type": "array" } }, "required": [ "record" ], "title": "CorpusIngestRequest", "type": "object" }, "CorpusIngestResponse": { "properties": { "episode_id": { "title": "Episode Id", "type": "string" }, "show_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Show Id" }, "status": { "title": "Status", "type": "string" }, "transcript_version_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Transcript Version Id" } }, "required": [ "status", "episode_id" ], "title": "CorpusIngestResponse", "type": "object" }, "CorpusIngestVector": { "additionalProperties": false, "description": "One chunk's embedding as the producer computed it (parquet sidecar).\n\nAccepted so older workers keep delivering, and never stored: the receiver\nembeds the chunk texts itself with the model behind every stored vector\n(TIDY-20237, ``nomic_embeddings``).", "properties": { "chunk_id": { "title": "Chunk Id", "type": "integer" }, "vector": { "items": { "type": "number" }, "title": "Vector", "type": "array" } }, "required": [ "chunk_id", "vector" ], "title": "CorpusIngestVector", "type": "object" }, "CorpusSearchHit": { "properties": { "chunk_id": { "title": "Chunk Id", "type": "string" }, "episode_artwork_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The episode's own artwork when its feed declares one; clients fall back to show_artwork_url. Null for show hits.", "title": "Episode Artwork Url" }, "episode_id": { "title": "Episode Id", "type": "string" }, "quality_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Quality Status" }, "result_type": { "default": "chunk", "description": "Discriminator (D16): 'chunk' = transcript hit (existing), 'show'/'episode' = global-catalog FTS hit. The client renders the matching row + 'mentioned in:' snippet from this.", "enum": [ "chunk", "show", "episode" ], "title": "Result Type", "type": "string" }, "score": { "title": "Score", "type": "number" }, "show_artwork_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The show's cover art as its feed declares it.", "title": "Show Artwork Url" }, "show_feed_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The show's RSS feed URL — the key a client opens the show by.", "title": "Show Feed Url" }, "show_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Show Id" }, "show_title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Title of the hit's show — every result names its podcast (TIDY-19384).", "title": "Show Title" }, "signals": { "additionalProperties": { "type": "number" }, "title": "Signals", "type": "object" }, "snippet": { "title": "Snippet", "type": "string" }, "speaker": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Speaker" }, "start_seconds": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Start Seconds" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Show/episode title for catalog hits; null for transcript chunks.", "title": "Title" } }, "required": [ "chunk_id", "episode_id", "snippet", "score" ], "title": "CorpusSearchHit", "type": "object" }, "CorpusSearchResponse": { "properties": { "degraded": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Set when retrieval degraded: 'bm25_only' when the query could not be embedded (keyword recall reads the same database as the request)", "title": "Degraded" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor" }, "query": { "title": "Query", "type": "string" }, "results": { "items": { "$ref": "#/components/schemas/CorpusSearchHit" }, "title": "Results", "type": "array" }, "scope": { "title": "Scope", "type": "string" } }, "required": [ "query", "scope", "results" ], "title": "CorpusSearchResponse", "type": "object" }, "CorpusSnapshotManifest": { "description": "One period manifest in the caller's corpus index.", "properties": { "byte_size": { "title": "Byte Size", "type": "integer" }, "chunk_count": { "title": "Chunk Count", "type": "integer" }, "compression": { "title": "Compression", "type": "string" }, "content_hash": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Content Hash" }, "period_end": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Period End" }, "period_key": { "title": "Period Key", "type": "string" }, "period_start": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Period Start" }, "snapshot_format": { "title": "Snapshot Format", "type": "string" }, "updated_at": { "format": "date-time", "title": "Updated At", "type": "string" } }, "required": [ "period_key", "byte_size", "chunk_count", "compression", "snapshot_format", "updated_at" ], "title": "CorpusSnapshotManifest", "type": "object" }, "CorpusSnapshotManifestList": { "description": "The caller's full corpus index — what B4 diffs against its local cache.", "properties": { "manifests": { "items": { "$ref": "#/components/schemas/CorpusSnapshotManifest" }, "title": "Manifests", "type": "array" } }, "required": [ "manifests" ], "title": "CorpusSnapshotManifestList", "type": "object" }, "CorpusStatsResponse": { "properties": { "entity_types": { "items": { "$ref": "#/components/schemas/CorpusEntityTypeCount" }, "title": "Entity Types", "type": "array" }, "top_entities": { "description": "Most mentioned entities by episode count, of `entity_type` when given.", "items": { "$ref": "#/components/schemas/CorpusTopEntity" }, "title": "Top Entities", "type": "array" }, "top_shows": { "description": "Shows with the most transcribed episodes.", "items": { "$ref": "#/components/schemas/CorpusTopShow" }, "title": "Top Shows", "type": "array" }, "totals": { "$ref": "#/components/schemas/CorpusStatsTotals" } }, "required": [ "totals", "entity_types", "top_entities", "top_shows" ], "title": "CorpusStatsResponse", "type": "object" }, "CorpusStatsTotals": { "properties": { "entities": { "description": "Entities with at least one mention.", "title": "Entities", "type": "integer" }, "episodes": { "title": "Episodes", "type": "integer" }, "mentions": { "title": "Mentions", "type": "integer" }, "shows": { "title": "Shows", "type": "integer" }, "transcribed_episodes": { "title": "Transcribed Episodes", "type": "integer" } }, "required": [ "shows", "episodes", "transcribed_episodes", "entities", "mentions" ], "title": "CorpusStatsTotals", "type": "object" }, "CorpusStatusResponse": { "description": "THIS env's corpus view from podcast_corpus_ingest_log (no dag call).", "properties": { "episodes_ingested": { "title": "Episodes Ingested", "type": "integer" }, "ingests_last_24h": { "title": "Ingests Last 24H", "type": "integer" }, "ingests_last_7d": { "title": "Ingests Last 7D", "type": "integer" }, "last_seed_at": { "anyOf": [ {}, { "type": "null" } ], "default": null, "title": "Last Seed At" }, "last_seed_count": { "default": 0, "title": "Last Seed Count", "type": "integer" }, "last_writeback_at": { "anyOf": [ {}, { "type": "null" } ], "default": null, "title": "Last Writeback At" }, "last_writeback_episode_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Last Writeback Episode Id" }, "pipeline_versions": { "default": [], "items": { "type": "string" }, "title": "Pipeline Versions", "type": "array" }, "schema_versions": { "default": [], "items": { "type": "string" }, "title": "Schema Versions", "type": "array" } }, "required": [ "episodes_ingested", "ingests_last_24h", "ingests_last_7d" ], "title": "CorpusStatusResponse", "type": "object" }, "CorpusTopEntity": { "properties": { "canonical_name": { "title": "Canonical Name", "type": "string" }, "episode_count": { "title": "Episode Count", "type": "integer" }, "id": { "title": "Id", "type": "string" }, "mention_count": { "title": "Mention Count", "type": "integer" }, "type": { "enum": [ "person", "organization", "product", "book" ], "title": "Type", "type": "string" } }, "required": [ "id", "canonical_name", "type", "episode_count", "mention_count" ], "title": "CorpusTopEntity", "type": "object" }, "CorpusTopShow": { "properties": { "artwork_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Artwork Url" }, "feed_url": { "title": "Feed Url", "type": "string" }, "id": { "title": "Id", "type": "string" }, "title": { "title": "Title", "type": "string" }, "transcribed_episodes": { "title": "Transcribed Episodes", "type": "integer" } }, "required": [ "id", "title", "feed_url", "transcribed_episodes" ], "title": "CorpusTopShow", "type": "object" }, "CorrelationCard": { "properties": { "correlation_direction": { "title": "Correlation Direction", "type": "string" }, "narrative": { "title": "Narrative", "type": "string" } }, "required": [ "correlation_direction", "narrative" ], "title": "CorrelationCard", "type": "object" }, "CorrelationCoverageResponse": { "description": "R17/R19 observability: % commits linked, % edit operations anchored.", "properties": { "anchor_pct": { "title": "Anchor Pct", "type": "number" }, "commit_link_pct": { "title": "Commit Link Pct", "type": "number" }, "commits_linked": { "title": "Commits Linked", "type": "integer" }, "commits_total": { "title": "Commits Total", "type": "integer" }, "edit_operations_anchored": { "title": "Edit Operations Anchored", "type": "integer" }, "edit_operations_total": { "title": "Edit Operations Total", "type": "integer" } }, "required": [ "commits_total", "commits_linked", "commit_link_pct", "edit_operations_total", "edit_operations_anchored", "anchor_pct" ], "title": "CorrelationCoverageResponse", "type": "object" }, "CorrelationsResponse": { "properties": { "by_week": { "items": { "$ref": "#/components/schemas/WeeklyBreakdown" }, "title": "By Week", "type": "array" }, "communication_overhead_pct": { "title": "Communication Overhead Pct", "type": "number" }, "email_to_task_conversion_pct": { "title": "Email To Task Conversion Pct", "type": "number" }, "focus_vs_completion": { "$ref": "#/components/schemas/CorrelationCard" }, "meeting_to_task_ratio": { "title": "Meeting To Task Ratio", "type": "number" }, "meeting_vs_completion": { "$ref": "#/components/schemas/CorrelationCard" } }, "required": [ "email_to_task_conversion_pct", "meeting_to_task_ratio", "communication_overhead_pct", "focus_vs_completion", "meeting_vs_completion", "by_week" ], "title": "CorrelationsResponse", "type": "object" }, "CostLineResponse": { "properties": { "detail": { "title": "Detail", "type": "string" }, "label": { "title": "Label", "type": "string" }, "micros": { "title": "Micros", "type": "integer" } }, "required": [ "label", "detail", "micros" ], "title": "CostLineResponse", "type": "object" }, "CostTrendRow": { "properties": { "auto_transcribed_usd": { "title": "Auto Transcribed Usd", "type": "number" }, "total_usd": { "title": "Total Usd", "type": "number" }, "usage_date": { "format": "date", "title": "Usage Date", "type": "string" }, "user_initiated_usd": { "title": "User Initiated Usd", "type": "number" } }, "required": [ "usage_date", "auto_transcribed_usd", "user_initiated_usd", "total_usd" ], "title": "CostTrendRow", "type": "object" }, "CounterProposalRequest": { "description": "Request model for proposing a different time (COUNTER).", "example": { "comment": "This time works better for me", "proposed_end": "2024-01-15T15:00:00Z", "proposed_start": "2024-01-15T14:00:00Z", "send_email": true }, "properties": { "comment": { "anyOf": [ { "maxLength": 1000, "type": "string" }, { "type": "null" } ], "description": "Optional comment explaining the proposal", "title": "Comment" }, "include_availability": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Embed a busy-blocks-only snippet of the member's week (the week of the proposed time, in the member's timezone) in the outbound proposal (TIDY-16595). Omitted/null follows the member's stored 'Include my availability' preference (TIDY-16596 — this is how the assistant's counter honors 'where enabled' without re-asking); an explicit true/false overrides it. When it resolves true and the availability cannot be computed the request FAILS rather than sending without it.", "title": "Include Availability" }, "negotiation": { "anyOf": [ { "$ref": "#/components/schemas/NegotiationRequest" }, { "type": "null" } ], "description": "Assistant-managed async negotiation context (TIDY-16597). Only the assistant's send path supplies this; manual proposals leave it unset and register no reply correlation." }, "proposed_end": { "description": "Proposed new end time for the event", "format": "date-time", "title": "Proposed End", "type": "string" }, "proposed_start": { "description": "Proposed new start time for the event", "format": "date-time", "title": "Proposed Start", "type": "string" }, "send_email": { "default": true, "description": "Whether to send COUNTER via email to organizer", "title": "Send Email", "type": "boolean" } }, "required": [ "proposed_start", "proposed_end" ], "title": "CounterProposalRequest", "type": "object" }, "CounterProposalResponse": { "description": "Response model after sending a counter proposal.", "example": { "counter_sent": true, "event_id": "550e8400-e29b-41d4-a716-446655440000", "ics_uid": "abc123@google.com", "proposed_end": "2024-01-15T15:00:00Z", "proposed_start": "2024-01-15T14:00:00Z" }, "properties": { "continuation_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The parked assistant_continuations row awaiting the reply.", "title": "Continuation Id" }, "counter_sent": { "description": "Whether COUNTER was sent via email", "title": "Counter Sent", "type": "boolean" }, "event_id": { "description": "Calendar event UUID", "title": "Event Id", "type": "string" }, "ics_uid": { "description": "ICS UID of the event", "title": "Ics Uid", "type": "string" }, "negotiation_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The async negotiation this send parked (assistant-managed sends only, TIDY-16597).", "title": "Negotiation Id" }, "proposed_end": { "description": "Proposed end time (ISO format)", "title": "Proposed End", "type": "string" }, "proposed_start": { "description": "Proposed start time (ISO format)", "title": "Proposed Start", "type": "string" } }, "required": [ "event_id", "ics_uid", "counter_sent", "proposed_start", "proposed_end" ], "title": "CounterProposalResponse", "type": "object" }, "CoverageContribution": { "description": "One implementing work item and how it classified.", "properties": { "activity_id": { "title": "Activity Id", "type": "string" }, "category": { "title": "Category", "type": "string" }, "facets": { "default": [], "items": { "type": "string" }, "title": "Facets", "type": "array" }, "link_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Link Id" }, "status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Status" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Title" } }, "required": [ "activity_id", "category" ], "title": "CoverageContribution", "type": "object" }, "CoverageReport": { "description": "Structured project coverage report (the compact verifier output).", "properties": { "commits_without_requirements": { "default": [], "items": { "type": "string" }, "title": "Commits Without Requirements", "type": "array" }, "counts": { "additionalProperties": { "type": "integer" }, "default": {}, "title": "Counts", "type": "object" }, "project_id": { "title": "Project Id", "type": "string" }, "requirements": { "default": [], "items": { "$ref": "#/components/schemas/RequirementReportEntry" }, "title": "Requirements", "type": "array" }, "tasks_done_without_passing_validation": { "default": [], "items": { "$ref": "#/components/schemas/UnlinkedWork" }, "title": "Tasks Done Without Passing Validation", "type": "array" }, "work_without_requirements": { "default": [], "items": { "$ref": "#/components/schemas/UnlinkedWork" }, "title": "Work Without Requirements", "type": "array" } }, "required": [ "project_id" ], "title": "CoverageReport", "type": "object" }, "CreateBundleRequest": { "properties": { "facet_slug": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Output type this bundle is bound to, e.g. 'briefing-doc'.", "title": "Facet Slug" }, "instructions": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Instructions" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name" } }, "title": "CreateBundleRequest", "type": "object" }, "CreateCardRequest": { "description": "Request body for creating a new card.", "properties": { "attachments": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "description": "Optional attachments (images, files)", "title": "Attachments" }, "cardType": { "description": "Type of card to create: 'ask', 'note', or 'journal'", "examples": [ "ask", "note", "journal" ], "title": "Cardtype", "type": "string" }, "content": { "description": "The text content of the card", "maxLength": 10000, "minLength": 1, "title": "Content", "type": "string" }, "location": { "anyOf": [ { "$ref": "#/components/schemas/Location" }, { "type": "null" } ], "description": "Optional location data" } }, "required": [ "cardType", "content" ], "title": "CreateCardRequest", "type": "object" }, "CreateCardResponse": { "description": "Response for card creation.", "properties": { "card": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "Full card object for immediate display in feed", "title": "Card" }, "cardId": { "description": "ID of the created card", "title": "Cardid", "type": "string" }, "estimatedCompletionSeconds": { "description": "Estimated time until AI response", "title": "Estimatedcompletionseconds", "type": "integer" }, "message": { "description": "Human-readable status message", "title": "Message", "type": "string" }, "status": { "description": "Initial processing status", "title": "Status", "type": "string" } }, "required": [ "cardId", "status", "message", "estimatedCompletionSeconds" ], "title": "CreateCardResponse", "type": "object" }, "CreateCouponRequest": { "properties": { "amount_off_cents": { "anyOf": [ { "exclusiveMinimum": 0.0, "type": "integer" }, { "type": "null" } ], "title": "Amount Off Cents" }, "duration": { "default": "once", "enum": [ "once", "repeating", "forever" ], "title": "Duration", "type": "string" }, "duration_in_months": { "anyOf": [ { "maximum": 36.0, "minimum": 1.0, "type": "integer" }, { "type": "null" } ], "title": "Duration In Months" }, "name": { "maxLength": 40, "minLength": 1, "title": "Name", "type": "string" }, "percent_off": { "anyOf": [ { "exclusiveMinimum": 0.0, "maximum": 100.0, "type": "number" }, { "type": "null" } ], "title": "Percent Off" } }, "required": [ "name" ], "title": "CreateCouponRequest", "type": "object" }, "CreateEventRequest": { "description": "Request to create calendar event from email.", "properties": { "all_day": { "default": false, "title": "All Day", "type": "boolean" }, "end_time": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "End Time" }, "meeting_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Meeting Url" }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Notes" }, "start_time": { "format": "date-time", "title": "Start Time", "type": "string" }, "title": { "maxLength": 500, "minLength": 1, "title": "Title", "type": "string" } }, "required": [ "title", "start_time" ], "title": "CreateEventRequest", "type": "object" }, "CreateEventResponse": { "description": "Response from event creation.", "properties": { "conflict_events": { "default": [], "items": { "type": "string" }, "title": "Conflict Events", "type": "array" }, "event_id": { "format": "uuid", "title": "Event Id", "type": "string" }, "has_conflict": { "title": "Has Conflict", "type": "boolean" }, "start_time": { "format": "date-time", "title": "Start Time", "type": "string" }, "title": { "title": "Title", "type": "string" } }, "required": [ "event_id", "title", "start_time", "has_conflict" ], "title": "CreateEventResponse", "type": "object" }, "CreateExtractionNoteRequest": { "description": "Request body for creating a note from selected email text.", "properties": { "end_offset": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Approximate end character offset in body_text", "title": "End Offset" }, "selected_html": { "anyOf": [ { "maxLength": 200000, "type": "string" }, { "type": "null" } ], "description": "HTML of selection (preserves links, images)", "title": "Selected Html" }, "selected_text": { "description": "Plain text selected by user", "maxLength": 50000, "minLength": 1, "title": "Selected Text", "type": "string" }, "start_offset": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Approximate start character offset in body_text", "title": "Start Offset" }, "tags": { "description": "User-assigned tags", "items": { "type": "string" }, "title": "Tags", "type": "array" }, "title": { "anyOf": [ { "maxLength": 500, "type": "string" }, { "type": "null" } ], "description": "Note title (defaults to email subject)", "title": "Title" }, "user_text": { "anyOf": [ { "maxLength": 10000, "type": "string" }, { "type": "null" } ], "description": "User's own notes about the quote", "title": "User Text" } }, "required": [ "selected_text" ], "title": "CreateExtractionNoteRequest", "type": "object" }, "CreateExtractionNoteResponse": { "description": "Response for extraction note creation.", "properties": { "backlink_created": { "default": true, "description": "Whether backlink to email was created", "title": "Backlink Created", "type": "boolean" }, "note_id": { "description": "Created note UUID", "format": "uuid", "title": "Note Id", "type": "string" } }, "required": [ "note_id" ], "title": "CreateExtractionNoteResponse", "type": "object" }, "CreateFileFromAttachmentRequest": { "description": "Save an email attachment into Files (TIDY-13529 / R2; Save to Tidy, TIDY-19664).\n\nName the attachment by its ``processed_attachments`` row, or by the email\npart itself: most parts of a message have no processed row.", "properties": { "email_canonical_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "description": "The email whose attachment to save (with filename)", "title": "Email Canonical Id" }, "filename": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The attachment's filename in that email", "title": "Filename" }, "folder_path": { "default": "/Email", "description": "Destination virtual folder", "title": "Folder Path", "type": "string" }, "part": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Selects one of several attachments sharing the filename, as the content endpoint's part parameter does", "title": "Part" }, "processed_attachment_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "description": "processed_attachments.id of the attachment to save", "title": "Processed Attachment Id" } }, "title": "CreateFileFromAttachmentRequest", "type": "object" }, "CreateFileFromObjectRequest": { "description": "Materialize a Tidy object (email → .eml, event → .ics) into a Files row\n(Universal Object Transfer, TIDY-14323 / R3). The server serializes the\nreferenced object's original bytes and stores them as a first-class file in\nthe destination folder — previewable, wiki-linkable, re-organizable.", "properties": { "folder_path": { "default": "/Uploads", "description": "Destination virtual folder", "title": "Folder Path", "type": "string" }, "object_id": { "description": "ID of the email or event to serialize", "format": "uuid", "title": "Object Id", "type": "string" }, "object_type": { "description": "Kind of object to serialize into a file", "enum": [ "email", "event" ], "title": "Object Type", "type": "string" } }, "required": [ "object_type", "object_id" ], "title": "CreateFileFromObjectRequest", "type": "object" }, "CreateGoalRequest": { "properties": { "contact_frequency": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": "weekly", "title": "Contact Frequency" }, "contact_id": { "format": "uuid", "title": "Contact Id", "type": "string" }, "meeting_cadence": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Meeting Cadence" }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Notes" }, "response_time_target_hours": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Response Time Target Hours" } }, "required": [ "contact_id" ], "title": "CreateGoalRequest", "type": "object" }, "CreateGoalResponse": { "properties": { "created": { "title": "Created", "type": "boolean" }, "record_id": { "title": "Record Id", "type": "string" } }, "required": [ "record_id", "created" ], "title": "CreateGoalResponse", "type": "object" }, "CreateGrantRequest": { "properties": { "action": { "enum": [ "read", "read_write" ], "title": "Action", "type": "string" }, "container_ref": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Container Ref" }, "delegatee_account_id": { "format": "uuid", "title": "Delegatee Account Id", "type": "string" }, "delegatee_member_type": { "enum": [ "human", "virtual_employee" ], "title": "Delegatee Member Type", "type": "string" }, "delegator_account_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Delegator Account Id" }, "expires_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Expires At" }, "facet_keys": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Facet Keys" }, "resource_type": { "enum": [ "calendar", "notes", "projects", "contacts", "activities", "inbox", "photos", "podcasts", "files", "structure", "sessions", "records" ], "title": "Resource Type", "type": "string" } }, "required": [ "resource_type", "delegatee_account_id", "delegatee_member_type", "action" ], "title": "CreateGrantRequest", "type": "object" }, "CreateKeywordAlertRequest": { "description": "Request body for ``POST /api/v1/chat/keyword-alerts``.", "properties": { "keyword": { "maxLength": 100, "minLength": 1, "title": "Keyword", "type": "string" } }, "required": [ "keyword" ], "title": "CreateKeywordAlertRequest", "type": "object" }, "CreateNoteRequest": { "description": "Request body for creating a note on an email.\n\nAttributes:\n content: Note text content (required)\n\nExample:\n {\"content\": \"Remember to follow up on this\"}", "properties": { "content": { "description": "Note text", "maxLength": 10000, "minLength": 1, "title": "Content", "type": "string" } }, "required": [ "content" ], "title": "CreateNoteRequest", "type": "object" }, "CreateNoteResponse": { "description": "Response for note creation endpoint.\n\nAttributes:\n id: Created note UUID\n email_id: Email the note is attached to\n thread_id: Thread the note belongs to\n content: Note text content\n created_at: When the note was created\n note_type: Source of note (always 'user' for manual creation)\n\nExample:\n {\n \"id\": \"uuid-here\",\n \"email_id\": \"email-uuid\",\n \"thread_id\": \"thread-uuid\",\n \"content\": \"Remember to follow up\",\n \"created_at\": \"2026-01-14T10:30:00Z\",\n \"note_type\": \"user\"\n }", "properties": { "content": { "description": "Note text content", "title": "Content", "type": "string" }, "created_at": { "description": "When the note was created", "format": "date-time", "title": "Created At", "type": "string" }, "email_id": { "description": "Email the note is attached to", "format": "uuid", "title": "Email Id", "type": "string" }, "id": { "description": "Created note UUID", "format": "uuid", "title": "Id", "type": "string" }, "note_type": { "default": "user", "description": "Source of note", "title": "Note Type", "type": "string" }, "thread_id": { "description": "Thread the note belongs to", "format": "uuid", "title": "Thread Id", "type": "string" } }, "required": [ "id", "email_id", "thread_id", "content", "created_at" ], "title": "CreateNoteResponse", "type": "object" }, "CreatePATRequest": { "properties": { "agent_label": { "anyOf": [ { "maxLength": 120, "type": "string" }, { "type": "null" } ], "title": "Agent Label" }, "client_kind": { "default": "user", "pattern": "^(agent|user)$", "title": "Client Kind", "type": "string" }, "expires_in_days": { "anyOf": [ { "maximum": 365.0, "minimum": 1.0, "type": "integer" }, { "type": "null" } ], "title": "Expires In Days" }, "name": { "maxLength": 120, "minLength": 1, "title": "Name", "type": "string" }, "scopes": { "items": { "type": "string" }, "title": "Scopes", "type": "array" } }, "required": [ "name", "scopes" ], "title": "CreatePATRequest", "type": "object" }, "CreatePATResponse": { "properties": { "record": { "$ref": "#/components/schemas/PATPublic" }, "value": { "title": "Value", "type": "string" } }, "required": [ "value", "record" ], "title": "CreatePATResponse", "type": "object" }, "CreatePlanRequest": { "properties": { "agent_assignee": { "anyOf": [ { "maxLength": 200, "type": "string" }, { "type": "null" } ], "title": "Agent Assignee" }, "tasks": { "items": { "$ref": "#/components/schemas/PlanTaskInput" }, "minItems": 1, "title": "Tasks", "type": "array" }, "title": { "maxLength": 500, "minLength": 1, "title": "Title", "type": "string" } }, "required": [ "title", "tasks" ], "title": "CreatePlanRequest", "type": "object" }, "CreatePollRequest": { "properties": { "allows_multiple": { "default": false, "title": "Allows Multiple", "type": "boolean" }, "close_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Close At" }, "hide_results_until_close": { "default": false, "title": "Hide Results Until Close", "type": "boolean" }, "is_anonymous": { "default": false, "title": "Is Anonymous", "type": "boolean" }, "kind": { "default": "quick", "pattern": "^(quick|structured)$", "title": "Kind", "type": "string" }, "options": { "items": { "$ref": "#/components/schemas/PollOption" }, "maxItems": 10, "minItems": 2, "title": "Options", "type": "array" }, "question": { "maxLength": 500, "minLength": 1, "title": "Question", "type": "string" }, "thread_event_id": { "anyOf": [ { "maxLength": 255, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Thread Event Id" } }, "required": [ "question", "options" ], "title": "CreatePollRequest", "type": "object" }, "CreatePresentationDesignRequest": { "description": "Body for POST /api/v1/presentation-designs.", "properties": { "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "design": { "$ref": "#/components/schemas/DesignPayload" }, "forked_from_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Forked From Id" }, "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Id" }, "name": { "minLength": 1, "title": "Name", "type": "string" }, "visibility": { "default": "private", "title": "Visibility", "type": "string" } }, "required": [ "name", "design" ], "title": "CreatePresentationDesignRequest", "type": "object" }, "CreateProjectFromSuggestionRequest": { "description": "Request to create a project from an approved suggestion.\n\nUsed in: POST /api/v1/projects/from-suggestion\n\nRelated: KCC-3473, KCC-A-108", "properties": { "keywords": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "description": "Keywords for email matching", "title": "Keywords" }, "name": { "description": "Project name (may be modified from suggestion)", "maxLength": 255, "minLength": 1, "title": "Name", "type": "string" }, "project_type": { "anyOf": [ { "pattern": "^(activity|goal|recurring|event|household|vacation|school|administrative|creative|community|work)?$", "type": "string" }, { "type": "null" } ], "description": "Project type (activity|goal|recurring|event|household|vacation|school|administrative|creative|community|work)", "title": "Project Type" }, "selected_email_ids": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "description": "Email IDs to link to the new project", "title": "Selected Email Ids" }, "suggestion_id": { "description": "UUID of the suggestion to approve", "title": "Suggestion Id", "type": "string" } }, "required": [ "suggestion_id", "name" ], "title": "CreateProjectFromSuggestionRequest", "type": "object" }, "CreateProjectFromSuggestionResponse": { "description": "Response after creating a project from a suggestion.\n\nRelated: KCC-3473, KCC-A-108", "properties": { "linked_count": { "default": 0, "description": "Number of emails linked to the project", "title": "Linked Count", "type": "integer" }, "message": { "description": "Human-readable success message", "title": "Message", "type": "string" }, "name": { "description": "Project name", "title": "Name", "type": "string" }, "project_id": { "description": "UUID of the created project", "title": "Project Id", "type": "string" } }, "required": [ "project_id", "name", "message" ], "title": "CreateProjectFromSuggestionResponse", "type": "object" }, "CreatePromoCodeRequest": { "properties": { "code": { "title": "Code", "type": "string" }, "coupon_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Coupon Id" }, "discount_type": { "default": "percent_off", "title": "Discount Type", "type": "string" }, "discount_value": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Discount Value" }, "duration": { "default": "repeating", "title": "Duration", "type": "string" }, "duration_in_months": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Duration In Months" }, "expires_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Expires At" }, "max_redemptions": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Max Redemptions" } }, "required": [ "code" ], "title": "CreatePromoCodeRequest", "type": "object" }, "CreateRingRequest": { "properties": { "client_operation_id": { "format": "uuid", "title": "Client Operation Id", "type": "string" }, "huddle_id": { "format": "uuid", "title": "Huddle Id", "type": "string" }, "recipient_account_ids": { "items": { "format": "uuid", "type": "string" }, "title": "Recipient Account Ids", "type": "array" }, "room_id": { "title": "Room Id", "type": "string" } }, "required": [ "room_id", "huddle_id", "client_operation_id" ], "title": "CreateRingRequest", "type": "object" }, "CreateRingResponse": { "properties": { "expires_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Expires At" }, "huddle_id": { "format": "uuid", "title": "Huddle Id", "type": "string" }, "realtime_sequence": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Realtime Sequence" }, "recipient_account_ids": { "items": { "format": "uuid", "type": "string" }, "title": "Recipient Account Ids", "type": "array" }, "ring_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "default": null, "title": "Ring Id" }, "room_id": { "title": "Room Id", "type": "string" }, "state": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "State" }, "status": { "enum": [ "created", "existing", "suppressed" ], "title": "Status", "type": "string" }, "suppressions": { "items": { "$ref": "#/components/schemas/SuppressionOut" }, "title": "Suppressions", "type": "array" } }, "required": [ "status", "huddle_id", "room_id" ], "title": "CreateRingResponse", "type": "object" }, "CreateRoomRequest": { "properties": { "description": { "anyOf": [ { "maxLength": 2000, "type": "string" }, { "type": "null" } ], "title": "Description" }, "member_account_ids": { "items": { "type": "string" }, "title": "Member Account Ids", "type": "array" }, "name": { "title": "Name", "type": "string" }, "project_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Project Id" }, "room_alias": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Room Alias" }, "room_type": { "default": "general", "title": "Room Type", "type": "string" }, "template_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Template Id" }, "visibility": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "public_in_workspace | private | restricted (default public_in_workspace)", "title": "Visibility" } }, "required": [ "name" ], "title": "CreateRoomRequest", "type": "object" }, "CreateSARequest": { "properties": { "description": { "anyOf": [ { "maxLength": 500, "type": "string" }, { "type": "null" } ], "title": "Description" }, "expires_in_days": { "maximum": 365.0, "minimum": 30.0, "title": "Expires In Days", "type": "integer" }, "name": { "maxLength": 120, "minLength": 1, "title": "Name", "type": "string" }, "scopes": { "items": { "type": "string" }, "title": "Scopes", "type": "array" } }, "required": [ "name", "scopes", "expires_in_days" ], "title": "CreateSARequest", "type": "object" }, "CreateSavedViewRequest": { "description": "Body for POST /api/v1/saved-views.\n\n`id` is optional for client-side idempotency: PowerSync's CRUD upload\nsends the locally-generated UUID so a retry after a lost ACK upserts\nagainst the same row instead of inserting a duplicate (TIDY-7564 +\nTIDY-4132 idempotency pattern). `entity_type` lets surfaces declare\nthe discriminator they own (calendar workspace writes\n`entity_type='calendar'`).", "properties": { "config": { "additionalProperties": true, "default": {}, "title": "Config", "type": "object" }, "entity_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Entity Type" }, "facet_slug": { "title": "Facet Slug", "type": "string" }, "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Id" }, "is_default": { "default": false, "title": "Is Default", "type": "boolean" }, "name": { "title": "Name", "type": "string" }, "navigation_key": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Navigation Key" }, "position": { "default": 0, "title": "Position", "type": "integer" }, "view_type": { "default": "table", "title": "View Type", "type": "string" } }, "required": [ "facet_slug", "name" ], "title": "CreateSavedViewRequest", "type": "object" }, "CreateServiceAccountResponse": { "properties": { "record": { "$ref": "#/components/schemas/ServiceAccountPublic" }, "value": { "title": "Value", "type": "string" } }, "required": [ "value", "record" ], "title": "CreateServiceAccountResponse", "type": "object" }, "CreateSignatureRequest": { "properties": { "document_note_id": { "description": "The Document facet's note id", "title": "Document Note Id", "type": "string" }, "expires_in_days": { "anyOf": [ { "maximum": 180.0, "minimum": 1.0, "type": "integer" }, { "type": "null" } ], "description": "Signing-link lifetime (default 14 days)", "title": "Expires In Days" }, "signer": { "$ref": "#/components/schemas/Signer" } }, "required": [ "document_note_id", "signer" ], "title": "CreateSignatureRequest", "type": "object" }, "CreateSignatureRequestResult": { "properties": { "id": { "title": "Id", "type": "string" }, "signing_url": { "title": "Signing Url", "type": "string" }, "status": { "title": "Status", "type": "string" } }, "required": [ "id", "status", "signing_url" ], "title": "CreateSignatureRequestResult", "type": "object" }, "CreateSmartGroupRequest": { "properties": { "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "name": { "title": "Name", "type": "string" }, "rule_definition": { "$ref": "#/components/schemas/SmartGroupRuleDefinition" } }, "required": [ "name", "rule_definition" ], "title": "CreateSmartGroupRequest", "type": "object" }, "CreateTabRequest": { "properties": { "kind": { "default": "doc", "description": "doc | database | drawing", "title": "Kind", "type": "string" }, "title": { "anyOf": [ { "maxLength": 200, "type": "string" }, { "type": "null" } ], "title": "Title" } }, "title": "CreateTabRequest", "type": "object" }, "CreateUserRequest": { "properties": { "email": { "format": "email", "title": "Email", "type": "string" }, "send_invite": { "default": true, "title": "Send Invite", "type": "boolean" }, "tenant_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional tenant to attach", "title": "Tenant Id" } }, "required": [ "email" ], "title": "CreateUserRequest", "type": "object" }, "CreateUserResponse": { "properties": { "email": { "title": "Email", "type": "string" }, "id": { "format": "uuid", "title": "Id", "type": "string" }, "invite_sent": { "title": "Invite Sent", "type": "boolean" } }, "required": [ "id", "email", "invite_sent" ], "title": "CreateUserResponse", "type": "object" }, "CreateVersionRequest": { "description": "Raw-bytes payload from a caller that already has the Yjs state.\n\n``yjs_state_hex`` is the Yjs document bytes encoded as hex (no 0x prefix).\nUsed by server-mediated paths (collab-service-backed BFF shim) where the\ncaller has read the Yjs state via Hocuspocus and needs a durable snapshot.", "properties": { "content_hash": { "title": "Content Hash", "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name" }, "preview_text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Preview Text" }, "trigger": { "default": "manual", "title": "Trigger", "type": "string" }, "yjs_state_hex": { "title": "Yjs State Hex", "type": "string" } }, "required": [ "yjs_state_hex", "content_hash" ], "title": "CreateVersionRequest", "type": "object" }, "CreateWorkstationRequest": { "description": "Body for POST /api/v1/workstations.\n\n`id` is optional for client-side idempotency: PowerSync's CRUD upload\nsends the locally-generated UUID so a retry after a lost ACK upserts\nagainst the same row instead of inserting a duplicate.", "properties": { "color": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Color" }, "create_config": { "additionalProperties": true, "default": {}, "title": "Create Config", "type": "object" }, "icon": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Icon" }, "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Id" }, "name": { "maxLength": 200, "minLength": 1, "title": "Name", "type": "string" }, "nav_config": { "additionalProperties": true, "default": {}, "title": "Nav Config", "type": "object" }, "position": { "default": 0, "title": "Position", "type": "integer" }, "visibility": { "default": "shared", "title": "Visibility", "type": "string" } }, "required": [ "name" ], "title": "CreateWorkstationRequest", "type": "object" }, "CreatedTrigger": { "additionalProperties": false, "description": "Fires when an item of the bound facet is created.", "properties": { "kind": { "const": "created", "title": "Kind", "type": "string" }, "tags_any": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "description": "Carried over from the data_change trigger schema: fire only when the item currently carries >=1 of these tags.", "title": "Tags Any" } }, "required": [ "kind" ], "title": "CreatedTrigger", "type": "object" }, "CredentialGrant": { "properties": { "conversation_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Conversation Id" }, "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "credential_id": { "title": "Credential Id", "type": "string" }, "employee_account_id": { "title": "Employee Account Id", "type": "string" }, "expires_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Expires At" }, "granted_by_account_id": { "title": "Granted By Account Id", "type": "string" }, "id": { "title": "Id", "type": "string" }, "purpose": { "title": "Purpose", "type": "string" }, "revoked_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Revoked At" }, "room_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Room Id" }, "runtime": { "anyOf": [ { "maxLength": 64, "minLength": 1, "type": "string" }, { "type": "null" } ], "default": null, "title": "Runtime" }, "scope": { "enum": [ "once", "session", "standing" ], "title": "Scope", "type": "string" }, "used_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Used At" } }, "required": [ "id", "credential_id", "employee_account_id", "scope", "purpose", "granted_by_account_id", "created_at" ], "title": "CredentialGrant", "type": "object" }, "CredentialGrantCreate": { "properties": { "conversation_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Conversation Id" }, "employee_account_id": { "format": "uuid", "title": "Employee Account Id", "type": "string" }, "expires_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Expires At" }, "purpose": { "maxLength": 1000, "minLength": 1, "title": "Purpose", "type": "string" }, "room_id": { "anyOf": [ { "maxLength": 512, "type": "string" }, { "type": "null" } ], "title": "Room Id" }, "runtime": { "anyOf": [ { "maxLength": 64, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Runtime" }, "scope": { "enum": [ "once", "session", "standing" ], "title": "Scope", "type": "string" } }, "required": [ "employee_account_id", "scope", "purpose" ], "title": "CredentialGrantCreate", "type": "object" }, "CredentialListResponse": { "properties": { "can_create_org": { "title": "Can Create Org", "type": "boolean" }, "credentials": { "items": { "$ref": "#/components/schemas/CredentialMetadata" }, "title": "Credentials", "type": "array" } }, "required": [ "can_create_org" ], "title": "CredentialListResponse", "type": "object" }, "CredentialMetadata": { "properties": { "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "env_key": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Env Key" }, "grants": { "items": { "$ref": "#/components/schemas/CredentialGrant" }, "title": "Grants", "type": "array" }, "id": { "title": "Id", "type": "string" }, "key_id": { "title": "Key Id", "type": "string" }, "kind": { "enum": [ "secret", "managed", "broker", "ssh_public_key", "automation", "mcp", "source", "webhook", "email_oauth", "imap" ], "title": "Kind", "type": "string" }, "last_rotated_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Last Rotated At" }, "name": { "title": "Name", "type": "string" }, "org_owned": { "title": "Org Owned", "type": "boolean" }, "owner_account_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Owner Account Id" }, "room_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Room Id" }, "status": { "enum": [ "active", "refresh_error", "rotation_required", "revoked" ], "title": "Status", "type": "string" } }, "required": [ "id", "name", "kind", "org_owned", "key_id", "status", "created_at" ], "title": "CredentialMetadata", "type": "object" }, "CredentialOverrideRequest": { "description": "One override action against a credential email.\n\n- ``not_credential``: un-mark a false positive (clears treatment, writes a\n member exception rule, re-enqueues the full pipeline).\n- ``mark_credential`` + ``kind``: manually mark a missed credential email.\n ``learn=true`` also writes a member rule fast-tracking the sender.\n- ``set_expiry`` + ``expires_in_minutes``: adjust the countdown.\n- ``clear_expiry``: cancel the countdown.", "properties": { "action": { "enum": [ "not_credential", "mark_credential", "set_expiry", "clear_expiry" ], "title": "Action", "type": "string" }, "expires_in_minutes": { "anyOf": [ { "minimum": 1.0, "type": "integer" }, { "type": "null" } ], "description": "set_expiry: minutes from now until the code expires", "title": "Expires In Minutes" }, "kind": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Credential kind for mark_credential", "title": "Kind" }, "learn": { "default": false, "description": "mark_credential: also fast-track this sender", "title": "Learn", "type": "boolean" } }, "required": [ "action" ], "title": "CredentialOverrideRequest", "type": "object" }, "CredentialOverrideResponse": { "description": "The updated credential/TTL state after an override.", "properties": { "action": { "title": "Action", "type": "string" }, "credential_expires_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Credential Expires At" }, "credential_kind": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Credential Kind" }, "credential_superseded_by": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Credential Superseded By" }, "credential_value": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Credential Value" }, "exception_rule_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Exception Rule Id" }, "reprocess_enqueued": { "default": false, "title": "Reprocess Enqueued", "type": "boolean" }, "ttl_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Ttl Reason" } }, "required": [ "action" ], "title": "CredentialOverrideResponse", "type": "object" }, "CredentialRecoveryReceiptRequest": { "properties": { "idempotency_key": { "format": "uuid", "title": "Idempotency Key", "type": "string" }, "machine_fingerprint": { "maxLength": 512, "minLength": 16, "title": "Machine Fingerprint", "type": "string" }, "recovery_token": { "maxLength": 512, "minLength": 32, "title": "Recovery Token", "type": "string" } }, "required": [ "recovery_token", "machine_fingerprint", "idempotency_key" ], "title": "CredentialRecoveryReceiptRequest", "type": "object" }, "CredentialRecoveryRequest": { "properties": { "command_target": { "anyOf": [ { "$ref": "#/components/schemas/ProtectedCommandTarget" }, { "type": "null" } ] }, "confirmation_slug": { "maxLength": 80, "minLength": 2, "title": "Confirmation Slug", "type": "string" }, "expected_generation": { "minimum": 0.0, "title": "Expected Generation", "type": "integer" }, "expected_host_instance_id": { "format": "uuid", "title": "Expected Host Instance Id", "type": "string" }, "expected_installation_id": { "format": "uuid", "title": "Expected Installation Id", "type": "string" }, "manifest_sha256": { "pattern": "^[0-9a-f]{64}$", "title": "Manifest Sha256", "type": "string" }, "reason": { "maxLength": 500, "minLength": 8, "title": "Reason", "type": "string" } }, "required": [ "expected_installation_id", "expected_host_instance_id", "expected_generation", "manifest_sha256", "reason", "confirmation_slug" ], "title": "CredentialRecoveryRequest", "type": "object" }, "CredentialRecoveryTokenResponse": { "properties": { "expires_at": { "format": "date-time", "title": "Expires At", "type": "string" }, "host_instance_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "default": null, "title": "Host Instance Id" }, "installation_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "default": null, "title": "Installation Id" }, "protected_setup_command": { "anyOf": [ { "$ref": "#/components/schemas/ProtectedSetupCommand" }, { "type": "null" } ], "default": null }, "recovery_token": { "title": "Recovery Token", "type": "string" } }, "required": [ "recovery_token", "expires_at" ], "title": "CredentialRecoveryTokenResponse", "type": "object" }, "CreditBalanceResponse": { "properties": { "billing_period_start": { "format": "date", "title": "Billing Period Start", "type": "string" }, "pool_balance": { "title": "Pool Balance", "type": "number" }, "pool_granted": { "title": "Pool Granted", "type": "number" }, "seats": { "title": "Seats", "type": "integer" }, "tenant_id": { "title": "Tenant Id", "type": "string" }, "user_consumed_5h": { "title": "User Consumed 5H", "type": "number" }, "user_consumed_period": { "title": "User Consumed Period", "type": "number" }, "user_ration": { "title": "User Ration", "type": "number" }, "weekly_ration": { "title": "Weekly Ration", "type": "number" } }, "required": [ "tenant_id", "billing_period_start", "pool_balance", "pool_granted", "seats", "user_ration", "weekly_ration", "user_consumed_period", "user_consumed_5h" ], "title": "CreditBalanceResponse", "type": "object" }, "CreditGrantRequest": { "properties": { "credits": { "description": "Credits to grant (negative = correction)", "title": "Credits", "type": "number" }, "reason": { "maxLength": 500, "minLength": 1, "title": "Reason", "type": "string" } }, "required": [ "credits", "reason" ], "title": "CreditGrantRequest", "type": "object" }, "CreditGrantResponse": { "properties": { "credits": { "title": "Credits", "type": "number" }, "ledger_id": { "title": "Ledger Id", "type": "integer" }, "reason": { "title": "Reason", "type": "string" }, "tenant_id": { "title": "Tenant Id", "type": "string" } }, "required": [ "ledger_id", "tenant_id", "credits", "reason" ], "title": "CreditGrantResponse", "type": "object" }, "CreditLedgerEntry": { "properties": { "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "credits": { "title": "Credits", "type": "number" }, "entry_type": { "title": "Entry Type", "type": "string" }, "feature": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Feature" }, "id": { "title": "Id", "type": "integer" }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Reason" }, "user_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "User Id" } }, "required": [ "id", "entry_type", "credits", "created_at" ], "title": "CreditLedgerEntry", "type": "object" }, "CreditRecentEntry": { "properties": { "created_at": { "title": "Created At", "type": "string" }, "credits": { "title": "Credits", "type": "number" }, "entry_type": { "title": "Entry Type", "type": "string" }, "feature": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Feature" }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Reason" } }, "required": [ "entry_type", "credits", "created_at" ], "title": "CreditRecentEntry", "type": "object" }, "CreditUsageResponse": { "properties": { "billing_period_start": { "format": "date", "title": "Billing Period Start", "type": "string" }, "checkpoint_5h_threshold": { "title": "Checkpoint 5H Threshold", "type": "number" }, "checkpoint_pct": { "title": "Checkpoint Pct", "type": "number" }, "drip_remaining_today": { "title": "Drip Remaining Today", "type": "number" }, "is_owner": { "title": "Is Owner", "type": "boolean" }, "owner_approval_required": { "title": "Owner Approval Required", "type": "boolean" }, "pool_balance": { "title": "Pool Balance", "type": "number" }, "pool_exhausted": { "title": "Pool Exhausted", "type": "boolean" }, "pool_granted": { "title": "Pool Granted", "type": "number" }, "recent": { "default": [], "items": { "$ref": "#/components/schemas/CreditRecentEntry" }, "title": "Recent", "type": "array" }, "reset_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Reset At" }, "rollup": { "anyOf": [ { "items": { "$ref": "#/components/schemas/CreditUsageUser" }, "type": "array" }, { "type": "null" } ], "default": null, "title": "Rollup" }, "seats": { "title": "Seats", "type": "integer" }, "tenant_id": { "title": "Tenant Id", "type": "string" }, "topup_owner_restricted": { "title": "Topup Owner Restricted", "type": "boolean" }, "trial_activation": { "anyOf": [ { "$ref": "#/components/schemas/TrialActivationView" }, { "type": "null" } ], "default": null }, "user_consumed_5h": { "title": "User Consumed 5H", "type": "number" }, "user_consumed_period": { "title": "User Consumed Period", "type": "number" }, "user_consumed_week": { "title": "User Consumed Week", "type": "number" }, "user_ration": { "title": "User Ration", "type": "number" }, "weekly_ration": { "title": "Weekly Ration", "type": "number" } }, "required": [ "tenant_id", "billing_period_start", "pool_balance", "pool_granted", "pool_exhausted", "seats", "user_ration", "weekly_ration", "user_consumed_period", "user_consumed_week", "user_consumed_5h", "checkpoint_5h_threshold", "drip_remaining_today", "is_owner", "checkpoint_pct", "owner_approval_required", "topup_owner_restricted" ], "title": "CreditUsageResponse", "type": "object" }, "CreditUsageUser": { "properties": { "consumed_period": { "title": "Consumed Period", "type": "number" }, "consumed_week": { "title": "Consumed Week", "type": "number" }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Email" }, "user_id": { "title": "User Id", "type": "string" } }, "required": [ "user_id", "consumed_period", "consumed_week" ], "title": "CreditUsageUser", "type": "object" }, "CreditsResponse": { "properties": { "billing_period_end": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Billing Period End" }, "billing_period_start": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Billing Period Start" }, "by_category": { "default": [], "items": { "$ref": "#/components/schemas/CategoryUsage" }, "title": "By Category", "type": "array" }, "by_user": { "default": [], "items": { "$ref": "#/components/schemas/UserUsage" }, "title": "By User", "type": "array" }, "credits_allocated": { "title": "Credits Allocated", "type": "integer" }, "credits_remaining": { "title": "Credits Remaining", "type": "number" }, "credits_used": { "title": "Credits Used", "type": "number" }, "usage_percentage": { "title": "Usage Percentage", "type": "number" } }, "required": [ "credits_allocated", "credits_used", "credits_remaining", "usage_percentage" ], "title": "CreditsResponse", "type": "object" }, "CrmSuppressionEntry": { "properties": { "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "email": { "title": "Email", "type": "string" }, "occurred_at": { "format": "date-time", "title": "Occurred At", "type": "string" }, "reason": { "description": "Why the address is suppressed: unsubscribe | bounce | complaint | manual | provider_sync | forget_me.", "title": "Reason", "type": "string" }, "source": { "description": "Which flow wrote the row (member, ses_reconcile, …).", "title": "Source", "type": "string" } }, "required": [ "email", "reason", "source", "occurred_at", "created_at" ], "title": "CrmSuppressionEntry", "type": "object" }, "CrmSuppressionListResponse": { "description": "Schema names are GLOBAL in the generated OpenAPI document — three unrelated\nmodules already declare a ``SuppressionEntry`` / ``SuppressionListResponse``\n(recipe behavior, CRM proposals) and reusing either name silently overwrites\nthe other module's schema in the contract. Hence the ``Crm`` prefix.", "properties": { "items": { "items": { "$ref": "#/components/schemas/CrmSuppressionEntry" }, "title": "Items", "type": "array" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Pass as ?cursor= to read the next page. Null on the last page — a caller enumerating the whole registry stops when it is null.", "title": "Next Cursor" } }, "required": [ "items" ], "title": "CrmSuppressionListResponse", "type": "object" }, "CustomCalendarCollectionCreate": { "description": "Input model for creating a custom calendar source.", "properties": { "color": { "anyOf": [ { "pattern": "^#[0-9A-Fa-f]{6}$", "type": "string" }, { "type": "null" } ], "title": "Color" }, "date_pivot_field": { "default": "dtstart", "maxLength": 255, "minLength": 1, "title": "Date Pivot Field", "type": "string" }, "default_facet_slug": { "maxLength": 255, "minLength": 1, "title": "Default Facet Slug", "type": "string" }, "description": { "anyOf": [ { "maxLength": 1000, "type": "string" }, { "type": "null" } ], "title": "Description" }, "is_visible": { "default": true, "title": "Is Visible", "type": "boolean" }, "name": { "maxLength": 255, "minLength": 1, "title": "Name", "type": "string" }, "timezone": { "default": "America/New_York", "maxLength": 255, "title": "Timezone", "type": "string" } }, "required": [ "name", "default_facet_slug" ], "title": "CustomCalendarCollectionCreate", "type": "object" }, "CustomEmojiListResponse": { "properties": { "emoji": { "items": { "additionalProperties": true, "type": "object" }, "title": "Emoji", "type": "array" }, "enabled": { "title": "Enabled", "type": "boolean" } }, "required": [ "enabled", "emoji" ], "title": "CustomEmojiListResponse", "type": "object" }, "CustomEmojiResponse": { "properties": { "content_type": { "title": "Content Type", "type": "string" }, "created_at": { "title": "Created At", "type": "string" }, "created_by": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Created By" }, "id": { "title": "Id", "type": "string" }, "image_url": { "title": "Image Url", "type": "string" }, "shortcode": { "title": "Shortcode", "type": "string" }, "sort_order": { "default": 0, "title": "Sort Order", "type": "integer" } }, "required": [ "id", "shortcode", "image_url", "content_type", "created_at" ], "title": "CustomEmojiResponse", "type": "object" }, "CustomSmartGroupResponse": { "properties": { "created_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Created At" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Description" }, "id": { "format": "uuid", "title": "Id", "type": "string" }, "member_count": { "default": 0, "title": "Member Count", "type": "integer" }, "name": { "title": "Name", "type": "string" }, "rule_definition": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "title": "Rule Definition" }, "type": { "default": "custom", "enum": [ "frequent", "stale", "follow_up", "custom" ], "title": "Type", "type": "string" }, "updated_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Updated At" } }, "required": [ "id", "name" ], "title": "CustomSmartGroupResponse", "type": "object" }, "CustomSplitCreate": { "description": "Request model for creating a custom email split.", "properties": { "color": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional color for the split", "title": "Color" }, "filter_domains": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "description": "Domains to match (e.g., school.edu)", "title": "Filter Domains" }, "filter_has_attachments": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Filter by attachment presence", "title": "Filter Has Attachments" }, "filter_is_unread": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Filter by read status", "title": "Filter Is Unread" }, "filter_keywords": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "description": "Keywords to match in subject/body", "title": "Filter Keywords" }, "filter_labels": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "description": "Labels/tags to match", "title": "Filter Labels" }, "filter_senders": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "description": "Email addresses to match", "title": "Filter Senders" }, "filter_triage_labels": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "description": "Triage labels: to_respond, fyi, low_priority", "title": "Filter Triage Labels" }, "icon": { "default": "folder", "description": "Lucide icon name", "title": "Icon", "type": "string" }, "name": { "description": "Split display name", "maxLength": 50, "minLength": 1, "title": "Name", "type": "string" }, "position": { "default": 0, "description": "Sort position (higher = later)", "title": "Position", "type": "integer" } }, "required": [ "name" ], "title": "CustomSplitCreate", "type": "object" }, "CustomSplitListResponse": { "description": "Response model for list of custom splits.", "properties": { "splits": { "description": "List of custom splits", "items": { "$ref": "#/components/schemas/CustomSplitResponse" }, "title": "Splits", "type": "array" } }, "title": "CustomSplitListResponse", "type": "object" }, "CustomSplitReorderRequest": { "description": "Request model for reordering custom splits.", "properties": { "split_ids": { "description": "Ordered list of split IDs", "items": { "format": "uuid", "type": "string" }, "title": "Split Ids", "type": "array" } }, "required": [ "split_ids" ], "title": "CustomSplitReorderRequest", "type": "object" }, "CustomSplitResponse": { "description": "Response model for a custom email split.", "properties": { "color": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Optional color", "title": "Color" }, "created_at": { "description": "When split was created", "format": "date-time", "title": "Created At", "type": "string" }, "filter_domains": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "default": null, "title": "Filter Domains" }, "filter_has_attachments": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "title": "Filter Has Attachments" }, "filter_is_unread": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "title": "Filter Is Unread" }, "filter_keywords": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "default": null, "title": "Filter Keywords" }, "filter_labels": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "default": null, "title": "Filter Labels" }, "filter_senders": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "default": null, "title": "Filter Senders" }, "filter_triage_labels": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "default": null, "title": "Filter Triage Labels" }, "icon": { "description": "Lucide icon name", "title": "Icon", "type": "string" }, "id": { "description": "Split UUID", "format": "uuid", "title": "Id", "type": "string" }, "is_hidden": { "description": "Whether split is hidden", "title": "Is Hidden", "type": "boolean" }, "name": { "description": "Split display name", "title": "Name", "type": "string" }, "position": { "description": "Sort position", "title": "Position", "type": "integer" }, "updated_at": { "description": "When split was last updated", "format": "date-time", "title": "Updated At", "type": "string" } }, "required": [ "id", "name", "icon", "position", "is_hidden", "created_at", "updated_at" ], "title": "CustomSplitResponse", "type": "object" }, "CustomSplitUpdate": { "description": "Request model for updating a custom email split.", "properties": { "color": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional color for the split", "title": "Color" }, "filter_domains": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "description": "Domains to match", "title": "Filter Domains" }, "filter_has_attachments": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Filter by attachment presence", "title": "Filter Has Attachments" }, "filter_is_unread": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Filter by read status", "title": "Filter Is Unread" }, "filter_keywords": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "description": "Keywords to match", "title": "Filter Keywords" }, "filter_labels": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "description": "Labels/tags to match", "title": "Filter Labels" }, "filter_senders": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "description": "Email addresses to match", "title": "Filter Senders" }, "filter_triage_labels": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "description": "Triage labels", "title": "Filter Triage Labels" }, "icon": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Lucide icon name", "title": "Icon" }, "is_hidden": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Hide from split navigation", "title": "Is Hidden" }, "name": { "anyOf": [ { "maxLength": 50, "minLength": 1, "type": "string" }, { "type": "null" } ], "description": "Split display name", "title": "Name" }, "position": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Sort position (higher = later)", "title": "Position" } }, "title": "CustomSplitUpdate", "type": "object" }, "CustomWebhookCreate": { "additionalProperties": false, "properties": { "label": { "maxLength": 200, "minLength": 1, "title": "Label", "type": "string" }, "verification": { "$ref": "#/components/schemas/VerificationSettings" }, "visibility": { "default": "private", "enum": [ "private", "shared" ], "title": "Visibility", "type": "string" } }, "required": [ "label", "verification" ], "title": "CustomWebhookCreate", "type": "object" }, "CustomerLinkRequest": { "properties": { "account_id": { "description": "The Tidy account to join this lead to.", "title": "Account Id", "type": "string" }, "facet_slug": { "description": "The contact facet whose pipeline this contact belongs to (e.g. the tenant's installed lead facet). Required: the caller resolves it from the tenant's own facet definitions — the platform holds no default pipeline vocabulary (TIDY-16775).", "minLength": 1, "title": "Facet Slug", "type": "string" } }, "required": [ "account_id", "facet_slug" ], "title": "CustomerLinkRequest", "type": "object" }, "CustomerLinkResponse": { "properties": { "contact_id": { "title": "Contact Id", "type": "string" }, "customer_link": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Customer Link" }, "outcome": { "enum": [ "linked", "unlinked" ], "title": "Outcome", "type": "string" }, "source_event_id": { "description": "Deterministic id of the signed_up audit engagement event.", "title": "Source Event Id", "type": "string" } }, "required": [ "contact_id", "customer_link", "outcome", "source_event_id" ], "title": "CustomerLinkResponse", "type": "object" }, "DCRRequest": { "description": "RFC 7591 §2 client metadata accepted by /oauth/register.\n\nAll fields except client_name + redirect_uris are optional with\nsafe defaults that produce a public PKCE+code+device_code client\n(the common case for MCP agents).", "properties": { "client_name": { "maxLength": 120, "minLength": 1, "title": "Client Name", "type": "string" }, "client_uri": { "anyOf": [ { "maxLength": 2048, "type": "string" }, { "type": "null" } ], "title": "Client Uri" }, "grant_types": { "items": { "type": "string" }, "title": "Grant Types", "type": "array" }, "logo_uri": { "anyOf": [ { "maxLength": 2048, "type": "string" }, { "type": "null" } ], "title": "Logo Uri" }, "redirect_uris": { "items": { "type": "string" }, "maxItems": 8, "minItems": 1, "title": "Redirect Uris", "type": "array" }, "response_types": { "items": { "type": "string" }, "title": "Response Types", "type": "array" }, "scope": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Scope" }, "software_id": { "anyOf": [ { "maxLength": 120, "type": "string" }, { "type": "null" } ], "title": "Software Id" }, "software_statement": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Software Statement" }, "software_version": { "anyOf": [ { "maxLength": 40, "type": "string" }, { "type": "null" } ], "title": "Software Version" }, "token_endpoint_auth_method": { "default": "none", "enum": [ "none", "client_secret_basic", "client_secret_post" ], "title": "Token Endpoint Auth Method", "type": "string" } }, "required": [ "client_name", "redirect_uris" ], "title": "DCRRequest", "type": "object" }, "DCRResponse": { "description": "RFC 7591 §3.2.1 successful registration response.\n\nOptional fields (`client_secret`, `software_id`, `software_version`,\n`logo_uri`, `client_uri`) are OMITTED from the JSON body when absent —\nnot serialized as `null`. RFC 7591 §3.2.1 specifies \"OPTIONAL\" parameters\nand the MCP SDK's Zod `optional()` schemas reject `null` for string-typed\noptional fields (TIDY-8880).\n\n`registration_access_token` is returned in plaintext exactly once;\nonly its hash is persisted (RFC 7592 management uses it).\n`client_id_issued_at` is unix seconds (per RFC).", "properties": { "client_id": { "title": "Client Id", "type": "string" }, "client_id_issued_at": { "title": "Client Id Issued At", "type": "integer" }, "client_name": { "title": "Client Name", "type": "string" }, "client_secret": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Client Secret" }, "client_secret_expires_at": { "default": 0, "title": "Client Secret Expires At", "type": "integer" }, "client_uri": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Client Uri" }, "grant_types": { "items": { "type": "string" }, "title": "Grant Types", "type": "array" }, "logo_uri": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Logo Uri" }, "redirect_uris": { "items": { "type": "string" }, "title": "Redirect Uris", "type": "array" }, "registration_access_token": { "title": "Registration Access Token", "type": "string" }, "response_types": { "items": { "type": "string" }, "title": "Response Types", "type": "array" }, "scope": { "title": "Scope", "type": "string" }, "software_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Software Id" }, "software_version": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Software Version" }, "token_endpoint_auth_method": { "title": "Token Endpoint Auth Method", "type": "string" } }, "required": [ "client_id", "client_id_issued_at", "client_secret", "registration_access_token", "client_name", "redirect_uris", "grant_types", "response_types", "token_endpoint_auth_method", "scope" ], "title": "DCRResponse", "type": "object" }, "DLQStats": { "description": "Stats for a single DLQ.", "properties": { "message_count": { "title": "Message Count", "type": "integer" }, "original_queue": { "title": "Original Queue", "type": "string" }, "queue_name": { "title": "Queue Name", "type": "string" }, "reason_counts": { "additionalProperties": true, "default": {}, "title": "Reason Counts", "type": "object" }, "sample_reasons": { "default": [], "items": { "type": "string" }, "title": "Sample Reasons", "type": "array" } }, "required": [ "queue_name", "message_count", "original_queue" ], "title": "DLQStats", "type": "object" }, "DLQStatsResponse": { "description": "Response for DLQ stats endpoint.", "properties": { "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error" }, "queues": { "items": { "$ref": "#/components/schemas/DLQStats" }, "title": "Queues", "type": "array" }, "success": { "title": "Success", "type": "boolean" }, "total_messages": { "title": "Total Messages", "type": "integer" } }, "required": [ "success", "total_messages", "queues" ], "title": "DLQStatsResponse", "type": "object" }, "DailyActivitySummarySettingsResponse": { "properties": { "enabled": { "title": "Enabled", "type": "boolean" }, "includeCalendarEvents": { "title": "Includecalendarevents", "type": "boolean" }, "includeEmails": { "title": "Includeemails", "type": "boolean" }, "includeOverdueTasks": { "title": "Includeoverduetasks", "type": "boolean" }, "includeTasks": { "title": "Includetasks", "type": "boolean" }, "maxCalendarEvents": { "title": "Maxcalendarevents", "type": "integer" }, "maxEmailSubjects": { "title": "Maxemailsubjects", "type": "integer" }, "maxTasks": { "title": "Maxtasks", "type": "integer" } }, "required": [ "enabled", "includeEmails", "includeCalendarEvents", "includeTasks", "includeOverdueTasks", "maxEmailSubjects", "maxCalendarEvents", "maxTasks" ], "title": "DailyActivitySummarySettingsResponse", "type": "object" }, "DailyActivitySummarySettingsUpdate": { "description": "Partial update — every field optional; server normalizes + clamps.", "properties": { "enabled": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Enabled" }, "includeCalendarEvents": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Includecalendarevents" }, "includeEmails": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Includeemails" }, "includeOverdueTasks": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Includeoverduetasks" }, "includeTasks": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Includetasks" }, "maxCalendarEvents": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Maxcalendarevents" }, "maxEmailSubjects": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Maxemailsubjects" }, "maxTasks": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Maxtasks" } }, "title": "DailyActivitySummarySettingsUpdate", "type": "object" }, "DailyBreakdown": { "properties": { "date": { "title": "Date", "type": "string" }, "emails_acted": { "title": "Emails Acted", "type": "integer" }, "emails_viewed": { "title": "Emails Viewed", "type": "integer" }, "inbox_opens": { "title": "Inbox Opens", "type": "integer" }, "time_minutes": { "title": "Time Minutes", "type": "number" } }, "required": [ "date", "inbox_opens", "time_minutes", "emails_viewed", "emails_acted" ], "title": "DailyBreakdown", "type": "object" }, "DailyBreakerReconciliationResponse": { "description": "What the daily cost breaker sees, next to what the ledger reports.\n\n``breaker_spend_usd`` is the figure the circuit breaker compares against\nthe limit; ``ledger_total_usd`` is a raw ``SUM(cost)`` over the same\nservice and UTC day. The two excluded buckets account for every cent\nbetween them, and ``reconciles`` asserts that identity (TIDY-17937).", "properties": { "breaker_calls": { "title": "Breaker Calls", "type": "integer" }, "breaker_spend_usd": { "title": "Breaker Spend Usd", "type": "number" }, "daily_limit_usd": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "title": "Daily Limit Usd" }, "excluded_cache_hit_usd": { "title": "Excluded Cache Hit Usd", "type": "number" }, "excluded_local_model_usd": { "title": "Excluded Local Model Usd", "type": "number" }, "ledger_calls": { "title": "Ledger Calls", "type": "integer" }, "ledger_total_usd": { "title": "Ledger Total Usd", "type": "number" }, "limit_env_key": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Limit Env Key" }, "reconciles": { "title": "Reconciles", "type": "boolean" }, "reference_sql": { "title": "Reference Sql", "type": "string" }, "service_name": { "title": "Service Name", "type": "string" }, "tenant_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "default": null, "title": "Tenant Id" }, "would_refuse": { "title": "Would Refuse", "type": "boolean" } }, "required": [ "service_name", "breaker_spend_usd", "ledger_total_usd", "excluded_cache_hit_usd", "excluded_local_model_usd", "breaker_calls", "ledger_calls", "reconciles", "would_refuse", "reference_sql" ], "title": "DailyBreakerReconciliationResponse", "type": "object" }, "DailyProviderUsage": { "description": "A single UTC day's cloud-vs-desktop split (for the over-time chart).", "properties": { "cloud": { "$ref": "#/components/schemas/ProviderUsage" }, "day": { "title": "Day", "type": "string" }, "desktop": { "$ref": "#/components/schemas/ProviderUsage" } }, "required": [ "day", "cloud", "desktop" ], "title": "DailyProviderUsage", "type": "object" }, "DailyStat": { "properties": { "blocked": { "title": "Blocked", "type": "integer" }, "day": { "description": "UTC day key, YYYY-MM-DD.", "title": "Day", "type": "string" }, "submissions": { "title": "Submissions", "type": "integer" } }, "required": [ "day", "submissions", "blocked" ], "title": "DailyStat", "type": "object" }, "DailyTrend": { "properties": { "cache_hits": { "default": 0, "title": "Cache Hits", "type": "integer" }, "calls": { "default": 0, "title": "Calls", "type": "integer" }, "cost_usd": { "default": 0.0, "title": "Cost Usd", "type": "number" }, "date": { "title": "Date", "type": "string" }, "provider_cached_tokens": { "default": 0, "title": "Provider Cached Tokens", "type": "integer" }, "tokens": { "default": 0, "title": "Tokens", "type": "integer" } }, "required": [ "date" ], "title": "DailyTrend", "type": "object" }, "DataExportJob": { "properties": { "completed_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Completed At" }, "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "download_expires_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Download Expires At" }, "download_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Download Url" }, "entity_types": { "items": { "type": "string" }, "title": "Entity Types", "type": "array" }, "error_message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Error Message" }, "job_id": { "title": "Job Id", "type": "string" }, "manifest": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "title": "Manifest" }, "progress": { "$ref": "#/components/schemas/ExportProgress" }, "scope": { "enum": [ "all", "partial" ], "title": "Scope", "type": "string" }, "status": { "enum": [ "queued", "building", "packaging", "ready", "failed", "expired" ], "title": "Status", "type": "string" }, "tenant_id": { "title": "Tenant Id", "type": "string" }, "updated_at": { "format": "date-time", "title": "Updated At", "type": "string" } }, "required": [ "job_id", "tenant_id", "scope", "entity_types", "status", "progress", "created_at", "updated_at" ], "title": "DataExportJob", "type": "object" }, "DataExportRequest": { "description": "Request model for data export.", "properties": { "format": { "default": "json", "description": "Export format: json or csv", "title": "Format", "type": "string" }, "include_contacts": { "default": true, "description": "Include contacts", "title": "Include Contacts", "type": "boolean" }, "include_emails": { "default": true, "description": "Include email content", "title": "Include Emails", "type": "boolean" }, "include_events": { "default": true, "description": "Include calendar events", "title": "Include Events", "type": "boolean" }, "include_tasks": { "default": true, "description": "Include tasks", "title": "Include Tasks", "type": "boolean" } }, "title": "DataExportRequest", "type": "object" }, "DataExportResponse": { "description": "Response model for data export.", "properties": { "download_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Download Url" }, "expires_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Expires At" }, "job_id": { "title": "Job Id", "type": "string" }, "message": { "title": "Message", "type": "string" }, "status": { "title": "Status", "type": "string" } }, "required": [ "job_id", "status", "message" ], "title": "DataExportResponse", "type": "object" }, "DataImportJob": { "properties": { "completed_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Completed At" }, "counts": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "title": "Counts" }, "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "error_message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Error Message" }, "failed_items_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Failed Items Url" }, "format": { "enum": [ "notion", "evernote", "mbox", "ics", "vcf" ], "title": "Format", "type": "string" }, "job_id": { "title": "Job Id", "type": "string" }, "mapping": { "anyOf": [ { "additionalProperties": { "type": "string" }, "type": "object" }, { "type": "null" } ], "default": null, "title": "Mapping" }, "phase": { "enum": [ "parsing", "previewing", "mapping", "importing", "complete", "failed", "cancelled" ], "title": "Phase", "type": "string" }, "preview": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "default": null, "title": "Preview" }, "progress_pct": { "default": 0, "title": "Progress Pct", "type": "integer" }, "tenant_id": { "title": "Tenant Id", "type": "string" }, "updated_at": { "format": "date-time", "title": "Updated At", "type": "string" } }, "required": [ "job_id", "tenant_id", "format", "phase", "created_at", "updated_at" ], "title": "DataImportJob", "type": "object" }, "DatabaseFacetAutoNameResponse": { "description": "Response payload for the Database facet auto-name helper endpoint.", "properties": { "title": { "title": "Title", "type": "string" } }, "required": [ "title" ], "title": "DatabaseFacetAutoNameResponse", "type": "object" }, "DatabaseFacetCreateRequest": { "description": "Request body for creating a canonical Database facet record.", "properties": { "aggregates": { "additionalProperties": true, "title": "Aggregates", "type": "object" }, "config_ext": { "additionalProperties": true, "title": "Config Ext", "type": "object" }, "context_scope": { "default": false, "title": "Context Scope", "type": "boolean" }, "facet_scope": { "anyOf": [ { "enum": [ "exact", "inheritors" ], "type": "string" }, { "type": "null" } ], "title": "Facet Scope" }, "filters": { "additionalProperties": true, "title": "Filters", "type": "object" }, "id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Id" }, "layout_settings": { "additionalProperties": true, "title": "Layout Settings", "type": "object" }, "parent_note_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Parent Note Id" }, "query_facets": { "items": { "type": "string" }, "title": "Query Facets", "type": "array" }, "saved_view_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Saved View Id" }, "sort_order": { "items": { "$ref": "#/components/schemas/SortClause" }, "title": "Sort Order", "type": "array" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Title" }, "view_type": { "default": "table", "enum": [ "table", "kanban", "calendar", "timeline", "gantt", "card", "gallery", "planning", "chart", "hierarchy", "grouped_list" ], "title": "View Type", "type": "string" }, "visible_columns": { "items": { "type": "string" }, "title": "Visible Columns", "type": "array" } }, "title": "DatabaseFacetCreateRequest", "type": "object" }, "DatabaseFacetResponse": { "description": "Canonical Database facet row returned by the REST API.", "properties": { "aggregates": { "additionalProperties": true, "title": "Aggregates", "type": "object" }, "config_ext": { "additionalProperties": true, "title": "Config Ext", "type": "object" }, "context_scope": { "title": "Context Scope", "type": "boolean" }, "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "facet_scope": { "anyOf": [ { "enum": [ "exact", "inheritors" ], "type": "string" }, { "type": "null" } ], "title": "Facet Scope" }, "filters": { "additionalProperties": true, "title": "Filters", "type": "object" }, "id": { "format": "uuid", "title": "Id", "type": "string" }, "layout_settings": { "additionalProperties": true, "title": "Layout Settings", "type": "object" }, "owner_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Owner Id" }, "parent_note_id": { "anyOf": [ { "description": "Typed primitive ID for notes (prefix 'N').", "examples": [ "N-550e8400-e29b-41d4-a716-446655440000" ], "pattern": "^N-[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "title": "NoteId", "type": "string", "x-tidy-typed-id-prefix": "N", "x-tidy-typed-id-table": "notes" }, { "type": "null" } ], "title": "Parent Note Id" }, "query_facets": { "items": { "type": "string" }, "title": "Query Facets", "type": "array" }, "saved_view_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Saved View Id" }, "sort_order": { "items": { "$ref": "#/components/schemas/SortClause" }, "title": "Sort Order", "type": "array" }, "tenant_id": { "format": "uuid", "title": "Tenant Id", "type": "string" }, "title": { "title": "Title", "type": "string" }, "updated_at": { "format": "date-time", "title": "Updated At", "type": "string" }, "view_type": { "enum": [ "table", "kanban", "calendar", "timeline", "gantt", "card", "gallery", "planning", "chart", "hierarchy", "grouped_list" ], "title": "View Type", "type": "string" }, "visibility": { "title": "Visibility", "type": "string" }, "visible_columns": { "items": { "type": "string" }, "title": "Visible Columns", "type": "array" } }, "required": [ "id", "tenant_id", "owner_id", "title", "query_facets", "filters", "view_type", "sort_order", "visible_columns", "layout_settings", "aggregates", "context_scope", "saved_view_id", "config_ext", "facet_scope", "parent_note_id", "visibility", "created_at", "updated_at" ], "title": "DatabaseFacetResponse", "type": "object" }, "DatabaseFacetRowsResponse": { "description": "A database view resolved to a static table (TIDY-14037 / S4).\n\n``columns`` are humanized header labels; ``rows`` are the per-record cell\nvalues as strings, aligned to ``columns``. Consumed by doc-service to render\nan embedded database view as a static table in a report export.", "properties": { "columns": { "items": { "type": "string" }, "title": "Columns", "type": "array" }, "rows": { "items": { "items": { "type": "string" }, "type": "array" }, "title": "Rows", "type": "array" } }, "title": "DatabaseFacetRowsResponse", "type": "object" }, "DatabaseFacetUpdateRequest": { "description": "Partial update body for a canonical Database facet record.", "properties": { "aggregates": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Aggregates" }, "config_ext": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Config Ext" }, "context_scope": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Context Scope" }, "facet_scope": { "anyOf": [ { "enum": [ "exact", "inheritors" ], "type": "string" }, { "type": "null" } ], "title": "Facet Scope" }, "filters": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Filters" }, "layout_settings": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Layout Settings" }, "query_facets": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Query Facets" }, "saved_view_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Saved View Id" }, "sort_order": { "anyOf": [ { "items": { "$ref": "#/components/schemas/SortClause" }, "type": "array" }, { "type": "null" } ], "title": "Sort Order" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Title" }, "view_type": { "anyOf": [ { "enum": [ "table", "kanban", "calendar", "timeline", "gantt", "card", "gallery", "planning", "chart", "hierarchy", "grouped_list" ], "type": "string" }, { "type": "null" } ], "title": "View Type" }, "visible_columns": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Visible Columns" } }, "title": "DatabaseFacetUpdateRequest", "type": "object" }, "DatabaseViewUsageResponse": { "description": "Where a saved database view is used (TIDY-19705 F9).", "properties": { "coverage": { "$ref": "#/components/schemas/ViewUsageCoverage" }, "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "created_by": { "anyOf": [ { "$ref": "#/components/schemas/RecordAuthor" }, { "type": "null" } ], "default": null }, "database_facet_id": { "description": "The view's typed id (`R-`).", "title": "Database Facet Id", "type": "string" }, "hidden_places": { "description": "How many more places use the view that you cannot open — a count only, never which ones or whose.", "title": "Hidden Places", "type": "integer" }, "in_use": { "description": "False only when nothing anywhere in the workspace uses the view: no place listed and no hidden place.", "title": "In Use", "type": "boolean" }, "places": { "description": "The places using the view that you can open.", "items": { "$ref": "#/components/schemas/ViewUsagePlace" }, "title": "Places", "type": "array" }, "title": { "title": "Title", "type": "string" } }, "required": [ "database_facet_id", "title", "created_at", "in_use", "hidden_places", "coverage" ], "title": "DatabaseViewUsageResponse", "type": "object" }, "DayArtifactAttachment": { "properties": { "content_type": { "title": "Content Type", "type": "string" }, "email_id": { "title": "Email Id", "type": "string" }, "filename": { "title": "Filename", "type": "string" }, "id": { "title": "Id", "type": "string" }, "sender": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Sender" }, "storage_path": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Storage Path" } }, "required": [ "id", "filename", "content_type", "email_id" ], "title": "DayArtifactAttachment", "type": "object" }, "DayArtifactCalendarEvent": { "properties": { "email_id": { "title": "Email Id", "type": "string" }, "id": { "title": "Id", "type": "string" }, "sender": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Sender" }, "start_time": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Start Time" }, "summary": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Summary" } }, "required": [ "id", "email_id" ], "title": "DayArtifactCalendarEvent", "type": "object" }, "DayArtifactContact": { "properties": { "approval_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Approval Status" }, "display_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Display Name" }, "email_id": { "title": "Email Id", "type": "string" }, "id": { "title": "Id", "type": "string" }, "sender": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Sender" } }, "required": [ "id", "email_id" ], "title": "DayArtifactContact", "type": "object" }, "DayArtifactDocument": { "description": "Per-email document/url row carrying its owning ``email_id`` + ``sender``\ndisplay so the day-scoped list links each item back to its journey.", "properties": { "content_char_count": { "default": 0, "title": "Content Char Count", "type": "integer" }, "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "domain": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Domain" }, "email_id": { "title": "Email Id", "type": "string" }, "filename": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Filename" }, "id": { "title": "Id", "type": "string" }, "sender": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Sender" }, "source_type": { "title": "Source Type", "type": "string" }, "success": { "default": true, "title": "Success", "type": "boolean" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Title" }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Url" } }, "required": [ "id", "source_type", "created_at", "email_id" ], "title": "DayArtifactDocument", "type": "object" }, "DebugLinksResponse": { "description": "Links to debugging tools.", "properties": { "grafana_logs": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Grafana Logs" }, "grafana_trace": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Grafana Trace" }, "loki_query": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Loki Query" }, "service_dashboards": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Service Dashboards" } }, "title": "DebugLinksResponse", "type": "object" }, "DecideCapabilityRequestResponse": { "properties": { "ok": { "title": "Ok", "type": "boolean" }, "status": { "title": "Status", "type": "string" } }, "required": [ "ok", "status" ], "title": "DecideCapabilityRequestResponse", "type": "object" }, "DecideRequest": { "properties": { "status": { "enum": [ "approved", "denied" ], "title": "Status", "type": "string" } }, "required": [ "status" ], "title": "DecideRequest", "type": "object" }, "DecideSenderRequest": { "description": "Request body for POST /screening/senders/decide.\n\nAddress-keyed decision entry point. Upserts the sender_screening row for the\naddress (creating it when the provider-spam short-circuit meant the bouncer\nnever inserted one) and applies the same decision core as the id-keyed\napprove / allow-once / block endpoints.", "properties": { "action": { "enum": [ "approve", "allow_once", "block", "unblock" ], "title": "Action", "type": "string" }, "email_address": { "title": "Email Address", "type": "string" }, "mark_done": { "default": false, "title": "Mark Done", "type": "boolean" }, "scope": { "default": "address", "enum": [ "address", "domain" ], "title": "Scope", "type": "string" }, "unsubscribe": { "default": false, "title": "Unsubscribe", "type": "boolean" } }, "required": [ "email_address", "action" ], "title": "DecideSenderRequest", "type": "object" }, "DecideSenderResponse": { "description": "Response for POST /screening/senders/decide.\n\nMirrors the id-keyed decision responses plus the resolved sender id. The\npopulated fields depend on the action: emails_routed for approve/allow_once,\nemails_restored for unblock, unsubscribe_* for block.", "properties": { "emails_restored": { "default": 0, "title": "Emails Restored", "type": "integer" }, "emails_routed": { "default": 0, "title": "Emails Routed", "type": "integer" }, "sender_id": { "format": "uuid", "title": "Sender Id", "type": "string" }, "status": { "title": "Status", "type": "string" }, "unsubscribe_attempted": { "default": false, "title": "Unsubscribe Attempted", "type": "boolean" }, "unsubscribe_result": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Unsubscribe Result" } }, "required": [ "sender_id", "status" ], "title": "DecideSenderResponse", "type": "object" }, "DeclineProposalRequest": { "description": "Request model for declining a time proposal.", "properties": { "comment": { "anyOf": [ { "maxLength": 1000, "type": "string" }, { "type": "null" } ], "description": "Optional comment explaining the decline", "title": "Comment" }, "send_email": { "default": true, "description": "Whether to send DECLINECOUNTER via email", "title": "Send Email", "type": "boolean" } }, "title": "DeclineProposalRequest", "type": "object" }, "DeclineProposalResponse": { "description": "Response model after declining a time proposal.", "example": { "declinecounter_sent": true, "declined": true, "event_id": "550e8400-e29b-41d4-a716-446655440000", "ics_uid": "abc123@google.com", "proposed_by": "sarah@example.com" }, "properties": { "declinecounter_sent": { "description": "Whether DECLINECOUNTER was sent via email", "title": "Declinecounter Sent", "type": "boolean" }, "declined": { "default": true, "description": "Whether the proposal was declined", "title": "Declined", "type": "boolean" }, "event_id": { "description": "Calendar event UUID", "title": "Event Id", "type": "string" }, "ics_uid": { "description": "ICS UID of the event", "title": "Ics Uid", "type": "string" }, "proposed_by": { "description": "Email of person who proposed the change", "title": "Proposed By", "type": "string" } }, "required": [ "event_id", "ics_uid", "declinecounter_sent", "proposed_by" ], "title": "DeclineProposalResponse", "type": "object" }, "DeclineResponse": { "properties": { "recipient_state": { "title": "Recipient State", "type": "string" }, "ring_id": { "format": "uuid", "title": "Ring Id", "type": "string" }, "session_state": { "title": "Session State", "type": "string" }, "terminal_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Terminal Reason" } }, "required": [ "ring_id", "recipient_state", "session_state" ], "title": "DeclineResponse", "type": "object" }, "DefaultEmployeeRef": { "additionalProperties": false, "properties": { "id": { "title": "Id", "type": "string" }, "kind": { "enum": [ "hosted", "workshop" ], "title": "Kind", "type": "string" } }, "required": [ "kind", "id" ], "title": "DefaultEmployeeRef", "type": "object" }, "DefenseEventResponse": { "properties": { "action": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Action" }, "cost_class": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Cost Class" }, "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "event_type": { "title": "Event Type", "type": "string" }, "execution_locus": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Execution Locus" }, "payload": { "additionalProperties": true, "default": {}, "title": "Payload", "type": "object" }, "rule_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Rule Id" }, "seq": { "title": "Seq", "type": "integer" }, "shadowed_rule_ids": { "default": [], "items": { "type": "string" }, "title": "Shadowed Rule Ids", "type": "array" }, "stage": { "title": "Stage", "type": "string" } }, "required": [ "seq", "stage", "event_type", "created_at" ], "title": "DefenseEventResponse", "type": "object" }, "DefenseKpiResponse": { "properties": { "health_counterweight": { "title": "Health Counterweight", "type": "number" }, "inbound_volume": { "title": "Inbound Volume", "type": "integer" }, "lambda": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Lambda" }, "minutes_saved": { "title": "Minutes Saved", "type": "number" }, "sample_sufficient": { "title": "Sample Sufficient", "type": "boolean" }, "spend": { "$ref": "#/components/schemas/SpendDelta" }, "tau_bucket": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Tau Bucket" }, "window": { "title": "Window", "type": "string" } }, "required": [ "window", "tau_bucket", "minutes_saved", "spend", "health_counterweight", "inbound_volume", "sample_sufficient" ], "title": "DefenseKpiResponse", "type": "object" }, "DefenseReplayArtifactsResponse": { "description": "Itemized per-email harvest artifacts for the journey detail view — the\nopenable rows behind the ``artifacts`` counters. Owner-scoped: only returned\nfor an email the caller owns a journey for.", "properties": { "attachments": { "default": [], "items": { "$ref": "#/components/schemas/ReplayArtifactAttachment" }, "title": "Attachments", "type": "array" }, "calendar_events": { "default": [], "items": { "$ref": "#/components/schemas/ReplayArtifactCalendarEvent" }, "title": "Calendar Events", "type": "array" }, "contacts": { "default": [], "items": { "$ref": "#/components/schemas/ReplayArtifactContact" }, "title": "Contacts", "type": "array" }, "documents": { "default": [], "items": { "$ref": "#/components/schemas/ReplayArtifactDocument" }, "title": "Documents", "type": "array" }, "email_id": { "title": "Email Id", "type": "string" } }, "required": [ "email_id" ], "title": "DefenseReplayArtifactsResponse", "type": "object" }, "DefenseReplayDayArtifactsResponse": { "description": "The day's itemized harvest lists for the Harvest-breakdown tab — the same\nopenable row shapes as the per-email artifacts endpoint, aggregated across\nthe day's owner-scoped journey email set (one batch per type, no per-email\nN+1). Each row carries email_id + sender to link back to the journey.", "properties": { "attachments": { "default": [], "items": { "$ref": "#/components/schemas/DayArtifactAttachment" }, "title": "Attachments", "type": "array" }, "calendar_events": { "default": [], "items": { "$ref": "#/components/schemas/DayArtifactCalendarEvent" }, "title": "Calendar Events", "type": "array" }, "contacts": { "default": [], "items": { "$ref": "#/components/schemas/DayArtifactContact" }, "title": "Contacts", "type": "array" }, "day": { "title": "Day", "type": "string" }, "documents": { "default": [], "items": { "$ref": "#/components/schemas/DayArtifactDocument" }, "title": "Documents", "type": "array" }, "truncated": { "default": false, "title": "Truncated", "type": "boolean" }, "tz": { "title": "Tz", "type": "string" } }, "required": [ "day", "tz" ], "title": "DefenseReplayDayArtifactsResponse", "type": "object" }, "DefenseReplayMemoriesResponse": { "properties": { "day": { "title": "Day", "type": "string" }, "memories": { "items": { "$ref": "#/components/schemas/ReplayMemory" }, "title": "Memories", "type": "array" }, "truncated": { "default": false, "title": "Truncated", "type": "boolean" }, "tz": { "title": "Tz", "type": "string" } }, "required": [ "day", "tz", "memories" ], "title": "DefenseReplayMemoriesResponse", "type": "object" }, "DefenseReplayResponse": { "properties": { "calendar_events_day": { "default": [], "items": { "$ref": "#/components/schemas/ReplayDayCalendarEvent" }, "title": "Calendar Events Day", "type": "array" }, "calendar_events_day_truncated": { "default": false, "title": "Calendar Events Day Truncated", "type": "boolean" }, "day": { "title": "Day", "type": "string" }, "facet_creations": { "default": [], "items": { "$ref": "#/components/schemas/ReplayFacetCreation" }, "title": "Facet Creations", "type": "array" }, "file_population": { "default": [], "items": { "$ref": "#/components/schemas/ReplayFileItem" }, "title": "File Population", "type": "array" }, "files_truncated": { "default": false, "title": "Files Truncated", "type": "boolean" }, "journeys": { "items": { "$ref": "#/components/schemas/ReplayJourney" }, "title": "Journeys", "type": "array" }, "payloads": { "default": [], "items": { "$ref": "#/components/schemas/ReplayPayload" }, "title": "Payloads", "type": "array" }, "sent": { "default": [], "items": { "$ref": "#/components/schemas/ReplaySentItem" }, "title": "Sent", "type": "array" }, "stats": { "$ref": "#/components/schemas/ReplayStats" }, "towers": { "items": { "$ref": "#/components/schemas/ReplayTower" }, "title": "Towers", "type": "array" }, "truncated": { "default": false, "title": "Truncated", "type": "boolean" }, "tz": { "title": "Tz", "type": "string" } }, "required": [ "day", "tz", "stats", "towers", "journeys" ], "title": "DefenseReplayResponse", "type": "object" }, "DefenseReplayTownResponse": { "description": "The persistent town population as of the selected day — pending contacts\n(residents) and email-harvested calendar events (bulletin board), each on a\n30-day trailing window ending at day_end.\n\nHONEST LIMITATION (documented, not faked): ``pending_contacts`` is the\nintersection of *currently* pending contacts with the created-in-window set.\nA contact approved AFTER the selected day cannot be reconstructed as\npending-at-that-time — there is no per-row approval-status history — so a\nreplay of an older day slightly under-counts residents that have since been\napproved. current-pending ∩ created-window is the contract.", "properties": { "blocked_emails_total": { "default": 0, "title": "Blocked Emails Total", "type": "integer" }, "blocked_senders_total": { "default": 0, "title": "Blocked Senders Total", "type": "integer" }, "bulletin_events": { "default": [], "items": { "$ref": "#/components/schemas/TownBulletinEvent" }, "title": "Bulletin Events", "type": "array" }, "day": { "title": "Day", "type": "string" }, "pending_contacts": { "default": [], "items": { "$ref": "#/components/schemas/TownPendingContact" }, "title": "Pending Contacts", "type": "array" }, "truncated": { "default": false, "title": "Truncated", "type": "boolean" }, "tz": { "title": "Tz", "type": "string" } }, "required": [ "day", "tz" ], "title": "DefenseReplayTownResponse", "type": "object" }, "DefenseRuleCreate": { "description": "Body for POST /api/v1/defense/rules.", "properties": { "action_family": { "enum": [ "block", "screen", "route", "classify", "defer", "harvest", "suppress", "calendar_shield", "workflow" ], "title": "Action Family", "type": "string" }, "actions": { "additionalProperties": true, "title": "Actions", "type": "object" }, "class": { "enum": [ "shepherd", "sentinel", "gatekeeper", "tesla_coil", "freeze_ray", "shield_generator", "teleporter" ], "title": "Class", "type": "string" }, "enabled": { "default": true, "title": "Enabled", "type": "boolean" }, "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Id" }, "is_exception": { "default": false, "title": "Is Exception", "type": "boolean" }, "match": { "$ref": "#/components/schemas/RuleMatch" }, "priority": { "default": 100, "title": "Priority", "type": "integer" }, "proposal_for": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Proposal For" }, "provenance": { "anyOf": [ { "enum": [ "manual", "draft" ], "type": "string" }, { "type": "null" } ], "title": "Provenance" }, "scope": { "default": "member", "enum": [ "member", "tenant", "global" ], "title": "Scope", "type": "string" }, "source_detail": { "additionalProperties": true, "title": "Source Detail", "type": "object" }, "surface": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Surface" } }, "required": [ "class", "action_family", "match" ], "title": "DefenseRuleCreate", "type": "object" }, "DefenseRuleResponse": { "description": "A persisted defense rule.", "properties": { "action_family": { "title": "Action Family", "type": "string" }, "actions": { "additionalProperties": true, "title": "Actions", "type": "object" }, "ai_confidence": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "title": "Ai Confidence" }, "confirmed_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Confirmed At" }, "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "enabled": { "title": "Enabled", "type": "boolean" }, "expires_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Expires At" }, "fire_count_30d": { "title": "Fire Count 30D", "type": "integer" }, "health_score": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "title": "Health Score" }, "id": { "title": "Id", "type": "string" }, "is_exception": { "title": "Is Exception", "type": "boolean" }, "last_fired_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Last Fired At" }, "match": { "additionalProperties": true, "title": "Match", "type": "object" }, "owner_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Owner Id" }, "pack_key": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Pack Key" }, "priority": { "title": "Priority", "type": "integer" }, "provenance": { "title": "Provenance", "type": "string" }, "rule_class": { "title": "Rule Class", "type": "string" }, "scope": { "title": "Scope", "type": "string" }, "source_detail": { "additionalProperties": true, "title": "Source Detail", "type": "object" }, "tenant_id": { "title": "Tenant Id", "type": "string" }, "updated_at": { "format": "date-time", "title": "Updated At", "type": "string" } }, "required": [ "id", "tenant_id", "scope", "rule_class", "action_family", "match", "actions", "priority", "enabled", "is_exception", "provenance", "source_detail", "fire_count_30d", "created_at", "updated_at" ], "title": "DefenseRuleResponse", "type": "object" }, "DefenseRuleUpdate": { "description": "Body for PATCH /api/v1/defense/rules/{id}.", "properties": { "actions": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Actions" }, "enabled": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Enabled" }, "is_exception": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is Exception" }, "match": { "anyOf": [ { "$ref": "#/components/schemas/RuleMatch" }, { "type": "null" } ] }, "priority": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Priority" } }, "title": "DefenseRuleUpdate", "type": "object" }, "DefinedEmployeeResponse": { "properties": { "employee": { "$ref": "#/components/schemas/AIEmployeeResponse" }, "objective_ids": { "items": { "type": "string" }, "title": "Objective Ids", "type": "array" }, "reports_to_membership_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Reports To Membership Id" }, "scheduled_job_ids": { "items": { "type": "string" }, "title": "Scheduled Job Ids", "type": "array" } }, "required": [ "employee" ], "title": "DefinedEmployeeResponse", "type": "object" }, "DefinedNameSummary": { "description": "A CHARTABLE defined name — a name holding anything other than a plain\nrectangle is omitted, so an agent can never offer one that dead-links.", "properties": { "name": { "title": "Name", "type": "string" }, "range": { "title": "Range", "type": "string" }, "scope": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "The sheet a sheet-scoped name belongs to; null for workbook scope.", "title": "Scope" }, "sheet": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Sheet" } }, "required": [ "name", "range" ], "title": "DefinedNameSummary", "type": "object" }, "DefinedTeamMember": { "properties": { "draft_key": { "title": "Draft Key", "type": "string" }, "employee": { "$ref": "#/components/schemas/AIEmployeeResponse" }, "objective_ids": { "items": { "type": "string" }, "title": "Objective Ids", "type": "array" }, "reports_to_membership_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Reports To Membership Id" }, "scheduled_job_ids": { "items": { "type": "string" }, "title": "Scheduled Job Ids", "type": "array" } }, "required": [ "employee", "draft_key" ], "title": "DefinedTeamMember", "type": "object" }, "DefinedTeamResponse": { "properties": { "employees": { "items": { "$ref": "#/components/schemas/DefinedTeamMember" }, "title": "Employees", "type": "array" } }, "title": "DefinedTeamResponse", "type": "object" }, "DefinitionCreateRequest": { "properties": { "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "display_name": { "minLength": 1, "title": "Display Name", "type": "string" }, "origin": { "default": "product", "enum": [ "product", "self_discovered" ], "title": "Origin", "type": "string" }, "output_class_primary": { "enum": [ "briefing", "internal_mutation", "approval_proposal", "capability_mutation", "operator_finding" ], "title": "Output Class Primary", "type": "string" }, "output_class_secondary": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Output Class Secondary" }, "owner_scope": { "default": "global", "enum": [ "global", "tenant" ], "title": "Owner Scope", "type": "string" }, "slug": { "maxLength": 128, "minLength": 1, "title": "Slug", "type": "string" }, "suppression_category": { "minLength": 1, "title": "Suppression Category", "type": "string" }, "tenant_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Tenant Id" } }, "required": [ "slug", "display_name", "output_class_primary", "suppression_category" ], "title": "DefinitionCreateRequest", "type": "object" }, "DefinitionDetailResponse": { "properties": { "definition": { "$ref": "#/components/schemas/DefinitionSummary" }, "rollouts": { "items": { "additionalProperties": true, "type": "object" }, "title": "Rollouts", "type": "array" }, "versions": { "items": { "additionalProperties": true, "type": "object" }, "title": "Versions", "type": "array" } }, "required": [ "definition", "versions", "rollouts" ], "title": "DefinitionDetailResponse", "type": "object" }, "DefinitionListResponse": { "properties": { "definitions": { "items": { "$ref": "#/components/schemas/DefinitionSummary" }, "title": "Definitions", "type": "array" } }, "required": [ "definitions" ], "title": "DefinitionListResponse", "type": "object" }, "DefinitionSummary": { "properties": { "active_rollout_count": { "default": 0, "title": "Active Rollout Count", "type": "integer" }, "active_version_number": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Active Version Number" }, "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "display_name": { "title": "Display Name", "type": "string" }, "id": { "format": "uuid", "title": "Id", "type": "string" }, "origin": { "title": "Origin", "type": "string" }, "output_class_primary": { "title": "Output Class Primary", "type": "string" }, "output_class_secondary": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Output Class Secondary" }, "owner_scope": { "title": "Owner Scope", "type": "string" }, "slug": { "title": "Slug", "type": "string" }, "suppression_category": { "title": "Suppression Category", "type": "string" }, "tenant_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Tenant Id" }, "updated_at": { "format": "date-time", "title": "Updated At", "type": "string" }, "version_count": { "default": 0, "title": "Version Count", "type": "integer" } }, "required": [ "id", "slug", "display_name", "description", "origin", "owner_scope", "tenant_id", "output_class_primary", "output_class_secondary", "suppression_category", "created_at", "updated_at" ], "title": "DefinitionSummary", "type": "object" }, "DelegationAuditEntry": { "properties": { "action": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Action" }, "actor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Actor" }, "context_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Context Id" }, "grant_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Grant Id" }, "outcome": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Outcome" }, "principal": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Principal" }, "resource_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Resource Id" }, "resource_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Resource Type" }, "ts": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Ts" } }, "title": "DelegationAuditEntry", "type": "object" }, "DelegationAuditResponse": { "properties": { "entries": { "items": { "$ref": "#/components/schemas/DelegationAuditEntry" }, "title": "Entries", "type": "array" } }, "required": [ "entries" ], "title": "DelegationAuditResponse", "type": "object" }, "DelegationBounds": { "additionalProperties": false, "description": "R45 bounds. An omitted bound leaves that dimension unconstrained.", "properties": { "definitions": { "anyOf": [ { "items": { "format": "uuid", "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Definitions" }, "external_actions": { "default": false, "title": "External Actions", "type": "boolean" }, "max_rollout_percentage": { "anyOf": [ { "maximum": 100.0, "minimum": 1.0, "type": "integer" }, { "type": "null" } ], "title": "Max Rollout Percentage" }, "max_spend_usd_month": { "anyOf": [ { "minimum": 0.0, "type": "number" }, { "type": "null" } ], "title": "Max Spend Usd Month" }, "max_tenant_count": { "anyOf": [ { "minimum": 1.0, "type": "integer" }, { "type": "null" } ], "title": "Max Tenant Count" }, "output_classes": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Output Classes" }, "risk_classes": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Risk Classes" } }, "title": "DelegationBounds", "type": "object" }, "DelegationCreateRequest": { "properties": { "agent_account_id": { "format": "uuid", "title": "Agent Account Id", "type": "string" }, "bounds": { "$ref": "#/components/schemas/DelegationBounds" }, "capabilities": { "items": { "enum": [ "author_version", "evaluate", "approve_opportunity", "rollout_tenants", "rollout_cohort", "rollout_staged", "rollout_global", "autonomy_change", "budget_change", "pause", "quarantine", "retire", "rollback", "renew_consent_request" ], "type": "string" }, "minItems": 1, "title": "Capabilities", "type": "array" }, "expires_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Expires At" }, "self_approval": { "default": false, "title": "Self Approval", "type": "boolean" } }, "required": [ "agent_account_id", "capabilities" ], "title": "DelegationCreateRequest", "type": "object" }, "DelegationListResponse": { "properties": { "delegations": { "items": { "$ref": "#/components/schemas/DelegationModel" }, "title": "Delegations", "type": "array" } }, "required": [ "delegations" ], "title": "DelegationListResponse", "type": "object" }, "DelegationModel": { "properties": { "agent_account_id": { "format": "uuid", "title": "Agent Account Id", "type": "string" }, "bounds": { "additionalProperties": true, "title": "Bounds", "type": "object" }, "capabilities": { "items": { "type": "string" }, "title": "Capabilities", "type": "array" }, "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "expires_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Expires At" }, "granted_by": { "format": "uuid", "title": "Granted By", "type": "string" }, "id": { "format": "uuid", "title": "Id", "type": "string" }, "revoked_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Revoked At" }, "revoked_by": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Revoked By" }, "self_approval": { "title": "Self Approval", "type": "boolean" } }, "required": [ "id", "agent_account_id", "granted_by", "capabilities", "bounds", "self_approval", "expires_at", "revoked_at", "revoked_by", "created_at" ], "title": "DelegationModel", "type": "object" }, "DelegationPatchRequest": { "properties": { "bounds": { "anyOf": [ { "$ref": "#/components/schemas/DelegationBounds" }, { "type": "null" } ] }, "capabilities": { "anyOf": [ { "items": { "enum": [ "author_version", "evaluate", "approve_opportunity", "rollout_tenants", "rollout_cohort", "rollout_staged", "rollout_global", "autonomy_change", "budget_change", "pause", "quarantine", "retire", "rollback", "renew_consent_request" ], "type": "string" }, "minItems": 1, "type": "array" }, { "type": "null" } ], "title": "Capabilities" }, "expires_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Expires At" }, "self_approval": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Self Approval" } }, "title": "DelegationPatchRequest", "type": "object" }, "DeleteChatMessageResponse": { "properties": { "deleted_mrs": { "title": "Deleted Mrs", "type": "boolean" }, "deleted_postgres": { "title": "Deleted Postgres", "type": "boolean" } }, "required": [ "deleted_postgres", "deleted_mrs" ], "title": "DeleteChatMessageResponse", "type": "object" }, "DeleteChunkResponse": { "properties": { "success": { "title": "Success", "type": "boolean" } }, "required": [ "success" ], "title": "DeleteChunkResponse", "type": "object" }, "DeleteDocumentByIdResponse": { "properties": { "document_id": { "title": "Document Id", "type": "string" }, "storage_deleted": { "default": false, "title": "Storage Deleted", "type": "boolean" }, "success": { "title": "Success", "type": "boolean" } }, "required": [ "success", "document_id" ], "title": "DeleteDocumentByIdResponse", "type": "object" }, "DeleteDocumentResponse": { "description": "Response for document deletion.", "properties": { "chunks_deleted": { "title": "Chunks Deleted", "type": "integer" }, "document_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Document Id" }, "source_document": { "title": "Source Document", "type": "string" }, "storage_deleted": { "default": false, "title": "Storage Deleted", "type": "boolean" }, "success": { "title": "Success", "type": "boolean" } }, "required": [ "success", "source_document", "chunks_deleted" ], "title": "DeleteDocumentResponse", "type": "object" }, "DeleteElementOp": { "additionalProperties": false, "description": "Remove ONE element from the elements map AND the z-order array.", "properties": { "id": { "maxLength": 200, "minLength": 1, "title": "Id", "type": "string" }, "op": { "const": "delete_element", "title": "Op", "type": "string" } }, "required": [ "id", "op" ], "title": "DeleteElementOp", "type": "object" }, "DeleteMessageRequest": { "description": "Optional reason recorded on the redaction event + audit row.", "properties": { "reason": { "anyOf": [ { "maxLength": 500, "type": "string" }, { "type": "null" } ], "title": "Reason" } }, "title": "DeleteMessageRequest", "type": "object" }, "DeleteMessageResponse": { "description": "The redaction event id Tuwunel issued for the m.room.redaction.", "properties": { "event_id": { "title": "Event Id", "type": "string" }, "redacted_at": { "title": "Redacted At", "type": "string" } }, "required": [ "event_id", "redacted_at" ], "title": "DeleteMessageResponse", "type": "object" }, "DeleteSpanOp": { "additionalProperties": false, "properties": { "old": { "maxLength": 10000, "minLength": 1, "title": "Old", "type": "string" }, "op": { "const": "delete_span", "title": "Op", "type": "string" } }, "required": [ "op", "old" ], "title": "DeleteSpanOp", "type": "object" }, "DeletedTrigger": { "additionalProperties": false, "properties": { "kind": { "const": "deleted", "title": "Kind", "type": "string" }, "tags_any": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Tags Any" } }, "required": [ "kind" ], "title": "DeletedTrigger", "type": "object" }, "DeletionAdoptRequest": { "properties": { "account_id": { "format": "uuid", "title": "Account Id", "type": "string" }, "confirm_account_id": { "format": "uuid", "title": "Confirm Account Id", "type": "string" }, "tenant_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Tenant Id" } }, "required": [ "account_id", "confirm_account_id" ], "title": "DeletionAdoptRequest", "type": "object" }, "DeletionAdoptResponse": { "properties": { "created": { "title": "Created", "type": "boolean" }, "operation_id": { "title": "Operation Id", "type": "string" }, "receipt_id": { "title": "Receipt Id", "type": "string" }, "status": { "title": "Status", "type": "string" } }, "required": [ "operation_id", "created", "status", "receipt_id" ], "title": "DeletionAdoptResponse", "type": "object" }, "DeletionInspectResponse": { "properties": { "operation": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "title": "Operation" }, "secret_count": { "default": 0, "title": "Secret Count", "type": "integer" }, "steps": { "default": [], "items": { "additionalProperties": true, "type": "object" }, "title": "Steps", "type": "array" }, "targets": { "default": [], "items": { "additionalProperties": true, "type": "object" }, "title": "Targets", "type": "array" }, "verifier": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "title": "Verifier" } }, "title": "DeletionInspectResponse", "type": "object" }, "DeletionOperationSummary": { "properties": { "attempt_count": { "default": 0, "title": "Attempt Count", "type": "integer" }, "completed_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Completed At" }, "has_account_id": { "default": false, "title": "Has Account Id", "type": "boolean" }, "has_tenant_id": { "default": false, "title": "Has Tenant Id", "type": "boolean" }, "id": { "title": "Id", "type": "string" }, "mode": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Mode" }, "phase": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Phase" }, "policy_version": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Policy Version" }, "started_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Started At" }, "status": { "title": "Status", "type": "string" }, "subject_hash": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Subject Hash" }, "verified_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Verified At" } }, "required": [ "id", "status" ], "title": "DeletionOperationSummary", "type": "object" }, "DeletionPreflightResponse": { "description": "Non-destructive account-erasure readiness (TIDY-17888 / S2).", "properties": { "code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Code" }, "planned_target_classes": { "items": { "type": "string" }, "title": "Planned Target Classes", "type": "array" }, "ready": { "title": "Ready", "type": "boolean" }, "retained_categories": { "items": { "type": "string" }, "title": "Retained Categories", "type": "array" } }, "required": [ "ready", "retained_categories", "planned_target_classes" ], "title": "DeletionPreflightResponse", "type": "object" }, "DeletionResult": { "properties": { "attribution_anonymized": { "default": 0, "title": "Attribution Anonymized", "type": "integer" }, "audit_targets_pseudonymized": { "default": 0, "title": "Audit Targets Pseudonymized", "type": "integer" }, "case": { "title": "Case", "type": "string" }, "membership_removed": { "default": 0, "title": "Membership Removed", "type": "integer" }, "usage_logs_anonymized": { "default": 0, "title": "Usage Logs Anonymized", "type": "integer" } }, "required": [ "case" ], "title": "DeletionResult", "type": "object" }, "DeletionResumeRequest": { "properties": { "confirm_operation_id": { "format": "uuid", "title": "Confirm Operation Id", "type": "string" } }, "required": [ "confirm_operation_id" ], "title": "DeletionResumeRequest", "type": "object" }, "DeletionResumeResponse": { "properties": { "operation_id": { "title": "Operation Id", "type": "string" }, "status": { "title": "Status", "type": "string" } }, "required": [ "operation_id", "status" ], "title": "DeletionResumeResponse", "type": "object" }, "DeletionScheduleResponse": { "description": "Accepted erasure operation (TIDY-17890 / S4). Additive over the S1 shape.", "properties": { "execute_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Execute At" }, "grace_period_days": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Grace Period Days" }, "message": { "title": "Message", "type": "string" }, "mode": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Mode" }, "operation_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Operation Id" }, "schedule_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Schedule Id" }, "status": { "title": "Status", "type": "string" }, "status_receipt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Status Receipt" }, "status_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Status Url" } }, "required": [ "status", "message" ], "title": "DeletionScheduleResponse", "type": "object" }, "DeletionStatusResponse": { "description": "Aggregate deletion status.", "properties": { "has_pending_deletion": { "title": "Has Pending Deletion", "type": "boolean" }, "schedule": { "anyOf": [ { "$ref": "#/components/schemas/DeletionStatusSchedule" }, { "type": "null" } ], "default": null } }, "required": [ "has_pending_deletion" ], "title": "DeletionStatusResponse", "type": "object" }, "DeletionStatusSchedule": { "description": "Single deletion schedule row.", "properties": { "cancelled_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Cancelled At" }, "execute_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Execute At" }, "executed_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Executed At" }, "grace_period_days": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Grace Period Days" }, "id": { "title": "Id", "type": "string" }, "scheduled_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Scheduled At" }, "status": { "title": "Status", "type": "string" } }, "required": [ "id", "status" ], "title": "DeletionStatusSchedule", "type": "object" }, "DeliverableProviderLinks": { "description": "Deep links OUT to the provider (D1 — Tidy is not a repo browser).\n\nEvery field is null for a repo-less deliverable or a provider that does not\nbuild web URLs; the UI hides the action rather than guessing a URL.", "properties": { "commit_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Commit Url" }, "file_history_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "File History Url" }, "file_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "File Url" }, "repo_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Repo Url" } }, "title": "DeliverableProviderLinks", "type": "object" }, "DeliveryOutcome": { "description": "What an accepted delivery set off.", "properties": { "assignment": { "anyOf": [ { "$ref": "#/components/schemas/AssignmentResult" }, { "type": "null" } ], "default": null }, "errors": { "items": { "type": "string" }, "title": "Errors", "type": "array" }, "execution_ids": { "items": { "type": "string" }, "title": "Execution Ids", "type": "array" }, "mapping_runs": { "items": { "$ref": "#/components/schemas/MappingRunOutcome" }, "title": "Mapping Runs", "type": "array" }, "rule_runs": { "items": { "type": "string" }, "title": "Rule Runs", "type": "array" } }, "title": "DeliveryOutcome", "type": "object" }, "DeltaSyncResponse": { "description": "Delta sync result.", "properties": { "connection_id": { "title": "Connection Id", "type": "string" }, "history_id": { "title": "History Id", "type": "string" }, "success": { "title": "Success", "type": "boolean" } }, "required": [ "connection_id", "history_id", "success" ], "title": "DeltaSyncResponse", "type": "object" }, "DemoteRequest": { "properties": { "force_by_admin": { "default": false, "description": "Tenant-owner override of owner-only demote", "title": "Force By Admin", "type": "boolean" }, "to_visibility": { "description": "Target tier: 'private' or 'shared'", "title": "To Visibility", "type": "string" } }, "required": [ "to_visibility" ], "title": "DemoteRequest", "type": "object" }, "DemoteResponse": { "properties": { "affected_user_count": { "default": 0, "title": "Affected User Count", "type": "integer" }, "from_visibility": { "title": "From Visibility", "type": "string" }, "notifications_queued": { "default": 0, "title": "Notifications Queued", "type": "integer" }, "ok": { "default": true, "title": "Ok", "type": "boolean" }, "orphaned_facet_count": { "default": 0, "title": "Orphaned Facet Count", "type": "integer" }, "to_visibility": { "title": "To Visibility", "type": "string" } }, "required": [ "from_visibility", "to_visibility" ], "title": "DemoteResponse", "type": "object" }, "DependencyWithTask": { "description": "A dependency record enriched with the related task's summary.", "properties": { "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "dependency_type": { "title": "Dependency Type", "type": "string" }, "id": { "title": "Id", "type": "string" }, "task": { "$ref": "#/components/schemas/TaskSummary" } }, "required": [ "id", "dependency_type", "created_at", "task" ], "title": "DependencyWithTask", "type": "object" }, "DeployFailureRow": { "description": "Deploy failures grouped by the step that failed.", "properties": { "count": { "title": "Count", "type": "integer" }, "last_error_sample": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Last Error Sample" }, "source": { "title": "Source", "type": "string" }, "step": { "title": "Step", "type": "string" } }, "required": [ "source", "step", "count" ], "title": "DeployFailureRow", "type": "object" }, "DeployPluginAccessPlan": { "description": "A deploy's plan; ``agent_account_id`` is null for a prospective one\n(Define, before the employee exists).", "properties": { "agent_account_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Agent Account Id" }, "key_requirements": { "items": { "$ref": "#/components/schemas/KeyRequirement" }, "title": "Key Requirements", "type": "array" }, "requirements": { "items": { "$ref": "#/components/schemas/PluginAccessRequirement" }, "title": "Requirements", "type": "array" }, "requirements_hash": { "title": "Requirements Hash", "type": "string" }, "runtime": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Runtime" }, "skills": { "items": { "$ref": "#/components/schemas/PluginAccessSkillRef" }, "title": "Skills", "type": "array" }, "workshop_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Workshop Id" }, "workshops": { "items": { "$ref": "#/components/schemas/PluginAccessWorkshop" }, "title": "Workshops", "type": "array" } }, "required": [ "skills", "requirements_hash", "workshops", "requirements" ], "title": "DeployPluginAccessPlan", "type": "object" }, "DeployPluginAccessPlanRequest": { "additionalProperties": false, "description": "A deploy's plan: an existing employee, or — before Define creates it —\nthe skills picked and the harness they will run on.", "properties": { "agent_account_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Agent Account Id" }, "harness": { "anyOf": [ { "maxLength": 32, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Harness" }, "skill_gives": { "items": { "$ref": "#/components/schemas/SkillGive" }, "maxItems": 64, "title": "Skill Gives", "type": "array" } }, "title": "DeployPluginAccessPlanRequest", "type": "object" }, "DeprecationCanaryResponse": { "description": "Response for the deprecation canary endpoint.", "properties": { "message": { "title": "Message", "type": "string" } }, "required": [ "message" ], "title": "DeprecationCanaryResponse", "type": "object" }, "DeprecationCatalog": { "description": "Full catalog of deprecated endpoints.", "properties": { "deprecations": { "items": { "$ref": "#/components/schemas/DeprecationEntry" }, "title": "Deprecations", "type": "array" } }, "required": [ "deprecations" ], "title": "DeprecationCatalog", "type": "object" }, "DeprecationEntry": { "description": "One deprecated endpoint in the catalog.", "properties": { "announced_at": { "description": "First time we registered this deprecation.", "format": "date-time", "title": "Announced At", "type": "string" }, "method": { "description": "HTTP method (GET/POST/…).", "title": "Method", "type": "string" }, "operation_id": { "description": "Stable dotted-name identifier.", "title": "Operation Id", "type": "string" }, "path": { "description": "Deprecated endpoint path.", "title": "Path", "type": "string" }, "reason": { "description": "Human-readable explanation.", "title": "Reason", "type": "string" }, "successor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Replacement endpoint path.", "title": "Successor" }, "successor_version": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Replacement version identifier.", "title": "Successor Version" }, "sunset": { "description": "When the endpoint will be removed (canonical UTC).", "format": "date-time", "title": "Sunset", "type": "string" } }, "required": [ "operation_id", "path", "method", "sunset", "reason", "announced_at" ], "title": "DeprecationEntry", "type": "object" }, "DescribeAuthorizeResponse": { "properties": { "client": { "$ref": "#/components/schemas/AuthorizeClientInfo" }, "redirect_uri": { "title": "Redirect Uri", "type": "string" }, "resource": { "title": "Resource", "type": "string" }, "scopes": { "items": { "$ref": "#/components/schemas/AuthorizeScopeDescription" }, "title": "Scopes", "type": "array" }, "state": { "title": "State", "type": "string" }, "user": { "$ref": "#/components/schemas/AuthorizeUserInfo" } }, "required": [ "client", "user", "scopes", "resource", "redirect_uri", "state" ], "title": "DescribeAuthorizeResponse", "type": "object" }, "DesignPayload": { "additionalProperties": false, "description": "The D11 design anatomy. Unknown top-level keys are rejected.", "properties": { "backgrounds": { "additionalProperties": true, "title": "Backgrounds", "type": "object" }, "cellStyles": { "additionalProperties": true, "title": "Cellstyles", "type": "object" }, "furniture": { "additionalProperties": true, "title": "Furniture", "type": "object" }, "layouts": { "items": { "additionalProperties": true, "type": "object" }, "title": "Layouts", "type": "array" }, "palette": { "additionalProperties": { "type": "string" }, "title": "Palette", "type": "object" }, "spacing": { "additionalProperties": true, "title": "Spacing", "type": "object" }, "typeScale": { "additionalProperties": true, "title": "Typescale", "type": "object" } }, "required": [ "palette", "typeScale", "backgrounds", "furniture", "spacing", "cellStyles", "layouts" ], "title": "DesignPayload", "type": "object" }, "DesktopVersionPolicy": { "description": "The backend-driven desktop version floor (TIDY-13461).\n\nServed on the device-health response AND on the unauthenticated\n``GET /api/v1/desktop/version-policy`` so the gate works even when the\nauthenticated API contract itself broke. ``update_required`` (below the\nfloor) is a HARD gate — the app suspends backend traffic after a grace\nwindow; ``update_available`` (below latest, above floor) is a non-blocking\nnudge. Both are False in the inert default (no version configured).", "properties": { "current_version": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "The build version the decision was computed against, echoed back", "title": "Current Version" }, "latest_version": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "The newest published build; below it → update_available", "title": "Latest Version" }, "message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Optional operator message shown in the update UX", "title": "Message" }, "min_supported_version": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "The floor: builds below this are update_required", "title": "Min Supported Version" }, "update_available": { "default": false, "description": "True when below latest but at/above the floor (soft nudge)", "title": "Update Available", "type": "boolean" }, "update_required": { "default": false, "description": "True when the build is below the floor (hard gate)", "title": "Update Required", "type": "boolean" } }, "title": "DesktopVersionPolicy", "type": "object" }, "DetectedDate": { "description": "A detected date/time from email content.", "properties": { "confidence": { "default": 1.0, "description": "Detection confidence 0-1", "title": "Confidence", "type": "number" }, "end": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "End datetime if range", "title": "End" }, "grain": { "description": "Precision: minute, hour, day, week, month", "title": "Grain", "type": "string" }, "start": { "description": "Parsed start datetime (UTC)", "format": "date-time", "title": "Start", "type": "string" }, "text": { "description": "Original text that was matched", "title": "Text", "type": "string" } }, "required": [ "text", "start", "grain" ], "title": "DetectedDate", "type": "object" }, "DetectedMeetingLink": { "description": "A detected meeting link.", "properties": { "meeting_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Meeting Id" }, "platform": { "description": "zoom, meet, teams, webex, generic", "title": "Platform", "type": "string" }, "url": { "title": "Url", "type": "string" } }, "required": [ "url", "platform" ], "title": "DetectedMeetingLink", "type": "object" }, "DevRunCreateRequest": { "properties": { "activity_id": { "description": "Bare activity uuid of the task being dispatched.", "title": "Activity Id", "type": "string" }, "attempt": { "default": 1, "description": "Retry attempt number (bounded).", "maximum": 5.0, "minimum": 1.0, "title": "Attempt", "type": "integer" }, "cwd": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The working directory the worker was spawned with.", "title": "Cwd" }, "expected_dev_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The retired dev-work word the task must reach for success (default ready_review: in_progress with the review tag, or done).", "title": "Expected Dev Status" }, "prompt_template": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The dispatch prompt template the policy selected.", "title": "Prompt Template" }, "repo": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The mapped repo the worker runs in.", "title": "Repo" }, "run_id": { "description": "Correlation token threaded to the worker + echoed in its evidence comment.", "minLength": 1, "title": "Run Id", "type": "string" }, "wedge_window_s": { "anyOf": [ { "maximum": 21600.0, "minimum": 60.0, "type": "integer" }, { "type": "null" } ], "description": "No-progress horizon before the wedge sweep flags the run.", "title": "Wedge Window S" }, "worker_cli": { "description": "The armed coding CLI dispatched (e.g. claude, codex, gemini, opencode).", "minLength": 1, "title": "Worker Cli", "type": "string" } }, "required": [ "run_id", "activity_id", "worker_cli" ], "title": "DevRunCreateRequest", "type": "object" }, "DevRunEventRequest": { "properties": { "detail": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "Structured event payload.", "title": "Detail" }, "event": { "description": "Lifecycle event name (running, awaiting_input, etc.) or a progress observation.", "minLength": 1, "title": "Event", "type": "string" } }, "required": [ "event" ], "title": "DevRunEventRequest", "type": "object" }, "DevRunListResponse": { "properties": { "runs": { "items": { "$ref": "#/components/schemas/DevRunResponse" }, "title": "Runs", "type": "array" } }, "required": [ "runs" ], "title": "DevRunListResponse", "type": "object" }, "DevRunOpenPrompt": { "properties": { "dm_room_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Dm Room Id" }, "kind": { "title": "Kind", "type": "string" }, "prompt_text": { "title": "Prompt Text", "type": "string" } }, "required": [ "kind", "prompt_text" ], "title": "DevRunOpenPrompt", "type": "object" }, "DevRunResponse": { "properties": { "activity_id": { "title": "Activity Id", "type": "string" }, "attempt": { "title": "Attempt", "type": "integer" }, "board_dev_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "The task's status now, '+review' while it carries the review tag.", "title": "Board Dev Status" }, "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "disposition": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Disposition" }, "evidence_comment_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Evidence Comment Id" }, "expected_dev_status": { "title": "Expected Dev Status", "type": "string" }, "id": { "title": "Id", "type": "string" }, "observed_dev_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "The task's status at verification, '+review' while it carries the review tag.", "title": "Observed Dev Status" }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Reason" }, "run_id": { "title": "Run Id", "type": "string" }, "status": { "title": "Status", "type": "string" }, "updated_at": { "format": "date-time", "title": "Updated At", "type": "string" }, "verified": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "title": "Verified" }, "worker_cli": { "title": "Worker Cli", "type": "string" } }, "required": [ "id", "run_id", "activity_id", "worker_cli", "status", "attempt", "expected_dev_status", "created_at", "updated_at" ], "title": "DevRunResponse", "type": "object" }, "DevRunSessionEvent": { "properties": { "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "detail": { "additionalProperties": true, "title": "Detail", "type": "object" }, "event": { "title": "Event", "type": "string" } }, "required": [ "event", "detail", "created_at" ], "title": "DevRunSessionEvent", "type": "object" }, "DevRunSessionEventListResponse": { "properties": { "events": { "items": { "$ref": "#/components/schemas/DevRunSessionEvent" }, "title": "Events", "type": "array" }, "run": { "anyOf": [ { "$ref": "#/components/schemas/DevRunSessionResponse" }, { "type": "null" } ], "default": null } }, "required": [ "events" ], "title": "DevRunSessionEventListResponse", "type": "object" }, "DevRunSessionListResponse": { "properties": { "runs": { "items": { "$ref": "#/components/schemas/DevRunSessionResponse" }, "title": "Runs", "type": "array" } }, "required": [ "runs" ], "title": "DevRunSessionListResponse", "type": "object" }, "DevRunSessionResponse": { "properties": { "activity_id": { "title": "Activity Id", "type": "string" }, "attempt": { "title": "Attempt", "type": "integer" }, "completed_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Completed At" }, "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "disposition": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Disposition" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Error" }, "events": { "items": { "$ref": "#/components/schemas/DevRunSessionEvent" }, "title": "Events", "type": "array" }, "open_prompt": { "anyOf": [ { "$ref": "#/components/schemas/DevRunOpenPrompt" }, { "type": "null" } ], "default": null }, "run_id": { "title": "Run Id", "type": "string" }, "status": { "title": "Status", "type": "string" }, "updated_at": { "format": "date-time", "title": "Updated At", "type": "string" }, "worker_cli": { "title": "Worker Cli", "type": "string" } }, "required": [ "run_id", "activity_id", "worker_cli", "status", "attempt", "created_at", "updated_at" ], "title": "DevRunSessionResponse", "type": "object" }, "DevRunUpdateRequest": { "properties": { "disposition": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Terminal disposition (verified, rejected, escalated, retried).", "title": "Disposition" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Failure detail when marking failed.", "title": "Error" }, "evidence_comment_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The evidence comment id the run resolved against.", "title": "Evidence Comment Id" }, "status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Explicit status to mark (running, awaiting_input, verifying, succeeded, failed, wedged, cancelled).", "title": "Status" }, "verify": { "default": false, "description": "When true, verify from board ground truth (the task's status and review tag + evidence comment) and mark succeeded only if proven.", "title": "Verify", "type": "boolean" } }, "title": "DevRunUpdateRequest", "type": "object" }, "DevSignupRequest": { "properties": { "email": { "format": "email", "title": "Email", "type": "string" }, "marketing_ok": { "default": false, "title": "Marketing Ok", "type": "boolean" }, "password": { "anyOf": [ { "maxLength": 128, "minLength": 12, "type": "string" }, { "type": "null" } ], "description": "Optional: a password the developer can later use to sign into the Tidy web app with the same account. If omitted, a random password is generated server-side (recoverable via forgot-password).", "title": "Password" } }, "required": [ "email" ], "title": "DevSignupRequest", "type": "object" }, "DevSignupResponse": { "properties": { "explorer_url": { "title": "Explorer Url", "type": "string" }, "sandbox_pat": { "title": "Sandbox Pat", "type": "string" }, "tenant_id": { "title": "Tenant Id", "type": "string" }, "webhook_signing_secret": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Webhook Signing Secret" } }, "required": [ "tenant_id", "sandbox_pat", "explorer_url" ], "title": "DevSignupResponse", "type": "object" }, "DevStatusResponse": { "properties": { "changed": { "title": "Changed", "type": "boolean" }, "dev_status": { "title": "Dev Status", "type": "string" }, "id": { "title": "Id", "type": "string" }, "updated_at": { "format": "date-time", "title": "Updated At", "type": "string" } }, "required": [ "id", "dev_status", "changed", "updated_at" ], "title": "DevStatusResponse", "type": "object" }, "DevStatusUpdateRequest": { "properties": { "dev_status": { "description": "A retired dev-work state, written as the task's own status: ready -> todo, in_progress -> in_progress, ready_review -> in_progress with the review tag, done -> done, blocked / failed / awaiting_input -> blocked. A workspace without one of those takes its own state of the same kind (ready -> its last open state, in_progress -> its first active one, done -> its first done one; its own ready_review state if it has one).", "title": "Dev Status", "type": "string" } }, "required": [ "dev_status" ], "title": "DevStatusUpdateRequest", "type": "object" }, "DeviceAuthorizationResponse": { "description": "RFC 8628 §3.2 successful response.", "properties": { "device_code": { "title": "Device Code", "type": "string" }, "expires_in": { "title": "Expires In", "type": "integer" }, "interval": { "title": "Interval", "type": "integer" }, "user_code": { "title": "User Code", "type": "string" }, "verification_uri": { "title": "Verification Uri", "type": "string" }, "verification_uri_complete": { "title": "Verification Uri Complete", "type": "string" } }, "required": [ "device_code", "user_code", "verification_uri", "verification_uri_complete", "expires_in", "interval" ], "title": "DeviceAuthorizationResponse", "type": "object" }, "DeviceBrowserEgressRequest": { "description": "TIDY-18934 F13: whether this computer may carry its owner's browsing accounts' pages.", "properties": { "enabled": { "description": "True to let the owner's browsing accounts browse through this computer", "title": "Enabled", "type": "boolean" } }, "required": [ "enabled" ], "title": "DeviceBrowserEgressRequest", "type": "object" }, "DeviceConsentRequest": { "properties": { "device_code_id": { "title": "Device Code Id", "type": "string" } }, "required": [ "device_code_id" ], "title": "DeviceConsentRequest", "type": "object" }, "DeviceContact": { "description": "Contact data from mobile device address book for sync operations.", "properties": { "device_contact_id": { "description": "Unique ID from device address book", "examples": [ "content://12345" ], "title": "Device Contact Id", "type": "string" }, "display_name": { "description": "Full contact name as displayed on device", "examples": [ "Jane Smith" ], "title": "Display Name", "type": "string" }, "emails": { "default": [], "description": "List of email addresses", "examples": [ [ "jane@school.edu" ] ], "items": { "type": "string" }, "title": "Emails", "type": "array" }, "family_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Last name", "examples": [ "Smith" ], "title": "Family Name" }, "given_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "First name", "examples": [ "Jane" ], "title": "Given Name" }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Free-form notes from the device contact (the OS 'Note' field, vnd.android.cursor.item/note). Merged INTO the Tidy contact body non-destructively on sync (TIDY-17041). Outbound (Tidy->OS) note publishing stays off the privacy whitelist.", "examples": [ "Prefers calls after 6pm; kids' soccer on Saturdays." ], "title": "Notes" }, "organization": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Company or organization", "examples": [ "Lincoln Elementary" ], "title": "Organization" }, "phones": { "default": [], "description": "List of phone numbers", "examples": [ [ "+15551234567" ] ], "items": { "type": "string" }, "title": "Phones", "type": "array" }, "photo_data": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Base64-encoded contact photo from device", "title": "Photo Data" } }, "required": [ "device_contact_id", "display_name" ], "title": "DeviceContact", "type": "object" }, "DeviceDescribeClientInfo": { "properties": { "client_id": { "title": "Client Id", "type": "string" }, "client_type": { "title": "Client Type", "type": "string" }, "first_party": { "default": false, "title": "First Party", "type": "boolean" }, "homepage_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Homepage Url" }, "logo_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Logo Url" }, "name": { "title": "Name", "type": "string" }, "review_status": { "title": "Review Status", "type": "string" } }, "required": [ "client_id", "name", "client_type", "review_status" ], "title": "DeviceDescribeClientInfo", "type": "object" }, "DeviceDescribeResponse": { "properties": { "client": { "$ref": "#/components/schemas/DeviceDescribeClientInfo" }, "device_code_id": { "title": "Device Code Id", "type": "string" }, "expires_at": { "title": "Expires At", "type": "string" }, "requester": { "$ref": "#/components/schemas/DeviceRequesterInfo" }, "resource": { "title": "Resource", "type": "string" }, "scopes": { "items": { "$ref": "#/components/schemas/AuthorizeScopeDescription" }, "title": "Scopes", "type": "array" }, "user": { "$ref": "#/components/schemas/DeviceDescribeUserInfo" } }, "required": [ "device_code_id", "client", "scopes", "resource", "expires_at", "user", "requester" ], "title": "DeviceDescribeResponse", "type": "object" }, "DeviceDescribeUserInfo": { "properties": { "account_id": { "title": "Account Id", "type": "string" }, "display_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Display Name" }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Email" }, "tenant_id": { "title": "Tenant Id", "type": "string" }, "tenant_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Tenant Name" } }, "required": [ "account_id", "tenant_id" ], "title": "DeviceDescribeUserInfo", "type": "object" }, "DeviceErrorResponse": { "description": "Error envelope returned by the credential-auth endpoints (register/token).\n\nThese paths return a raw `{error, error_description}` body on a\nDeviceAuthError instead of the success model, so it is declared here and\nattached via `responses=` so generated SDKs know the shape (F10).", "properties": { "error": { "description": "Stable error code (e.g. invalid_grant)", "title": "Error", "type": "string" }, "error_description": { "description": "Human-readable failure reason", "title": "Error Description", "type": "string" } }, "required": [ "error", "error_description" ], "title": "DeviceErrorResponse", "type": "object" }, "DeviceHealthReportRequest": { "description": "A desktop's slow health beat (TIDY-13274 / S10.3, D-8, NFR-5).\n\nReported by the desktop main process against its OWN device row on a slow\ncadence, authenticated by the user session bearer. All fields are the\ndevice's current main-process truth; capability_tier is a HINT kept fresh so\na rescan-changed tier propagates without a re-enroll (never authorization).", "properties": { "app_version": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The running desktop app version (app.getVersion())", "title": "App Version" }, "capability_tier": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Advertised tier HINT, kept fresh (quality|standard|lite|cpu_minimal|none)", "title": "Capability Tier" }, "pending_update_version": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The version that applies on restart when update_pending, else null", "title": "Pending Update Version" }, "serving_state": { "description": "Current offload serving state (off|paused_battery|paused_thermal|idle|serving)", "enum": [ "off", "paused_battery", "paused_thermal", "idle", "serving" ], "title": "Serving State", "type": "string" }, "update_pending": { "default": false, "description": "True when an update is DOWNLOADED and applies on the next restart", "title": "Update Pending", "type": "boolean" } }, "required": [ "serving_state" ], "title": "DeviceHealthReportRequest", "type": "object" }, "DeviceHeartbeatRequest": { "description": "Worker heartbeat: re-assert liveness and refresh last_seen (throttled).", "properties": { "access_token": { "description": "Device access token (tidy_devat_...) to validate", "title": "Access Token", "type": "string" } }, "required": [ "access_token" ], "title": "DeviceHeartbeatRequest", "type": "object" }, "DeviceHeartbeatResponse": { "description": "Heartbeat outcome. `valid=false` means the device is expired/revoked and\nthe gateway should drop its worker socket within the heartbeat window.", "properties": { "device_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Device Id" }, "last_seen_touched": { "default": false, "title": "Last Seen Touched", "type": "boolean" }, "offload_consent": { "default": false, "title": "Offload Consent", "type": "boolean" }, "tenant_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Tenant Id" }, "valid": { "title": "Valid", "type": "boolean" } }, "required": [ "valid" ], "title": "DeviceHeartbeatResponse", "type": "object" }, "DeviceListResponse": { "properties": { "devices": { "items": { "$ref": "#/components/schemas/DeviceResponse" }, "title": "Devices", "type": "array" } }, "required": [ "devices" ], "title": "DeviceListResponse", "type": "object" }, "DeviceOffloadConsentRequest": { "properties": { "consent": { "description": "True to grant per-device offload consent, False to revoke", "title": "Consent", "type": "boolean" } }, "required": [ "consent" ], "title": "DeviceOffloadConsentRequest", "type": "object" }, "DeviceRegisterRequest": { "description": "Enroll a device. `signature` proves control of `device_pubkey`.", "properties": { "capabilities": { "additionalProperties": true, "description": "Advertised capability HINTS (RAM, GPU, models, …)", "title": "Capabilities", "type": "object" }, "capability_tier": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Advertised tier HINT (quality|standard|lite|cpu_minimal|none)", "title": "Capability Tier" }, "device_pubkey": { "description": "Ed25519 public key, base64 raw 32 bytes", "title": "Device Pubkey", "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Human-friendly device name", "title": "Name" }, "nonce": { "description": "Client nonce included in the signed message", "title": "Nonce", "type": "string" }, "platform": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "macos | windows | linux", "title": "Platform" }, "signature": { "description": "Ed25519 signature over the register challenge", "title": "Signature", "type": "string" }, "signed_at": { "description": "ISO 8601 UTC timestamp included in the signed message", "title": "Signed At", "type": "string" } }, "required": [ "device_pubkey", "signature", "signed_at", "nonce" ], "title": "DeviceRegisterRequest", "type": "object" }, "DeviceRegisterResponse": { "properties": { "credential": { "description": "One-time device credential plaintext (store securely)", "title": "Credential", "type": "string" }, "credential_expires_at": { "format": "date-time", "title": "Credential Expires At", "type": "string" }, "device": { "$ref": "#/components/schemas/DeviceResponse" } }, "required": [ "device", "credential", "credential_expires_at" ], "title": "DeviceRegisterResponse", "type": "object" }, "DeviceRequesterInfo": { "description": "Who asked for the code, so a member can spot one they did not start.", "properties": { "device_label": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Device Label" }, "form_factor": { "anyOf": [ { "enum": [ "phone", "watch" ], "type": "string" }, { "type": "null" } ], "title": "Form Factor" }, "ip_masked": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Ip Masked" }, "network_match": { "enum": [ "same", "different", "unknown" ], "title": "Network Match", "type": "string" }, "requested_at": { "title": "Requested At", "type": "string" }, "verified_app": { "default": false, "title": "Verified App", "type": "boolean" } }, "required": [ "network_match", "requested_at" ], "title": "DeviceRequesterInfo", "type": "object" }, "DeviceResponse": { "properties": { "account_id": { "title": "Account Id", "type": "string" }, "app_version": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "App Version" }, "browser_egress": { "default": false, "title": "Browser Egress", "type": "boolean" }, "browser_egress_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Browser Egress At" }, "capabilities": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "title": "Capabilities" }, "capabilities_corrupt": { "default": false, "description": "True when the stored capabilities value was unparseable and is surfaced degraded", "title": "Capabilities Corrupt", "type": "boolean" }, "capability_tier": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Capability Tier" }, "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "id": { "title": "Id", "type": "string" }, "last_seen_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Last Seen At" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Name" }, "offload_consent": { "title": "Offload Consent", "type": "boolean" }, "offload_consent_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Offload Consent At" }, "pending_update_version": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Pending Update Version" }, "platform": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Platform" }, "serving_state": { "anyOf": [ { "enum": [ "off", "paused_battery", "paused_thermal", "idle", "serving" ], "type": "string" }, { "type": "null" } ], "default": null, "title": "Serving State" }, "tenant_id": { "title": "Tenant Id", "type": "string" }, "update_pending": { "default": false, "title": "Update Pending", "type": "boolean" }, "updated_at": { "format": "date-time", "title": "Updated At", "type": "string" }, "version_policy": { "anyOf": [ { "$ref": "#/components/schemas/DesktopVersionPolicy" }, { "type": "null" } ], "default": null } }, "required": [ "id", "tenant_id", "account_id", "offload_consent", "created_at", "updated_at" ], "title": "DeviceResponse", "type": "object" }, "DeviceRevokeResponse": { "properties": { "id": { "title": "Id", "type": "string" }, "revoked": { "title": "Revoked", "type": "boolean" } }, "required": [ "id", "revoked" ], "title": "DeviceRevokeResponse", "type": "object" }, "DeviceStatusResponse": { "description": "Whether the CURRENT device must wipe its local data.\n\nTrue when this token was issued before the account's forced-wipe epoch —\ni.e. it belongs to a session revoked by a later revoke-devices call.", "properties": { "wipe_required": { "title": "Wipe Required", "type": "boolean" } }, "required": [ "wipe_required" ], "title": "DeviceStatusResponse", "type": "object" }, "DeviceTokenRequest": { "description": "Exchange a device credential + proof-of-possession for an access token.", "properties": { "credential": { "description": "Device credential plaintext from registration", "title": "Credential", "type": "string" }, "nonce": { "description": "Client nonce included in the signed message", "title": "Nonce", "type": "string" }, "signature": { "description": "Ed25519 signature over the token challenge", "title": "Signature", "type": "string" }, "signed_at": { "description": "ISO 8601 UTC timestamp included in the signed message", "title": "Signed At", "type": "string" } }, "required": [ "credential", "signature", "signed_at", "nonce" ], "title": "DeviceTokenRequest", "type": "object" }, "DeviceTokenResponse": { "properties": { "access_token": { "title": "Access Token", "type": "string" }, "device_id": { "title": "Device Id", "type": "string" }, "expires_at": { "format": "date-time", "title": "Expires At", "type": "string" }, "token_type": { "default": "Bearer", "title": "Token Type", "type": "string" } }, "required": [ "access_token", "expires_at", "device_id" ], "title": "DeviceTokenResponse", "type": "object" }, "DeviceVerifyRequest": { "description": "Verify a device access token presented by a connecting worker.", "properties": { "access_token": { "description": "Device access token (tidy_devat_...) to validate", "title": "Access Token", "type": "string" } }, "required": [ "access_token" ], "title": "DeviceVerifyRequest", "type": "object" }, "DeviceVerifyResponse": { "description": "Resolved device identity for a valid token, else valid=false.\n\n`offload_consent` is the gate the gateway enforces: a valid token whose\ndevice has consent OFF must NOT be admitted as an offload worker. Capability\ntier is a HINT for tier gating (S9.5), never authorization on its own.", "properties": { "account_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Account Id" }, "capability_tier": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Capability Tier" }, "device_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Device Id" }, "offload_consent": { "default": false, "title": "Offload Consent", "type": "boolean" }, "tenant_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Tenant Id" }, "valid": { "title": "Valid", "type": "boolean" } }, "required": [ "valid" ], "title": "DeviceVerifyResponse", "type": "object" }, "DigestHistoryItem": { "properties": { "generated_at": { "title": "Generated At", "type": "string" }, "highlights": { "items": { "type": "string" }, "title": "Highlights", "type": "array" }, "narrative_text": { "title": "Narrative Text", "type": "string" }, "period_end": { "title": "Period End", "type": "string" }, "period_start": { "title": "Period Start", "type": "string" }, "record_id": { "title": "Record Id", "type": "string" } }, "required": [ "record_id", "period_start", "period_end", "narrative_text", "highlights", "generated_at" ], "title": "DigestHistoryItem", "type": "object" }, "DimensionPosture": { "properties": { "buckets": { "items": { "$ref": "#/components/schemas/PostureBucket" }, "title": "Buckets", "type": "array" }, "dimension": { "title": "Dimension", "type": "string" }, "hot": { "items": { "$ref": "#/components/schemas/HotTenant" }, "title": "Hot", "type": "array" }, "label": { "title": "Label", "type": "string" } }, "required": [ "dimension", "label", "buckets", "hot" ], "title": "DimensionPosture", "type": "object" }, "DirectoryListResponse": { "properties": { "limit": { "title": "Limit", "type": "integer" }, "offset": { "title": "Offset", "type": "integer" }, "rooms": { "items": { "$ref": "#/components/schemas/DirectoryRoomResponse" }, "title": "Rooms", "type": "array" }, "total": { "title": "Total", "type": "integer" } }, "required": [ "rooms", "total", "limit", "offset" ], "title": "DirectoryListResponse", "type": "object" }, "DirectoryRoomResponse": { "properties": { "archived_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Archived At" }, "caller_is_member": { "default": false, "title": "Caller Is Member", "type": "boolean" }, "caller_join_request_status": { "default": "none", "enum": [ "none", "pending", "approved", "denied", "cancelled" ], "title": "Caller Join Request Status", "type": "string" }, "created_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Created At" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Description" }, "id": { "title": "Id", "type": "string" }, "last_activity_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Last Activity At" }, "member_count": { "default": 0, "title": "Member Count", "type": "integer" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Name" }, "room_id": { "title": "Room Id", "type": "string" }, "topic": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Topic" }, "visibility": { "title": "Visibility", "type": "string" } }, "required": [ "id", "room_id", "visibility" ], "title": "DirectoryRoomResponse", "type": "object" }, "DirectoryUser": { "properties": { "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Email" }, "first_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "First Name" }, "id": { "format": "uuid", "title": "Id", "type": "string" }, "is_admin": { "default": false, "title": "Is Admin", "type": "boolean" }, "last_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Last Name" }, "suspended_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Suspended At" }, "tenant_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Tenant Id" }, "tenant_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Tenant Name" }, "tenant_tier": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Tenant Tier" } }, "required": [ "id" ], "title": "DirectoryUser", "type": "object" }, "DisarmHarnessResponse": { "properties": { "job_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Job Id" }, "pending_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Pending Reason" }, "runtime": { "title": "Runtime", "type": "string" }, "status": { "title": "Status", "type": "string" } }, "required": [ "status", "runtime" ], "title": "DisarmHarnessResponse", "type": "object" }, "DiscoveredEpisode": { "properties": { "artwork_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Artwork Url" }, "audio_length_bytes": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Audio Length Bytes" }, "audio_url": { "title": "Audio Url", "type": "string" }, "author": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Author" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "duration_seconds": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Duration Seconds" }, "explicit": { "default": false, "title": "Explicit", "type": "boolean" }, "guid": { "title": "Guid", "type": "string" }, "published_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Published At" }, "rss_feed_url": { "title": "Rss Feed Url", "type": "string" }, "show_artwork_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Show Artwork Url" }, "show_author": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Show Author" }, "show_language": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Show Language" }, "show_title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Show Title" }, "title": { "title": "Title", "type": "string" }, "webpage_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Webpage Url" } }, "required": [ "rss_feed_url", "guid", "title", "audio_url" ], "title": "DiscoveredEpisode", "type": "object" }, "DiscoveredEpisodeResult": { "properties": { "created": { "title": "Created", "type": "boolean" }, "episode_id": { "title": "Episode Id", "type": "string" }, "show_id": { "title": "Show Id", "type": "string" } }, "required": [ "show_id", "episode_id", "created" ], "title": "DiscoveredEpisodeResult", "type": "object" }, "DismissProposedItemRequest": { "description": "Optional dismiss options (TIDY-17754).\n\n``use_existing_id``: the organization the user selected as the existing\nidentity for this proposed organization (\"Use this one\"). When present,\nthe dismiss is executed as an organization MERGE (loser = the proposed\nitem, survivor = the chosen organization) so the item's already-written\nlinked references re-point to the survivor instead of dangling on a row\nthat no sync lane delivers (TIDY-17753). Absent = plain dismiss\n(unchanged behaviour).", "properties": { "use_existing_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "description": "Organization dismiss only: id of the existing organization the user chose. The proposed organization is merged into it (transactional linked-reference re-pointing) instead of being barely rejected.", "title": "Use Existing Id" } }, "title": "DismissProposedItemRequest", "type": "object" }, "DismissRequest": { "description": "Request for POST /api/v1/contacts/duplicates/dismiss.\n\nDismisses a duplicate pair as \"not duplicates\" so it won't\nbe flagged again in future scans.\n\nAttributes:\n contact_a_id: First contact ID\n contact_b_id: Second contact ID\n reason: Optional reason for dismissal", "properties": { "contact_a_id": { "description": "First contact ID", "title": "Contact A Id", "type": "string" }, "contact_b_id": { "description": "Second contact ID", "title": "Contact B Id", "type": "string" }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional reason for dismissal", "examples": [ "Same name but different people (father and son)" ], "title": "Reason" } }, "required": [ "contact_a_id", "contact_b_id" ], "title": "DismissRequest", "type": "object" }, "DismissSuggestionRequest": { "description": "Request to dismiss a project suggestion.\n\nUsed in: POST /api/v1/projects/suggestions/{id}/dismiss\n\nRelated: KCC-3473, KCC-A-108", "properties": { "never_suggest_again": { "default": false, "description": "If true, permanently block similar suggestions. If false, 30-day cooldown applies.", "title": "Never Suggest Again", "type": "boolean" } }, "title": "DismissSuggestionRequest", "type": "object" }, "DismissedDuplicatePair": { "description": "A dismissed duplicate pair.\n\nReturned by GET /api/v1/contacts/duplicates/dismissed.\n\nAttributes:\n id: Dismissal record UUID\n contact_a: First contact summary\n contact_b: Second contact summary\n dismissed_at: When the pair was dismissed\n dismissed_by: User who dismissed the pair\n reason: Reason for dismissal (optional)\n\nRelated: apps/mobile/src/lib/components/contacts/DismissedList.svelte", "properties": { "contact_a": { "$ref": "#/components/schemas/ContactSummary", "description": "First contact" }, "contact_b": { "$ref": "#/components/schemas/ContactSummary", "description": "Second contact" }, "dismissed_at": { "description": "When pair was dismissed", "format": "date-time", "title": "Dismissed At", "type": "string" }, "dismissed_by": { "description": "User ID who dismissed", "title": "Dismissed By", "type": "string" }, "id": { "description": "Dismissal record UUID", "title": "Id", "type": "string" }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Dismissal reason", "title": "Reason" } }, "required": [ "id", "contact_a", "contact_b", "dismissed_at", "dismissed_by" ], "title": "DismissedDuplicatePair", "type": "object" }, "DismissedListResponse": { "description": "Response for GET /api/v1/contacts/duplicates/dismissed.\n\nAttributes:\n pairs: List of dismissed pairs\n total_count: Total number of dismissed pairs", "properties": { "pairs": { "default": [], "description": "List of dismissed pairs", "items": { "$ref": "#/components/schemas/DismissedDuplicatePair" }, "title": "Pairs", "type": "array" }, "total_count": { "description": "Total dismissed pairs", "title": "Total Count", "type": "integer" } }, "required": [ "total_count" ], "title": "DismissedListResponse", "type": "object" }, "DismissedOrganizationPair": { "description": "A pair a member marked as 'not duplicates'.", "properties": { "dismissed_at": { "format": "date-time", "title": "Dismissed At", "type": "string" }, "dismissed_by": { "title": "Dismissed By", "type": "string" }, "id": { "title": "Id", "type": "string" }, "organization_a": { "$ref": "#/components/schemas/api_service__models__organization_merge__OrganizationSummary" }, "organization_b": { "$ref": "#/components/schemas/api_service__models__organization_merge__OrganizationSummary" }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Reason" } }, "required": [ "id", "organization_a", "organization_b", "dismissed_at", "dismissed_by" ], "title": "DismissedOrganizationPair", "type": "object" }, "DisplaySubjectRequest": { "properties": { "display_subject": { "maxLength": 500, "minLength": 1, "title": "Display Subject", "type": "string" } }, "required": [ "display_subject" ], "title": "DisplaySubjectRequest", "type": "object" }, "DisplaySubjectResponse": { "properties": { "display_subject": { "title": "Display Subject", "type": "string" }, "id": { "format": "uuid", "title": "Id", "type": "string" }, "original_subject": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Original Subject" } }, "required": [ "id", "display_subject", "original_subject" ], "title": "DisplaySubjectResponse", "type": "object" }, "DmEncryptionEnableRequest": { "properties": { "ack_disabled_features": { "items": { "type": "string" }, "title": "Ack Disabled Features", "type": "array" }, "confirmation_phrase": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Confirmation Phrase" } }, "title": "DmEncryptionEnableRequest", "type": "object" }, "DmEncryptionResponse": { "properties": { "ack_disabled_features": { "items": { "type": "string" }, "title": "Ack Disabled Features", "type": "array" }, "enabled": { "title": "Enabled", "type": "boolean" }, "enabled_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Enabled At" }, "enabled_by_account_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Enabled By Account Id" }, "room_id": { "title": "Room Id", "type": "string" } }, "required": [ "room_id", "enabled", "ack_disabled_features" ], "title": "DmEncryptionResponse", "type": "object" }, "DmParticipantResponse": { "properties": { "account_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Account Id" }, "display_name": { "title": "Display Name", "type": "string" }, "is_bot": { "default": false, "title": "Is Bot", "type": "boolean" }, "is_guest": { "default": false, "title": "Is Guest", "type": "boolean" }, "matrix_id": { "title": "Matrix Id", "type": "string" } }, "required": [ "matrix_id", "display_name" ], "title": "DmParticipantResponse", "type": "object" }, "DocumentConflictResponse": { "properties": { "detail": { "anyOf": [ { "$ref": "#/components/schemas/LivenessConflict" }, { "$ref": "#/components/schemas/OperationConflict" } ], "title": "Detail" } }, "required": [ "detail" ], "title": "DocumentConflictResponse", "type": "object" }, "DocumentContentResponse": { "description": "Response with full document content.", "properties": { "chunk_count": { "title": "Chunk Count", "type": "integer" }, "document_id": { "title": "Document Id", "type": "string" }, "extracted_content": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Extracted Content" }, "filename": { "title": "Filename", "type": "string" }, "module": { "title": "Module", "type": "string" }, "status": { "title": "Status", "type": "string" } }, "required": [ "document_id", "filename", "module", "status", "chunk_count" ], "title": "DocumentContentResponse", "type": "object" }, "DocumentEmbed": { "description": "One embed in a note or journal body, in document order.", "properties": { "block_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "The node's block id in the body.", "title": "Block Id" }, "facet_slug": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "The embedded record's facet (`database` for a saved view) — a record you can see.", "title": "Facet Slug" }, "id": { "description": "Typed id of the embedded item, e.g. `R-` for a view.", "title": "Id", "type": "string" }, "node": { "description": "The body node: `database` (a saved database view), `chartEmbed`, `dashboardEmbed`, `embeddedBlock` (a card of any item) or `activityEmbed`.", "title": "Node", "type": "string" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "The embedded record's title, when you can see it.", "title": "Title" } }, "required": [ "id", "node" ], "title": "DocumentEmbed", "type": "object" }, "DocumentListResponse": { "description": "Response for document list.", "properties": { "documents": { "items": { "$ref": "#/components/schemas/DocumentSummary" }, "title": "Documents", "type": "array" }, "total": { "title": "Total", "type": "integer" } }, "required": [ "documents", "total" ], "title": "DocumentListResponse", "type": "object" }, "DocumentOperationStatus": { "description": "Whether one keyed markdown write landed in this document (TIDY-18493).", "properties": { "applied_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Applied At" }, "applied_by": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Applied By" }, "blocks_added": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Blocks Added" }, "operation_key": { "title": "Operation Key", "type": "string" }, "status": { "enum": [ "applied", "not_applied" ], "title": "Status", "type": "string" }, "version_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Version Id" } }, "required": [ "operation_key", "status" ], "title": "DocumentOperationStatus", "type": "object" }, "DocumentSummary": { "description": "Summary of a processed document.", "properties": { "chunk_count": { "title": "Chunk Count", "type": "integer" }, "created_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Created At" }, "filename": { "title": "Filename", "type": "string" }, "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Id" }, "module": { "title": "Module", "type": "string" }, "processed_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Processed At" }, "source_document": { "title": "Source Document", "type": "string" }, "status": { "default": "processed", "title": "Status", "type": "string" }, "tags": { "default": [], "items": { "type": "string" }, "title": "Tags", "type": "array" } }, "required": [ "source_document", "filename", "module", "chunk_count" ], "title": "DocumentSummary", "type": "object" }, "DogfoodVerdictRequest": { "properties": { "artifact": { "additionalProperties": true, "title": "Artifact", "type": "object" }, "artifact_schema_version": { "default": "native-email-dogfood-v1", "title": "Artifact Schema Version", "type": "string" }, "member_a_account_id": { "format": "uuid", "title": "Member A Account Id", "type": "string" }, "member_b_account_id": { "format": "uuid", "title": "Member B Account Id", "type": "string" }, "zero_access_incidents": { "title": "Zero Access Incidents", "type": "boolean" } }, "required": [ "member_a_account_id", "member_b_account_id", "artifact", "zero_access_incidents" ], "title": "DogfoodVerdictRequest", "type": "object" }, "DogfoodVerdictResponse": { "properties": { "id": { "format": "uuid", "title": "Id", "type": "string" } }, "required": [ "id" ], "title": "DogfoodVerdictResponse", "type": "object" }, "DomainCheckResponse": { "description": "Response for domain auto-join availability check.", "properties": { "auto_join_available": { "title": "Auto Join Available", "type": "boolean" }, "domain": { "title": "Domain", "type": "string" }, "is_public_provider": { "default": false, "title": "Is Public Provider", "type": "boolean" }, "tenant_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Tenant Id" }, "tenant_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Tenant Name" } }, "required": [ "domain", "auto_join_available" ], "title": "DomainCheckResponse", "type": "object" }, "DomainJoinResponse": { "description": "Response after successfully joining a tenant via domain auto-join.", "properties": { "message": { "title": "Message", "type": "string" }, "role": { "default": "Member", "title": "Role", "type": "string" }, "success": { "title": "Success", "type": "boolean" }, "tenant_id": { "title": "Tenant Id", "type": "string" }, "tenant_name": { "title": "Tenant Name", "type": "string" } }, "required": [ "success", "tenant_id", "tenant_name", "message" ], "title": "DomainJoinResponse", "type": "object" }, "DownloadUrlResponse": { "properties": { "url": { "description": "Download URL. Scoped files require bearer authentication on the returned storage-proxy path.", "title": "Url", "type": "string" } }, "required": [ "url" ], "title": "DownloadUrlResponse", "type": "object" }, "DraftAttachFromObjectRequest": { "description": "Attach a Tidy object to an email draft.\n\n``email`` / ``event`` serialize a frozen ``.eml`` / ``.ics`` snapshot, as\n``AttachFromObjectRequest`` does. ``attachment`` (a ``processed_attachments``\nid) and ``email_attachment`` (an email id plus ``filename`` and optional\n``part``) attach an EXISTING email attachment, and ``file`` (a My Files\n``files`` id) a stored file, by reference: the draft points at the bytes\nTidy already holds, so nothing is copied (TIDY-19473).", "properties": { "filename": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Attachment filename — required for `email_attachment`", "title": "Filename" }, "object_id": { "description": "Email or event id; the processed_attachments id for `attachment`; the email the part belongs to for `email_attachment`; the files id for `file`", "format": "uuid", "title": "Object Id", "type": "string" }, "object_type": { "description": "Kind of object to attach", "enum": [ "email", "event", "attachment", "email_attachment", "file" ], "title": "Object Type", "type": "string" }, "part": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Selects one of several same-name parts of an `email_attachment`: the locator's provider attachment_id or storage_path", "title": "Part" } }, "required": [ "object_type", "object_id" ], "title": "DraftAttachFromObjectRequest", "type": "object" }, "DraftAttachment": { "description": "Attachment metadata for email drafts.", "properties": { "content_hash": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "SHA-256 content hash for duplicate-document reuse", "title": "Content Hash" }, "content_type": { "description": "MIME type", "title": "Content Type", "type": "string" }, "filename": { "description": "Original filename", "title": "Filename", "type": "string" }, "id": { "description": "Attachment UUID", "title": "Id", "type": "string" }, "locator": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "Where the bytes of an attachment held BY REFERENCE live — the AttachmentLocator of the original email's part. Nothing is copied; send fetches the bytes through it (TIDY-19473).", "title": "Locator" }, "size": { "description": "File size in bytes", "title": "Size", "type": "integer" }, "source_email_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The email a by-reference attachment was taken from", "title": "Source Email Id" }, "source_file_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The My Files file a by-reference attachment points at", "title": "Source File Id" }, "storage_path": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Path in Supabase Storage of a copy the draft owns. Absent on an attachment held by reference (see `locator`).", "title": "Storage Path" } }, "required": [ "id", "filename", "content_type", "size" ], "title": "DraftAttachment", "type": "object" }, "DraftAttachmentListResponse": { "description": "Response for listing attachments on a draft.", "properties": { "attachments": { "description": "Attachments currently attached to the draft", "items": { "$ref": "#/components/schemas/DraftAttachment" }, "title": "Attachments", "type": "array" }, "total_count": { "description": "Total number of attachments", "title": "Total Count", "type": "integer" } }, "required": [ "total_count" ], "title": "DraftAttachmentListResponse", "type": "object" }, "DraftAttachmentRemoveResponse": { "description": "Response for attachment removal.", "properties": { "attachment_id": { "description": "Removed attachment ID", "title": "Attachment Id", "type": "string" }, "removed": { "description": "Whether attachment was removed", "title": "Removed", "type": "boolean" } }, "required": [ "removed", "attachment_id" ], "title": "DraftAttachmentRemoveResponse", "type": "object" }, "DraftAttachmentUploadResponse": { "description": "Response for attachment upload.", "properties": { "attachment": { "$ref": "#/components/schemas/DraftAttachment", "description": "Uploaded attachment metadata" } }, "required": [ "attachment" ], "title": "DraftAttachmentUploadResponse", "type": "object" }, "DraftConflictResolution": { "description": "Additive resolution instructions for a publish conflict.", "properties": { "action": { "title": "Action", "type": "string" }, "approve_path": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Approve Path" }, "loser_id": { "format": "uuid", "title": "Loser Id", "type": "string" }, "merge_path": { "title": "Merge Path", "type": "string" }, "survivor_id": { "format": "uuid", "title": "Survivor Id", "type": "string" } }, "required": [ "action", "merge_path", "survivor_id", "loser_id" ], "title": "DraftConflictResolution", "type": "object" }, "DraftFeedbackRequest": { "description": "Feedback on AI-generated draft.", "properties": { "feedback": { "description": "accepted, edited, regenerated, discarded", "title": "Feedback", "type": "string" }, "feedback_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "too_formal, too_casual, too_long, too_short, other", "title": "Feedback Reason" }, "final_body": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Final body text user sent (if edited)", "title": "Final Body" }, "generation_id": { "format": "uuid", "title": "Generation Id", "type": "string" } }, "required": [ "generation_id", "feedback" ], "title": "DraftFeedbackRequest", "type": "object" }, "DraftLifecycleResponse": { "description": "Uniform response shape across all three lifecycle operations.\n\nThe boolean field name matches the operation:\n - ``inserted`` for create\n - ``published`` for publish\n - ``discarded`` for discard", "properties": { "discarded": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Discarded" }, "id": { "format": "uuid", "title": "Id", "type": "string" }, "inserted": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Inserted" }, "primitive_kind": { "title": "Primitive Kind", "type": "string" }, "published": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Published" } }, "required": [ "id", "primitive_kind" ], "title": "DraftLifecycleResponse", "type": "object" }, "DraftListItem": { "description": "Lightweight draft summary for list responses (excludes body_html to reduce payload).", "properties": { "attachments": { "description": "Attached files", "items": { "$ref": "#/components/schemas/DraftAttachment" }, "title": "Attachments", "type": "array" }, "bcc_recipients": { "description": "BCC recipients", "items": { "$ref": "#/components/schemas/EmailRecipient" }, "title": "Bcc Recipients", "type": "array" }, "body_text": { "default": "", "description": "Truncated plain text preview (max 200 chars)", "title": "Body Text", "type": "string" }, "cc_recipients": { "description": "CC recipients", "items": { "$ref": "#/components/schemas/EmailRecipient" }, "title": "Cc Recipients", "type": "array" }, "compose_type": { "default": "new", "description": "Compose type", "title": "Compose Type", "type": "string" }, "created_at": { "description": "Creation timestamp", "format": "date-time", "title": "Created At", "type": "string" }, "id": { "description": "Draft UUID", "format": "uuid", "title": "Id", "type": "string" }, "reply_to_email_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "default": null, "description": "Reply-to email ID", "title": "Reply To Email Id" }, "send_error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Error message if send failed", "title": "Send Error" }, "status": { "default": "draft", "description": "Draft status", "title": "Status", "type": "string" }, "subject": { "default": "", "description": "Email subject", "title": "Subject", "type": "string" }, "thread_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "default": null, "description": "Thread ID for replies", "title": "Thread Id" }, "to_recipients": { "description": "To recipients", "items": { "$ref": "#/components/schemas/EmailRecipient" }, "title": "To Recipients", "type": "array" }, "updated_at": { "description": "Last update timestamp", "format": "date-time", "title": "Updated At", "type": "string" } }, "required": [ "id", "created_at", "updated_at" ], "title": "DraftListItem", "type": "object" }, "DraftListResponse": { "description": "Response for listing drafts.", "properties": { "items": { "description": "List of drafts", "items": { "$ref": "#/components/schemas/DraftListItem" }, "title": "Items", "type": "array" }, "total": { "description": "Total number of drafts", "title": "Total", "type": "integer" } }, "required": [ "items", "total" ], "title": "DraftListResponse", "type": "object" }, "DraftPublishConflictResponse": { "description": "RFC 9457 wire envelope for a typed draft conflict.", "properties": { "code": { "title": "Code", "type": "string" }, "detail": { "title": "Detail", "type": "string" }, "docs_url": { "title": "Docs Url", "type": "string" }, "draft_id": { "format": "uuid", "title": "Draft Id", "type": "string" }, "error_code": { "title": "Error Code", "type": "string" }, "existing_organization": { "anyOf": [ { "$ref": "#/components/schemas/OrganizationConflictTarget" }, { "type": "null" } ] }, "instance": { "title": "Instance", "type": "string" }, "primitive_kind": { "title": "Primitive Kind", "type": "string" }, "request_id": { "title": "Request Id", "type": "string" }, "resolution": { "anyOf": [ { "$ref": "#/components/schemas/DraftConflictResolution" }, { "type": "null" } ] }, "retry_after_seconds": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Retry After Seconds" }, "retryable": { "title": "Retryable", "type": "boolean" }, "status": { "title": "Status", "type": "integer" }, "title": { "title": "Title", "type": "string" }, "type": { "title": "Type", "type": "string" } }, "required": [ "type", "title", "status", "detail", "instance", "request_id", "code", "retryable", "docs_url", "error_code", "primitive_kind", "draft_id" ], "title": "DraftPublishConflictResponse", "type": "object" }, "DraftResponse": { "description": "Response for draft operations.", "properties": { "attachments": { "description": "Attached files", "items": { "$ref": "#/components/schemas/DraftAttachment" }, "title": "Attachments", "type": "array" }, "bcc_recipients": { "description": "BCC recipients", "items": { "$ref": "#/components/schemas/EmailRecipient" }, "title": "Bcc Recipients", "type": "array" }, "body_html": { "default": "", "description": "HTML body content", "title": "Body Html", "type": "string" }, "body_prosemirror": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "description": "Authoritative ProseMirror doc for the compose body (TIDY-8977 S10). When non-null the editor rehydrates from this on reopen; the send pipeline renders fresh email-safe HTML from it via EmailRenderer.", "title": "Body Prosemirror" }, "body_text": { "default": "", "description": "Plain text body content", "title": "Body Text", "type": "string" }, "cc_recipients": { "description": "CC recipients", "items": { "$ref": "#/components/schemas/EmailRecipient" }, "title": "Cc Recipients", "type": "array" }, "compose_type": { "default": "new", "description": "Compose type", "title": "Compose Type", "type": "string" }, "created_at": { "description": "Creation timestamp", "format": "date-time", "title": "Created At", "type": "string" }, "id": { "description": "Draft UUID", "format": "uuid", "title": "Id", "type": "string" }, "reply_to_email_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "default": null, "description": "Reply-to email ID", "title": "Reply To Email Id" }, "send_error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Error message if send failed (TIDY-3989)", "title": "Send Error" }, "status": { "default": "draft", "description": "Draft status", "title": "Status", "type": "string" }, "subject": { "default": "", "description": "Email subject", "title": "Subject", "type": "string" }, "thread_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "default": null, "description": "Thread ID for replies", "title": "Thread Id" }, "to_recipients": { "description": "To recipients", "items": { "$ref": "#/components/schemas/EmailRecipient" }, "title": "To Recipients", "type": "array" }, "updated_at": { "description": "Last update timestamp", "format": "date-time", "title": "Updated At", "type": "string" } }, "required": [ "id", "created_at", "updated_at" ], "title": "DraftResponse", "type": "object" }, "DraftStatusResponse": { "description": "Lightweight status check for a draft (used for send-status polling).", "properties": { "id": { "description": "Draft UUID", "format": "uuid", "title": "Id", "type": "string" }, "send_error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Error message if status is failed", "title": "Send Error" }, "sent_email_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "description": "Canonical sent email ID when the draft has been persisted to email_canonical", "title": "Sent Email Id" }, "status": { "description": "Current status: draft, sending, sent, failed", "title": "Status", "type": "string" } }, "required": [ "id", "status" ], "title": "DraftStatusResponse", "type": "object" }, "DrawingPreviewResponse": { "properties": { "storagePath": { "title": "Storagepath", "type": "string" }, "success": { "title": "Success", "type": "boolean" }, "url": { "title": "Url", "type": "string" } }, "required": [ "success", "storagePath", "url" ], "title": "DrawingPreviewResponse", "type": "object" }, "DreamerPauseRequest": { "properties": { "until": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Until" } }, "title": "DreamerPauseRequest", "type": "object" }, "DreamerPauseResponse": { "properties": { "paused_until": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Paused Until" } }, "title": "DreamerPauseResponse", "type": "object" }, "DreamerStateResponse": { "properties": { "last_run_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Last Run At" }, "paused_until": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Paused Until" }, "recent_insight_count": { "default": 0, "title": "Recent Insight Count", "type": "integer" }, "recent_run_count": { "default": 0, "title": "Recent Run Count", "type": "integer" }, "tenant_paused_until": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Tenant Paused Until" } }, "title": "DreamerStateResponse", "type": "object" }, "DriveCreateRequest": { "description": "Request body to create a new Google Drive document or folder.", "properties": { "doc_type": { "description": "Type of document: document, spreadsheet, presentation, form, drawing, folder", "enum": [ "document", "spreadsheet", "presentation", "form", "drawing", "folder" ], "title": "Doc Type", "type": "string" }, "name": { "description": "Name for the new document or folder", "maxLength": 500, "minLength": 1, "title": "Name", "type": "string" }, "parent_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Parent folder ID (defaults to root)", "title": "Parent Id" } }, "required": [ "name", "doc_type" ], "title": "DriveCreateRequest", "type": "object" }, "DriveCreateResponse": { "description": "Response after creating a new Google Drive document or folder.", "properties": { "file_id": { "description": "Google Drive file ID", "title": "File Id", "type": "string" }, "mime_type": { "description": "MIME type", "title": "Mime Type", "type": "string" }, "name": { "description": "Name of the created document/folder", "title": "Name", "type": "string" }, "web_view_link": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "URL to open in Google editor", "title": "Web View Link" } }, "required": [ "file_id", "name", "mime_type" ], "title": "DriveCreateResponse", "type": "object" }, "DriveFileItem": { "description": "A single file or folder from Google Drive.", "properties": { "iconLink": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "URL to file type icon", "title": "Iconlink" }, "id": { "description": "Google Drive file ID", "title": "Id", "type": "string" }, "mimeType": { "description": "MIME type", "title": "Mimetype", "type": "string" }, "modifiedTime": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Last modified timestamp (ISO 8601)", "title": "Modifiedtime" }, "name": { "description": "File name", "title": "Name", "type": "string" }, "parents": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "description": "Parent folder IDs", "title": "Parents" }, "size": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "File size in bytes (folders have no size)", "title": "Size" }, "webViewLink": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "URL to view/edit in Google Drive", "title": "Webviewlink" } }, "required": [ "id", "name", "mimeType" ], "title": "DriveFileItem", "type": "object" }, "DriveFileReadResponse": { "description": "``GET /drive/files/{file_id}`` — metadata plus, for text-bearing files,\nthe content itself so an employee under a ``drive.read`` lend can read a\ndocument without a download round-trip (TIDY-18241 / R22).", "properties": { "content": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Plain-text content for Docs/Sheets/Slides/text files; None otherwise", "title": "Content" }, "content_truncated": { "default": false, "title": "Content Truncated", "type": "boolean" }, "id": { "description": "Google Drive file ID", "title": "Id", "type": "string" }, "mime_type": { "title": "Mime Type", "type": "string" }, "modified_time": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Modified Time" }, "name": { "title": "Name", "type": "string" }, "size": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Size" }, "web_view_link": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Web View Link" } }, "required": [ "id", "name", "mime_type" ], "title": "DriveFileReadResponse", "type": "object" }, "DriveFilesResponse": { "description": "Paginated response from Drive files listing.", "properties": { "files": { "items": { "$ref": "#/components/schemas/DriveFileItem" }, "title": "Files", "type": "array" }, "next_page_token": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Token for fetching the next page of results", "title": "Next Page Token" } }, "required": [ "files" ], "title": "DriveFilesResponse", "type": "object" }, "DriveImportRequest": { "description": "Body for POST /api/v1/drive/import.", "properties": { "connection_id": { "minLength": 1, "title": "Connection Id", "type": "string" }, "drive_file_id": { "maxLength": 128, "minLength": 1, "title": "Drive File Id", "type": "string" }, "replace": { "default": false, "description": "When true, reuse the existing primitive id and reset import_status to 'importing'; content is overwritten via the same conversion path.", "title": "Replace", "type": "boolean" } }, "required": [ "drive_file_id", "connection_id" ], "title": "DriveImportRequest", "type": "object" }, "DriveImportResponse": { "description": "Response from POST /api/v1/drive/import.", "properties": { "drive_mime_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Drive Mime Type" }, "existing": { "title": "Existing", "type": "boolean" }, "id": { "title": "Id", "type": "string" }, "import_status": { "title": "Import Status", "type": "string" }, "primitive_subtype": { "title": "Primitive Subtype", "type": "string" }, "primitive_type": { "title": "Primitive Type", "type": "string" }, "same_content": { "default": false, "description": "TIDY-19809: the Drive file's bytes were already in Tidy, so the import resolved to that existing file instead of storing a second copy. Re-importing it changes nothing.", "title": "Same Content", "type": "boolean" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Title" } }, "required": [ "id", "primitive_type", "primitive_subtype", "import_status", "existing" ], "title": "DriveImportResponse", "type": "object" }, "DriveLinkRequest": { "description": "Request body to link a Google Drive file to Tidy.", "properties": { "drive_file_id": { "description": "Google Drive file ID", "title": "Drive File Id", "type": "string" }, "drive_file_name": { "description": "Display name of the file", "title": "Drive File Name", "type": "string" }, "drive_mime_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "MIME type from Google Drive", "title": "Drive Mime Type" }, "drive_size_bytes": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "File size in bytes", "title": "Drive Size Bytes" }, "drive_web_link": { "description": "Google Drive web view URL", "title": "Drive Web Link", "type": "string" }, "folder_path": { "default": "/", "description": "Virtual folder path in Tidy's file explorer", "title": "Folder Path", "type": "string" }, "project_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Project UUID to associate with", "title": "Project Id" }, "visibility": { "default": "private", "description": "Visibility scope: private (owner only), project (project members), team (all tenant members)", "enum": [ "private", "project", "team" ], "title": "Visibility", "type": "string" } }, "required": [ "drive_file_id", "drive_file_name", "drive_web_link" ], "title": "DriveLinkRequest", "type": "object" }, "DriveLinkResponse": { "description": "Response after linking a Drive file to Tidy.", "properties": { "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "folder_path": { "title": "Folder Path", "type": "string" }, "id": { "title": "Id", "type": "string" }, "mime_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Mime Type" }, "name": { "title": "Name", "type": "string" }, "owner_id": { "title": "Owner Id", "type": "string" }, "project_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Project Id" }, "size_bytes": { "title": "Size Bytes", "type": "integer" }, "storage_ref": { "title": "Storage Ref", "type": "string" }, "storage_type": { "title": "Storage Type", "type": "string" }, "tenant_id": { "title": "Tenant Id", "type": "string" }, "updated_at": { "format": "date-time", "title": "Updated At", "type": "string" }, "visibility": { "default": "private", "title": "Visibility", "type": "string" } }, "required": [ "id", "tenant_id", "owner_id", "name", "folder_path", "storage_type", "storage_ref", "size_bytes", "created_at", "updated_at" ], "title": "DriveLinkResponse", "type": "object" }, "DriveMoveRequest": { "description": "Move a Drive file into another folder (TIDY-18241 / R22).", "properties": { "file_id": { "description": "Google Drive file ID to move", "title": "File Id", "type": "string" }, "new_parent_id": { "description": "Destination folder ID", "title": "New Parent Id", "type": "string" } }, "required": [ "file_id", "new_parent_id" ], "title": "DriveMoveRequest", "type": "object" }, "DriveMoveResponse": { "description": "The moved file, with its new parent set.", "properties": { "file_id": { "description": "Google Drive file ID", "title": "File Id", "type": "string" }, "mime_type": { "description": "MIME type", "title": "Mime Type", "type": "string" }, "name": { "description": "File name", "title": "Name", "type": "string" }, "parents": { "description": "Parent folder IDs after the move", "items": { "type": "string" }, "title": "Parents", "type": "array" }, "web_view_link": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "URL to open in Google", "title": "Web View Link" } }, "required": [ "file_id", "name", "mime_type" ], "title": "DriveMoveResponse", "type": "object" }, "DriveNotificationReceipt": { "properties": { "outcome": { "title": "Outcome", "type": "string" } }, "required": [ "outcome" ], "title": "DriveNotificationReceipt", "type": "object" }, "DriveSaveRequest": { "description": "Request body for POST /api/v1/drive/save.\n\nExactly one of ``note_id`` / ``file_id`` (R7/D15). There is deliberately\nNO field accepting an existing Drive file id — save always CREATES a new\napp-authored Google Doc and never overwrites a user's file (R8).", "properties": { "connection_id": { "anyOf": [ { "minLength": 1, "type": "string" }, { "type": "null" } ], "description": "OAuth connection id (must be owned by the caller). Omit to use the caller's single Drive-capable Google connection.", "title": "Connection Id" }, "file_id": { "anyOf": [ { "maxLength": 64, "minLength": 1, "type": "string" }, { "type": "null" } ], "description": "Tidy text-file id whose stored text becomes the Doc body", "title": "File Id" }, "note_id": { "anyOf": [ { "maxLength": 64, "minLength": 1, "type": "string" }, { "type": "null" } ], "description": "Tidy note id (typed form N- accepted) whose content becomes the Doc body", "title": "Note Id" }, "title": { "anyOf": [ { "maxLength": 500, "minLength": 1, "type": "string" }, { "type": "null" } ], "description": "Title for the new Google Doc (defaults to the note title / file name)", "title": "Title" } }, "title": "DriveSaveRequest", "type": "object" }, "DriveSaveResponse": { "description": "Response after saving Tidy content into a NEW Google Doc.", "properties": { "drive_file_id": { "description": "Google Drive file ID of the newly created Doc", "title": "Drive File Id", "type": "string" }, "name": { "description": "Title of the created Doc", "title": "Name", "type": "string" }, "web_view_link": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "URL to open the new Doc in Google's editor", "title": "Web View Link" } }, "required": [ "drive_file_id", "name" ], "title": "DriveSaveResponse", "type": "object" }, "DuplicatePair": { "description": "A pair of potentially duplicate contacts.\n\nReturned by GET /api/v1/contacts/duplicates endpoint.\nSorted by confidence_score descending (highest confidence first).\n\nAttributes:\n id: Unique pair identifier (sorted UUIDs)\n contact_a: First contact (lower UUID)\n contact_b: Second contact (higher UUID)\n confidence_score: Match confidence 0.0-1.0\n match_reason: Why these contacts were flagged\n match_details: Human-readable explanation\n\nRelated: apps/mobile/src/lib/components/contacts/DuplicatePairCard.svelte", "properties": { "confidence_score": { "description": "Match confidence score 0.0-1.0", "examples": [ 0.95 ], "maximum": 1.0, "minimum": 0.0, "title": "Confidence Score", "type": "number" }, "contact_a": { "$ref": "#/components/schemas/api_service__models__contact_merge__ContactSummary", "description": "First contact in pair" }, "contact_b": { "$ref": "#/components/schemas/api_service__models__contact_merge__ContactSummary", "description": "Second contact in pair" }, "id": { "description": "Unique pair ID (sorted contact UUIDs)", "examples": [ "abc123_def456" ], "title": "Id", "type": "string" }, "match_details": { "description": "Human-readable match explanation", "examples": [ "Both contacts have email: jane@school.edu" ], "title": "Match Details", "type": "string" }, "match_reason": { "$ref": "#/components/schemas/MatchReason", "description": "Why contacts were flagged as duplicates" } }, "required": [ "id", "contact_a", "contact_b", "confidence_score", "match_reason", "match_details" ], "title": "DuplicatePair", "type": "object" }, "DuplicatesResponse": { "description": "Response for GET /api/v1/contacts/duplicates.\n\nAttributes:\n pairs: List of duplicate pairs sorted by confidence\n total_count: Total number of duplicate pairs found\n dismissed_count: Number of dismissed pairs (not shown)\n\nRelated: apps/mobile/src/routes/contacts/+page.svelte", "properties": { "dismissed_count": { "default": 0, "description": "Number of dismissed pairs (not shown)", "title": "Dismissed Count", "type": "integer" }, "pairs": { "default": [], "description": "List of duplicate pairs", "items": { "$ref": "#/components/schemas/DuplicatePair" }, "title": "Pairs", "type": "array" }, "total_count": { "description": "Total duplicate pairs found", "title": "Total Count", "type": "integer" } }, "required": [ "total_count" ], "title": "DuplicatesResponse", "type": "object" }, "EarnedBadge": { "properties": { "badge_type": { "title": "Badge Type", "type": "string" }, "description": { "title": "Description", "type": "string" }, "earned_at": { "title": "Earned At", "type": "string" }, "icon": { "title": "Icon", "type": "string" }, "metric_value": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Metric Value" }, "name": { "title": "Name", "type": "string" } }, "required": [ "badge_type", "name", "description", "icon", "earned_at" ], "title": "EarnedBadge", "type": "object" }, "EdgeJobPayload": { "properties": { "function": { "title": "Function", "type": "string" }, "job_id": { "title": "Job Id", "type": "string" }, "payload": { "additionalProperties": true, "title": "Payload", "type": "object" }, "rung_target": { "title": "Rung Target", "type": "string" } }, "required": [ "job_id", "function", "payload", "rung_target" ], "title": "EdgeJobPayload", "type": "object" }, "EdgeJobResultRequest": { "properties": { "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Set when the worker failed to serve the job", "title": "Error" }, "served_by": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Model id that served (worker-side audit)", "title": "Served By" }, "text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The model's raw response text", "title": "Text" } }, "title": "EdgeJobResultRequest", "type": "object" }, "EdgeWorkerRegisterRequest": { "properties": { "capabilities": { "additionalProperties": true, "title": "Capabilities", "type": "object" }, "device_id": { "description": "devices row id this worker runs on", "title": "Device Id", "type": "string" }, "surface": { "default": "desktop", "description": "'desktop' (server-side rung) or a client surface ('web', 'android')", "title": "Surface", "type": "string" }, "tier": { "description": "Declared serving tier: T1 | T2 | T3", "title": "Tier", "type": "string" } }, "required": [ "device_id", "tier" ], "title": "EdgeWorkerRegisterRequest", "type": "object" }, "EdgeWorkerResponse": { "properties": { "device_id": { "title": "Device Id", "type": "string" }, "surface": { "title": "Surface", "type": "string" }, "tenant_id": { "title": "Tenant Id", "type": "string" }, "tier": { "title": "Tier", "type": "string" }, "worker_id": { "title": "Worker Id", "type": "string" } }, "required": [ "worker_id", "tenant_id", "device_id", "surface", "tier" ], "title": "EdgeWorkerResponse", "type": "object" }, "EditBody": { "properties": { "final_reply": { "maxLength": 350, "minLength": 1, "title": "Final Reply", "type": "string" } }, "required": [ "final_reply" ], "title": "EditBody", "type": "object" }, "EditMentionRequest": { "description": "Minimal mention shape mirroring the matrix.py router's\n``MatrixMentionRequest`` so models module is import-safe.", "properties": { "display_name": { "maxLength": 255, "minLength": 1, "title": "Display Name", "type": "string" }, "end": { "minimum": 0.0, "title": "End", "type": "integer" }, "start": { "minimum": 0.0, "title": "Start", "type": "integer" }, "user_id": { "maxLength": 255, "minLength": 3, "title": "User Id", "type": "string" } }, "required": [ "user_id", "display_name", "start", "end" ], "title": "EditMentionRequest", "type": "object" }, "EditMessageRequest": { "description": "Payload to replace the body of a previously sent message.\n\n``formatted_body`` is sanitized server-side via\n``matrix_html_sanitizer`` before publishing — same allow-list as\n``send-message`` (TIDY-10218 F3 S1 D2).", "properties": { "body": { "maxLength": 10000, "minLength": 1, "title": "Body", "type": "string" }, "formatted_body": { "anyOf": [ { "maxLength": 40000, "type": "string" }, { "type": "null" } ], "title": "Formatted Body" }, "mentions": { "items": { "$ref": "#/components/schemas/EditMentionRequest" }, "title": "Mentions", "type": "array" } }, "required": [ "body" ], "title": "EditMessageRequest", "type": "object" }, "EditMessageResponse": { "description": "The replacement event id Tuwunel issued for the m.replace.", "properties": { "edited_at": { "title": "Edited At", "type": "string" }, "event_id": { "title": "Event Id", "type": "string" } }, "required": [ "event_id", "edited_at" ], "title": "EditMessageResponse", "type": "object" }, "EmailActionResponse": { "description": "Response for email action endpoints (archive/unarchive).\n\nAttributes:\n id: Email UUID that was acted upon\n success: Whether the action succeeded\n message: Human-readable result message\n\nExample:\n {\"id\": \"uuid-here\", \"success\": true, \"message\": \"Email archived\"}", "properties": { "id": { "description": "Email UUID", "format": "uuid", "title": "Id", "type": "string" }, "message": { "description": "Result message", "title": "Message", "type": "string" }, "success": { "description": "Whether action succeeded", "title": "Success", "type": "boolean" } }, "required": [ "id", "success", "message" ], "title": "EmailActionResponse", "type": "object" }, "EmailAddressLegacy": { "description": "Email address with optional name (legacy view format).", "properties": { "address": { "title": "Address", "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name" } }, "required": [ "address" ], "title": "EmailAddressLegacy", "type": "object" }, "EmailAttachment": { "description": "Detailed attachment metadata. Propagates the AttachmentLocator so clients\ncan resolve bytes via the /api/v1/attachments/{id}/{filename}/content\nendpoint without storage-path-centric assumptions (TIDY-6862, D15).\n\nAttributes:\n id: processed_attachments id\n filename: Original attachment filename\n content_type: MIME type\n size: File size in bytes\n storage_path: Retained for IMAP/SMTP fast path\n locator: Full AttachmentLocator dict ({type, ...}); None for legacy rows\n locator_reason: Populated when locator.type == \"unavailable\"\n content_id: RFC Content-ID for inline MIME assets, if available", "properties": { "content_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC Content-ID for inline MIME assets", "title": "Content Id" }, "content_type": { "description": "MIME type", "title": "Content Type", "type": "string" }, "filename": { "description": "Original attachment filename", "title": "Filename", "type": "string" }, "id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "description": "processed_attachments UUID", "title": "Id" }, "is_inline": { "default": false, "description": "True when the part is an inline asset (Content-Disposition inline or a Content-ID is present)", "title": "Is Inline", "type": "boolean" }, "locator": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "AttachmentLocator dict (storage/provider/unavailable)", "title": "Locator" }, "locator_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Reason string when locator.type == 'unavailable'", "title": "Locator Reason" }, "size": { "default": 0, "description": "File size in bytes", "title": "Size", "type": "integer" }, "storage_path": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Storage path for signed URL generation", "title": "Storage Path" } }, "required": [ "filename", "content_type" ], "title": "EmailAttachment", "type": "object" }, "EmailAttachmentTextResponse": { "description": "Docling-extracted text for one email attachment (TIDY-13457).\n\nWhen the pipeline has processed the attachment, `text` holds the extracted\nmarkdown; otherwise `processed` is False and `message` states why (not\nprocessed yet, or no extractable text).", "properties": { "content_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Attachment MIME type", "title": "Content Type" }, "email_canonical_id": { "description": "Source email id", "format": "uuid", "title": "Email Canonical Id", "type": "string" }, "extraction_state": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "On-demand extraction dispatch state when text is unavailable: 'queued' (extraction was just dispatched), 'processing' (a run is already in flight). TIDY-14782.", "title": "Extraction State" }, "filename": { "description": "Attachment filename", "title": "Filename", "type": "string" }, "full_length": { "default": 0, "description": "Character length of the untruncated text", "title": "Full Length", "type": "integer" }, "message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Human-readable state when text is unavailable", "title": "Message" }, "processed": { "default": false, "description": "True when extracted text is available", "title": "Processed", "type": "boolean" }, "processing_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "processed_attachments.processing_status", "title": "Processing Status" }, "retry_after_seconds": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Suggested delay before re-calling this endpoint for the result", "title": "Retry After Seconds" }, "text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Extracted markdown text (present when processed)", "title": "Text" }, "trace_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Pipeline trace id of the queued/in-flight extraction run", "title": "Trace Id" }, "truncated": { "default": false, "description": "True when text was cut to the length cap", "title": "Truncated", "type": "boolean" } }, "required": [ "email_canonical_id", "filename" ], "title": "EmailAttachmentTextResponse", "type": "object" }, "EmailBehaviorResponse": { "properties": { "action_rate_pct": { "title": "Action Rate Pct", "type": "number" }, "avg_inbox_opens_per_day": { "title": "Avg Inbox Opens Per Day", "type": "number" }, "avg_time_in_inbox_minutes": { "title": "Avg Time In Inbox Minutes", "type": "number" }, "avg_views_per_email": { "title": "Avg Views Per Email", "type": "number" }, "daily_breakdown": { "items": { "$ref": "#/components/schemas/DailyBreakdown" }, "title": "Daily Breakdown", "type": "array" }, "emails_viewed_3plus_times": { "title": "Emails Viewed 3Plus Times", "type": "integer" }, "engagement": { "anyOf": [ { "$ref": "#/components/schemas/EngagementMetrics" }, { "type": "null" } ] }, "pct_emails_reopened": { "title": "Pct Emails Reopened", "type": "number" }, "stale_emails_14d": { "title": "Stale Emails 14D", "type": "integer" }, "stale_emails_7d": { "title": "Stale Emails 7D", "type": "integer" } }, "required": [ "avg_views_per_email", "emails_viewed_3plus_times", "pct_emails_reopened", "avg_inbox_opens_per_day", "avg_time_in_inbox_minutes", "stale_emails_7d", "stale_emails_14d", "action_rate_pct", "daily_breakdown" ], "title": "EmailBehaviorResponse", "type": "object" }, "EmailBodiesRequest": { "properties": { "ids": { "description": "List of email_canonical ids to fetch bodies for. Min 1, max 100. Accepts the typed `E-` ids emitted by the LIST endpoint or bare UUIDs; both normalize to bare UUIDs before lookup.", "items": { "type": "string" }, "title": "Ids", "type": "array" }, "prefer": { "default": "html", "description": "Body representation to return. html/markdown are persistent hydrator variants; *_one_off variants are for render-mode toggles.", "enum": [ "html", "markdown", "html_one_off", "markdown_one_off" ], "title": "Prefer", "type": "string" } }, "required": [ "ids" ], "title": "EmailBodiesRequest", "type": "object" }, "EmailBodiesResponse": { "properties": { "bodies": { "items": { "$ref": "#/components/schemas/EmailBodyRow" }, "title": "Bodies", "type": "array" } }, "required": [ "bodies" ], "title": "EmailBodiesResponse", "type": "object" }, "EmailBodyRow": { "properties": { "body_html_sanitized": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Body Html Sanitized" }, "body_markdown": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Body Markdown" }, "body_text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Body Text" }, "id": { "title": "Id", "type": "string" }, "variant": { "enum": [ "html", "markdown", "html_one_off", "markdown_one_off" ], "title": "Variant", "type": "string" } }, "required": [ "id", "variant", "body_html_sanitized", "body_text", "body_markdown" ], "title": "EmailBodyRow", "type": "object" }, "EmailCategoryCount": { "properties": { "category": { "title": "Category", "type": "string" }, "count": { "title": "Count", "type": "integer" } }, "required": [ "category", "count" ], "title": "EmailCategoryCount", "type": "object" }, "EmailCountResponse": { "description": "Response model for document count endpoint.", "properties": { "count": { "description": "Total number of documents", "examples": [ 42 ], "title": "Count", "type": "integer" } }, "required": [ "count" ], "title": "EmailCountResponse", "type": "object" }, "EmailDetailResponse": { "description": "Full email detail response with thread context.\n\nUsed in GET /api/v1/emails/{email_id} response.\nIncludes full body content and thread position for conversation navigation.\n\nAttributes:\n id: Email UUID\n subject: Email subject line\n from_address: Sender email address\n from_name: Sender display name (optional)\n to_addresses: List of recipient addresses\n cc_addresses: List of CC addresses\n sent_at: Email sent timestamp\n body_html: HTML body content (optional)\n body_html_sanitized: Pre-sanitized HTML from the server nh3 pipeline\n (TIDY-7319). Null when the ingest-time sanitize has not yet\n populated this row; clients render body_html via their own\n worker-based sanitize fallback in that case.\n body_text: Plain text body content (optional)\n body_markdown: Markdown body content (optional)\n attachments: List of attachment metadata\n is_archived: Whether email is in archive\n user_labels: User-assigned labels\n tags: Semantic tags extracted for cross-primitive linking\n thread_id: Thread UUID (null for standalone emails)\n thread_position: 1-indexed position in thread (null if standalone)\n thread_total: Total emails in thread (null if standalone)\n\nExample:\n {\n \"id\": \"uuid-here\",\n \"subject\": \"Re: School Play Auditions\",\n \"from_address\": \"parent@email.com\",\n \"sent_at\": \"2025-11-19T12:30:00Z\",\n \"body_html\": \"...\",\n \"thread_id\": \"thread-uuid\",\n \"thread_position\": 3,\n \"thread_total\": 5\n }", "properties": { "archived_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Archive reason: 'calendar_invite' (REQUEST), 'calendar_response' (REPLY/CANCEL/COUNTER), or null for normal emails", "title": "Archived Reason" }, "attachments": { "description": "List of attachment metadata with storage paths", "items": { "$ref": "#/components/schemas/EmailAttachment" }, "title": "Attachments", "type": "array" }, "body_html": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "HTML body content", "title": "Body Html" }, "body_html_sanitized": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Pre-sanitized HTML from the server nh3 pipeline (TIDY-7319). Null when this row has not yet been sanitized at ingest.", "title": "Body Html Sanitized" }, "body_markdown": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Markdown body content", "title": "Body Markdown" }, "body_text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Plain text body content", "title": "Body Text" }, "category_forced": { "default": false, "description": "Whether triage_category was forced by a sender rule", "title": "Category Forced", "type": "boolean" }, "cc_addresses": { "description": "List of CC addresses", "items": { "type": "string" }, "title": "Cc Addresses", "type": "array" }, "from_address": { "description": "Sender email address", "title": "From Address", "type": "string" }, "from_contact_approval_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Approval status of resolved sender contact: 'approved', 'pending_review', or 'dismissed'", "title": "From Contact Approval Status" }, "from_contact_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "default": null, "description": "UUID of contact matching sender email address, if found", "title": "From Contact Id" }, "from_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Sender display name", "title": "From Name" }, "from_photo_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Sender contact photo URL from contacts table", "title": "From Photo Url" }, "id": { "description": "Email UUID", "format": "uuid", "title": "Id", "type": "string" }, "is_archived": { "description": "Whether email is in archive", "title": "Is Archived", "type": "boolean" }, "llm_confidence": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "description": "Confidence score from triage (0.0-1.0)", "title": "Llm Confidence" }, "routing_decision": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Triage routing decision (process, archive, etc.)", "title": "Routing Decision" }, "sent_at": { "description": "Email sent timestamp", "format": "date-time", "title": "Sent At", "type": "string" }, "subject": { "description": "Email subject line", "title": "Subject", "type": "string" }, "tags": { "description": "Semantic tags extracted for cross-primitive linking", "items": { "type": "string" }, "title": "Tags", "type": "array" }, "thread_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "default": null, "description": "Thread UUID (null for standalone emails)", "title": "Thread Id" }, "thread_position": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "1-indexed position in thread (null if standalone)", "title": "Thread Position" }, "thread_total": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Total emails in thread (null if standalone)", "title": "Thread Total" }, "to_addresses": { "description": "List of recipient addresses", "items": { "type": "string" }, "title": "To Addresses", "type": "array" }, "triage_category": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Category from email triage (school, family, etc.)", "title": "Triage Category" }, "triage_label": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "User-facing triage label: to_respond, fyi, low_priority", "title": "Triage Label" }, "triage_summary": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "LLM-generated summary from triage", "title": "Triage Summary" }, "user_labels": { "description": "User-assigned labels", "items": { "type": "string" }, "title": "User Labels", "type": "array" } }, "required": [ "id", "subject", "from_address", "sent_at", "is_archived" ], "title": "EmailDetailResponse", "type": "object" }, "EmailExportRequest": { "properties": { "message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Message" }, "range": { "default": "30d", "title": "Range", "type": "string" }, "recipient_email": { "format": "email", "title": "Recipient Email", "type": "string" }, "sections": { "items": { "type": "string" }, "title": "Sections", "type": "array" } }, "required": [ "recipient_email", "sections" ], "title": "EmailExportRequest", "type": "object" }, "EmailExportResponse": { "properties": { "sent": { "title": "Sent", "type": "boolean" } }, "required": [ "sent" ], "title": "EmailExportResponse", "type": "object" }, "EmailFeedbackRequest": { "description": "Request body for submitting email summary feedback.", "properties": { "feedback_text": { "anyOf": [ { "maxLength": 1000, "type": "string" }, { "type": "null" } ], "description": "Optional free-text feedback", "title": "Feedback Text" }, "feedback_type": { "description": "Feedback type: thumbs_up, thumbs_down, too_formal, too_casual, too_long, too_short, inaccurate, helpful, unhelpful", "title": "Feedback Type", "type": "string" } }, "required": [ "feedback_type" ], "title": "EmailFeedbackRequest", "type": "object" }, "EmailFeedbackResponse": { "description": "Response for email feedback submission.", "properties": { "created_at": { "description": "When feedback was submitted", "format": "date-time", "title": "Created At", "type": "string" }, "email_id": { "description": "Email the feedback is for", "format": "uuid", "title": "Email Id", "type": "string" }, "feedback_type": { "description": "Type of feedback", "title": "Feedback Type", "type": "string" }, "id": { "description": "Feedback UUID", "format": "uuid", "title": "Id", "type": "string" }, "message": { "default": "Feedback submitted successfully", "description": "Result message", "title": "Message", "type": "string" } }, "required": [ "id", "email_id", "feedback_type", "created_at" ], "title": "EmailFeedbackResponse", "type": "object" }, "EmailGroup": { "description": "A recurring group of email participants.", "properties": { "conversation_count": { "title": "Conversation Count", "type": "integer" }, "custom_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Custom Name" }, "id": { "title": "Id", "type": "string" }, "last_email_at": { "format": "date-time", "title": "Last Email At", "type": "string" }, "member_count": { "title": "Member Count", "type": "integer" }, "members": { "items": { "$ref": "#/components/schemas/EmailGroupMember" }, "title": "Members", "type": "array" }, "sample_conversations": { "items": { "$ref": "#/components/schemas/SampleConversation" }, "title": "Sample Conversations", "type": "array" }, "sample_subjects": { "items": { "type": "string" }, "title": "Sample Subjects", "type": "array" } }, "required": [ "id", "members", "member_count", "conversation_count", "last_email_at", "sample_subjects", "sample_conversations" ], "title": "EmailGroup", "type": "object" }, "EmailGroupMember": { "description": "A member of an email group.", "properties": { "email": { "title": "Email", "type": "string" }, "message_count": { "default": 0, "title": "Message Count", "type": "integer" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name" } }, "required": [ "email" ], "title": "EmailGroupMember", "type": "object" }, "EmailGroupsResponse": { "description": "Response for email groups endpoint.", "properties": { "groups": { "items": { "$ref": "#/components/schemas/EmailGroup" }, "title": "Groups", "type": "array" }, "total": { "title": "Total", "type": "integer" } }, "required": [ "groups", "total" ], "title": "EmailGroupsResponse", "type": "object" }, "EmailId": { "description": "Typed primitive ID for email_canonical (prefix 'E').", "examples": [ "E-550e8400-e29b-41d4-a716-446655440000" ], "pattern": "^E-[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "title": "EmailId", "type": "string", "x-tidy-typed-id-prefix": "E", "x-tidy-typed-id-table": "email_canonical" }, "EmailImportRequest": { "properties": { "raw_message_b64": { "description": "Base64-encoded raw RFC 822 message: one .eml file or mbox entry.", "minLength": 1, "title": "Raw Message B64", "type": "string" } }, "required": [ "raw_message_b64" ], "title": "EmailImportRequest", "type": "object" }, "EmailImportResponse": { "properties": { "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The email (`E-…`) in your mailbox. Null while `processing`: import the same message again to get it once it is filed.", "title": "Id" }, "message_id": { "description": "The message's Message-ID, the dedup key.", "title": "Message Id", "type": "string" }, "status": { "description": "`imported`: filed now. `duplicate`: you already had this message; `id` is that email. `processing`: accepted, not filed yet.", "enum": [ "imported", "duplicate", "processing" ], "title": "Status", "type": "string" } }, "required": [ "id", "status", "message_id" ], "title": "EmailImportResponse", "type": "object" }, "EmailListItem": { "description": "Email item for list view display.\n\nUsed in GET /api/v1/emails response items. Contains essential fields\nfor inbox/archive list display without full email body.\n\nAttributes:\n id: Email UUID (email_canonical.id)\n subject: Email subject line\n from_address: Sender email address\n from_name: Sender display name (optional)\n sent_at: Email sent timestamp\n is_read: Whether email has been read (optional, future feature)\n is_archived: Whether email is in archive\n user_labels: User-assigned labels (string array)\n snippet: First 150 chars of body_text for preview\n thread_id: Conversation thread UUID (nullable for standalone emails)\n has_attachments: Whether email has attachments\n triage_category: Category from email triage (school, family, etc.)\n tags: Semantic tags extracted for cross-primitive linking\n triage_summary: LLM-generated summary from triage\n llm_confidence: Confidence score from triage (0.0-1.0)\n routing_decision: Triage routing decision (process, archive, etc.)\n\nExample:\n {\n \"id\": \"uuid-here\",\n \"subject\": \"School Play Auditions\",\n \"from_address\": \"drama@school.edu\",\n \"from_name\": \"Drama Club\",\n \"sent_at\": \"2025-11-19T10:00:00Z\",\n \"is_archived\": false,\n \"user_labels\": [\"school\", \"important\"],\n \"snippet\": \"Dear Parents, We are excited to announce...\",\n \"triage_category\": \"school\",\n \"triage_summary\": \"School play auditions announced for next week.\",\n \"llm_confidence\": 0.95,\n \"thread_id\": \"thread-uuid\",\n \"has_attachments\": true\n }", "properties": { "category_forced": { "default": false, "description": "Whether triage_category was forced by a sender rule", "title": "Category Forced", "type": "boolean" }, "cc_addresses": { "description": "CC email addresses", "items": { "type": "string" }, "title": "Cc Addresses", "type": "array" }, "content_char_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Character count of message_content", "title": "Content Char Count" }, "depth": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Enrichment depth: header, body, or processed", "title": "Depth" }, "display_mode": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Display mode: 'full' or 'summary'", "title": "Display Mode" }, "display_subject": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Cleaned subject line (Re:/Fwd: stripped). Preferred over subject when set.", "title": "Display Subject" }, "enrichment_summary": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "description": "Count of enrichment overlays by type", "title": "Enrichment Summary" }, "from_address": { "description": "Sender email address", "title": "From Address", "type": "string" }, "from_avatar_schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Sender contact custom vector avatar schema (JSON string). When present, the shared avatar resolver renders it in preference to the photo (avatar-over-photo precedence, TIDY-13123).", "title": "From Avatar Schema" }, "from_contact_approval_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Approval status of the resolved sender contact: 'approved', 'pending_review', or 'dismissed'. Null when sender doesn't match any contact. Drives the sender-pending UX indicator.", "title": "From Contact Approval Status" }, "from_contact_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "default": null, "description": "UUID of contact matching sender email address, if found", "title": "From Contact Id" }, "from_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Sender display name", "title": "From Name" }, "from_photo_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Sender contact photo URL from contacts table", "title": "From Photo Url" }, "has_attachments": { "default": false, "description": "Whether email has attachments", "title": "Has Attachments", "type": "boolean" }, "id": { "description": "Email UUID (email_canonical.id)", "format": "uuid", "title": "Id", "type": "string" }, "imap_folder": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "IMAP folder path (shown as badge for non-INBOX emails)", "title": "Imap Folder" }, "inbox_split": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Three-way inbox split: important, feed, or paper_trail", "title": "Inbox Split" }, "is_archived": { "description": "Whether email is in archive", "title": "Is Archived", "type": "boolean" }, "is_done": { "default": false, "description": "Whether email is marked as done", "title": "Is Done", "type": "boolean" }, "is_read": { "default": true, "description": "Whether email has been read", "title": "Is Read", "type": "boolean" }, "is_sent": { "default": false, "description": "True for outgoing sent emails", "title": "Is Sent", "type": "boolean" }, "is_starred": { "default": false, "description": "Whether email is starred/flagged", "title": "Is Starred", "type": "boolean" }, "linked_refs_summary": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Materialized linked-reference rollup JSON used for list badges and pending-approval counts.", "title": "Linked Refs Summary" }, "llm_confidence": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "description": "Confidence score from triage (0.0-1.0)", "title": "Llm Confidence" }, "message_content": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Net-new message content only (no quoted history or signatures)", "title": "Message Content" }, "project_color": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Project color hex code for badge", "title": "Project Color" }, "project_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "default": null, "description": "Project UUID if email is assigned to a project", "title": "Project Id" }, "project_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Project name for display", "title": "Project Name" }, "routing_decision": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Triage routing decision (process, archive, etc.)", "title": "Routing Decision" }, "sent_at": { "description": "Email sent timestamp", "format": "date-time", "title": "Sent At", "type": "string" }, "snippet": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "First 150 chars of body_text for preview", "title": "Snippet" }, "subject": { "description": "Email subject line", "title": "Subject", "type": "string" }, "tags": { "description": "Semantic tags extracted for cross-primitive linking", "items": { "type": "string" }, "title": "Tags", "type": "array" }, "thread_count": { "default": 1, "description": "Number of emails in this thread (1 for standalone)", "title": "Thread Count", "type": "integer" }, "thread_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "default": null, "description": "Conversation thread UUID (nullable for standalone)", "title": "Thread Id" }, "tidy_folder": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Tidy folder bucket: inbox, sent, drafts, outbox, done, or 'custom:'. Source of truth for folder filtering.", "title": "Tidy Folder" }, "to_addresses": { "description": "Recipient email addresses", "items": { "type": "string" }, "title": "To Addresses", "type": "array" }, "tracker_count": { "default": 0, "description": "Number of tracking pixels blocked from this email", "title": "Tracker Count", "type": "integer" }, "triage_category": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Category from email triage (school, family, etc.)", "title": "Triage Category" }, "triage_label": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "User-facing triage label: to_respond, fyi, low_priority", "title": "Triage Label" }, "triage_summary": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "LLM-generated summary from triage", "title": "Triage Summary" }, "user_labels": { "description": "User-assigned labels", "items": { "type": "string" }, "title": "User Labels", "type": "array" } }, "required": [ "id", "subject", "from_address", "sent_at", "is_archived" ], "title": "EmailListItem", "type": "object" }, "EmailListResponse": { "description": "Paginated list of emails with metadata.\n\nUsed in GET /api/v1/emails response.\n\nAttributes:\n items: Array of EmailListItem objects\n pagination: Pagination metadata\n\nExample:\n {\n \"items\": [{...}, {...}],\n \"pagination\": {\"total\": 127, \"limit\": 50, \"offset\": 0, \"has_more\": true}\n }", "properties": { "items": { "description": "Array of email items", "items": { "$ref": "#/components/schemas/EmailListItem" }, "title": "Items", "type": "array" }, "matching_email_count": { "default": 0, "description": "All messages matching the filters before thread collapsing or pagination.", "minimum": 0.0, "title": "Matching Email Count", "type": "integer" }, "pagination": { "$ref": "#/components/schemas/api_service__models__email_base__PaginationInfo", "description": "Thread-head pagination metadata" }, "split_counts": { "anyOf": [ { "$ref": "#/components/schemas/EmailListSplitCounts" }, { "type": "null" } ], "description": "Each inbox split's thread count under the same filters; present only when include_split_counts=true on an inbox listing." } }, "required": [ "items", "pagination" ], "title": "EmailListResponse", "type": "object" }, "EmailListSplitCounts": { "description": "Thread heads in each inbox split under one list request's filters (TIDY-18527).\n\nEach count is what ``pagination.total`` would read for the same request\nwith ``split`` set to that value, so a caller reading one view of the inbox\nlearns the others exist and how large they are.", "properties": { "feed": { "description": "Threads in split=feed.", "minimum": 0.0, "title": "Feed", "type": "integer" }, "important": { "description": "Threads in split=important.", "minimum": 0.0, "title": "Important", "type": "integer" }, "paper_trail": { "description": "Threads in split=paper_trail.", "minimum": 0.0, "title": "Paper Trail", "type": "integer" }, "screening": { "description": "Threads in split=screening: mail from senders awaiting approval, which no other inbox view includes.", "minimum": 0.0, "title": "Screening", "type": "integer" } }, "required": [ "important", "feed", "paper_trail", "screening" ], "title": "EmailListSplitCounts", "type": "object" }, "EmailMemoryBackfillCursor": { "additionalProperties": false, "description": "The resume cursor — exactly the shape the response's next_cursor carries.\n\nBoth fields are required: a half cursor would silently re-scan from the\nbeginning of the tenant.", "properties": { "after_id": { "format": "uuid", "title": "After Id", "type": "string" }, "after_sent_at": { "format": "date-time", "title": "After Sent At", "type": "string" } }, "required": [ "after_sent_at", "after_id" ], "title": "EmailMemoryBackfillCursor", "type": "object" }, "EmailMemoryBackfillRequest": { "additionalProperties": false, "description": "Request for one window of the historical email→memory backfill.\n\nextra=\"forbid\" is load-bearing: the pre-fix contract took flat\nafter_sent_at/after_id while next_cursor came back nested, so passing\nnext_cursor straight back was silently ignored and every iteration\nrestarted the sweep from the tenant's beginning. An unknown key is now a\n422, never a silent restart.", "properties": { "batch_size": { "default": 200, "maximum": 500.0, "minimum": 1.0, "title": "Batch Size", "type": "integer" }, "cursor": { "anyOf": [ { "$ref": "#/components/schemas/EmailMemoryBackfillCursor" }, { "type": "null" } ] }, "dry_run": { "default": false, "title": "Dry Run", "type": "boolean" }, "max_emails": { "default": 1000, "maximum": 10000.0, "minimum": 1.0, "title": "Max Emails", "type": "integer" }, "tenant_id": { "format": "uuid", "title": "Tenant Id", "type": "string" } }, "required": [ "tenant_id" ], "title": "EmailMemoryBackfillRequest", "type": "object" }, "EmailNoteItem": { "description": "A single note attached to an email (list-response item).", "properties": { "content": { "description": "Note text content", "title": "Content", "type": "string" }, "created_at": { "description": "When the note was created", "format": "date-time", "title": "Created At", "type": "string" }, "created_by": { "description": "Author account UUID", "format": "uuid", "title": "Created By", "type": "string" }, "email_id": { "description": "Email the note is attached to", "format": "uuid", "title": "Email Id", "type": "string" }, "id": { "description": "Note UUID", "format": "uuid", "title": "Id", "type": "string" }, "note_type": { "default": "user", "description": "Source of note", "title": "Note Type", "type": "string" }, "thread_id": { "description": "Thread the note belongs to", "format": "uuid", "title": "Thread Id", "type": "string" } }, "required": [ "id", "email_id", "thread_id", "content", "created_at", "created_by" ], "title": "EmailNoteItem", "type": "object" }, "EmailNotesListResponse": { "description": "Response for listing notes on an email.", "properties": { "notes": { "description": "Notes authored by the current account on this email", "items": { "$ref": "#/components/schemas/EmailNoteItem" }, "title": "Notes", "type": "array" }, "total_count": { "description": "Total number of notes", "title": "Total Count", "type": "integer" } }, "required": [ "total_count" ], "title": "EmailNotesListResponse", "type": "object" }, "EmailPhotoExtractItem": { "description": "Per-attachment extraction outcome (partial success allowed).", "properties": { "already_ingested": { "default": false, "title": "Already Ingested", "type": "boolean" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Error" }, "filename": { "title": "Filename", "type": "string" }, "photo_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "default": null, "title": "Photo Id" } }, "required": [ "filename" ], "title": "EmailPhotoExtractItem", "type": "object" }, "EmailPhotoExtractRequest": { "description": "Request body for explicit email-attachment photo extraction (S12).", "properties": { "email_canonical_id": { "format": "uuid", "title": "Email Canonical Id", "type": "string" }, "filenames": { "items": { "type": "string" }, "maxItems": 50, "minItems": 1, "title": "Filenames", "type": "array" }, "tz": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Caller's IANA timezone (browser tz) for the today-journal landing.", "title": "Tz" } }, "required": [ "email_canonical_id", "filenames" ], "title": "EmailPhotoExtractRequest", "type": "object" }, "EmailPhotoExtractResponse": { "description": "Response for an email-attachment extraction call.", "properties": { "collage_note_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "default": null, "title": "Collage Note Id" }, "journal_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "default": null, "title": "Journal Id" }, "photos": { "items": { "$ref": "#/components/schemas/EmailPhotoExtractItem" }, "title": "Photos", "type": "array" } }, "required": [ "photos" ], "title": "EmailPhotoExtractResponse", "type": "object" }, "EmailPreferencesPatch": { "description": "Partial update — only supplied fields are written.\n\nPer TIDY-A-608 §10.4, OOO and signature fields live on\n``public.user_preferences`` (per-user), while ``default_send_as_email``\nlives on ``tenants`` (tenant-wide).", "properties": { "default_send_as_email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Default Send As Email" }, "out_of_office_enabled": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Out Of Office Enabled" }, "out_of_office_end_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Out Of Office End At" }, "out_of_office_start_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Out Of Office Start At" }, "out_of_office_template_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Out Of Office Template Id" }, "reply_outside_signature_template_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Reply Outside Signature Template Id" }, "reply_within_signature_template_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Reply Within Signature Template Id" } }, "title": "EmailPreferencesPatch", "type": "object" }, "EmailPreferencesResponse": { "description": "Combined tenant + user email preferences.", "properties": { "default_send_as_email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Default send-as email address. Null means first primary address.", "title": "Default Send As Email" }, "out_of_office_enabled": { "default": false, "title": "Out Of Office Enabled", "type": "boolean" }, "out_of_office_end_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Out Of Office End At" }, "out_of_office_start_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Out Of Office Start At" }, "out_of_office_template_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "default": null, "title": "Out Of Office Template Id" }, "reply_outside_signature_template_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "default": null, "title": "Reply Outside Signature Template Id" }, "reply_within_signature_template_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "default": null, "title": "Reply Within Signature Template Id" } }, "title": "EmailPreferencesResponse", "type": "object" }, "EmailPreferencesUpdate": { "description": "Replace tenant-scoped email preferences. Used by legacy PUT clients\nthat only know about ``default_send_as_email``.", "properties": { "default_send_as_email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Email address to set as default. Null to clear.", "title": "Default Send As Email" } }, "title": "EmailPreferencesUpdate", "type": "object" }, "EmailQuarantineActionResponse": { "properties": { "action": { "title": "Action", "type": "string" }, "changed": { "title": "Changed", "type": "boolean" }, "email_id": { "format": "uuid", "title": "Email Id", "type": "string" } }, "required": [ "email_id", "action", "changed" ], "title": "EmailQuarantineActionResponse", "type": "object" }, "EmailReaderAttachmentSummary": { "description": "Compact attachment summary for the assistant email reader (TIDY-13457).\n\nTells the model what attachments an email carries and whether their\nextracted text is available to read via getEmailAttachmentText.", "properties": { "content_type": { "description": "MIME type", "title": "Content Type", "type": "string" }, "filename": { "description": "Original attachment filename", "title": "Filename", "type": "string" }, "has_extracted_text": { "default": false, "description": "True when extracted markdown text is available to read", "title": "Has Extracted Text", "type": "boolean" }, "processed": { "default": false, "description": "True when the docling pipeline finished extracting this attachment", "title": "Processed", "type": "boolean" }, "processing_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "processed_attachments.processing_status, if a row exists", "title": "Processing Status" }, "size": { "default": 0, "description": "File size in bytes", "title": "Size", "type": "integer" } }, "required": [ "filename", "content_type" ], "title": "EmailReaderAttachmentSummary", "type": "object" }, "EmailReaderContentResponse": { "description": "Cleaned, model-readable email content for the assistant (TIDY-13457).\n\nReturns readable text chosen from the best available body variant\n(message_content -> body_markdown -> body_text -> html-to-text(body_html)),\nnever raw HTML, plus a compact attachment summary. Truncation is explicit.", "properties": { "attachments": { "description": "Attachment summaries for this email", "items": { "$ref": "#/components/schemas/EmailReaderAttachmentSummary" }, "title": "Attachments", "type": "array" }, "content": { "default": "", "description": "Cleaned readable body text (never raw HTML)", "title": "Content", "type": "string" }, "content_source": { "default": "none", "description": "Which variant produced content: message_content | body_markdown | body_text | html_to_text | none", "title": "Content Source", "type": "string" }, "from_address": { "default": "", "description": "Sender address", "title": "From Address", "type": "string" }, "from_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Sender display name", "title": "From Name" }, "full_length": { "default": 0, "description": "Character length of the untruncated content", "title": "Full Length", "type": "integer" }, "id": { "description": "email_canonical id", "format": "uuid", "title": "Id", "type": "string" }, "sent_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "description": "When the email was sent", "title": "Sent At" }, "subject": { "description": "Email subject", "title": "Subject", "type": "string" }, "truncated": { "default": false, "description": "True when content was cut to the length cap", "title": "Truncated", "type": "boolean" } }, "required": [ "id", "subject" ], "title": "EmailReaderContentResponse", "type": "object" }, "EmailRecipient": { "description": "Email recipient with address and optional name.", "properties": { "address": { "default": "", "description": "Email address", "title": "Address", "type": "string" }, "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Entity id for non-email recipients such as groups", "title": "Id" }, "member_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Member count for group recipients", "title": "Member Count" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Display name", "title": "Name" }, "type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": "contact", "description": "Recipient type: contact or group", "title": "Type" } }, "title": "EmailRecipient", "type": "object" }, "EmailScreeningAuditResponse": { "properties": { "hint": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Hint" }, "junk_keys": { "items": { "$ref": "#/components/schemas/JunkKeyOut" }, "title": "Junk Keys", "type": "array" }, "orphan_pending": { "items": { "$ref": "#/components/schemas/StuckEmailOut" }, "title": "Orphan Pending", "type": "array" }, "pending_from_decided_senders": { "items": { "$ref": "#/components/schemas/StuckEmailOut" }, "title": "Pending From Decided Senders", "type": "array" }, "screening_held_runs": { "items": { "$ref": "#/components/schemas/StuckEmailOut" }, "title": "Screening Held Runs", "type": "array" } }, "title": "EmailScreeningAuditResponse", "type": "object" }, "EmailScreeningExplainResponse": { "properties": { "email_id": { "title": "Email Id", "type": "string" }, "from_address": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "From Address" }, "from_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "From Name" }, "hint": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Hint" }, "inbox_split": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Inbox Split" }, "pipeline": { "$ref": "#/components/schemas/PipelineSnapshot" }, "reasons": { "items": { "type": "string" }, "title": "Reasons", "type": "array" }, "screening_resumed_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Screening Resumed At" }, "screening_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Screening Status" }, "sender_keys": { "items": { "$ref": "#/components/schemas/SenderScreeningKey" }, "title": "Sender Keys", "type": "array" }, "subject": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Subject" }, "tidy_folder": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Tidy Folder" }, "visible_in": { "items": { "type": "string" }, "title": "Visible In", "type": "array" } }, "required": [ "email_id" ], "title": "EmailScreeningExplainResponse", "type": "object" }, "EmailSourceConfigResponse": { "description": "An email source configuration tied to a provider connection.", "properties": { "email_address": { "description": "Email address for this source", "title": "Email Address", "type": "string" }, "folders_to_sync": { "description": "Folders/labels to sync", "items": { "type": "string" }, "title": "Folders To Sync", "type": "array" }, "id": { "description": "Config UUID", "title": "Id", "type": "string" }, "imap_host": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "IMAP server hostname", "title": "Imap Host" }, "imap_port": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "IMAP server port", "title": "Imap Port" }, "provider_connection_id": { "description": "Parent connection UUID", "title": "Provider Connection Id", "type": "string" }, "smtp_host": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "SMTP server hostname", "title": "Smtp Host" }, "smtp_port": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "SMTP server port", "title": "Smtp Port" }, "status": { "$ref": "#/components/schemas/EmailSourceConfigStatus", "default": "active", "description": "Config status" }, "sync_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Opaque sync cursor/token", "title": "Sync Cursor" }, "tenant_id": { "description": "Tenant UUID", "title": "Tenant Id", "type": "string" } }, "required": [ "id", "provider_connection_id", "tenant_id", "email_address" ], "title": "EmailSourceConfigResponse", "type": "object" }, "EmailSourceConfigStatus": { "description": "Email source config sync status.", "enum": [ "active", "paused", "error" ], "title": "EmailSourceConfigStatus", "type": "string" }, "EmailSourceItem": { "description": "Email source for filtering.", "properties": { "display_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Display name", "title": "Display Name" }, "email_address": { "description": "Email address", "title": "Email Address", "type": "string" }, "id": { "description": "Email source UUID", "format": "uuid", "title": "Id", "type": "string" }, "provider": { "description": "Provider: gmail, imap, etc.", "title": "Provider", "type": "string" } }, "required": [ "id", "email_address", "provider" ], "title": "EmailSourceItem", "type": "object" }, "EmailSourcesResponse": { "description": "Response for available email sources endpoint.", "properties": { "count": { "description": "Number of sources", "title": "Count", "type": "integer" }, "sources": { "description": "List of email sources", "items": { "$ref": "#/components/schemas/EmailSourceItem" }, "title": "Sources", "type": "array" } }, "required": [ "sources", "count" ], "title": "EmailSourcesResponse", "type": "object" }, "EmailSummary": { "description": "Summary of a related email.", "properties": { "from_address": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Sender email address", "title": "From Address" }, "id": { "description": "Email ID (UUID)", "title": "Id", "type": "string" }, "link_direction": { "default": "outgoing", "description": "Direction of the edge relative to the primitive you asked about: 'outgoing' (the edge starts there and points at this one) or 'incoming' (this one points AT it). TIDY-15687.", "title": "Link Direction", "type": "string" }, "link_type": { "description": "How this email is related", "title": "Link Type", "type": "string" }, "received_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "description": "When the email was received", "title": "Received At" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Email subject (resolved as title)", "title": "Title" }, "type": { "const": "email", "default": "email", "title": "Type", "type": "string" } }, "required": [ "id", "link_type" ], "title": "EmailSummary", "type": "object" }, "EmailSummaryResponse": { "properties": { "avg_response_time_seconds": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Avg Response Time Seconds" }, "engagement": { "anyOf": [ { "$ref": "#/components/schemas/EngagementMetrics" }, { "type": "null" } ] }, "inbox_split": { "$ref": "#/components/schemas/InboxSplitCounts" }, "median_response_time_seconds": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Median Response Time Seconds" }, "period_comparison": { "$ref": "#/components/schemas/PeriodComparison" }, "reply_rate_pct": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Reply Rate Pct" }, "top_category": { "anyOf": [ { "$ref": "#/components/schemas/CategoryCount" }, { "type": "null" } ] }, "total_received": { "title": "Total Received", "type": "integer" }, "total_sent": { "title": "Total Sent", "type": "integer" }, "unresponded_count": { "title": "Unresponded Count", "type": "integer" } }, "required": [ "total_received", "total_sent", "avg_response_time_seconds", "median_response_time_seconds", "reply_rate_pct", "unresponded_count", "top_category", "inbox_split", "period_comparison" ], "title": "EmailSummaryResponse", "type": "object" }, "EmailTrigger": { "additionalProperties": false, "description": "Fires on an inbound-mail happening (TIDY-16717 / S2, R4).\n\nEmails are NOT facet items, so an email rule is system-lane exactly like\n``system_event``: ``facet_id`` must be null and the trigger context\ncarries an email SNAPSHOT (``{{trigger.email.*}}``) instead of a facet\nitem. The three events map 1:1 onto the ``email.*`` outbox vocabulary the\ncanonical writers emit:\n\n * ``received`` — a new message was ingested (``email.received``)\n * ``entered_folder`` — it landed in ``folder`` (``email.entered_folder``)\n * ``label_applied`` — it gained ``label`` (``email.label_applied``)\n\n``folder``/``label`` NARROW the event; omitting them fires on any folder /\nany label. A folder value is a ``tidy_folder`` string — one of the Tidy\nbuckets or ``custom:`` (the S1 defense-routing target).", "properties": { "event": { "enum": [ "received", "entered_folder", "label_applied" ], "title": "Event", "type": "string" }, "folder": { "anyOf": [ { "maxLength": 512, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Folder" }, "kind": { "const": "email", "title": "Kind", "type": "string" }, "label": { "anyOf": [ { "maxLength": 128, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Label" } }, "required": [ "kind", "event" ], "title": "EmailTrigger", "type": "object" }, "EmailTriggerPreviewRequest": { "additionalProperties": false, "properties": { "conditions": { "$ref": "#/components/schemas/ConditionGroup" }, "days": { "default": 7, "maximum": 30.0, "minimum": 1.0, "title": "Days", "type": "integer" }, "sample_limit": { "default": 5, "maximum": 25.0, "minimum": 0.0, "title": "Sample Limit", "type": "integer" }, "trigger": { "$ref": "#/components/schemas/EmailTrigger" } }, "required": [ "trigger" ], "title": "EmailTriggerPreviewRequest", "type": "object" }, "EmailTriggerPreviewResponse": { "description": "``matched_count`` counts messages in the window the rule WOULD have\nfired on. ``scanned_count`` is the window's corpus size, so a zero match\nis legible as \"nothing matched\" rather than \"nothing to match\".", "properties": { "days": { "title": "Days", "type": "integer" }, "matched_count": { "title": "Matched Count", "type": "integer" }, "samples": { "items": { "$ref": "#/components/schemas/EmailTriggerPreviewSample" }, "title": "Samples", "type": "array" }, "scanned_count": { "title": "Scanned Count", "type": "integer" } }, "required": [ "matched_count", "scanned_count", "days" ], "title": "EmailTriggerPreviewResponse", "type": "object" }, "EmailTriggerPreviewSample": { "properties": { "email_id": { "title": "Email Id", "type": "string" }, "folder": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Folder" }, "received_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Received At" }, "sender_address": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Sender Address" }, "subject": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Subject" } }, "required": [ "email_id" ], "title": "EmailTriggerPreviewSample", "type": "object" }, "EmailViewResponse": { "description": "Response for email view endpoint (legacy format).", "properties": { "downloadUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Downloadurl" }, "email": { "$ref": "#/components/schemas/ParsedEmail" }, "sourcePath": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Sourcepath" } }, "required": [ "email" ], "title": "EmailViewResponse", "type": "object" }, "EmailWritebackJobResponse": { "properties": { "action_type": { "title": "Action Type", "type": "string" }, "attempt_count": { "title": "Attempt Count", "type": "integer" }, "completed_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Completed At" }, "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "email_id": { "format": "uuid", "title": "Email Id", "type": "string" }, "email_source_config_id": { "format": "uuid", "title": "Email Source Config Id", "type": "string" }, "id": { "format": "uuid", "title": "Id", "type": "string" }, "imap_folder": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Imap Folder" }, "last_error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Last Error" }, "source_email_address": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Source Email Address" }, "status": { "title": "Status", "type": "string" }, "subject": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Subject" }, "target_folder": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Target Folder" }, "tenant_id": { "format": "uuid", "title": "Tenant Id", "type": "string" }, "updated_at": { "format": "date-time", "title": "Updated At", "type": "string" } }, "required": [ "id", "tenant_id", "email_id", "email_source_config_id", "action_type", "status", "attempt_count", "created_at", "updated_at" ], "title": "EmailWritebackJobResponse", "type": "object" }, "EmailWritebackRetryResponse": { "properties": { "message": { "title": "Message", "type": "string" }, "success": { "description": "Whether the retry request was accepted", "title": "Success", "type": "boolean" } }, "required": [ "success", "message" ], "title": "EmailWritebackRetryResponse", "type": "object" }, "EmbedBlockRequest": { "properties": { "primitive_id": { "description": "Typed id (e.g. A-, C-) or bare uuid of the row to embed.", "minLength": 1, "title": "Primitive Id", "type": "string" }, "primitive_type": { "description": "Kind of row to embed: note, task/activity, contact, event/calendar_event, organization, journal, or reminder.", "minLength": 1, "title": "Primitive Type", "type": "string" } }, "required": [ "primitive_type", "primitive_id" ], "title": "EmbedBlockRequest", "type": "object" }, "EmbedExpandRequest": { "properties": { "facet_id": { "maxLength": 120, "minLength": 1, "title": "Facet Id", "type": "string" }, "facet_type": { "maxLength": 80, "minLength": 1, "title": "Facet Type", "type": "string" }, "room_id": { "maxLength": 255, "minLength": 1, "title": "Room Id", "type": "string" } }, "required": [ "room_id", "facet_type", "facet_id" ], "title": "EmbedExpandRequest", "type": "object" }, "EmbedResult": { "properties": { "event_id": { "title": "Event Id", "type": "string" }, "facet_id": { "title": "Facet Id", "type": "string" }, "facet_type": { "title": "Facet Type", "type": "string" }, "room_id": { "title": "Room Id", "type": "string" }, "room_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Room Name" }, "score": { "title": "Score", "type": "number" }, "sender_name": { "title": "Sender Name", "type": "string" }, "ts": { "format": "date-time", "title": "Ts", "type": "string" } }, "required": [ "facet_type", "facet_id", "event_id", "room_id", "room_name", "sender_name", "ts", "score" ], "title": "EmbedResult", "type": "object" }, "EmbedSummary": { "properties": { "facet_id": { "title": "Facet Id", "type": "string" }, "facet_type": { "title": "Facet Type", "type": "string" } }, "required": [ "facet_type", "facet_id" ], "title": "EmbedSummary", "type": "object" }, "EmbedViewRequest": { "properties": { "view_id": { "description": "The saved database-view record id (a records row with facet_slug='database', as returned by createSavedDatabaseView) — bare uuid or a typed id. Embedded inline in the note body as a `database` node (TIDY-14305 / B6: embedded, not linked).", "minLength": 1, "title": "View Id", "type": "string" } }, "required": [ "view_id" ], "title": "EmbedViewRequest", "type": "object" }, "EmployeeAgentSettingsPayload": { "properties": { "default_playback_speed": { "default": 1.0, "title": "Default Playback Speed", "type": "number" }, "default_project_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "default": null, "title": "Default Project Id" }, "default_voice_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Default Voice Id" }, "harness_skills": { "anyOf": [ { "additionalProperties": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ] }, "maxProperties": 6, "type": "object" }, { "type": "null" } ], "default": null, "title": "Harness Skills" }, "manners_markdown": { "default": "# TIDY MANNERS\n\nYou are connected to Tidy as a virtual employee.\n\nWhen you are in a group chat, you can read the conversation for context, but you should not reply to every message. Speak up when someone addresses you by name, asks you a question, delegates a task to you, replies to your current work, or you need to report meaningful progress, a blocker, or completion. Answer once, in the thread you were reached in. Never reply only to agree, thank or acknowledge, and never repeat what someone else already said.\n\nDo not assume every group message is for you. If the conversation is between other people or other employees, follow along silently. If you are unsure whether you are being asked to act, ask one short clarifying question or wait.\n\nDo not take action on private data or delegated work unless Tidy grants you the needed tool access.\n\n## Work skill-first\n\nBefore starting any multi-step task, list your installed skills and read the one that matches the task: its SKILL.md first, then only the reference file it points you to for this task, not every file. It carries the commands, paths, credentials, and failure remedies you would otherwise rediscover by trial and error. Follow the matching skill's steps instead of probing with ad-hoc terminal commands. Improvise only when no installed skill matches the task.\n\n## Colleagues and your inbox\n\nYou may work alongside other virtual employees. To tell, ask, or update a colleague, call `message_employee` with their name, and pass the item's `item_ref` when the message is about one. On shared work, a comment on the task that @mentions their handle reaches them too. `send_to_assistant` reaches Tidy's built-in assistant, never a colleague, and its reply is not theirs.\n\nMessages colleagues send you and @mentions waiting on you are in your inbox. Check it with `agent_inbox` when you start work, and before you tell anyone whether a message arrived. Answer a comment mention with `comment_reply` in its thread; reply to a colleague with `message_employee`.\n\nTidy also keeps a home room for you, where it posts system alerts. It is not a chat and no one waits in it to talk; every mention and colleague message it alerts you to is also in `agent_inbox`.\n\n## Shared knowledge framing\n\nTidy's memory holds facts from ALL of the user's assistants and from their notes, email, calendar and contacts, and recalls the ones relevant to a message for you under \"Personal Context\". Present a shared fact that did not come from your own conversation with this user as Tidy's record (\"our records show the launch moved to March\"), NEVER as your own history with them (\"as we discussed\", \"you told me\"): that fabricates a history and breaks their trust.\n\n## Recording and correcting memory\n\nWrite to memory only deliberately, never every turn. The tidy-mcp skill says when to correct a fact in the user's shared memory, when to keep a note of your own, and how to check what you remember.", "title": "Manners Markdown", "type": "string" }, "runtime_skills": { "items": { "$ref": "#/components/schemas/RuntimeSkillInfo" }, "title": "Runtime Skills", "type": "array" }, "skill_catalogue": { "items": { "$ref": "#/components/schemas/AgentSkillCatalogueEntry" }, "title": "Skill Catalogue", "type": "array" }, "skill_selection_basis": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Skill Selection Basis" }, "skills": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "default": null, "title": "Skills" }, "soul_markdown": { "default": "", "title": "Soul Markdown", "type": "string" }, "voice_engine": { "default": "gemini-realtime", "pattern": "^(gemini-realtime|self-hosted|openai-realtime)$", "title": "Voice Engine", "type": "string" } }, "title": "EmployeeAgentSettingsPayload", "type": "object" }, "EmployeeAgentSettingsPayload-Input": { "properties": { "default_playback_speed": { "default": 1.0, "title": "Default Playback Speed", "type": "number" }, "default_project_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Default Project Id" }, "default_voice_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Default Voice Id" }, "harness_skills": { "anyOf": [ { "additionalProperties": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ] }, "maxProperties": 6, "type": "object" }, { "type": "null" } ], "title": "Harness Skills" }, "manners_markdown": { "default": "# TIDY MANNERS\n\nYou are connected to Tidy as a virtual employee.\n\nWhen you are in a group chat, you can read the conversation for context, but you should not reply to every message. Speak up when someone addresses you by name, asks you a question, delegates a task to you, replies to your current work, or you need to report meaningful progress, a blocker, or completion. Answer once, in the thread you were reached in. Never reply only to agree, thank or acknowledge, and never repeat what someone else already said.\n\nDo not assume every group message is for you. If the conversation is between other people or other employees, follow along silently. If you are unsure whether you are being asked to act, ask one short clarifying question or wait.\n\nDo not take action on private data or delegated work unless Tidy grants you the needed tool access.\n\n## Work skill-first\n\nBefore starting any multi-step task, list your installed skills and read the one that matches the task: its SKILL.md first, then only the reference file it points you to for this task, not every file. It carries the commands, paths, credentials, and failure remedies you would otherwise rediscover by trial and error. Follow the matching skill's steps instead of probing with ad-hoc terminal commands. Improvise only when no installed skill matches the task.\n\n## Colleagues and your inbox\n\nYou may work alongside other virtual employees. To tell, ask, or update a colleague, call `message_employee` with their name, and pass the item's `item_ref` when the message is about one. On shared work, a comment on the task that @mentions their handle reaches them too. `send_to_assistant` reaches Tidy's built-in assistant, never a colleague, and its reply is not theirs.\n\nMessages colleagues send you and @mentions waiting on you are in your inbox. Check it with `agent_inbox` when you start work, and before you tell anyone whether a message arrived. Answer a comment mention with `comment_reply` in its thread; reply to a colleague with `message_employee`.\n\nTidy also keeps a home room for you, where it posts system alerts. It is not a chat and no one waits in it to talk; every mention and colleague message it alerts you to is also in `agent_inbox`.\n\n## Shared knowledge framing\n\nTidy's memory holds facts from ALL of the user's assistants and from their notes, email, calendar and contacts, and recalls the ones relevant to a message for you under \"Personal Context\". Present a shared fact that did not come from your own conversation with this user as Tidy's record (\"our records show the launch moved to March\"), NEVER as your own history with them (\"as we discussed\", \"you told me\"): that fabricates a history and breaks their trust.\n\n## Recording and correcting memory\n\nWrite to memory only deliberately, never every turn. The tidy-mcp skill says when to correct a fact in the user's shared memory, when to keep a note of your own, and how to check what you remember.", "title": "Manners Markdown", "type": "string" }, "runtime_skills": { "items": { "$ref": "#/components/schemas/RuntimeSkillInfo-Input" }, "title": "Runtime Skills", "type": "array" }, "skill_catalogue": { "items": { "$ref": "#/components/schemas/AgentSkillCatalogueEntry-Input" }, "title": "Skill Catalogue", "type": "array" }, "skill_selection_basis": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Skill Selection Basis" }, "skills": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Skills" }, "soul_markdown": { "default": "", "title": "Soul Markdown", "type": "string" }, "voice_engine": { "default": "gemini-realtime", "pattern": "^(gemini-realtime|self-hosted|openai-realtime)$", "title": "Voice Engine", "type": "string" } }, "title": "EmployeeAgentSettingsPayload", "type": "object" }, "EmployeeAgentSettingsPayload-Output": {}, "EmployeeConfigurationResponse": { "description": "An employee's work policy and standing instructions, after a change.", "properties": { "account_id": { "title": "Account Id", "type": "string" }, "authority": { "description": "Why you may change it: a workspace Owner/Admin, its owner, or its direct manager on the team Org chart.", "enum": [ "admin", "owner", "manager" ], "title": "Authority", "type": "string" }, "available_states": { "description": "The states a policy may name: the workspace's task states, then any on its backlog.", "items": { "type": "string" }, "title": "Available States", "type": "array" }, "changed": { "description": "False when the request matched what was set.", "title": "Changed", "type": "boolean" }, "employee": { "description": "Its slug.", "title": "Employee", "type": "string" }, "employee_name": { "title": "Employee Name", "type": "string" }, "policy_source": { "enum": [ "employee", "workspace", "default" ], "title": "Policy Source", "type": "string" }, "standing_instructions": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Standing Instructions" }, "standing_instructions_changed": { "anyOf": [ { "$ref": "#/components/schemas/ConfigurationChange" }, { "type": "null" } ], "default": null }, "standing_instructions_sha256": { "description": "sha256 of the instructions (of an empty text when there are none).", "title": "Standing Instructions Sha256", "type": "string" }, "wakes_for": { "description": "The states that wake it on its own (TIDY-20074): the policy as one list.", "items": { "type": "string" }, "title": "Wakes For", "type": "array" }, "work_policy": { "$ref": "#/components/schemas/VeWorkPolicy", "description": "The policy its heartbeat follows." }, "work_policy_changed": { "anyOf": [ { "$ref": "#/components/schemas/ConfigurationChange" }, { "type": "null" } ], "default": null } }, "required": [ "employee", "employee_name", "account_id", "changed", "authority", "work_policy", "wakes_for", "policy_source", "available_states", "standing_instructions_sha256" ], "title": "EmployeeConfigurationResponse", "type": "object" }, "EmployeeConversationWorktrees": { "description": "TIDY-20066 F12 — a separate working copy (git worktree) per conversation.", "properties": { "default": { "description": "What a project without its own choice gets. Off unless chosen.", "title": "Default", "type": "boolean" }, "projects": { "description": "Projects the caller can choose for its conversations that are linked to a repository, including before their workshop folder is ready. A choice grants no project access.", "items": { "$ref": "#/components/schemas/ConversationWorktreeProject" }, "title": "Projects", "type": "array" } }, "required": [ "default", "projects" ], "title": "EmployeeConversationWorktrees", "type": "object" }, "EmployeeDefinitionRequest": { "description": "One hosted employee, defined whole (TIDY-19500 F2, D9).\n\nRequired at hire: ``display_name``, a one-line ``role_title`` and the\n``soul_markdown``. Automatic when omitted: ``mention_handle`` (from the\nname), ``voice_id`` (a Kokoro preset), ``reflection_cadence`` (weekly) and\nthe heartbeat. Everything else is optional and can be added later through\nits own endpoint.", "properties": { "display_name": { "maxLength": 120, "minLength": 1, "title": "Display Name", "type": "string" }, "heartbeat_enabled": { "default": true, "title": "Heartbeat Enabled", "type": "boolean" }, "hire_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Hire Id" }, "manners_markdown": { "default": "# TIDY MANNERS\n\nYou are connected to Tidy as a virtual employee.\n\nWhen you are in a group chat, you can read the conversation for context, but you should not reply to every message. Speak up when someone addresses you by name, asks you a question, delegates a task to you, replies to your current work, or you need to report meaningful progress, a blocker, or completion. Answer once, in the thread you were reached in. Never reply only to agree, thank or acknowledge, and never repeat what someone else already said.\n\nDo not assume every group message is for you. If the conversation is between other people or other employees, follow along silently. If you are unsure whether you are being asked to act, ask one short clarifying question or wait.\n\nDo not take action on private data or delegated work unless Tidy grants you the needed tool access.\n\n## Work skill-first\n\nBefore starting any multi-step task, list your installed skills and read the one that matches the task: its SKILL.md first, then only the reference file it points you to for this task, not every file. It carries the commands, paths, credentials, and failure remedies you would otherwise rediscover by trial and error. Follow the matching skill's steps instead of probing with ad-hoc terminal commands. Improvise only when no installed skill matches the task.\n\n## Colleagues and your inbox\n\nYou may work alongside other virtual employees. To tell, ask, or update a colleague, call `message_employee` with their name, and pass the item's `item_ref` when the message is about one. On shared work, a comment on the task that @mentions their handle reaches them too. `send_to_assistant` reaches Tidy's built-in assistant, never a colleague, and its reply is not theirs.\n\nMessages colleagues send you and @mentions waiting on you are in your inbox. Check it with `agent_inbox` when you start work, and before you tell anyone whether a message arrived. Answer a comment mention with `comment_reply` in its thread; reply to a colleague with `message_employee`.\n\nTidy also keeps a home room for you, where it posts system alerts. It is not a chat and no one waits in it to talk; every mention and colleague message it alerts you to is also in `agent_inbox`.\n\n## Shared knowledge framing\n\nTidy's memory holds facts from ALL of the user's assistants and from their notes, email, calendar and contacts, and recalls the ones relevant to a message for you under \"Personal Context\". Present a shared fact that did not come from your own conversation with this user as Tidy's record (\"our records show the launch moved to March\"), NEVER as your own history with them (\"as we discussed\", \"you told me\"): that fabricates a history and breaks their trust.\n\n## Recording and correcting memory\n\nWrite to memory only deliberately, never every turn. The tidy-mcp skill says when to correct a fact in the user's shared memory, when to keep a note of your own, and how to check what you remember.", "maxLength": 20000, "title": "Manners Markdown", "type": "string" }, "mention_handle": { "anyOf": [ { "maxLength": 80, "minLength": 2, "type": "string" }, { "type": "null" } ], "title": "Mention Handle" }, "model_access": { "anyOf": [ { "$ref": "#/components/schemas/EmployeeModelAccess" }, { "type": "null" } ] }, "objectives": { "items": { "$ref": "#/components/schemas/EmployeeObjective" }, "maxItems": 10, "title": "Objectives", "type": "array" }, "reflection_cadence": { "anyOf": [ { "maxLength": 32, "pattern": "^P(?:\\d+D)?(?:T(?:\\d+H)?(?:\\d+M)?)?$", "type": "string" }, { "type": "null" } ], "default": "P7D", "title": "Reflection Cadence" }, "reports_to": { "anyOf": [ { "$ref": "#/components/schemas/EmployeeReportsTo" }, { "type": "null" } ] }, "role_title": { "maxLength": 160, "minLength": 1, "title": "Role Title", "type": "string" }, "scheduled_jobs": { "items": { "$ref": "#/components/schemas/EmployeeScheduledJob" }, "maxItems": 10, "title": "Scheduled Jobs", "type": "array" }, "skills": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Skills" }, "soul_markdown": { "maxLength": 20000, "minLength": 1, "title": "Soul Markdown", "type": "string" }, "template_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Template Id" }, "voice_id": { "anyOf": [ { "maxLength": 120, "type": "string" }, { "type": "null" } ], "title": "Voice Id" } }, "required": [ "display_name", "role_title", "soul_markdown" ], "title": "EmployeeDefinitionRequest", "type": "object" }, "EmployeeDeployAccess": { "description": "One employee's consent within a roster redeploy.", "properties": { "agent_account_id": { "format": "uuid", "title": "Agent Account Id", "type": "string" }, "assign_pending": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Assign Pending" }, "plugin_access": { "anyOf": [ { "items": { "$ref": "#/components/schemas/PluginAccessChoice" }, "maxItems": 16, "type": "array" }, { "type": "null" } ], "title": "Plugin Access" }, "requirements_hash": { "anyOf": [ { "maxLength": 64, "minLength": 64, "type": "string" }, { "type": "null" } ], "title": "Requirements Hash" }, "secret_files": { "anyOf": [ { "items": { "$ref": "#/components/schemas/SecretFileChoice" }, "maxItems": 16, "type": "array" }, { "type": "null" } ], "title": "Secret Files" }, "skill_gives": { "items": { "$ref": "#/components/schemas/SkillGive" }, "maxItems": 64, "title": "Skill Gives", "type": "array" } }, "required": [ "agent_account_id" ], "title": "EmployeeDeployAccess", "type": "object" }, "EmployeeDeployPlan": { "properties": { "agent_account_id": { "title": "Agent Account Id", "type": "string" }, "display_name": { "title": "Display Name", "type": "string" }, "plan": { "$ref": "#/components/schemas/SkillPluginAccessPlan" } }, "required": [ "agent_account_id", "display_name", "plan" ], "title": "EmployeeDeployPlan", "type": "object" }, "EmployeeDmAttachBlock": { "additionalProperties": false, "description": "TIDY-18719 (D23) — one AG-UI `attach` block a DM may carry.\n\nThe shape is `@tidy/matrix-message-schema`'s `TidyAttachBlock`, narrowed to\nthe one block kind a DM sender may author. It is deliberately NOT a general\nblock channel: a DM cannot fabricate a tool call, a reasoning trace or a\nturn's answer, and `extra='forbid'` plus the payload cap keep this lane from\nbecoming one. The renderer keys on `attachment_type`; a type it does not\nknow degrades to the paperclip chip, so an unknown type is a forward\ncompatibility path, not an error — which is why it is bounded rather than\nenumerated here.", "properties": { "attachment_id": { "format": "uuid", "title": "Attachment Id", "type": "string" }, "attachment_type": { "description": "The typed kind a renderer keys on, e.g. `browser.session`.", "maxLength": 64, "minLength": 1, "title": "Attachment Type", "type": "string" }, "payload": { "additionalProperties": true, "description": "The attachment's own fields, serialized under 4096 bytes of JSON.", "title": "EmployeeDmAttachBlockPayload", "type": "object" }, "type": { "const": "attach", "title": "Type", "type": "string" } }, "required": [ "type", "attachment_id", "attachment_type", "payload" ], "title": "EmployeeDmAttachBlock", "type": "object" }, "EmployeeDmItemThread": { "properties": { "body": { "title": "Body", "type": "string" }, "body_withheld": { "default": false, "description": "True when body is redacted: caller cannot see the work or own either employee.", "title": "Body Withheld", "type": "boolean" }, "created_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Created At" }, "matrix_room_id": { "title": "Matrix Room Id", "type": "string" }, "resolution": { "title": "Resolution", "type": "string" }, "sender_display_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Sender Display Name" }, "sender_employee": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Sender Employee" }, "target_display_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Target Display Name" }, "target_employee": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Target Employee" } }, "required": [ "matrix_room_id", "body", "resolution" ], "title": "EmployeeDmItemThread", "type": "object" }, "EmployeeDmRequest": { "properties": { "blocks": { "anyOf": [ { "items": { "$ref": "#/components/schemas/EmployeeDmAttachBlock" }, "maxItems": 4, "type": "array" }, { "type": "null" } ], "description": "TIDY-18719 (D23) — AG-UI attach blocks appended to the message's structured content, so a live browser session (or the next typed attachment) lands in the thread as a card. Additive: `body` stays required and carries the text a client without the renderer shows.", "title": "Blocks" }, "body": { "description": "The message. Steer and inform — this channel cannot assign work.", "maxLength": 8000, "minLength": 1, "title": "Body", "type": "string" }, "confirm": { "default": false, "description": "TIDY-20074 F9 — send it anyway. An employee's messages to one colleague are braked past its hourly limit (5 unless its owner changed it): the next is not sent and is refused 409 `colleague_message_limit`, with the count and the suggestion to comment on the task instead. Sending the same message again with `confirm: true` delivers it; a confirm counts only after that refusal. A person's message is never braked.", "title": "Confirm", "type": "boolean" }, "conversation_ref": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "A specific conversation of that employee, when the message is about a thread rather than a work item. Takes precedence over `item_ref`. For an employee sender this is a STEER into that conversation, allowed only to the employee's manager, direct report or peer under the same manager, to the employee itself from another of its conversations (TIDY-20074 F8), and to its owner; anyone else is refused `not_in_direct_line` (TIDY-19705 F16). The person the sender works for must own the conversation or currently belong to its room: a read-only share is refused `conversation_read_only`. Without it an employee's message starts a new conversation.", "title": "Conversation Ref" }, "employee": { "description": "The employee's slug, @mention handle, or account id.", "maxLength": 200, "minLength": 1, "title": "Employee", "type": "string" }, "item_ref": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The work the message is about, as a typed id (`A-` task, `N-` note, `F-` file, `P-` project, `C-` contact, `V-` event). The platform resolves it to the employee's live conversation for that item.", "title": "Item Ref" }, "operation_key": { "anyOf": [ { "maxLength": 200, "minLength": 1, "type": "string" }, { "type": "null" } ], "description": "TIDY-19705 — the caller's retry identity for THIS message. A retry with the same key returns `delivery: duplicate` and the same refs, never a second message or turn; the same key with a different message is refused (409 `operation_key_reused`).", "title": "Operation Key" }, "turn_effort": { "anyOf": [ { "enum": [ "off", "minimal", "low", "medium", "high", "xhigh", "max" ], "type": "string" }, { "type": "null" } ], "description": "TIDY-20000 — how much the employee thinks on the turn THIS message starts, and that turn only; the conversation's own setting is untouched, so its next turn runs as before. Resolved against the conversation's model: the least effort it declares at or above this one, else its highest below. A model with no thinking setting runs the turn at the conversation's own effort; the response's `turn_effort` and `turn_effort_note` say what applies. Only a person's message: an employee's is refused (400 `turn_effort_unsupported`).", "title": "Turn Effort" } }, "required": [ "employee", "body" ], "title": "EmployeeDmRequest", "type": "object" }, "EmployeeDmResponse": { "properties": { "conversation_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "The conversation the message landed in. A person's message runs there as chat in their DM with the employee (TIDY-19705); read its status and the reply from `GET /conversations/{id}/transcript`.", "title": "Conversation Id" }, "conversation_running": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "description": "For a steer: whether a turn was running in that conversation when it was sent — it lands in that turn's context mid-work — or not, so it runs as the conversation's next turn.", "title": "Conversation Running" }, "delivery": { "description": "`steered` — delivered into a conversation that is already going: into its running turn, or as its next turn when it is idle (TIDY-19705 F16); `delivered` — landed in the employee's conversation for that work, or started a new one; `queued_for_turn_boundary` — waiting for its current turn to finish; `parked` — on its inbox, wake-eligible; `duplicate` — this message (or this operation key) was already sent.", "title": "Delivery", "type": "string" }, "employee": { "title": "Employee", "type": "string" }, "employee_display_name": { "title": "Employee Display Name", "type": "string" }, "employee_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "The employee's acting status when the message was sent — `active`, or e.g. `offline` (it reads the message when it is back).", "title": "Employee Status" }, "encrypted": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "title": "Encrypted" }, "injection_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Injection Id" }, "matrix_event_id": { "title": "Matrix Event Id", "type": "string" }, "resolution": { "description": "`conversation_ref` | `item_episode` | `no_episode` | `none`", "title": "Resolution", "type": "string" }, "room_id": { "title": "Room Id", "type": "string" }, "turn_effort": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "TIDY-20000 — the option of the conversation's model the message's turn runs at, when the request named a `turn_effort` and the model offers one; null otherwise. A message that joins a turn already running takes that turn's effort.", "title": "Turn Effort" }, "turn_effort_note": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Why the turn does not run at exactly the requested `turn_effort`, in words a member reads; null when it does.", "title": "Turn Effort Note" } }, "required": [ "room_id", "matrix_event_id", "employee", "employee_display_name", "delivery", "resolution" ], "title": "EmployeeDmResponse", "type": "object" }, "EmployeeDmThread": { "properties": { "first_message_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "First Message At" }, "item_refs": { "items": { "type": "string" }, "title": "Item Refs", "type": "array" }, "last_message_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Last Message At" }, "matrix_room_id": { "title": "Matrix Room Id", "type": "string" }, "message_count": { "title": "Message Count", "type": "integer" }, "participants": { "items": { "additionalProperties": true, "type": "object" }, "title": "Participants", "type": "array" } }, "required": [ "matrix_room_id", "message_count" ], "title": "EmployeeDmThread", "type": "object" }, "EmployeeDmThreadsResponse": { "properties": { "item_messages": { "items": { "$ref": "#/components/schemas/EmployeeDmItemThread" }, "title": "Item Messages", "type": "array" }, "threads": { "items": { "$ref": "#/components/schemas/EmployeeDmThread" }, "title": "Threads", "type": "array" } }, "title": "EmployeeDmThreadsResponse", "type": "object" }, "EmployeeEntitlementStateResponse": { "description": "What the composer banner renders when an employee is plan-paused.", "properties": { "banner": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Banner" }, "entitled": { "title": "Entitled", "type": "boolean" }, "paused_employee_ids": { "items": { "type": "string" }, "title": "Paused Employee Ids", "type": "array" }, "tenant_id": { "title": "Tenant Id", "type": "string" }, "tier_id": { "title": "Tier Id", "type": "string" } }, "required": [ "tenant_id", "entitled", "tier_id" ], "title": "EmployeeEntitlementStateResponse", "type": "object" }, "EmployeeHarnessCapabilities": { "description": "TIDY-19926 F2 — what one of an employee's harnesses can do.", "properties": { "access_modes": { "items": { "type": "string" }, "title": "Access Modes", "type": "array" }, "approvals": { "title": "Approvals", "type": "boolean" }, "cannot": { "items": { "type": "string" }, "title": "Cannot", "type": "array" }, "compaction": { "$ref": "#/components/schemas/HarnessCompaction" }, "currency": { "title": "Currency", "type": "string" }, "fork": { "title": "Fork", "type": "boolean" }, "image_input": { "title": "Image Input", "type": "boolean" }, "installed_version": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Installed Version" }, "is_default": { "title": "Is Default", "type": "boolean" }, "models": { "items": { "$ref": "#/components/schemas/HarnessCapabilityModel" }, "title": "Models", "type": "array" }, "name": { "title": "Name", "type": "string" }, "plan_mode": { "title": "Plan Mode", "type": "boolean" }, "runtime": { "title": "Runtime", "type": "string" }, "sign_in": { "enum": [ "signed_in", "needs_sign_in", "unknown" ], "title": "Sign In", "type": "string" }, "steering": { "enum": [ "live", "next_turn", "none" ], "title": "Steering", "type": "string" }, "subagents": { "title": "Subagents", "type": "boolean" }, "update_required_models": { "items": { "$ref": "#/components/schemas/HarnessUpdateRequiredModel" }, "title": "Update Required Models", "type": "array" } }, "required": [ "runtime", "name", "is_default", "currency", "sign_in", "steering", "plan_mode", "approvals", "subagents", "compaction", "fork", "image_input" ], "title": "EmployeeHarnessCapabilities", "type": "object" }, "EmployeeHarnessCapabilitiesResponse": { "description": "TIDY-19926 F2 — an employee's harnesses and what each can do, default first.", "properties": { "account_id": { "title": "Account Id", "type": "string" }, "employee": { "title": "Employee", "type": "string" }, "employee_name": { "title": "Employee Name", "type": "string" }, "harnesses": { "items": { "$ref": "#/components/schemas/EmployeeHarnessCapabilities" }, "title": "Harnesses", "type": "array" } }, "required": [ "employee", "employee_name", "account_id" ], "title": "EmployeeHarnessCapabilitiesResponse", "type": "object" }, "EmployeeHarnessListResponse": { "properties": { "can_manage_model_access": { "default": false, "title": "Can Manage Model Access", "type": "boolean" }, "employee_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Employee Status" }, "harnesses": { "items": { "$ref": "#/components/schemas/EmployeeHarnessRow" }, "title": "Harnesses", "type": "array" }, "host": { "enum": [ "hosted", "workshop" ], "title": "Host", "type": "string" }, "refused_plugin": { "anyOf": [ { "$ref": "#/components/schemas/RefusedModelPlugin" }, { "type": "null" } ], "default": null } }, "required": [ "host" ], "title": "EmployeeHarnessListResponse", "type": "object" }, "EmployeeHarnessRow": { "properties": { "accounts": { "items": { "additionalProperties": true, "type": "object" }, "title": "Accounts", "type": "array" }, "armed_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Armed At" }, "auth_methods": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "default": null, "title": "Auth Methods" }, "auth_state": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Auth State" }, "credential_method": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Credential Method" }, "eligible": { "default": false, "title": "Eligible", "type": "boolean" }, "installed_on_workshop": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "title": "Installed On Workshop" }, "is_default": { "title": "Is Default", "type": "boolean" }, "last_error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Last Error" }, "model_catalog": { "items": { "type": "string" }, "title": "Model Catalog", "type": "array" }, "model_catalog_entries": { "items": { "$ref": "#/components/schemas/HarnessCatalogModel" }, "title": "Model Catalog Entries", "type": "array" }, "model_catalog_sources": { "additionalProperties": { "$ref": "#/components/schemas/HarnessModelOwner" }, "title": "Model Catalog Sources", "type": "object" }, "model_selection": { "items": { "type": "string" }, "title": "Model Selection", "type": "array" }, "model_sources": { "items": { "type": "string" }, "title": "Model Sources", "type": "array" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Name" }, "readiness": { "anyOf": [ { "$ref": "#/components/schemas/HarnessReadiness" }, { "type": "null" } ], "default": null }, "reasoning_level": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Reasoning Level" }, "reasoning_levels": { "items": { "type": "string" }, "title": "Reasoning Levels", "type": "array" }, "runtime": { "title": "Runtime", "type": "string" }, "settings": { "items": { "$ref": "#/components/schemas/HarnessSettingRow" }, "title": "Settings", "type": "array" }, "sign_in_method": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Sign In Method" }, "status": { "enum": [ "configured", "arming", "ready", "error", "disarming" ], "title": "Status", "type": "string" }, "update_required_models": { "items": { "$ref": "#/components/schemas/HarnessUpdateRequiredModel" }, "title": "Update Required Models", "type": "array" }, "usage": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "title": "Usage" }, "usage_by_profile": { "anyOf": [ { "additionalProperties": { "additionalProperties": true, "type": "object" }, "type": "object" }, { "type": "null" } ], "default": null, "title": "Usage By Profile" } }, "required": [ "runtime", "is_default", "status" ], "title": "EmployeeHarnessRow", "type": "object" }, "EmployeeHarnessSkillsReset": { "description": "A harness that carries the employee-wide skills again (TIDY-19569 F5).", "properties": { "agent_account_id": { "title": "Agent Account Id", "type": "string" }, "changed": { "title": "Changed", "type": "boolean" }, "runtime": { "title": "Runtime", "type": "string" }, "skills": { "items": { "type": "string" }, "title": "Skills", "type": "array" } }, "required": [ "agent_account_id", "runtime", "changed", "skills" ], "title": "EmployeeHarnessSkillsReset", "type": "object" }, "EmployeeInboxMessage": { "properties": { "body": { "title": "Body", "type": "string" }, "conversation_ref": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Conversation Ref" }, "created_at": { "title": "Created At", "type": "string" }, "id": { "title": "Id", "type": "string" }, "item_ref": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Item Ref" }, "matrix_event_id": { "title": "Matrix Event Id", "type": "string" }, "matrix_room_id": { "title": "Matrix Room Id", "type": "string" }, "resolution": { "title": "Resolution", "type": "string" }, "sender_display_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Sender Display Name" }, "sender_employee": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Sender Employee" } }, "required": [ "id", "body", "resolution", "matrix_room_id", "matrix_event_id", "created_at" ], "title": "EmployeeInboxMessage", "type": "object" }, "EmployeeInboxReadRequest": { "properties": { "dm_ids": { "items": { "format": "uuid", "type": "string" }, "maxItems": 50, "minItems": 1, "title": "Dm Ids", "type": "array" } }, "required": [ "dm_ids" ], "title": "EmployeeInboxReadRequest", "type": "object" }, "EmployeeInboxReadResponse": { "properties": { "marked": { "description": "The ids that were your unread DMs and are now read.", "items": { "type": "string" }, "title": "Marked", "type": "array" } }, "title": "EmployeeInboxReadResponse", "type": "object" }, "EmployeeInboxResponse": { "properties": { "mentions": { "description": "Open @mentions; answering (comment_reply) or acking closes one.", "items": { "$ref": "#/components/schemas/ActionableMention" }, "title": "Mentions", "type": "array" }, "messages": { "description": "Unread colleague DMs no conversation has taken yet, newest first.", "items": { "$ref": "#/components/schemas/EmployeeInboxMessage" }, "title": "Messages", "type": "array" } }, "title": "EmployeeInboxResponse", "type": "object" }, "EmployeeLifecycleResponse": { "properties": { "agent_account_id": { "title": "Agent Account Id", "type": "string" }, "changed": { "default": true, "title": "Changed", "type": "boolean" }, "control_delivered": { "default": false, "title": "Control Delivered", "type": "boolean" }, "display_name": { "title": "Display Name", "type": "string" }, "grants_revoked": { "default": 0, "title": "Grants Revoked", "type": "integer" }, "harness_credentials_removed": { "default": 0, "title": "Harness Credentials Removed", "type": "integer" }, "identity_delete_after": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Identity Delete After" }, "identity_deleted": { "default": false, "title": "Identity Deleted", "type": "boolean" }, "lifecycle_state": { "enum": [ "provisioned", "active", "paused", "retired" ], "title": "Lifecycle State", "type": "string" }, "matrix_devices_revoked": { "default": 0, "title": "Matrix Devices Revoked", "type": "integer" }, "paused_reason": { "anyOf": [ { "enum": [ "user", "entitlement" ], "type": "string" }, { "type": "null" } ], "default": null, "title": "Paused Reason" }, "plugin_shipments_revoked": { "default": 0, "title": "Plugin Shipments Revoked", "type": "integer" }, "push_job_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Push Job Id" }, "reports_reassigned": { "items": { "$ref": "#/components/schemas/EmployeeReportReassigned" }, "title": "Reports Reassigned", "type": "array" }, "retired_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Retired At" }, "summary": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Summary" } }, "required": [ "agent_account_id", "display_name", "lifecycle_state" ], "title": "EmployeeLifecycleResponse", "type": "object" }, "EmployeeModelAccess": { "description": "How the employee reaches a model on Tidy compute.\n\n``tidy_inference`` is Tidy's keyless lane; ``api_key`` lends the model\nplugin holding ``credential_id`` — the member's own, or one shared with the\nworkspace. Omitted on the define call means the default the hosted create\nalready assigns (the keyless lane where it is served).", "properties": { "credential_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Credential Id" }, "method": { "enum": [ "tidy_inference", "api_key" ], "title": "Method", "type": "string" }, "models": { "items": { "type": "string" }, "maxItems": 8, "title": "Models", "type": "array" } }, "required": [ "method" ], "title": "EmployeeModelAccess", "type": "object" }, "EmployeeMoveRequest": { "description": "`target_kind='hosted'` takes no workshop; `'workshop'` requires one.\nTIDY-19802: a move onto a workshop approves its plugin access with it.", "properties": { "assign_pending": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Assign Pending" }, "force": { "default": false, "title": "Force", "type": "boolean" }, "plugin_access": { "anyOf": [ { "items": { "$ref": "#/components/schemas/PluginAccessChoice" }, "maxItems": 16, "type": "array" }, { "type": "null" } ], "title": "Plugin Access" }, "requirements_hash": { "anyOf": [ { "maxLength": 64, "minLength": 64, "type": "string" }, { "type": "null" } ], "title": "Requirements Hash" }, "secret_files": { "anyOf": [ { "items": { "$ref": "#/components/schemas/SecretFileChoice" }, "maxItems": 16, "type": "array" }, { "type": "null" } ], "title": "Secret Files" }, "skill_gives": { "items": { "$ref": "#/components/schemas/SkillGive" }, "maxItems": 64, "title": "Skill Gives", "type": "array" }, "target_kind": { "default": "workshop", "enum": [ "workshop", "hosted" ], "title": "Target Kind", "type": "string" }, "to_workshop_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "To Workshop Id" } }, "title": "EmployeeMoveRequest", "type": "object" }, "EmployeeMoveResponse": { "properties": { "agent_account_id": { "title": "Agent Account Id", "type": "string" }, "ai_employee_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Ai Employee Id" }, "display_name": { "title": "Display Name", "type": "string" }, "failed_step": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Failed Step" }, "from_kind": { "enum": [ "workshop", "hosted" ], "title": "From Kind", "type": "string" }, "from_workshop_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "From Workshop Id" }, "from_workshop_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "From Workshop Name" }, "host_rebind_token": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Host Rebind Token" }, "left_work_behind": { "default": false, "title": "Left Work Behind", "type": "boolean" }, "materialization": { "$ref": "#/components/schemas/MaterializationSummary" }, "move_id": { "title": "Move Id", "type": "string" }, "plugin_access": { "items": { "$ref": "#/components/schemas/AppliedPluginAccess" }, "title": "Plugin Access", "type": "array" }, "push_job_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Push Job Id" }, "push_job_state": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Push Job State" }, "rebind_receipt_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Rebind Receipt Id" }, "state": { "enum": [ "settling", "detaching", "enrolling", "materializing", "active", "failed" ], "title": "State", "type": "string" }, "target_kind": { "enum": [ "workshop", "hosted" ], "title": "Target Kind", "type": "string" }, "to_workshop_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "To Workshop Id" }, "to_workshop_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "To Workshop Name" }, "unsettled_conversations": { "items": { "$ref": "#/components/schemas/UnsettledConversation" }, "title": "Unsettled Conversations", "type": "array" } }, "required": [ "move_id", "agent_account_id", "display_name", "from_kind", "target_kind", "state", "materialization" ], "title": "EmployeeMoveResponse", "type": "object" }, "EmployeeMoveTarget": { "description": "One place the employee could run, and whether it can take it today.", "properties": { "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Id" }, "is_current": { "default": false, "title": "Is Current", "type": "boolean" }, "kind": { "enum": [ "workshop", "hosted" ], "title": "Kind", "type": "string" }, "name": { "title": "Name", "type": "string" }, "note": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Note" }, "unavailable_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Unavailable Code" }, "unavailable_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Unavailable Reason" } }, "required": [ "kind", "name" ], "title": "EmployeeMoveTarget", "type": "object" }, "EmployeeMoveTargetsResponse": { "properties": { "agent_account_id": { "title": "Agent Account Id", "type": "string" }, "current_kind": { "enum": [ "workshop", "hosted" ], "title": "Current Kind", "type": "string" }, "display_name": { "title": "Display Name", "type": "string" }, "targets": { "items": { "$ref": "#/components/schemas/EmployeeMoveTarget" }, "title": "Targets", "type": "array" } }, "required": [ "agent_account_id", "display_name", "current_kind" ], "title": "EmployeeMoveTargetsResponse", "type": "object" }, "EmployeeObjective": { "properties": { "description": { "anyOf": [ { "maxLength": 20000, "type": "string" }, { "type": "null" } ], "title": "Description" }, "horizon": { "default": "ongoing", "enum": [ "quarter", "year", "ongoing" ], "title": "Horizon", "type": "string" }, "success_signal": { "anyOf": [ { "maxLength": 2000, "type": "string" }, { "type": "null" } ], "title": "Success Signal" }, "title": { "maxLength": 200, "minLength": 1, "title": "Title", "type": "string" } }, "required": [ "title" ], "title": "EmployeeObjective", "type": "object" }, "EmployeePluginGrant": { "description": "What the dispatcher needs to attach ``X-Tidy-Plugin-Grant`` to a tool call.", "properties": { "capability_scope": { "items": { "type": "string" }, "title": "Capability Scope", "type": "array" }, "conversation_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Conversation Id" }, "expires_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Expires At" }, "id": { "title": "Id", "type": "string" }, "plugin_id": { "title": "Plugin Id", "type": "string" }, "plugin_kind": { "title": "Plugin Kind", "type": "string" }, "plugin_label": { "title": "Plugin Label", "type": "string" }, "scope": { "enum": [ "once", "session", "standing" ], "title": "Scope", "type": "string" } }, "required": [ "id", "plugin_id", "plugin_kind", "plugin_label", "scope", "capability_scope" ], "title": "EmployeePluginGrant", "type": "object" }, "EmployeePluginGrantsResponse": { "properties": { "grants": { "items": { "$ref": "#/components/schemas/EmployeePluginGrant" }, "title": "Grants", "type": "array" } }, "required": [ "grants" ], "title": "EmployeePluginGrantsResponse", "type": "object" }, "EmployeeRedeployRequest": { "description": "TIDY-20019 F3: a Redeploy may start the employee with its own harness\nextensions off, the recovery for a harness that will not start.", "properties": { "harness_extensions": { "default": "on", "description": "'off' starts the employee with its own harness extensions and packages turned off (only Tidy's own load), for an employee whose harness will not start. Its configuration is untouched; the next deploy without 'off' turns them back on. pi only; the workshop must run connector 1.1.737 or newer.", "enum": [ "on", "off" ], "title": "Harness Extensions", "type": "string" } }, "title": "EmployeeRedeployRequest", "type": "object" }, "EmployeeReportReassigned": { "description": "TIDY-19500 F4: someone who reported to a retired manager, moved up.", "properties": { "name": { "title": "Name", "type": "string" }, "now_reports_to": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Now Reports To" } }, "required": [ "name" ], "title": "EmployeeReportReassigned", "type": "object" }, "EmployeeReportsTo": { "description": "Who the new employee reports to — exactly one of two ways to say it.\n\nTIDY-19500 D4: the edge is ``contact_organizations.parent_membership_id``\nin the workspace's team organization (TIDY-18959). ``account_id`` names an EXISTING member or\nemployee of this workspace. ``draft_key`` (F4) names another employee of\nthe same team definition, which does not exist until that call creates it.", "properties": { "account_id": { "anyOf": [ { "maxLength": 64, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Account Id" }, "draft_key": { "anyOf": [ { "maxLength": 64, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Draft Key" } }, "title": "EmployeeReportsTo", "type": "object" }, "EmployeeScheduledJob": { "description": "One duty, in ``POST /scheduled-jobs``'s own declaration vocabulary.\n\nThe employee and provenance are the define call's, never the caller's to\nrestate, so they are not fields here.", "properties": { "cron": { "default": "", "maxLength": 200, "title": "Cron", "type": "string" }, "ends_at": { "anyOf": [ { "maxLength": 10, "type": "string" }, { "type": "null" } ], "title": "Ends At" }, "max_runs": { "anyOf": [ { "maximum": 1000.0, "minimum": 1.0, "type": "integer" }, { "type": "null" } ], "title": "Max Runs" }, "name": { "maxLength": 200, "minLength": 1, "title": "Name", "type": "string" }, "prompt": { "maxLength": 20000, "minLength": 1, "title": "Prompt", "type": "string" }, "recurrence_byday": { "anyOf": [ { "items": { "type": "string" }, "maxItems": 7, "type": "array" }, { "type": "null" } ], "title": "Recurrence Byday" }, "recurrence_freq": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Recurrence Freq" }, "recurrence_interval": { "anyOf": [ { "maximum": 52.0, "minimum": 1.0, "type": "integer" }, { "type": "null" } ], "title": "Recurrence Interval" }, "recurrence_position": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Recurrence Position" }, "recurrence_time": { "anyOf": [ { "maxLength": 5, "type": "string" }, { "type": "null" } ], "title": "Recurrence Time" }, "repeats": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Repeats" }, "starts_at": { "anyOf": [ { "maxLength": 10, "type": "string" }, { "type": "null" } ], "title": "Starts At" } }, "required": [ "name", "prompt" ], "title": "EmployeeScheduledJob", "type": "object" }, "EmployeeSetupChecklistResponse": { "description": "Derived needs-setup state for an AI employee (D25). Any unauthorized MCP\nconnection => needs_setup; each connection carries an authorize verdict.", "properties": { "ai_employee_id": { "format": "uuid", "title": "Ai Employee Id", "type": "string" }, "connections": { "items": { "$ref": "#/components/schemas/EmployeeSetupConnection" }, "title": "Connections", "type": "array" }, "needs_setup": { "title": "Needs Setup", "type": "boolean" } }, "required": [ "ai_employee_id", "needs_setup" ], "title": "EmployeeSetupChecklistResponse", "type": "object" }, "EmployeeSetupConnection": { "properties": { "auth_method": { "title": "Auth Method", "type": "string" }, "authorization": { "title": "Authorization", "type": "string" }, "authorized": { "title": "Authorized", "type": "boolean" }, "connection_id": { "format": "uuid", "title": "Connection Id", "type": "string" }, "name": { "title": "Name", "type": "string" }, "status": { "title": "Status", "type": "string" } }, "required": [ "connection_id", "name", "auth_method", "status", "authorization", "authorized" ], "title": "EmployeeSetupConnection", "type": "object" }, "EmployeeSkillGive": { "additionalProperties": false, "description": "Give the employee exactly this version of the skill, with the plugin\naccess it needs approved in the same gesture (TIDY-19802 F2).", "properties": { "assign_pending": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Assign Pending" }, "plugin_access": { "anyOf": [ { "items": { "$ref": "#/components/schemas/PluginAccessChoice" }, "maxItems": 16, "type": "array" }, { "type": "null" } ], "title": "Plugin Access" }, "requirements_hash": { "anyOf": [ { "maxLength": 64, "minLength": 64, "type": "string" }, { "type": "null" } ], "title": "Requirements Hash" }, "runtime": { "anyOf": [ { "maxLength": 32, "minLength": 1, "type": "string" }, { "type": "null" } ], "description": "Give it on this one harness only, in that harness's own skill list. A harness without its own list starts from the employee-wide one. Omitted, the employee-wide selection changes.", "title": "Runtime" }, "secret_files": { "anyOf": [ { "items": { "$ref": "#/components/schemas/SecretFileChoice" }, "maxItems": 16, "type": "array" }, { "type": "null" } ], "title": "Secret Files" }, "version": { "description": "The version the employee is to load. It is published if it is not already; a newer published version refuses rather than being given.", "exclusiveMinimum": 0.0, "title": "Version", "type": "integer" } }, "required": [ "version" ], "title": "EmployeeSkillGive", "type": "object" }, "EmployeeSkillInventoryEntry": { "description": "One skill identity in an employee's inventory, as the reader may see it.\n\nTIDY-19569 F5. Configured (``provenance``/``runtimes``), published\n(``published_version``) and delivered (``targets``, the workshop the\nemployee runs on now; ``history``, retired workshops) are separate facts.\n``skill_id`` is None only for an unresolved receipt (``skill_tier``\n``unresolved``): a slug on the machine no configured skill accounts for;\nand for a ``local`` skill (TIDY-20203 F1): a folder the operator put in\na harness's skill root that Tidy does not manage.", "properties": { "configured": { "title": "Configured", "type": "boolean" }, "employee_wide": { "title": "Employee Wide", "type": "boolean" }, "history": { "items": { "$ref": "#/components/schemas/EmployeeSkillReceipt" }, "title": "History", "type": "array" }, "id": { "format": "uuid", "title": "Id", "type": "string" }, "installed_version": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Installed Version" }, "name": { "title": "Name", "type": "string" }, "provenance": { "items": { "$ref": "#/components/schemas/EmployeeSkillRoute" }, "title": "Provenance", "type": "array" }, "published_version": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Published Version" }, "runtimes": { "items": { "type": "string" }, "title": "Runtimes", "type": "array" }, "skill_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Skill Id" }, "skill_tier": { "enum": [ "system", "tenant", "unresolved", "local" ], "title": "Skill Tier", "type": "string" }, "slug": { "title": "Slug", "type": "string" }, "sources": { "items": { "type": "string" }, "title": "Sources", "type": "array" }, "status": { "enum": [ "installed", "update_pending", "pending", "blocked", "failed", "not_deployed", "on_tidy_compute", "not_carried", "shadowed", "not_assigned", "retired", "local" ], "title": "Status", "type": "string" }, "targets": { "items": { "$ref": "#/components/schemas/EmployeeSkillReceipt" }, "title": "Targets", "type": "array" }, "version": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Version" }, "workshop_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Workshop Id" } }, "required": [ "id", "slug", "name", "skill_tier", "status", "configured", "employee_wide" ], "title": "EmployeeSkillInventoryEntry", "type": "object" }, "EmployeeSkillInventoryResponse": { "properties": { "employee_account_id": { "format": "uuid", "title": "Employee Account Id", "type": "string" }, "harnesses": { "items": { "type": "string" }, "title": "Harnesses", "type": "array" }, "hosted": { "default": false, "title": "Hosted", "type": "boolean" }, "selection": { "anyOf": [ { "$ref": "#/components/schemas/EmployeeSkillSelectionUse" }, { "type": "null" } ], "default": null }, "skills": { "items": { "$ref": "#/components/schemas/EmployeeSkillInventoryEntry" }, "title": "Skills", "type": "array" }, "workshop_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Workshop Id" } }, "required": [ "employee_account_id" ], "title": "EmployeeSkillInventoryResponse", "type": "object" }, "EmployeeSkillReceipt": { "description": "What one harness on one workshop last reported holding.", "properties": { "expected_version": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Expected Version" }, "missing_keys": { "items": { "type": "string" }, "title": "Missing Keys", "type": "array" }, "missing_requirements": { "items": { "$ref": "#/components/schemas/SkillMissingRequirement" }, "title": "Missing Requirements", "type": "array" }, "path": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Path" }, "repo_commit": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Repo Commit" }, "repo_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Repo Url" }, "runtime": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Runtime" }, "status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Status" }, "version": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Version" }, "workshop_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Workshop Id" } }, "title": "EmployeeSkillReceipt", "type": "object" }, "EmployeeSkillResolutionEntry": { "description": "One skill in an employee's effective set, with why it is (in)active.", "properties": { "collection_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Collection Id" }, "collection_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Collection Name" }, "content_hash": { "title": "Content Hash", "type": "string" }, "description": { "title": "Description", "type": "string" }, "name": { "title": "Name", "type": "string" }, "pinned_bytes": { "default": false, "title": "Pinned Bytes", "type": "boolean" }, "placement": { "default": "harness_global", "enum": [ "harness_global", "project_scoped" ], "title": "Placement", "type": "string" }, "project_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Project Id" }, "scope": { "enum": [ "direct", "member", "org", "project" ], "title": "Scope", "type": "string" }, "shadowed": { "default": false, "title": "Shadowed", "type": "boolean" }, "shadowed_by_collection_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Shadowed By Collection Name" }, "shadowed_by_scope": { "anyOf": [ { "enum": [ "direct", "member", "org", "project" ], "type": "string" }, { "type": "null" } ], "default": null, "title": "Shadowed By Scope" }, "skill_id": { "title": "Skill Id", "type": "string" }, "slug": { "title": "Slug", "type": "string" }, "sync_mode": { "anyOf": [ { "enum": [ "tracked", "pinned" ], "type": "string" }, { "type": "null" } ], "default": null, "title": "Sync Mode" }, "version": { "title": "Version", "type": "integer" } }, "required": [ "skill_id", "name", "slug", "description", "version", "content_hash", "scope" ], "title": "EmployeeSkillResolutionEntry", "type": "object" }, "EmployeeSkillResolutionResponse": { "properties": { "ai_employee_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Ai Employee Id" }, "bundle_hash": { "title": "Bundle Hash", "type": "string" }, "employee_account_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Employee Account Id" }, "employee_kind": { "enum": [ "virtual_employee", "ai_employee" ], "title": "Employee Kind", "type": "string" }, "skills": { "items": { "$ref": "#/components/schemas/EmployeeSkillResolutionEntry" }, "title": "Skills", "type": "array" } }, "required": [ "employee_kind", "bundle_hash" ], "title": "EmployeeSkillResolutionResponse", "type": "object" }, "EmployeeSkillRoute": { "description": "One way a skill reaches the employee (TIDY-19569 F5).\n\n``runtime`` is None for an employee-wide route. A collection or project the\nreader may not see keeps its kind and is ``redacted``: its id and name are\nwithheld, never used to justify the row.", "properties": { "collection_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Collection Id" }, "collection_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Collection Name" }, "kind": { "enum": [ "direct", "collection", "project" ], "title": "Kind", "type": "string" }, "project_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Project Id" }, "redacted": { "default": false, "title": "Redacted", "type": "boolean" }, "runtime": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Runtime" }, "scope": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Scope" }, "sync_mode": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Sync Mode" } }, "required": [ "kind" ], "title": "EmployeeSkillRoute", "type": "object" }, "EmployeeSkillSelection": { "description": "What the employee now carries, as the server holds it (TIDY-19569 R5d).", "properties": { "agent_account_id": { "title": "Agent Account Id", "type": "string" }, "overridden_runtimes": { "items": { "type": "string" }, "title": "Overridden Runtimes", "type": "array" }, "plugin_access": { "items": { "$ref": "#/components/schemas/AppliedPluginAccess" }, "title": "Plugin Access", "type": "array" }, "published_version": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Published Version" }, "runtime": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Runtime" }, "selected": { "title": "Selected", "type": "boolean" }, "skill_id": { "title": "Skill Id", "type": "string" }, "skills": { "items": { "type": "string" }, "title": "Skills", "type": "array" }, "slug": { "title": "Slug", "type": "string" } }, "required": [ "agent_account_id", "skill_id", "slug", "selected", "skills" ], "title": "EmployeeSkillSelection", "type": "object" }, "EmployeeSkillSelectionUse": { "description": "TIDY-20030: how full each of the employee's skill lists is.\n\nOne cap applies to each list on its own: the employee-wide one, and every\nharness that keeps its own.", "properties": { "cap": { "title": "Cap", "type": "integer" }, "employee_wide": { "title": "Employee Wide", "type": "integer" }, "harnesses": { "additionalProperties": { "type": "integer" }, "title": "EmployeeSkillSelectionHarnessCounts", "type": "object" } }, "required": [ "cap", "employee_wide" ], "title": "EmployeeSkillSelectionUse", "type": "object" }, "EmployeeStandingInstructionsChange": { "additionalProperties": false, "description": "TIDY-20154: set one employee's standing instructions.", "properties": { "based_on_sha256": { "anyOf": [ { "maxLength": 64, "minLength": 64, "type": "string" }, { "type": "null" } ], "description": "sha256 of the text you read (standing_instructions_sha256). When it no longer matches, nothing is written: someone changed them since.", "title": "Based On Sha256" }, "instructions": { "description": "replace: the WHOLE new text (empty clears them). append: lines added after what is there.", "maxLength": 20000, "title": "Instructions", "type": "string" }, "mode": { "default": "replace", "enum": [ "replace", "append" ], "title": "Mode", "type": "string" } }, "required": [ "instructions" ], "title": "EmployeeStandingInstructionsChange", "type": "object" }, "EmployeeTeamDefinitionRequest": { "description": "A team of hosted employees, defined whole on one approved card (D3/D12).", "properties": { "employees": { "items": { "$ref": "#/components/schemas/TeamEmployeeDefinition" }, "maxItems": 10, "minItems": 1, "title": "Employees", "type": "array" } }, "required": [ "employees" ], "title": "EmployeeTeamDefinitionRequest", "type": "object" }, "EmployeeVoiceResponse": { "properties": { "speed": { "title": "Speed", "type": "number" }, "voice_engine": { "enum": [ "gemini-realtime", "openai-realtime", "self-hosted" ], "title": "Voice Engine", "type": "string" }, "voice_id": { "title": "Voice Id", "type": "string" }, "voice_name": { "title": "Voice Name", "type": "string" }, "voice_repicked": { "title": "Voice Repicked", "type": "boolean" } }, "required": [ "voice_engine", "voice_id", "voice_name", "speed", "voice_repicked" ], "title": "EmployeeVoiceResponse", "type": "object" }, "EmployeeVoiceUpdate": { "description": "Any of an employee's engine, voice and speed; what is left out is kept.", "properties": { "speed": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Speed" }, "voice_engine": { "anyOf": [ { "enum": [ "gemini-realtime", "openai-realtime", "self-hosted" ], "type": "string" }, { "type": "null" } ], "title": "Voice Engine" }, "voice_id": { "anyOf": [ { "maxLength": 120, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Voice Id" } }, "title": "EmployeeVoiceUpdate", "type": "object" }, "EmployeeWorkPolicyChange": { "additionalProperties": false, "description": "TIDY-20154: set one employee's work policy by name, slug or account id.", "properties": { "work_policy": { "anyOf": [ { "$ref": "#/components/schemas/VeWorkPolicy" }, { "type": "null" } ], "description": "Its own policy; null follows the workspace default. Each status must be one of the workspace's task states (or one the policy already names)." } }, "required": [ "work_policy" ], "title": "EmployeeWorkPolicyChange", "type": "object" }, "EmployeeWorkPolicyRequest": { "properties": { "conversation_worktrees": { "anyOf": [ { "$ref": "#/components/schemas/ConversationWorktreesChange" }, { "type": "null" } ], "description": "TIDY-20066 F12 — whether each new conversation in a project gets its own working copy. Omitted leaves it as it is." }, "work_policy": { "anyOf": [ { "$ref": "#/components/schemas/VeWorkPolicy" }, { "type": "null" } ], "description": "This employee's own policy; null follows the workspace default. Omitted leaves it as it is." } }, "title": "EmployeeWorkPolicyRequest", "type": "object" }, "EmployeeWorkPolicyResponse": { "properties": { "available_states": { "description": "The states the settings offer: the workspace task facet's, in its order, then any other state on this employee's backlog.", "items": { "type": "string" }, "title": "Available States", "type": "array" }, "can_edit_work_policy": { "default": false, "description": "Workspace admins and the employee's direct manager may edit the work-order policy; employee owners may edit only working-copy choices.", "title": "Can Edit Work Policy", "type": "boolean" }, "conversation_worktrees": { "anyOf": [ { "$ref": "#/components/schemas/EmployeeConversationWorktrees" }, { "type": "null" } ], "default": null, "description": "TIDY-20066 F12 — a separate working copy per conversation, per project. Null where no conversation works on a workshop (the built-in assistant)." }, "effective_work_policy": { "$ref": "#/components/schemas/VeWorkPolicy" }, "policy_source": { "enum": [ "employee", "workspace", "default" ], "title": "Policy Source", "type": "string" }, "stuck_work": { "description": "Its stuck work the caller can see (TIDY-20074).", "items": { "$ref": "#/components/schemas/StuckWorkItem" }, "title": "Stuck Work", "type": "array" }, "stuck_work_manager": { "anyOf": [ { "$ref": "#/components/schemas/StuckWorkManager" }, { "type": "null" } ], "description": "Who is alerted to its stuck work; null when its manager is not an employee." }, "wakes_for": { "description": "The states that wake it on its own (TIDY-20074) — its effective work policy as one list.", "items": { "type": "string" }, "title": "Wakes For", "type": "array" }, "work_policy": { "anyOf": [ { "$ref": "#/components/schemas/VeWorkPolicy" }, { "type": "null" } ] }, "work_policy_changed": { "anyOf": [ { "$ref": "#/components/schemas/ConfigurationChange" }, { "type": "null" } ], "default": null, "description": "Who last set this employee's own policy (TIDY-20154)." } }, "required": [ "work_policy", "effective_work_policy", "wakes_for", "stuck_work", "stuck_work_manager", "policy_source", "available_states" ], "title": "EmployeeWorkPolicyResponse", "type": "object" }, "EnableFromCatalogRequest": { "additionalProperties": false, "description": "Enable body. Only token/api_key/pat connectors use ``secret_value``;\nOAuth connectors ignore it (they authorize out-of-band).", "properties": { "secret_value": { "anyOf": [ { "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Secret Value", "writeOnly": true } }, "title": "EnableFromCatalogRequest", "type": "object" }, "EnableFromCatalogResponse": { "properties": { "authorization": { "enum": [ "authorized", "needs_oauth", "needs_credential", "needs_client_app", "needs_github_connection", "error" ], "title": "Authorization", "type": "string" }, "authorization_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Authorization Url" }, "connection": { "$ref": "#/components/schemas/McpServerConnectionResponse" }, "detail": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Detail" }, "state": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "State" } }, "required": [ "connection", "authorization" ], "title": "EnableFromCatalogResponse", "type": "object" }, "EncryptedDmSummary": { "properties": { "enabled_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Enabled At" }, "enabled_by_account_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Enabled By Account Id" }, "room_id_hash": { "title": "Room Id Hash", "type": "string" }, "room_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Room Name" } }, "required": [ "room_id_hash" ], "title": "EncryptedDmSummary", "type": "object" }, "EncryptionConfigRequest": { "properties": { "assistant_chat_decrypt_enabled": { "default": true, "title": "Assistant Chat Decrypt Enabled", "type": "boolean" }, "require_e2ee_dms": { "title": "Require E2Ee Dms", "type": "boolean" } }, "required": [ "require_e2ee_dms" ], "title": "EncryptionConfigRequest", "type": "object" }, "EncryptionConfigResponse": { "properties": { "assistant_chat_decrypt_enabled": { "title": "Assistant Chat Decrypt Enabled", "type": "boolean" }, "encrypted_dms": { "items": { "$ref": "#/components/schemas/EncryptedDmSummary" }, "title": "Encrypted Dms", "type": "array" }, "encrypted_dms_count": { "title": "Encrypted Dms Count", "type": "integer" }, "require_e2ee_dms": { "title": "Require E2Ee Dms", "type": "boolean" } }, "required": [ "require_e2ee_dms", "assistant_chat_decrypt_enabled", "encrypted_dms_count", "encrypted_dms" ], "title": "EncryptionConfigResponse", "type": "object" }, "EngagementMetrics": { "description": "Real read-engagement from first-party interaction telemetry (TIDY-13031).\n\nOwner-scoped (member-private): these fields reflect ONLY the requesting\nmember's own opens/read-time — never another member's. ``None`` on the\nenclosing response when the member has no telemetry in range.", "properties": { "emails_dwelled_gt2m": { "default": 0, "title": "Emails Dwelled Gt2M", "type": "integer" }, "read_time_bucket_counts": { "additionalProperties": { "type": "integer" }, "title": "Read Time Bucket Counts", "type": "object" }, "total_opens": { "default": 0, "title": "Total Opens", "type": "integer" } }, "title": "EngagementMetrics", "type": "object" }, "EngineVoices": { "properties": { "engine": { "enum": [ "gemini-realtime", "openai-realtime", "self-hosted" ], "title": "Engine", "type": "string" }, "voices": { "items": { "$ref": "#/components/schemas/CatalogueVoice" }, "title": "Voices", "type": "array" } }, "required": [ "engine", "voices" ], "title": "EngineVoices", "type": "object" }, "EnrichmentMetadataResponse": { "description": "Response for enrichment metadata queries.", "properties": { "contact_id": { "title": "Contact Id", "type": "string" }, "enrichment_metadata": { "additionalProperties": true, "title": "Enrichment Metadata", "type": "object" } }, "required": [ "contact_id" ], "title": "EnrichmentMetadataResponse", "type": "object" }, "EnrichmentSourceCountersResponse": { "properties": { "exa_budget": { "additionalProperties": true, "title": "Exa Budget", "type": "object" }, "per_source": { "additionalProperties": true, "title": "Per Source", "type": "object" } }, "required": [ "per_source", "exa_budget" ], "title": "EnrichmentSourceCountersResponse", "type": "object" }, "EnrollmentCommand": { "properties": { "clipboard_payload_base64": { "title": "Clipboard Payload Base64", "type": "string" }, "clipboard_payload_sha256": { "title": "Clipboard Payload Sha256", "type": "string" }, "expires_at": { "format": "date-time", "title": "Expires At", "type": "string" } }, "required": [ "clipboard_payload_base64", "clipboard_payload_sha256", "expires_at" ], "title": "EnrollmentCommand", "type": "object" }, "EnsureForInstallRequest": { "additionalProperties": false, "properties": { "servers": { "items": { "$ref": "#/components/schemas/EnsureForInstallServerSpec" }, "minItems": 1, "title": "Servers", "type": "array" } }, "required": [ "servers" ], "title": "EnsureForInstallRequest", "type": "object" }, "EnsureForInstallResponse": { "properties": { "results": { "items": { "$ref": "#/components/schemas/EnsureForInstallResult" }, "title": "Results", "type": "array" } }, "title": "EnsureForInstallResponse", "type": "object" }, "EnsureForInstallResult": { "properties": { "authorization": { "enum": [ "authorized", "needs_oauth", "needs_credential", "needs_client_app", "needs_github_connection", "error" ], "title": "Authorization", "type": "string" }, "authorization_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Authorization Url" }, "connection_id": { "title": "Connection Id", "type": "string" }, "detail": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Detail" }, "name": { "title": "Name", "type": "string" }, "state": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "State" } }, "required": [ "name", "connection_id", "authorization" ], "title": "EnsureForInstallResult", "type": "object" }, "EnsureForInstallServerSpec": { "additionalProperties": false, "description": "One MCP server a template names. Secret-free by construction:\n``extra='forbid'`` rejects any unexpected (e.g. secret-bearing) field with a\n422, so a template can never smuggle a ``secret_value``/``credential_id``\nthrough this path (D-AC5b).", "properties": { "auth_method": { "default": "none", "enum": [ "none", "oauth", "bearer_token", "api_key", "pat", "github_app" ], "title": "Auth Method", "type": "string" }, "connection_type": { "default": "external", "enum": [ "internal", "external" ], "title": "Connection Type", "type": "string" }, "endpoint_url": { "maxLength": 2048, "minLength": 1, "title": "Endpoint Url", "type": "string" }, "name": { "maxLength": 120, "minLength": 1, "title": "Name", "type": "string" }, "oauth_authorize_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Oauth Authorize Url" }, "oauth_client_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Oauth Client Id" }, "oauth_scope": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Oauth Scope" }, "oauth_token_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Oauth Token Url" } }, "required": [ "name", "endpoint_url" ], "title": "EnsureForInstallServerSpec", "type": "object" }, "EnsureTagPageRequest": { "description": "Request payload for note page upsert by tag title.", "properties": { "title": { "maxLength": 120, "minLength": 1, "title": "Title", "type": "string" } }, "required": [ "title" ], "title": "EnsureTagPageRequest", "type": "object" }, "EnsureTagPageResponse": { "description": "Idempotent result for ensure-tag-page.", "properties": { "created": { "title": "Created", "type": "boolean" }, "note_id": { "title": "Note Id", "type": "string" } }, "required": [ "note_id", "created" ], "title": "EnsureTagPageResponse", "type": "object" }, "EnsureTranscriptNoteResponse": { "description": "Result of materializing the caller-tenant transcript note (R-P4.12).\n\n``yjs_state_b64`` carries the note's Yjs body for direct client-side\nhydration of ``ydoc_state_local``: notes.yjs_state is deliberately not\nsynced (bodies load on demand) and the bulk Y.doc download runs on\nfirst-device setup only — without this, a note materialized now would\nnever render on an already-set-up device.", "properties": { "episode_id": { "title": "Episode Id", "type": "string" }, "transcript_note_id": { "title": "Transcript Note Id", "type": "string" }, "yjs_state_b64": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Yjs State B64" } }, "required": [ "transcript_note_id", "episode_id" ], "title": "EnsureTranscriptNoteResponse", "type": "object" }, "EntitlementsResponse": { "properties": { "allotments": { "additionalProperties": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "title": "Allotments", "type": "object" }, "billing_exempt": { "title": "Billing Exempt", "type": "boolean" }, "features": { "additionalProperties": { "type": "boolean" }, "title": "Features", "type": "object" }, "overrides_applied": { "items": { "type": "string" }, "title": "Overrides Applied", "type": "array" }, "subscription_status": { "default": "none", "title": "Subscription Status", "type": "string" }, "tier_id": { "title": "Tier Id", "type": "string" } }, "required": [ "tier_id", "features", "allotments", "overrides_applied", "billing_exempt" ], "title": "EntitlementsResponse", "type": "object" }, "EntityAliasItem": { "description": "A name this entity is heard as on one show (\"Steve\" on The Diary Of A CEO).", "properties": { "alias": { "title": "Alias", "type": "string" }, "show_id": { "title": "Show Id", "type": "string" }, "show_title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Show Title" } }, "required": [ "alias", "show_id" ], "title": "EntityAliasItem", "type": "object" }, "EntityCoAppearanceItem": { "properties": { "canonical_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Canonical Name" }, "entity_id": { "title": "Entity Id", "type": "string" }, "shared_episode_count": { "title": "Shared Episode Count", "type": "integer" }, "type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Type" } }, "required": [ "entity_id", "shared_episode_count" ], "title": "EntityCoAppearanceItem", "type": "object" }, "EntityConversionResponse": { "description": "Response returned after converting one primitive type into another.", "properties": { "entity_type": { "description": "Converted entity type", "title": "Entity Type", "type": "string" }, "id": { "description": "New entity UUID", "title": "Id", "type": "string" }, "name": { "description": "Display name for the converted entity", "title": "Name", "type": "string" } }, "required": [ "id", "name", "entity_type" ], "title": "EntityConversionResponse", "type": "object" }, "EntityCreateRequest": { "description": "Request body for creating a generic entity.", "properties": { "attributes": { "additionalProperties": true, "title": "Attributes", "type": "object" }, "derivation_source_visibility": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Derivation Source Visibility" }, "entity_type": { "title": "Entity Type", "type": "string" }, "facets": { "items": { "type": "string" }, "title": "Facets", "type": "array" }, "name": { "title": "Name", "type": "string" }, "owner_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Owner Id" }, "summary": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Summary" }, "visibility": { "default": "private", "enum": [ "private", "shared" ], "title": "Visibility", "type": "string" } }, "required": [ "entity_type", "name" ], "title": "EntityCreateRequest", "type": "object" }, "EntityEnrichment": { "description": "The bio header an enriched entity carries (TIDY-19386).", "properties": { "bio": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Bio" }, "image_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Image Url" }, "source_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Source Url" }, "sources": { "default": [], "items": { "type": "string" }, "title": "Sources", "type": "array" }, "summary": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Summary" } }, "title": "EntityEnrichment", "type": "object" }, "EntityId": { "description": "Typed primitive ID for entities (prefix 'T').", "examples": [ "T-550e8400-e29b-41d4-a716-446655440000" ], "pattern": "^T-[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "title": "EntityId", "type": "string", "x-tidy-typed-id-prefix": "T", "x-tidy-typed-id-table": "entities" }, "EntityListResponse": { "description": "Response for listing generic entities.", "properties": { "entities": { "items": { "$ref": "#/components/schemas/EntityResponse" }, "title": "Entities", "type": "array" }, "total": { "default": 0, "title": "Total", "type": "integer" } }, "title": "EntityListResponse", "type": "object" }, "EntityMatchSuggestion": { "description": "A single entity match suggestion.", "properties": { "contact_display_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Contact Display Name" }, "contact_id": { "format": "uuid", "title": "Contact Id", "type": "string" }, "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "email_id": { "format": "uuid", "title": "Email Id", "type": "string" }, "email_subject": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Email Subject" }, "id": { "format": "uuid", "title": "Id", "type": "string" }, "match_reason": { "default": "contact_linked_to_project", "title": "Match Reason", "type": "string" }, "project_id": { "format": "uuid", "title": "Project Id", "type": "string" }, "project_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Project Name" }, "status": { "default": "pending", "title": "Status", "type": "string" } }, "required": [ "id", "email_id", "project_id", "contact_id", "created_at" ], "title": "EntityMatchSuggestion", "type": "object" }, "EntityMatchSuggestionsResponse": { "description": "Response for listing entity match suggestions.", "properties": { "suggestions": { "items": { "$ref": "#/components/schemas/EntityMatchSuggestion" }, "title": "Suggestions", "type": "array" }, "total": { "default": 0, "title": "Total", "type": "integer" } }, "title": "EntityMatchSuggestionsResponse", "type": "object" }, "EntityMatchTriggerRequest": { "description": "Internal request to trigger entity matching for an email.", "properties": { "cc_addresses": { "items": { "type": "string" }, "title": "Cc Addresses", "type": "array" }, "email_id": { "format": "uuid", "title": "Email Id", "type": "string" }, "email_subject": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Email Subject" }, "from_address": { "title": "From Address", "type": "string" }, "tenant_id": { "format": "uuid", "title": "Tenant Id", "type": "string" }, "to_addresses": { "items": { "type": "string" }, "title": "To Addresses", "type": "array" } }, "required": [ "tenant_id", "email_id", "from_address" ], "title": "EntityMatchTriggerRequest", "type": "object" }, "EntityMergeSelection": { "description": "A review-time choice to add a page's content to an existing entity (S1).\n\nDefault behavior when a page is NOT listed here is keep-as-note-page;\na page only merges into the entity's notes when the user explicitly opts\nin by submitting an entry with ``merge=True``.", "properties": { "entity_id": { "maxLength": 64, "minLength": 1, "title": "Entity Id", "type": "string" }, "entity_type": { "enum": [ "contact", "organization" ], "title": "Entity Type", "type": "string" }, "merge": { "default": true, "title": "Merge", "type": "boolean" }, "page_title": { "maxLength": 512, "minLength": 1, "title": "Page Title", "type": "string" } }, "required": [ "page_title", "entity_type", "entity_id" ], "title": "EntityMergeSelection", "type": "object" }, "EntityRecord": { "properties": { "aliases": { "items": { "$ref": "#/components/schemas/EntityAliasItem" }, "title": "Aliases", "type": "array" }, "canonical_name": { "title": "Canonical Name", "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Description" }, "enrichment": { "anyOf": [ { "$ref": "#/components/schemas/EntityEnrichment" }, { "type": "null" } ], "default": null }, "enrichment_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Enrichment Status" }, "episode_count": { "title": "Episode Count", "type": "integer" }, "id": { "title": "Id", "type": "string" }, "mention_count": { "title": "Mention Count", "type": "integer" }, "type": { "title": "Type", "type": "string" } }, "required": [ "id", "type", "canonical_name", "mention_count", "episode_count", "aliases" ], "title": "EntityRecord", "type": "object" }, "EntityResponse": { "description": "Generic entity row returned by API endpoints.", "properties": { "access_count": { "default": 0, "title": "Access Count", "type": "integer" }, "attributes": { "additionalProperties": true, "title": "Attributes", "type": "object" }, "community_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Community Id" }, "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "deleted_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Deleted At" }, "derivation_source_visibility": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Derivation Source Visibility" }, "entity_type": { "title": "Entity Type", "type": "string" }, "facets": { "items": { "type": "string" }, "title": "Facets", "type": "array" }, "id": { "title": "Id", "type": "string" }, "last_accessed_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Last Accessed At" }, "name": { "title": "Name", "type": "string" }, "owner_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Owner Id" }, "salience_score": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "title": "Salience Score" }, "summary": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Summary" }, "tenant_id": { "title": "Tenant Id", "type": "string" }, "updated_at": { "format": "date-time", "title": "Updated At", "type": "string" }, "visibility": { "default": "private", "enum": [ "private", "shared" ], "title": "Visibility", "type": "string" } }, "required": [ "id", "tenant_id", "entity_type", "name", "created_at", "updated_at" ], "title": "EntityResponse", "type": "object" }, "EntityShowItem": { "description": "A show the entity is heard on, most episodes first (TIDY-19386).", "properties": { "artwork_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Artwork Url" }, "author": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Author" }, "episode_count": { "title": "Episode Count", "type": "integer" }, "mention_count": { "title": "Mention Count", "type": "integer" }, "role": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Role" }, "rss_feed_url": { "title": "Rss Feed Url", "type": "string" }, "show_id": { "title": "Show Id", "type": "string" }, "title": { "title": "Title", "type": "string" } }, "required": [ "show_id", "title", "rss_feed_url", "episode_count", "mention_count" ], "title": "EntityShowItem", "type": "object" }, "EntityTimelineItem": { "properties": { "confidence": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "title": "Confidence" }, "detection_source": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Detection Source" }, "end_ms": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "End Ms" }, "episode_id": { "title": "Episode Id", "type": "string" }, "episode_title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Episode Title" }, "id": { "title": "Id", "type": "string" }, "published_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Published At" }, "show_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Show Id" }, "show_title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Show Title" }, "speaker_role": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Speaker Role" }, "start_ms": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Start Ms" }, "surface_form": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Surface Form" } }, "required": [ "id", "episode_id" ], "title": "EntityTimelineItem", "type": "object" }, "EntityTimelineResponse": { "properties": { "co_appearances": { "items": { "$ref": "#/components/schemas/EntityCoAppearanceItem" }, "title": "Co Appearances", "type": "array" }, "entity": { "$ref": "#/components/schemas/EntityRecord" }, "entity_id": { "title": "Entity Id", "type": "string" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Next Cursor" }, "shows": { "items": { "$ref": "#/components/schemas/EntityShowItem" }, "title": "Shows", "type": "array" }, "timeline": { "items": { "$ref": "#/components/schemas/EntityTimelineItem" }, "title": "Timeline", "type": "array" } }, "required": [ "entity_id", "entity", "shows", "timeline", "co_appearances" ], "title": "EntityTimelineResponse", "type": "object" }, "EntityUpdateRequest": { "description": "Request body for partially updating a generic entity.", "properties": { "attributes": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Attributes" }, "facets": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Facets" }, "summary": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Summary" } }, "title": "EntityUpdateRequest", "type": "object" }, "EphemeralPreview": { "description": "A preview is TEMPORARY until saved (R119/D33) — stated, not implied.", "properties": { "binding": { "$ref": "#/components/schemas/EphemeralPreviewBinding" }, "container": { "default": "working_panel", "title": "Container", "type": "string" }, "notice": { "default": "Preview only — this view is not saved. Save it to keep it in your workspace, project nav, or a note.", "title": "Notice", "type": "string" }, "persistence": { "default": "ephemeral", "title": "Persistence", "type": "string" }, "temporary": { "default": true, "title": "Temporary", "type": "boolean" }, "title": { "title": "Title", "type": "string" } }, "required": [ "title", "binding" ], "title": "EphemeralPreview", "type": "object" }, "EphemeralPreviewBinding": { "description": "The working-panel binding a client opens to show this preview.\n\nMirrors ``openEphemeralDatabaseView``'s params so the panel renders the\npreview through the SAME canonical renderer a saved view uses — a preview\nthat looked different from the thing it previews would be worthless.", "properties": { "facet_slug": { "title": "Facet Slug", "type": "string" }, "filters": { "additionalProperties": true, "title": "EphemeralPreviewFilters", "type": "object" }, "layout": { "title": "Layout", "type": "string" }, "layout_settings": { "additionalProperties": true, "title": "EphemeralPreviewLayoutSettings", "type": "object" }, "sort": { "items": { "additionalProperties": true, "type": "object" }, "title": "Sort", "type": "array" } }, "required": [ "facet_slug", "layout" ], "title": "EphemeralPreviewBinding", "type": "object" }, "EphemeralRunAccepted": { "properties": { "run_id": { "title": "Run Id", "type": "string" }, "status": { "default": "queued", "title": "Status", "type": "string" }, "workflow_id": { "title": "Workflow Id", "type": "string" } }, "required": [ "run_id", "workflow_id" ], "title": "EphemeralRunAccepted", "type": "object" }, "EphemeralRunInputs": { "additionalProperties": true, "description": "Arbitrary one-off script inputs forwarded as ``INPUTS_JSON``.", "title": "EphemeralRunInputs", "type": "object" }, "EphemeralRunRequest": { "description": "One-off script dispatched through the canonical workflow sandbox lane.", "properties": { "allowed_hosts": { "items": { "type": "string" }, "title": "Allowed Hosts", "type": "array" }, "creating_conversation_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Creating Conversation Id" }, "inputs": { "$ref": "#/components/schemas/EphemeralRunInputs" }, "language": { "default": "python", "title": "Language", "type": "string" }, "script": { "minLength": 1, "title": "Script", "type": "string" }, "timeout_sec": { "default": 120, "title": "Timeout Sec", "type": "integer" } }, "required": [ "script" ], "title": "EphemeralRunRequest", "type": "object" }, "EpisodeChapter": { "description": "One player chapter marker (TIDY-12399). ``start_ms`` is the chapter start\noffset in integer ms.", "properties": { "start_ms": { "title": "Start Ms", "type": "integer" }, "title": { "title": "Title", "type": "string" } }, "required": [ "title", "start_ms" ], "title": "EpisodeChapter", "type": "object" }, "EpisodeEnrichmentItem": { "description": "One catalog episode's hub content + processing/enrichment signals.", "properties": { "ai_summary": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Ai Summary" }, "ai_summary_topics": { "default": null, "title": "Ai Summary Topics" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Description" }, "global_id": { "title": "Global Id", "type": "string" }, "guid": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Guid" }, "has_summary": { "default": false, "title": "Has Summary", "type": "boolean" }, "has_transcript": { "default": false, "title": "Has Transcript", "type": "boolean" }, "mention_count": { "default": 0, "title": "Mention Count", "type": "integer" }, "published_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Published At" }, "show_artwork_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Show Artwork Url" }, "show_feed_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Show Feed Url" }, "show_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Show Id" }, "show_title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Show Title" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Title" }, "transcript_note_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Transcript Note Id" }, "transcription_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Transcription Status" } }, "required": [ "global_id" ], "title": "EpisodeEnrichmentItem", "type": "object" }, "EpisodeEnrichmentResponse": { "properties": { "episodes": { "items": { "$ref": "#/components/schemas/EpisodeEnrichmentItem" }, "title": "Episodes", "type": "array" } }, "required": [ "episodes" ], "title": "EpisodeEnrichmentResponse", "type": "object" }, "EpisodeMentionItem": { "properties": { "canonical_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Canonical Name" }, "confidence": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "title": "Confidence" }, "detection_source": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Detection Source" }, "end_ms": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "End Ms" }, "entity_id": { "title": "Entity Id", "type": "string" }, "id": { "title": "Id", "type": "string" }, "speaker_role": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Speaker Role" }, "start_ms": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Start Ms" }, "surface_form": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Surface Form" }, "type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Type" } }, "required": [ "id", "entity_id" ], "title": "EpisodeMentionItem", "type": "object" }, "EpisodeMentionsResponse": { "properties": { "episode_id": { "title": "Episode Id", "type": "string" }, "mentions": { "items": { "$ref": "#/components/schemas/EpisodeMentionItem" }, "title": "Mentions", "type": "array" } }, "required": [ "episode_id", "mentions" ], "title": "EpisodeMentionsResponse", "type": "object" }, "EpisodeNoteResponse": { "properties": { "note_id": { "title": "Note Id", "type": "string" } }, "required": [ "note_id" ], "title": "EpisodeNoteResponse", "type": "object" }, "EpisodeTranscriptResponse": { "description": "Transcript + chapters for the in-app player (TIDY-12399 / TIDY-A-951).\n\nRead from THIS env's CURRENT transcript version for the GLOBAL episode plus\nthe (deliberately-not-synced) ``podcast_global_episodes.chapters`` column.\n404 when the episode has no current transcript version.", "properties": { "chapters": { "items": { "$ref": "#/components/schemas/EpisodeChapter" }, "title": "Chapters", "type": "array" }, "episode_id": { "title": "Episode Id", "type": "string" }, "segments": { "items": { "$ref": "#/components/schemas/EpisodeTranscriptSegment" }, "title": "Segments", "type": "array" } }, "required": [ "episode_id" ], "title": "EpisodeTranscriptResponse", "type": "object" }, "EpisodeTranscriptSegment": { "description": "One player transcript segment (TIDY-12399). Times are integer ms from the\ntop of the episode; ``speaker`` is the namer's name → diarization label →\nnull (a namer abstention renders no name).", "properties": { "end_ms": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "End Ms" }, "speaker": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Speaker" }, "start_ms": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Start Ms" }, "text": { "default": "", "title": "Text", "type": "string" } }, "title": "EpisodeTranscriptSegment", "type": "object" }, "ErasureAuditResponse": { "properties": { "external_state_note": { "title": "External State Note", "type": "string" }, "intended_retentions": { "items": { "$ref": "#/components/schemas/IntendedRetentionModel" }, "title": "Intended Retentions", "type": "array" }, "passed": { "title": "Passed", "type": "boolean" }, "residual_rows": { "additionalProperties": { "type": "integer" }, "title": "Residual Rows", "type": "object" }, "tables_scanned": { "title": "Tables Scanned", "type": "integer" }, "tenant_id": { "title": "Tenant Id", "type": "string" }, "unverified_stores": { "default": [], "items": { "type": "string" }, "title": "Unverified Stores", "type": "array" }, "warnings": { "items": { "$ref": "#/components/schemas/RetainedWarningModel" }, "title": "Warnings", "type": "array" } }, "required": [ "tenant_id", "passed", "residual_rows", "intended_retentions", "warnings", "external_state_note", "tables_scanned" ], "title": "ErasureAuditResponse", "type": "object" }, "ErrorCatalog": { "description": "Full catalog response.", "properties": { "errors": { "items": { "$ref": "#/components/schemas/ErrorCatalogEntry" }, "title": "Errors", "type": "array" } }, "required": [ "errors" ], "title": "ErrorCatalog", "type": "object" }, "ErrorCatalogEntry": { "description": "One row of the error catalog served at /api/v1/errors.", "properties": { "category": { "description": "Coarse grouping (auth, validation, rate_limit, etc.).", "title": "Category", "type": "string" }, "code": { "description": "Stable snake_case error code.", "title": "Code", "type": "string" }, "docs_url": { "description": "Canonical docs URL for this error code.", "title": "Docs Url", "type": "string" }, "http_status": { "description": "HTTP status emitted for this code.", "title": "Http Status", "type": "integer" }, "retryable": { "description": "Whether clients should retry per R65/R103 semantics.", "title": "Retryable", "type": "boolean" }, "title": { "description": "Short human-readable title.", "title": "Title", "type": "string" } }, "required": [ "code", "http_status", "title", "retryable", "category", "docs_url" ], "title": "ErrorCatalogEntry", "type": "object" }, "ErrorCategoryResponse": { "description": "Categorized error with fix suggestion.", "properties": { "category": { "title": "Category", "type": "string" }, "error_text": { "title": "Error Text", "type": "string" }, "service": { "title": "Service", "type": "string" }, "severity": { "default": "info", "title": "Severity", "type": "string" }, "stage": { "title": "Stage", "type": "string" }, "suggestion": { "title": "Suggestion", "type": "string" } }, "required": [ "category", "stage", "service", "error_text", "suggestion" ], "title": "ErrorCategoryResponse", "type": "object" }, "EscalationFunnelResponse": { "description": "The escalation funnel for the caller's tenant.", "properties": { "funnel": { "items": { "additionalProperties": true, "type": "object" }, "title": "Funnel", "type": "array" }, "time_to_action": { "items": { "additionalProperties": true, "type": "object" }, "title": "Time To Action", "type": "array" }, "undelivered": { "title": "Undelivered", "type": "integer" }, "window_days": { "title": "Window Days", "type": "integer" } }, "required": [ "window_days", "funnel", "time_to_action", "undelivered" ], "title": "EscalationFunnelResponse", "type": "object" }, "EscalationPolicyRequest": { "properties": { "max_urgency": { "default": "today", "description": "now | today | fyi", "title": "Max Urgency", "type": "string" }, "push_after_seconds": { "default": 0, "maximum": 86400.0, "minimum": 0.0, "title": "Push After Seconds", "type": "integer" }, "sms_after_seconds": { "default": 600, "maximum": 86400.0, "minimum": 60.0, "title": "Sms After Seconds", "type": "integer" }, "sms_allowed": { "default": false, "title": "Sms Allowed", "type": "boolean" } }, "title": "EscalationPolicyRequest", "type": "object" }, "EscalationPolicyResponse": { "description": "The bounds in force for one employee.", "properties": { "configured": { "description": "False when no settings row exists and the quiet defaults are in force — the editor shows what is actually applying, not a blank.", "title": "Configured", "type": "boolean" }, "max_urgency": { "description": "The loudest tier this employee may use: now | today | fyi.", "title": "Max Urgency", "type": "string" }, "push_after_seconds": { "title": "Push After Seconds", "type": "integer" }, "sms_after_seconds": { "title": "Sms After Seconds", "type": "integer" }, "sms_allowed": { "description": "Whether a tier-now escalation may reach SMS.", "title": "Sms Allowed", "type": "boolean" } }, "required": [ "max_urgency", "sms_allowed", "push_after_seconds", "sms_after_seconds", "configured" ], "title": "EscalationPolicyResponse", "type": "object" }, "EscalationReceiptRequest": { "description": "One carrier verdict on a message this service may have sent.", "properties": { "error_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error Code" }, "provider_message_id": { "description": "The provider's id — the only key a receipt carries.", "title": "Provider Message Id", "type": "string" }, "status": { "description": "Normalized delivery status.", "title": "Status", "type": "string" } }, "required": [ "provider_message_id", "status" ], "title": "EscalationReceiptRequest", "type": "object" }, "EscalationReceiptResponse": { "properties": { "correlated": { "title": "Correlated", "type": "boolean" }, "escalation_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Escalation Id" } }, "required": [ "correlated" ], "title": "EscalationReceiptResponse", "type": "object" }, "EscalationResolveResponse": { "description": "Where this escalation lands, and what it was about.", "properties": { "anchor": { "title": "Anchor", "type": "string" }, "escalation_id": { "title": "Escalation Id", "type": "string" }, "moved": { "title": "Moved", "type": "boolean" }, "path": { "description": "In-app path the client should open.", "title": "Path", "type": "string" }, "primitive_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Primitive Id" }, "primitive_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Primitive Type" }, "status": { "title": "Status", "type": "string" }, "title": { "title": "Title", "type": "string" }, "urgency": { "title": "Urgency", "type": "string" } }, "required": [ "escalation_id", "urgency", "status", "title", "anchor", "moved", "path" ], "title": "EscalationResolveResponse", "type": "object" }, "EspConnectionCreate": { "properties": { "config": { "additionalProperties": true, "description": "Provider-lane config (configuration_set, tracking_domain, ...).", "title": "Config", "type": "object" }, "credential_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Unified credential vault (ve_credentials) row holding the provider key (entered via the existing user-facing vault flow — D4).", "title": "Credential Id" }, "is_default": { "default": false, "description": "One default connection per tenant; overridable per campaign.", "title": "Is Default", "type": "boolean" }, "name": { "maxLength": 200, "minLength": 1, "title": "Name", "type": "string" }, "provider": { "enum": [ "ses", "custom" ], "title": "Provider", "type": "string" }, "region": { "anyOf": [ { "maxLength": 64, "type": "string" }, { "type": "null" } ], "title": "Region" } }, "required": [ "provider", "name" ], "title": "EspConnectionCreate", "type": "object" }, "EspConnectionResponse": { "properties": { "config": { "additionalProperties": true, "title": "Config", "type": "object" }, "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "credential_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Credential Id" }, "id": { "title": "Id", "type": "string" }, "is_default": { "title": "Is Default", "type": "boolean" }, "last_event_received_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Last Event Received At" }, "last_verified_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Last Verified At" }, "name": { "title": "Name", "type": "string" }, "owner_id": { "title": "Owner Id", "type": "string" }, "provider": { "title": "Provider", "type": "string" }, "region": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Region" }, "send_error_count": { "title": "Send Error Count", "type": "integer" }, "sig_fail_count": { "title": "Sig Fail Count", "type": "integer" }, "status": { "title": "Status", "type": "string" }, "status_detail": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Status Detail" }, "tenant_id": { "title": "Tenant Id", "type": "string" }, "updated_at": { "format": "date-time", "title": "Updated At", "type": "string" }, "webhook_url": { "description": "The exact URL to paste into the provider console (SNS HTTPS subscription endpoint).", "title": "Webhook Url", "type": "string" } }, "required": [ "id", "tenant_id", "owner_id", "provider", "name", "webhook_url", "status", "is_default", "sig_fail_count", "send_error_count", "created_at", "updated_at" ], "title": "EspConnectionResponse", "type": "object" }, "EspConnectionUpdate": { "properties": { "config": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Config" }, "credential_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Credential Id" }, "is_default": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is Default" }, "name": { "anyOf": [ { "maxLength": 200, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Name" }, "region": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Region" } }, "title": "EspConnectionUpdate", "type": "object" }, "EspConnectionVerifyResponse": { "properties": { "error": { "anyOf": [ { "$ref": "#/components/schemas/EspVerifyError" }, { "type": "null" } ], "default": null }, "ok": { "title": "Ok", "type": "boolean" }, "production_access": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "title": "Production Access" }, "quota": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "title": "Quota" }, "sending_enabled": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "title": "Sending Enabled" }, "status": { "title": "Status", "type": "string" }, "verified_identities": { "items": { "type": "string" }, "title": "Verified Identities", "type": "array" } }, "required": [ "ok", "status" ], "title": "EspConnectionVerifyResponse", "type": "object" }, "EspVerifyError": { "properties": { "code": { "default": "", "title": "Code", "type": "string" }, "credential_failure": { "default": false, "title": "Credential Failure", "type": "boolean" }, "reason": { "default": "", "title": "Reason", "type": "string" }, "retryable": { "default": false, "title": "Retryable", "type": "boolean" } }, "title": "EspVerifyError", "type": "object" }, "EstimateRequest": { "description": "Ask what a generation would cost, before committing to it.", "properties": { "facet_slug": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Output type to price; defaults to the bundle's binding", "title": "Facet Slug" }, "instructions": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The steering for THIS run, if the caller is overriding the bundle's own instruction — the same field `POST /bundles/{id}/generate` takes. Omit it to price the bundle's stored instruction, exactly as before. It is priced and fingerprinted here so the submission that carries it can confirm against this estimate (TIDY-17831); an estimate that ignored it issued a fingerprint the matching submit could never match.", "title": "Instructions" }, "producer_options": { "anyOf": [ { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "boolean" } ] }, "type": "object" }, { "type": "null" } ], "description": "The per-invocation choices this output type declares in `generation.invocation_fields` (TIDY-17830), keyed by field. Absent keys take the definition's defaults; an unknown key, a choice the field does not offer, a wrong scalar type, an over-long text or a field hidden by its `visible_when` rule is a named 422 and creates nothing. Omitting the whole map is valid and behaves exactly as it did before the field existed.", "title": "Producer Options" } }, "title": "EstimateRequest", "type": "object" }, "EvaluateRequest": { "properties": { "cost_regression_approved": { "default": false, "description": "Explicit approval of a cost regression above the threshold.", "title": "Cost Regression Approved", "type": "boolean" }, "family": { "title": "Family", "type": "string" } }, "required": [ "family" ], "title": "EvaluateRequest", "type": "object" }, "EvaluateResponse": { "properties": { "artifact": { "additionalProperties": true, "title": "Artifact", "type": "object" }, "readiness": { "additionalProperties": true, "title": "Readiness", "type": "object" }, "version_id": { "format": "uuid", "title": "Version Id", "type": "string" } }, "required": [ "version_id", "artifact", "readiness" ], "title": "EvaluateResponse", "type": "object" }, "EvaluatedFeatureSwitch": { "description": "One registered switch with the SEAM's evaluated answer for a tenant.", "properties": { "enabled": { "title": "Enabled", "type": "boolean" }, "key": { "title": "Key", "type": "string" } }, "required": [ "key", "enabled" ], "title": "EvaluatedFeatureSwitch", "type": "object" }, "EvaluatedFeatureSwitchesResponse": { "properties": { "evaluations": { "items": { "$ref": "#/components/schemas/EvaluatedFeatureSwitch" }, "title": "Evaluations", "type": "array" }, "tenant_id": { "title": "Tenant Id", "type": "string" } }, "required": [ "tenant_id", "evaluations" ], "title": "EvaluatedFeatureSwitchesResponse", "type": "object" }, "EvaluationResponse": { "description": "A measurement. ``verdict_id`` is set only by the persisting endpoint.", "properties": { "artifact": { "additionalProperties": true, "title": "Artifact", "type": "object" }, "artifact_hash": { "title": "Artifact Hash", "type": "string" }, "artifact_schema_version": { "title": "Artifact Schema Version", "type": "integer" }, "decision": { "title": "Decision", "type": "string" }, "failed_thresholds": { "items": { "type": "string" }, "title": "Failed Thresholds", "type": "array" }, "signature_key_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Signature Key Id" }, "signed": { "default": false, "title": "Signed", "type": "boolean" }, "tenant_id": { "format": "uuid", "title": "Tenant Id", "type": "string" }, "thresholds": { "items": { "$ref": "#/components/schemas/ThresholdResultResponse" }, "title": "Thresholds", "type": "array" }, "verdict_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "default": null, "title": "Verdict Id" }, "window_end": { "format": "date-time", "title": "Window End", "type": "string" }, "window_start": { "format": "date-time", "title": "Window Start", "type": "string" } }, "required": [ "tenant_id", "window_start", "window_end", "decision", "failed_thresholds", "thresholds", "artifact_hash", "artifact_schema_version", "artifact" ], "title": "EvaluationResponse", "type": "object" }, "EvaluationWindow": { "description": "The window to measure. Defaults to the last 30 days, ending now.", "properties": { "window_days": { "default": 30, "description": "Used only when window_start/window_end are omitted.", "maximum": 365.0, "minimum": 1.0, "title": "Window Days", "type": "integer" }, "window_end": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Window End" }, "window_start": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Window Start" } }, "title": "EvaluationWindow", "type": "object" }, "EventApprovalResponse": { "description": "Response after approving/rejecting an event.", "properties": { "event_status": { "title": "Event Status", "type": "string" }, "id": { "title": "Id", "type": "string" }, "rejection_notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Rejection Notes" }, "reviewed_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Reviewed At" }, "reviewed_by": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Reviewed By" } }, "required": [ "id", "event_status" ], "title": "EventApprovalResponse", "type": "object" }, "EventAttachment": { "description": "Attachment metadata stored on ``calendar_events.attachments``.", "properties": { "content_hash": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "SHA-256 content hash of the stored bytes", "title": "Content Hash" }, "content_type": { "description": "MIME type", "title": "Content Type", "type": "string" }, "filename": { "description": "Original filename", "title": "Filename", "type": "string" }, "id": { "description": "Attachment UUID", "title": "Id", "type": "string" }, "size": { "description": "File size in bytes", "title": "Size", "type": "integer" }, "storage_path": { "description": "Object-storage key in the attachments bucket", "title": "Storage Path", "type": "string" } }, "required": [ "id", "filename", "content_type", "size", "storage_path" ], "title": "EventAttachment", "type": "object" }, "EventAttachmentListResponse": { "description": "Response for listing attachments on a calendar event.", "properties": { "attachments": { "description": "Attachments currently attached to the event", "items": { "$ref": "#/components/schemas/EventAttachment" }, "title": "Attachments", "type": "array" }, "total_count": { "description": "Total number of attachments", "title": "Total Count", "type": "integer" } }, "required": [ "total_count" ], "title": "EventAttachmentListResponse", "type": "object" }, "EventAttachmentRemoveResponse": { "description": "Response for removing an attachment from an event.", "properties": { "attachment_id": { "description": "Removed attachment ID", "title": "Attachment Id", "type": "string" }, "removed": { "description": "Whether the attachment was removed", "title": "Removed", "type": "boolean" } }, "required": [ "removed", "attachment_id" ], "title": "EventAttachmentRemoveResponse", "type": "object" }, "EventAttachmentUploadResponse": { "description": "Response for an event attachment upload / attach-from-object.", "properties": { "attachment": { "$ref": "#/components/schemas/EventAttachment", "description": "The attachment that was added" } }, "required": [ "attachment" ], "title": "EventAttachmentUploadResponse", "type": "object" }, "EventCatalog": { "description": "Full event catalog response.", "properties": { "events": { "items": { "$ref": "#/components/schemas/EventCatalogEntry" }, "title": "Events", "type": "array" } }, "required": [ "events" ], "title": "EventCatalog", "type": "object" }, "EventCatalogEntry": { "description": "One entry in the external event catalog.", "properties": { "event_type": { "description": "Stable dotted-name identifier.", "title": "Event Type", "type": "string" }, "event_version": { "description": "Pinned payload schema version per R72.", "title": "Event Version", "type": "integer" }, "schema_ref": { "description": "JSON pointer into /api/v1/asyncapi.json for the payload schema.", "title": "Schema Ref", "type": "string" }, "title": { "description": "Short human-readable description.", "title": "Title", "type": "string" } }, "required": [ "event_type", "event_version", "title", "schema_ref" ], "title": "EventCatalogEntry", "type": "object" }, "EventFieldModel": { "additionalProperties": false, "description": "One field a delivery carries: a dotted path, its type, whether it must\nbe present, and the most it may hold (characters, items or bytes).", "properties": { "max_size": { "anyOf": [ { "minimum": 1.0, "type": "integer" }, { "type": "null" } ], "title": "Max Size" }, "name": { "maxLength": 600, "minLength": 1, "title": "Name", "type": "string" }, "required": { "default": false, "title": "Required", "type": "boolean" }, "type": { "enum": [ "text", "number", "boolean", "object", "list" ], "title": "Type", "type": "string" } }, "required": [ "name", "type" ], "title": "EventFieldModel", "type": "object" }, "EventMatch": { "additionalProperties": false, "description": "How a delivery is routed to this event: a header (or a top-level body\nkey) whose value equals ``value`` — GitHub's ``X-GitHub-Event: issues``.", "properties": { "key": { "maxLength": 200, "minLength": 1, "title": "Key", "type": "string" }, "source": { "enum": [ "header", "body" ], "title": "Source", "type": "string" }, "value": { "maxLength": 200, "minLength": 1, "title": "Value", "type": "string" } }, "required": [ "source", "key", "value" ], "title": "EventMatch", "type": "object" }, "EventRejectRequest": { "description": "Request for rejecting an event.", "properties": { "rejection_notes": { "anyOf": [ { "maxLength": 1000, "type": "string" }, { "type": "null" } ], "description": "Reason for rejection (optional)", "title": "Rejection Notes" } }, "title": "EventRejectRequest", "type": "object" }, "EventSourceMapping": { "description": "External source mapping for a canonical calendar event.\n\n``id`` is the source-mapping row id (internal). ``event_id`` is the\ncanonical calendar event reference, rewritten to ``V-``.\n``source_email_id`` (when present) is rewritten to ``E-``.", "properties": { "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "etag": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Etag" }, "event_id": { "title": "Event Id", "type": "string" }, "external_provider_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "External Provider Id" }, "external_uid": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "External Uid" }, "id": { "title": "Id", "type": "string" }, "last_synced_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Last Synced At" }, "sequence": { "default": 0, "title": "Sequence", "type": "integer" }, "source_calendar_external_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Source Calendar External Id" }, "source_calendar_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Source Calendar Id" }, "source_calendar_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Source Calendar Name" }, "source_calendar_provider": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Source Calendar Provider" }, "source_email_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Source Email Id" }, "source_type": { "title": "Source Type", "type": "string" }, "tenant_id": { "title": "Tenant Id", "type": "string" }, "updated_at": { "format": "date-time", "title": "Updated At", "type": "string" } }, "required": [ "id", "event_id", "tenant_id", "source_type", "created_at", "updated_at" ], "title": "EventSourceMapping", "type": "object" }, "EventSummary": { "description": "Summary of a related event.", "properties": { "id": { "description": "Event ID (UUID)", "title": "Id", "type": "string" }, "link_direction": { "default": "outgoing", "description": "Direction of the edge relative to the primitive you asked about: 'outgoing' (the edge starts there and points at this one) or 'incoming' (this one points AT it). TIDY-15687.", "title": "Link Direction", "type": "string" }, "link_type": { "description": "How this event is related", "title": "Link Type", "type": "string" }, "location": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Event location", "title": "Location" }, "start_time": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "description": "Event start time", "title": "Start Time" }, "title": { "description": "Event title", "title": "Title", "type": "string" }, "type": { "const": "event", "default": "event", "title": "Type", "type": "string" } }, "required": [ "id", "title", "link_type" ], "title": "EventSummary", "type": "object" }, "EvidenceBatchIngest": { "properties": { "commits": { "default": [], "items": { "$ref": "#/components/schemas/CommitIngest" }, "title": "Commits", "type": "array" }, "pull_requests": { "default": [], "items": { "$ref": "#/components/schemas/PullRequestIngest" }, "title": "Pull Requests", "type": "array" }, "running_work": { "default": [], "items": { "$ref": "#/components/schemas/RunningWorkIngest" }, "title": "Running Work", "type": "array" }, "validation_runs": { "default": [], "items": { "$ref": "#/components/schemas/ValidationRunIngest" }, "title": "Validation Runs", "type": "array" } }, "title": "EvidenceBatchIngest", "type": "object" }, "EvidenceBatchResult": { "properties": { "commits": { "default": [], "items": { "$ref": "#/components/schemas/EvidenceIngestResult" }, "title": "Commits", "type": "array" }, "pull_requests": { "default": [], "items": { "$ref": "#/components/schemas/EvidenceIngestResult" }, "title": "Pull Requests", "type": "array" }, "running_work": { "default": [], "items": { "$ref": "#/components/schemas/EvidenceIngestResult" }, "title": "Running Work", "type": "array" }, "validation_runs": { "default": [], "items": { "$ref": "#/components/schemas/EvidenceIngestResult" }, "title": "Validation Runs", "type": "array" } }, "title": "EvidenceBatchResult", "type": "object" }, "EvidenceForTargetResponse": { "properties": { "records": { "default": [], "items": { "$ref": "#/components/schemas/EvidenceRecord" }, "title": "Records", "type": "array" }, "target_id": { "title": "Target Id", "type": "string" } }, "required": [ "target_id" ], "title": "EvidenceForTargetResponse", "type": "object" }, "EvidenceIngestResult": { "description": "Upsert outcome for one evidence record.", "properties": { "created": { "title": "Created", "type": "boolean" }, "evidence_kind": { "title": "Evidence Kind", "type": "string" }, "id": { "title": "Id", "type": "string" }, "links": { "default": [], "items": { "$ref": "#/components/schemas/EvidenceLinkOut" }, "title": "Links", "type": "array" }, "unresolved_refs": { "default": [], "items": { "type": "string" }, "title": "Unresolved Refs", "type": "array" } }, "required": [ "id", "evidence_kind", "created" ], "title": "EvidenceIngestResult", "type": "object" }, "EvidenceLinkIn": { "description": "One in-call link from the evidence record to work/a requirement.\n\nName the target by activity id, or (TIDY-15590) by the tracker key the\nwork item was imported under (``target_ref``, e.g. ``TIDY-1234`` —\n``activities.provenance->>'source_ref'``). A git hook only knows the key\nin the commit subject; the server resolves it, and an unknown key is\nreported back as ``unresolved_refs`` rather than failing the ingest.", "properties": { "relation": { "default": "evidences", "enum": [ "evidences", "evidenced_by" ], "title": "Relation", "type": "string" }, "target_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Activity typed id (A-)", "title": "Target Id" }, "target_ref": { "anyOf": [ { "maxLength": 64, "minLength": 1, "type": "string" }, { "type": "null" } ], "description": "Tracker key the activity was imported under (e.g. TIDY-1234)", "title": "Target Ref" } }, "title": "EvidenceLinkIn", "type": "object" }, "EvidenceLinkOut": { "properties": { "relation": { "default": "evidences", "title": "Relation", "type": "string" }, "target_id": { "title": "Target Id", "type": "string" } }, "required": [ "target_id" ], "title": "EvidenceLinkOut", "type": "object" }, "EvidenceRecord": { "description": "One evidence record (union shape across the three kinds).", "properties": { "author": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Author" }, "authored_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Authored At" }, "created_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Created At" }, "evidence_kind": { "title": "Evidence Kind", "type": "string" }, "head_sha": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Head Sha" }, "health_detail": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Health Detail" }, "health_state": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Health State" }, "id": { "title": "Id", "type": "string" }, "kind": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Kind" }, "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Label" }, "last_checked_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Last Checked At" }, "links": { "default": [], "items": { "$ref": "#/components/schemas/EvidenceLinkOut" }, "title": "Links", "type": "array" }, "message_subject": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Message Subject" }, "number": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Number" }, "provider": { "title": "Provider", "type": "string" }, "ran_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Ran At" }, "repository": { "title": "Repository", "type": "string" }, "result": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Result" }, "run_identifier": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Run Identifier" }, "session_links": { "default": [], "items": { "$ref": "#/components/schemas/EvidenceSessionLink" }, "title": "Session Links", "type": "array" }, "sha": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Sha" }, "source_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Source Url" }, "state": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "State" }, "summary": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "title": "Summary" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Title" }, "updated_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Updated At" }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Url" }, "workshop": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Workshop" } }, "required": [ "id", "evidence_kind", "repository", "provider" ], "title": "EvidenceRecord", "type": "object" }, "EvidenceSessionLink": { "description": "One authored-ref session↔commit link on a commit/PR chip (TIDY-17541).\n\nPresent ONLY when an explicit `commit_created` event linked the SHA to the\nexact authoring turn — a webhook-only commit carries none, and the chip\nmust not claim an exact turn for it (D8).", "properties": { "agent_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Agent Name" }, "authored_ref": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Authored Ref" }, "conversation_title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Conversation Title" }, "matrix_room_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Matrix Room Id" }, "matrix_thread_root_event_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Matrix Thread Root Event Id" }, "session_id": { "title": "Session Id", "type": "string" }, "turn_ordinal": { "title": "Turn Ordinal", "type": "integer" } }, "required": [ "session_id", "turn_ordinal" ], "title": "EvidenceSessionLink", "type": "object" }, "ExceptionResult": { "description": "Result of creating a single-occurrence exception (TIDY-11427).", "properties": { "override_event_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "The standalone override event id (V-) for a reschedule.", "title": "Override Event Id" }, "skipped": { "description": "True when the occurrence was skipped (no override).", "title": "Skipped", "type": "boolean" } }, "required": [ "skipped" ], "title": "ExceptionResult", "type": "object" }, "ExchangeRequest": { "properties": { "account_id": { "description": "End-user account_id (UUID).", "title": "Account Id", "type": "string" }, "room_audience": { "anyOf": [ { "$ref": "#/components/schemas/ExchangeRoomAudience" }, { "type": "null" } ], "description": "TIDY-19557: mint the bearer for a turn in this project room or channel. It then reads only what every reader of the room may read and reaches only the routes proven for that; a room that cannot be served this way is refused with turn_audience_unsupported." }, "tenant_id": { "description": "End-user tenant_id (UUID).", "title": "Tenant Id", "type": "string" }, "work_audience": { "anyOf": [ { "$ref": "#/components/schemas/ExchangeWorkAudience" }, { "type": "null" } ], "description": "TIDY-19370: mint the bearer for the Tidy Assistant working this shared item of account_id's. It then reads only what every member who changed the item's instructions may read and writes only that item; an item that cannot be served this way is refused with turn_audience_unsupported." } }, "required": [ "account_id", "tenant_id" ], "title": "ExchangeRequest", "type": "object" }, "ExchangeResponse": { "properties": { "access_token": { "title": "Access Token", "type": "string" }, "expires_in": { "title": "Expires In", "type": "integer" }, "scope": { "title": "Scope", "type": "string" }, "token_type": { "default": "Bearer", "title": "Token Type", "type": "string" } }, "required": [ "access_token", "expires_in", "scope" ], "title": "ExchangeResponse", "type": "object" }, "ExchangeRoomAudience": { "description": "The room a turn answers in, as the delegating service read it (TIDY-19557 F3).", "properties": { "members": { "description": "Joined and invited Matrix ids of the room, from the homeserver.", "items": { "type": "string" }, "maxItems": 2000, "title": "Members", "type": "array" }, "room_id": { "maxLength": 512, "minLength": 1, "title": "Room Id", "type": "string" }, "sender": { "description": "Matrix id of the human who addressed the assistant: account_id's own.", "maxLength": 512, "minLength": 1, "title": "Sender", "type": "string" } }, "required": [ "room_id", "sender", "members" ], "title": "ExchangeRoomAudience", "type": "object" }, "ExchangeSessionRequest": { "description": "Request body for Supabase session → Tidy JWT exchange.\n\n`resource` is the OAuth 2.1 resource (RFC 8707) the minted token is bound\nto. When omitted the server resolves it from its own configuration\n(`https://{app_hostname}/api/v1`) so the public OpenAPI spec does not\nleak per-environment hostnames.", "properties": { "client_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Client Id" }, "device_label": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Device Label" }, "resource": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Resource" }, "scope": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Scope" }, "supabase_access_token": { "title": "Supabase Access Token", "type": "string" } }, "required": [ "supabase_access_token" ], "title": "ExchangeSessionRequest", "type": "object" }, "ExchangeSessionResponse": { "description": "Response from Supabase session → Tidy JWT exchange.\n\n``refresh_token`` is null only for the TIDY-17567 unverified-operator\nbootstrap credential (tenantless, verified=false, no refresh family —\nsame shape as the signup pre-verification credential). Every customer\nexchange returns a real refresh token, unchanged.", "properties": { "access_token": { "title": "Access Token", "type": "string" }, "expires_in": { "title": "Expires In", "type": "integer" }, "refresh_token": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Refresh Token" }, "scope": { "title": "Scope", "type": "string" }, "token_type": { "title": "Token Type", "type": "string" } }, "required": [ "access_token", "token_type", "expires_in", "scope" ], "title": "ExchangeSessionResponse", "type": "object" }, "ExchangeWorkAudience": { "description": "The shared item a run works on, as the delegating service names it (TIDY-19370).", "properties": { "item_id": { "description": "The item (activity) the run works on.", "format": "uuid", "title": "Item Id", "type": "string" } }, "required": [ "item_id" ], "title": "ExchangeWorkAudience", "type": "object" }, "ExecuteAccepted": { "properties": { "execution_id": { "title": "Execution Id", "type": "string" }, "status": { "default": "queued", "title": "Status", "type": "string" } }, "required": [ "execution_id" ], "title": "ExecuteAccepted", "type": "object" }, "ExecuteAsyncAccepted": { "properties": { "continuation_id": { "title": "Continuation Id", "type": "string" }, "status": { "default": "queued", "title": "Status", "type": "string" }, "workflow_run_id": { "title": "Workflow Run Id", "type": "string" } }, "required": [ "workflow_run_id", "continuation_id" ], "title": "ExecuteAsyncAccepted", "type": "object" }, "ExecuteAsyncRequest": { "description": "Body for ``POST /workflows/{id}/execute-async`` (TIDY-11351 / S3).\n\nDispatches a background workflow run AND writes an ``assistant_continuations``\nrow so the assistant is auto-re-engaged in ``conversation_id`` on completion.", "properties": { "agent_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "AI-employee persona agent_id to preserve across the resume.", "title": "Agent Id" }, "conversation_id": { "description": "Conversation to resume on completion.", "title": "Conversation Id", "type": "string" }, "depth": { "default": 0, "description": "Resumption depth; the resumed turn dispatches at depth+1.", "minimum": 0.0, "title": "Depth", "type": "integer" }, "inputs": { "additionalProperties": true, "description": "Inputs forwarded to the workflow run.", "title": "Inputs", "type": "object" }, "notify_policy": { "default": "on_complete", "description": "on_complete | on_error | on_each_batch | silent", "title": "Notify Policy", "type": "string" }, "resume_instruction": { "description": "What the assistant should do when the job finishes.", "maxLength": 4000, "minLength": 1, "title": "Resume Instruction", "type": "string" }, "trigger_source": { "default": "assistant_background", "title": "Trigger Source", "type": "string" } }, "required": [ "conversation_id", "resume_instruction" ], "title": "ExecuteAsyncRequest", "type": "object" }, "ExecutionResponse": { "properties": { "ceilings": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "title": "Ceilings" }, "completed_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Completed At" }, "cost_micros": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Cost Micros" }, "duration_ms": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Duration Ms" }, "ephemeral": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "title": "Ephemeral" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error" }, "execution_user_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Execution User Id" }, "exit_code": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Exit Code" }, "id": { "title": "Id", "type": "string" }, "memory_mb": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Memory Mb" }, "started_at": { "format": "date-time", "title": "Started At", "type": "string" }, "status": { "title": "Status", "type": "string" }, "stderr": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Stderr" }, "stdout": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Stdout" }, "temporal_execution_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Temporal Execution Id" }, "tenant_id": { "title": "Tenant Id", "type": "string" }, "trigger_source": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Trigger Source" }, "user_id": { "title": "User Id", "type": "string" }, "workflow_id": { "title": "Workflow Id", "type": "string" }, "workflow_owner_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Workflow Owner Id" } }, "required": [ "id", "tenant_id", "user_id", "workflow_id", "temporal_execution_id", "started_at", "completed_at", "duration_ms", "memory_mb", "status", "exit_code", "error", "stdout", "stderr", "cost_micros" ], "title": "ExecutionResponse", "type": "object" }, "ExpansionIssue": { "description": "A flag surfaced during send-time recipient expansion (TIDY-14747 / R18, R21).\n\nExpansion is a deterministic read; nothing is silently dropped. Each\nunresolvable member/chip becomes one of these. The send path enforces\nblocking issues (``empty_group`` chip, top-level ``unaddressable_org`` chip,\nzero resolvable → 400) and returns the rest as ``expansion_warnings``; the\npreview endpoint returns them all so the client can warn pre-send.", "properties": { "field": { "description": "Which recipient field the chip was in", "enum": [ "to", "cc", "bcc" ], "title": "Field", "type": "string" }, "group_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "description": "Set when the issue is for a member inside a group chip", "title": "Group Id" }, "id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "description": "Contact or organization id", "title": "Id" }, "kind": { "enum": [ "no_address", "unaddressable_org", "empty_group" ], "title": "Kind", "type": "string" }, "member_kind": { "anyOf": [ { "enum": [ "contact", "organization" ], "type": "string" }, { "type": "null" } ], "description": "For 'no_address'/'unaddressable_org': the member's kind", "title": "Member Kind" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Member/org/group display name", "title": "Name" }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "For 'unaddressable_org': the addressability reason", "title": "Reason" } }, "required": [ "kind", "field" ], "title": "ExpansionIssue", "type": "object" }, "ExportCreateRequest": { "properties": { "date_range": { "anyOf": [ { "$ref": "#/components/schemas/ExportDateRange" }, { "type": "null" } ] }, "entity_types": { "anyOf": [ { "items": { "enum": [ "email", "calendar", "contacts", "notes", "podcasts", "files", "audit" ], "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Entity Types" }, "scope": { "default": "all", "enum": [ "all", "partial" ], "title": "Scope", "type": "string" } }, "title": "ExportCreateRequest", "type": "object" }, "ExportCreateResponse": { "properties": { "job_id": { "title": "Job Id", "type": "string" }, "status": { "default": "queued", "enum": [ "queued", "building", "packaging", "ready", "failed", "expired" ], "title": "Status", "type": "string" } }, "required": [ "job_id" ], "title": "ExportCreateResponse", "type": "object" }, "ExportDateRange": { "description": "Optional date-range filter for partial exports.", "properties": { "end": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "End" }, "start": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Start" } }, "title": "ExportDateRange", "type": "object" }, "ExportDocxRequest": { "properties": { "headerFooter": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Headerfooter" }, "noteId": { "title": "Noteid", "type": "string" } }, "required": [ "noteId" ], "title": "ExportDocxRequest", "type": "object" }, "ExportFacetPdfRequest": { "description": "Facet-scoped report export — resolves the instance's host note.", "properties": { "cover": { "anyOf": [ { "$ref": "#/components/schemas/ReportCoverModel" }, { "type": "null" } ] }, "instanceId": { "title": "Instanceid", "type": "string" } }, "required": [ "instanceId" ], "title": "ExportFacetPdfRequest", "type": "object" }, "ExportFilters": { "properties": { "action": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Action" }, "actor_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Actor Type" }, "mcp_session_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Mcp Session Id" }, "resource_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Resource Type" } }, "title": "ExportFilters", "type": "object" }, "ExportFormPdf": { "description": "Form projection export (TIDY-14397 / S8): a blank (print-and-use) or\nfilled render of a canonical primitive-backed facet form. ``filled``\nrequires ``record_id`` plus the facet identity used to resolve and validate\nthe registered backing primitive; ``blank`` requires ``facet_slug`` or\n``template_id`` (optionally pinned to ``template_version_id``).", "properties": { "facetSlug": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Facetslug" }, "mode": { "enum": [ "blank", "filled" ], "title": "Mode", "type": "string" }, "recordId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Recordid" }, "templateId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Templateid" }, "templateVersionId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Templateversionid" } }, "required": [ "mode" ], "title": "ExportFormPdf", "type": "object" }, "ExportImageBytes": { "description": "Binary transport marker; actual response is image bytes.", "properties": {}, "title": "ExportImageBytes", "type": "object" }, "ExportJobResponse": { "properties": { "job_id": { "format": "uuid", "title": "Job Id", "type": "string" }, "location": { "title": "Location", "type": "string" }, "status": { "title": "Status", "type": "string" } }, "required": [ "job_id", "status", "location" ], "title": "ExportJobResponse", "type": "object" }, "ExportJobStatusResponse": { "properties": { "download_expires_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Download Expires At" }, "download_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Download Url" }, "entry_count": { "default": 0, "title": "Entry Count", "type": "integer" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Error" }, "job_id": { "format": "uuid", "title": "Job Id", "type": "string" }, "status": { "title": "Status", "type": "string" } }, "required": [ "job_id", "status" ], "title": "ExportJobStatusResponse", "type": "object" }, "ExportPdfRequest": { "properties": { "brandColor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Brandcolor" }, "cover": { "anyOf": [ { "$ref": "#/components/schemas/ReportCoverModel" }, { "type": "null" } ] }, "form": { "anyOf": [ { "$ref": "#/components/schemas/ExportFormPdf" }, { "type": "null" } ] }, "logoFileId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Logofileid" }, "noteId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Noteid" }, "options": { "anyOf": [ { "$ref": "#/components/schemas/PdfOptions" }, { "type": "null" } ] }, "profile": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Profile" }, "sectionOrder": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Sectionorder" } }, "title": "ExportPdfRequest", "type": "object" }, "ExportPptxRequest": { "properties": { "noteId": { "title": "Noteid", "type": "string" } }, "required": [ "noteId" ], "title": "ExportPptxRequest", "type": "object" }, "ExportProgress": { "properties": { "current_stage": { "default": "queued", "title": "Current Stage", "type": "string" }, "processed": { "default": 0, "title": "Processed", "type": "integer" }, "total": { "default": 0, "title": "Total", "type": "integer" } }, "title": "ExportProgress", "type": "object" }, "ExportRequest": { "properties": { "date_from": { "format": "date", "title": "Date From", "type": "string" }, "date_to": { "format": "date", "title": "Date To", "type": "string" }, "filters": { "$ref": "#/components/schemas/ExportFilters" }, "format": { "default": "jsonl", "enum": [ "jsonl", "csv" ], "title": "Format", "type": "string" } }, "required": [ "date_from", "date_to" ], "title": "ExportRequest", "type": "object" }, "ExportResult": { "properties": { "archive": { "additionalProperties": true, "title": "Archive", "type": "object" }, "counts": { "additionalProperties": { "type": "integer" }, "title": "Counts", "type": "object" }, "schema_version": { "title": "Schema Version", "type": "string" } }, "required": [ "schema_version", "counts", "archive" ], "title": "ExportResult", "type": "object" }, "ExportRoomOption": { "properties": { "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Name" }, "room_id": { "title": "Room Id", "type": "string" } }, "required": [ "room_id" ], "title": "ExportRoomOption", "type": "object" }, "ExportXlsxRequest": { "properties": { "noteId": { "title": "Noteid", "type": "string" } }, "required": [ "noteId" ], "title": "ExportXlsxRequest", "type": "object" }, "ExtensionAssistantMessageRequest": { "properties": { "conversation_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Conversation Id" }, "message": { "maxLength": 10000, "minLength": 1, "title": "Message", "type": "string" }, "page_context": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Page Context" } }, "required": [ "message" ], "title": "ExtensionAssistantMessageRequest", "type": "object" }, "ExtensionAssistantMessageResponse": { "properties": { "answer_text": { "title": "Answer Text", "type": "string" }, "channel": { "default": "extension_assistant", "title": "Channel", "type": "string" }, "conversation_id": { "title": "Conversation Id", "type": "string" }, "error": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Error" } }, "required": [ "conversation_id", "answer_text" ], "title": "ExtensionAssistantMessageResponse", "type": "object" }, "ExtensionPrimitiveCacheItem": { "properties": { "id": { "title": "Id", "type": "string" }, "secondary": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Secondary" }, "title": { "title": "Title", "type": "string" }, "type": { "title": "Type", "type": "string" }, "typed_id": { "title": "Typed Id", "type": "string" }, "updated_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Updated At" } }, "required": [ "id", "typed_id", "type", "title" ], "title": "ExtensionPrimitiveCacheItem", "type": "object" }, "ExtensionPrimitiveCacheResponse": { "properties": { "primitives": { "items": { "$ref": "#/components/schemas/ExtensionPrimitiveCacheItem" }, "title": "Primitives", "type": "array" } }, "required": [ "primitives" ], "title": "ExtensionPrimitiveCacheResponse", "type": "object" }, "ExtractOnlyResponse": { "description": "Response from extract-only processing (no chunking).", "properties": { "char_count": { "default": 0, "title": "Char Count", "type": "integer" }, "document_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Document Id" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error" }, "module": { "title": "Module", "type": "string" }, "source_document": { "title": "Source Document", "type": "string" }, "success": { "title": "Success", "type": "boolean" } }, "required": [ "success", "source_document", "module" ], "title": "ExtractOnlyResponse", "type": "object" }, "ExtractResponse": { "properties": { "formality_score": { "title": "Formality Score", "type": "number" }, "profile_id": { "format": "uuid", "title": "Profile Id", "type": "string" }, "profile_version": { "title": "Profile Version", "type": "integer" }, "samples_analyzed": { "title": "Samples Analyzed", "type": "integer" }, "style_guide": { "title": "Style Guide", "type": "string" } }, "required": [ "profile_id", "style_guide", "formality_score", "samples_analyzed", "profile_version" ], "title": "ExtractResponse", "type": "object" }, "ExtractedContactCandidate": { "description": "Normalized contact candidate extracted from unstructured text.", "properties": { "addresses": { "description": "Normalized address candidates", "items": { "additionalProperties": true, "type": "object" }, "title": "Addresses", "type": "array" }, "email_addresses": { "description": "Normalized email address candidates", "items": { "additionalProperties": true, "type": "object" }, "title": "Email Addresses", "type": "array" }, "first_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Extracted first name", "title": "First Name" }, "last_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Extracted last name", "title": "Last Name" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Extracted contact name", "title": "Name" }, "organization": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Related organization name", "title": "Organization" }, "phone_numbers": { "description": "Normalized phone number candidates", "items": { "additionalProperties": true, "type": "object" }, "title": "Phone Numbers", "type": "array" }, "role": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Extracted role or title", "title": "Role" } }, "title": "ExtractedContactCandidate", "type": "object" }, "ExtractedOrganizationCandidate": { "description": "Normalized organization candidate extracted from unstructured text.", "properties": { "address": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Extracted organization address", "title": "Address" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Extracted summary text", "title": "Description" }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Extracted organization email", "title": "Email" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Extracted organization name", "title": "Name" }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Extracted organization phone", "title": "Phone" }, "type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Inferred organization type", "title": "Type" }, "website": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Extracted website", "title": "Website" } }, "title": "ExtractedOrganizationCandidate", "type": "object" }, "ExtractionDefaultsBody": { "description": "Map of primitive_type -> default destination config.", "properties": { "defaults": { "additionalProperties": { "additionalProperties": true, "type": "object" }, "title": "Defaults", "type": "object" } }, "title": "ExtractionDefaultsBody", "type": "object" }, "ExtractionDefaultsResponse": { "properties": { "defaults": { "additionalProperties": { "additionalProperties": true, "type": "object" }, "title": "Defaults", "type": "object" } }, "required": [ "defaults" ], "title": "ExtractionDefaultsResponse", "type": "object" }, "ExtractionDetailResponse": { "properties": { "canonicalDoc": { "anyOf": [ { "$ref": "#/components/schemas/CanonicalDocInfo" }, { "type": "null" } ] }, "entityId": { "title": "Entityid", "type": "string" }, "entityTable": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Entitytable" }, "extraction": { "anyOf": [ { "$ref": "#/components/schemas/ExtractionRecord" }, { "type": "null" } ] }, "isGraphReconciled": { "default": false, "title": "Isgraphreconciled", "type": "boolean" }, "pipelineRun": { "anyOf": [ { "$ref": "#/components/schemas/PipelineRunInfo" }, { "type": "null" } ] } }, "required": [ "entityId" ], "title": "ExtractionDetailResponse", "type": "object" }, "ExtractionInsightsResponse": { "description": "Itemized extraction insight for one source document (file or attachment).\n\n``source_type`` discriminates the origin. Exactly one of ``file_id`` /\n``attachment_id`` is populated; ``email_id`` is the owning email for the\nattachment source (None for the file source). Every list reuses the replay\nartifact/memory sub-models, so the frontend renders files, attachments, and\nthe replay journey through one component set.", "properties": { "attachment_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Attachment Id" }, "attachments": { "default": [], "items": { "$ref": "#/components/schemas/ReplayArtifactAttachment" }, "title": "Attachments", "type": "array" }, "calendar_events": { "default": [], "items": { "$ref": "#/components/schemas/ReplayArtifactCalendarEvent" }, "title": "Calendar Events", "type": "array" }, "contacts": { "default": [], "items": { "$ref": "#/components/schemas/ReplayArtifactContact" }, "title": "Contacts", "type": "array" }, "documents": { "default": [], "items": { "$ref": "#/components/schemas/ReplayArtifactDocument" }, "title": "Documents", "type": "array" }, "email_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Email Id" }, "failure_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Failure Reason" }, "file_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "File Id" }, "memories": { "default": [], "items": { "$ref": "#/components/schemas/ReplayMemory" }, "title": "Memories", "type": "array" }, "memory_trace_count": { "default": 0, "title": "Memory Trace Count", "type": "integer" }, "organizations": { "default": [], "items": { "$ref": "#/components/schemas/ReplayArtifactOrganization" }, "title": "Organizations", "type": "array" }, "processor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Processor" }, "reminders": { "default": [], "items": { "$ref": "#/components/schemas/ReplayArtifactReminder" }, "title": "Reminders", "type": "array" }, "routing": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Routing" }, "run_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Run Status" }, "source_type": { "title": "Source Type", "type": "string" } }, "required": [ "source_type" ], "title": "ExtractionInsightsResponse", "type": "object" }, "ExtractionRecord": { "description": "Row from pending_extractions plus synthetic rows built from entities.", "properties": { "confidence_score": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "title": "Confidence Score" }, "created_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Created At" }, "doc_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Doc Id" }, "extracted_data": { "anyOf": [ {}, { "type": "null" } ], "default": null, "title": "Extracted Data" }, "id": { "title": "Id", "type": "string" }, "primitive_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Primitive Type" }, "reasoning": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Reasoning" }, "source_snippet": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Source Snippet" }, "status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Status" }, "target_entity_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Target Entity Id" }, "target_table": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Target Table" }, "tenant_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Tenant Id" }, "updated_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Updated At" } }, "required": [ "id" ], "title": "ExtractionRecord", "type": "object" }, "ExtractionsByDocResponse": { "properties": { "canonicalDoc": { "anyOf": [ { "$ref": "#/components/schemas/CanonicalDocInfo" }, { "type": "null" } ] }, "docId": { "title": "Docid", "type": "string" }, "extractions": { "items": { "$ref": "#/components/schemas/ExtractionRecord" }, "title": "Extractions", "type": "array" }, "pipelineRun": { "anyOf": [ { "$ref": "#/components/schemas/PipelineRunInfo" }, { "type": "null" } ] } }, "required": [ "extractions", "docId" ], "title": "ExtractionsByDocResponse", "type": "object" }, "FaceBox": { "properties": { "h": { "title": "H", "type": "number" }, "w": { "title": "W", "type": "number" }, "x": { "title": "X", "type": "number" }, "y": { "title": "Y", "type": "number" } }, "required": [ "x", "y", "w", "h" ], "title": "FaceBox", "type": "object" }, "FaceCluster": { "properties": { "face_count": { "title": "Face Count", "type": "integer" }, "id": { "format": "uuid", "title": "Id", "type": "string" }, "representative_face": { "anyOf": [ { "$ref": "#/components/schemas/RepresentativeFace" }, { "type": "null" } ], "default": null }, "sample_faces": { "items": { "$ref": "#/components/schemas/RepresentativeFace" }, "title": "Sample Faces", "type": "array" }, "suggestion": { "anyOf": [ { "$ref": "#/components/schemas/ClusterSuggestion" }, { "type": "null" } ], "default": null } }, "required": [ "id", "face_count" ], "title": "FaceCluster", "type": "object" }, "FaceClusterListResponse": { "properties": { "clusters": { "items": { "$ref": "#/components/schemas/FaceCluster" }, "title": "Clusters", "type": "array" } }, "required": [ "clusters" ], "title": "FaceClusterListResponse", "type": "object" }, "FaceDetection": { "description": "One face on a photo. ``contact_id``/``link_*`` are populated only when the\nlinked contact is visible to the caller; otherwise the detection is returned\nwith ``linked=false`` and a null contact (detection visible, link hidden).", "properties": { "box": { "$ref": "#/components/schemas/FaceBox" }, "contact_display_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Contact Display Name" }, "contact_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "default": null, "title": "Contact Id" }, "dismissed": { "default": false, "title": "Dismissed", "type": "boolean" }, "id": { "format": "uuid", "title": "Id", "type": "string" }, "link_confidence": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "title": "Link Confidence" }, "link_source": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Link Source" }, "linked": { "default": false, "title": "Linked", "type": "boolean" }, "quality": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "title": "Quality" } }, "required": [ "id", "box" ], "title": "FaceDetection", "type": "object" }, "FaceLinkResponse": { "properties": { "contact_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "default": null, "title": "Contact Id" }, "face_id": { "format": "uuid", "title": "Face Id", "type": "string" }, "link_source": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Link Source" }, "linked": { "default": false, "title": "Linked", "type": "boolean" } }, "required": [ "face_id" ], "title": "FaceLinkResponse", "type": "object" }, "FaceListResponse": { "properties": { "faces": { "items": { "$ref": "#/components/schemas/FaceDetection" }, "title": "Faces", "type": "array" }, "photo_id": { "format": "uuid", "title": "Photo Id", "type": "string" } }, "required": [ "photo_id", "faces" ], "title": "FaceListResponse", "type": "object" }, "FaceSuggestion": { "properties": { "contact_id": { "format": "uuid", "title": "Contact Id", "type": "string" }, "display_name": { "title": "Display Name", "type": "string" }, "photo_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Photo Url" }, "similarity": { "title": "Similarity", "type": "number" } }, "required": [ "contact_id", "display_name", "similarity" ], "title": "FaceSuggestion", "type": "object" }, "FaceSuggestionsResponse": { "properties": { "face_id": { "format": "uuid", "title": "Face Id", "type": "string" }, "suggestions": { "items": { "$ref": "#/components/schemas/FaceSuggestion" }, "title": "Suggestions", "type": "array" } }, "required": [ "face_id", "suggestions" ], "title": "FaceSuggestionsResponse", "type": "object" }, "FacetDemoteRequest": { "properties": { "to_visibility": { "description": "Target tier: 'private' or 'shared'", "title": "To Visibility", "type": "string" } }, "required": [ "to_visibility" ], "title": "FacetDemoteRequest", "type": "object" }, "FacetExtractionRequest": { "properties": { "bundle_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "description": "The caller's capture bundle (TIDY-19719 F8). Its sources — pasted text, linked notes/tasks/emails/files, web pages, photos — are read into the extraction through the shared bundle assembler: member visibility re-checked per item, excluded items left out, reviewed instructions steering. Every item that contributed nothing comes back in sources_not_used. Absent, only text/image_urls/source_url are read, exactly as before.", "title": "Bundle Id" }, "bundle_item_ids": { "anyOf": [ { "items": { "type": "string" }, "maxItems": 500, "type": "array" }, { "type": "null" } ], "description": "Read only these top-level bundle items (and their children). A caller that already carries some of the bundle in text/image_urls (the phone's own dictations and photos) names the rest here so nothing is read twice. Absent, the whole bundle is read.", "title": "Bundle Item Ids" }, "captured_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "When the user captured this (TIDY-19719 F10). Relative dates (\"Friday\", \"tomorrow\") resolve from this moment on the member's clock, so a capture filled hours later still means the day it was made. Absent, now.", "title": "Captured At" }, "content_instructions": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "AI content generation instructions from facet_definitions (TIDY-6428).", "title": "Content Instructions" }, "context": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Surrounding text for disambiguation", "title": "Context" }, "facet_slug": { "description": "Facet definition slug, e.g. 'task'", "title": "Facet Slug", "type": "string" }, "idempotency_key": { "anyOf": [ { "maxLength": 200, "type": "string" }, { "type": "null" } ], "description": "Stable key identifying THIS extraction (TIDY-15980). Supply it and a completed extraction survives the caller: the result is recorded before the response is written, so a client that read-timed out gets the stored result on its next request instead of paying for the same LLM call again. A request whose key is still executing gets 409 with Retry-After rather than starting a duplicate. Absent, the endpoint behaves exactly as before — every call runs the LLM and the result exists only in the response.", "title": "Idempotency Key" }, "image_urls": { "description": "Image URLs (base64 data URIs or HTTPS) for multimodal extraction. Max 3.", "items": { "type": "string" }, "title": "Image Urls", "type": "array" }, "include_title": { "default": false, "description": "Add a concise-title field to the extraction model (TIDY-13338). Capture surfaces set this when the facet schema has no title field so a dictated capture gets an AI title instead of the raw text.", "title": "Include Title", "type": "boolean" }, "input_type": { "default": "text", "description": "Input source type", "enum": [ "text", "transcription", "email_canonical", "selection" ], "title": "Input Type", "type": "string" }, "instructions": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Per-invocation instruction override (TIDY-15681). Layers on top of the definition's content_instructions and ai_instructions and wins where they disagree — but cannot change modality, producer tier or target primitive; those come from the definition's generation contract, and a request to change one comes back in instruction_conflicts.", "title": "Instructions" }, "source_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ID of source email/note", "title": "Source Id" }, "source_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "'email', 'note', or 'document'", "title": "Source Type" }, "source_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "URL to fetch content from (Supabase storage attachment or web URL).", "title": "Source Url" }, "text": { "default": "", "description": "Selected text to extract from", "title": "Text", "type": "string" }, "time_zone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The member's IANA timezone, as the client resolves it (TIDY-19719 F10). Presence is the version signal: the model returns wall-clock times and they are converted to UTC from this zone (or from a zone the content names). Absent, yesterday's UTC contract — an installed client that does not send this still asks the model for UTC with a Z.", "title": "Time Zone" } }, "required": [ "facet_slug" ], "title": "FacetExtractionRequest", "type": "object" }, "FacetExtractionResponse": { "properties": { "confidence": { "maximum": 1.0, "minimum": 0.0, "title": "Confidence", "type": "number" }, "create_errors": { "description": "Always empty on HTTP 200. Create/refer failures are named HTTP errors (create_child / invented_uuid / unknown_reference), never a completed extract with buried errors (TIDY-17388).", "items": { "type": "string" }, "title": "Create Errors", "type": "array" }, "created_children": { "additionalProperties": { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, "description": "Rows minted for ``ai_create`` fields, keyed by field. Each item carries the server-assigned id. Empty when nothing was created.", "title": "Created Children", "type": "object" }, "extracted_fields": { "additionalProperties": true, "title": "Extracted Fields", "type": "object" }, "facet_slug": { "title": "Facet Slug", "type": "string" }, "field_confidence": { "additionalProperties": { "type": "number" }, "title": "Field Confidence", "type": "object" }, "generated_content": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Generated Content" }, "instruction_conflicts": { "description": "What the per-invocation override asked for that the output type's generation contract did not honour (TIDY-15681). Empty when there was no override, or nothing in it contradicted the definition.", "items": { "type": "string" }, "title": "Instruction Conflicts", "type": "array" }, "producer_payload": { "anyOf": [ { "$ref": "#/components/schemas/ProducerPayload" }, { "type": "null" } ] }, "requires_review": { "default": false, "title": "Requires Review", "type": "boolean" }, "signals": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Signals" }, "sources_not_used": { "description": "Everything the caller put in the capture that the extraction did not read, and why (TIDY-19719 F8) — so the client can say so instead of skipping it silently. Empty when everything was read.", "items": { "$ref": "#/components/schemas/FacetSourceNotUsed" }, "title": "Sources Not Used", "type": "array" }, "time_zone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The IANA zone wall-clock datetimes were converted from (TIDY-19719 F10). A string when the client sent time_zone; null or absent on an older server, or when the client did not send one (the UTC contract). A new client that sent time_zone and gets no string must fail loud rather than store unconverted times.", "title": "Time Zone" } }, "required": [ "facet_slug", "extracted_fields", "confidence", "field_confidence" ], "title": "FacetExtractionResponse", "type": "object" }, "FacetOption": { "properties": { "disabled": { "default": false, "title": "Disabled", "type": "boolean" }, "id": { "title": "Id", "type": "string" }, "label": { "title": "Label", "type": "string" }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Reason" } }, "required": [ "id", "label" ], "title": "FacetOption", "type": "object" }, "FacetOptionsResponse": { "properties": { "dependencies": { "items": { "type": "string" }, "title": "Dependencies", "type": "array" }, "message": { "default": "", "title": "Message", "type": "string" }, "missing_dependencies": { "items": { "type": "string" }, "title": "Missing Dependencies", "type": "array" }, "options": { "items": { "$ref": "#/components/schemas/FacetOption" }, "title": "Options", "type": "array" }, "resolved_at": { "format": "date-time", "title": "Resolved At", "type": "string" }, "state": { "default": "resolved", "enum": [ "resolved", "empty", "missing_dependencies", "host_only" ], "title": "State", "type": "string" } }, "required": [ "options", "resolved_at" ], "title": "FacetOptionsResponse", "type": "object" }, "FacetOwnerAttribution": { "description": "Attribution shown for shared/global facets owned by another member.", "properties": { "display_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Display Name" }, "id": { "format": "uuid", "title": "Id", "type": "string" } }, "required": [ "id" ], "title": "FacetOwnerAttribution", "type": "object" }, "FacetPromoteRequest": { "properties": { "to_visibility": { "description": "Target tier: 'shared' or 'global'", "title": "To Visibility", "type": "string" } }, "required": [ "to_visibility" ], "title": "FacetPromoteRequest", "type": "object" }, "FacetSelection": { "properties": { "accepted": { "title": "Accepted", "type": "boolean" }, "cluster_id": { "maxLength": 255, "minLength": 1, "title": "Cluster Id", "type": "string" }, "inherits_from": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Inherits From" }, "materialize_as_entity": { "anyOf": [ { "enum": [ "contact", "organization" ], "type": "string" }, { "type": "null" } ], "title": "Materialize As Entity" }, "name": { "maxLength": 255, "minLength": 1, "title": "Name", "type": "string" }, "property_keys": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Property Keys" }, "property_mapping": { "anyOf": [ { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "type": "object" }, { "type": "null" } ], "title": "Property Mapping" }, "source_cluster_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Source Cluster Id" }, "source_cluster_ids": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Source Cluster Ids" }, "use_existing_facet": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Use Existing Facet" } }, "required": [ "cluster_id", "name", "accepted" ], "title": "FacetSelection", "type": "object" }, "FacetShadowReportResponse": { "description": "Per-FACET edge quality over the requested window (TIDY-15776 / F12-S7).", "properties": { "facets": { "additionalProperties": true, "default": {}, "title": "Facets", "type": "object" }, "min_window_samples": { "title": "Min Window Samples", "type": "integer" }, "quality_floor": { "title": "Quality Floor", "type": "number" }, "total_evals": { "title": "Total Evals", "type": "integer" }, "window_days": { "title": "Window Days", "type": "integer" } }, "required": [ "window_days", "total_evals", "quality_floor", "min_window_samples" ], "title": "FacetShadowReportResponse", "type": "object" }, "FacetSourceNotUsed": { "description": "One thing in the capture the extraction did not read (TIDY-19719 F8).", "properties": { "bundle_item_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Bundle Item Id" }, "image_index": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Index into the request's image_urls, for a caller image.", "title": "Image Index" }, "message": { "description": "The reason in plain words, for the user.", "title": "Message", "type": "string" }, "reason": { "description": "A bundle item failure code or omission reason (the shared bundle vocabulary), or `image_over_cap` for an image past the image cap.", "title": "Reason", "type": "string" }, "title": { "title": "Title", "type": "string" } }, "required": [ "title", "reason", "message" ], "title": "FacetSourceNotUsed", "type": "object" }, "FacetSummary": { "description": "One existing facet definition, summarized for authoring decisions.", "properties": { "field_count": { "title": "Field Count", "type": "integer" }, "formula_field_count": { "title": "Formula Field Count", "type": "integer" }, "is_system": { "title": "Is System", "type": "boolean" }, "name": { "title": "Name", "type": "string" }, "slug": { "title": "Slug", "type": "string" }, "target_table": { "title": "Target Table", "type": "string" } }, "required": [ "slug", "name", "target_table", "is_system", "field_count", "formula_field_count" ], "title": "FacetSummary", "type": "object" }, "FacetVisibilityResponse": { "description": "Successful promote/demote: the visibility transition that was applied.", "properties": { "from_visibility": { "title": "From Visibility", "type": "string" }, "ok": { "default": true, "title": "Ok", "type": "boolean" }, "to_visibility": { "title": "To Visibility", "type": "string" } }, "required": [ "from_visibility", "to_visibility" ], "title": "FacetVisibilityResponse", "type": "object" }, "FactorsResponse": { "properties": { "factors": { "items": { "enum": [ "password", "provider", "email_otp", "totp", "passkey" ], "type": "string" }, "title": "Factors", "type": "array" }, "providers": { "items": { "type": "string" }, "title": "Providers", "type": "array" }, "recent_auth": { "anyOf": [ { "$ref": "#/components/schemas/RecentAuth" }, { "type": "null" } ], "default": null } }, "required": [ "factors", "providers" ], "title": "FactorsResponse", "type": "object" }, "FailedLedgerItemRow": { "description": "P4 S1 (R-P4.2): one FAILED priority-request ledger item.\n\n``request_ref`` is the item id (carried on the pipeline job, returned on the\nfailure push). The error payload + failure stage come from the P3 failure\npush (mark_item_failed_by_request_ref).", "properties": { "account_id": { "format": "uuid", "title": "Account Id", "type": "string" }, "audio_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Audio Url" }, "batch_id": { "format": "uuid", "title": "Batch Id", "type": "string" }, "created_at": { "title": "Created At" }, "error_message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error Message" }, "external_episode_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "External Episode Id" }, "failed_at": { "title": "Failed At" }, "failure_stage": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Failure Stage" }, "request_ref": { "format": "uuid", "title": "Request Ref", "type": "string" }, "tenant_id": { "format": "uuid", "title": "Tenant Id", "type": "string" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Title" } }, "required": [ "request_ref", "batch_id", "tenant_id", "account_id", "external_episode_id", "title", "audio_url", "error_message", "failure_stage", "failed_at", "created_at" ], "title": "FailedLedgerItemRow", "type": "object" }, "FamilyMemberInput": { "description": "Input model for a single family member.", "properties": { "date_of_birth": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Date of birth (YYYY-MM-DD format)", "title": "Date Of Birth" }, "email": { "anyOf": [ { "maxLength": 320, "type": "string" }, { "type": "null" } ], "description": "Email address", "title": "Email" }, "full_name": { "maxLength": 255, "minLength": 1, "title": "Full Name", "type": "string" }, "phone": { "anyOf": [ { "maxLength": 50, "type": "string" }, { "type": "null" } ], "description": "Phone number", "title": "Phone" }, "relationship": { "description": "Relationship: spouse, partner, child, parent, grandparent, sibling, other", "pattern": "^(spouse|partner|child|parent|grandparent|sibling|other)$", "title": "Relationship", "type": "string" } }, "required": [ "full_name", "relationship" ], "title": "FamilyMemberInput", "type": "object" }, "FamilyMemberPatch": { "description": "Partial update body for family-member management.", "properties": { "date_of_birth": { "anyOf": [ { "format": "date", "type": "string" }, { "type": "null" } ], "title": "Date Of Birth" }, "email": { "anyOf": [ { "format": "email", "type": "string" }, { "type": "null" } ], "title": "Email" }, "full_name": { "anyOf": [ { "maxLength": 255, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Full Name" }, "phone": { "anyOf": [ { "maxLength": 50, "type": "string" }, { "type": "null" } ], "title": "Phone" }, "relationship": { "anyOf": [ { "enum": [ "spouse", "partner", "child", "parent", "grandparent", "sibling", "other" ], "type": "string" }, { "type": "null" } ], "title": "Relationship" } }, "title": "FamilyMemberPatch", "type": "object" }, "FamilyMemberRecord": { "description": "A family member as stored for the current tenant.", "properties": { "contact_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Linked contact UUID", "title": "Contact Id" }, "date_of_birth": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Date of birth (YYYY-MM-DD)", "title": "Date Of Birth" }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Email address", "title": "Email" }, "full_name": { "maxLength": 255, "minLength": 1, "title": "Full Name", "type": "string" }, "id": { "description": "Family member UUID", "title": "Id", "type": "string" }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Phone number", "title": "Phone" }, "relationship": { "description": "Relationship to the user", "title": "Relationship", "type": "string" } }, "required": [ "id", "full_name", "relationship" ], "title": "FamilyMemberRecord", "type": "object" }, "FamilyMemberResponse": { "description": "Response model for family member data.", "properties": { "contact_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "default": null, "description": "Linked contact UUID", "title": "Contact Id" }, "created_at": { "description": "Creation timestamp", "format": "date-time", "title": "Created At", "type": "string" }, "created_by": { "description": "Account UUID that created this record", "format": "uuid", "title": "Created By", "type": "string" }, "date_of_birth": { "anyOf": [ { "format": "date", "type": "string" }, { "type": "null" } ], "default": null, "description": "Date of birth", "title": "Date Of Birth" }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Email address", "title": "Email" }, "full_name": { "description": "Full name", "maxLength": 255, "minLength": 1, "title": "Full Name", "type": "string" }, "gender": { "anyOf": [ { "pattern": "^(male|female|other|prefer_not_to_say)$", "type": "string" }, { "type": "null" } ], "default": null, "description": "Gender: male, female, other, prefer_not_to_say", "title": "Gender" }, "id": { "description": "Family member UUID", "format": "uuid", "title": "Id", "type": "string" }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Phone number", "title": "Phone" }, "relationship": { "description": "Relationship to user", "pattern": "^(spouse|partner|child|parent|grandparent|sibling|other)$", "title": "Relationship", "type": "string" }, "tenant_id": { "description": "Tenant UUID this family member belongs to", "format": "uuid", "title": "Tenant Id", "type": "string" }, "updated_at": { "description": "Last update timestamp", "format": "date-time", "title": "Updated At", "type": "string" } }, "required": [ "full_name", "relationship", "id", "tenant_id", "created_by", "created_at", "updated_at" ], "title": "FamilyMemberResponse", "type": "object" }, "FamilyMemberUpdate": { "description": "Request model for updating a family member (all fields optional).", "properties": { "date_of_birth": { "anyOf": [ { "format": "date", "type": "string" }, { "type": "null" } ], "title": "Date Of Birth" }, "email": { "anyOf": [ { "maxLength": 320, "type": "string" }, { "type": "null" } ], "title": "Email" }, "full_name": { "anyOf": [ { "maxLength": 255, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Full Name" }, "gender": { "anyOf": [ { "pattern": "^(male|female|other|prefer_not_to_say)$", "type": "string" }, { "type": "null" } ], "title": "Gender" }, "phone": { "anyOf": [ { "maxLength": 50, "type": "string" }, { "type": "null" } ], "title": "Phone" }, "relationship": { "anyOf": [ { "pattern": "^(spouse|partner|child|parent|grandparent|sibling|other)$", "type": "string" }, { "type": "null" } ], "title": "Relationship" } }, "title": "FamilyMemberUpdate", "type": "object" }, "FamilyMembersRequest": { "description": "Request model for adding family members.", "properties": { "members": { "description": "List of family members to add", "items": { "$ref": "#/components/schemas/FamilyMemberInput" }, "minItems": 0, "title": "Members", "type": "array" } }, "required": [ "members" ], "title": "FamilyMembersRequest", "type": "object" }, "FamilyMembersResponse": { "description": "Response model for family members operation.", "properties": { "added_count": { "description": "Number of family members added", "title": "Added Count", "type": "integer" }, "total_count": { "description": "Total family members for tenant", "title": "Total Count", "type": "integer" } }, "required": [ "added_count", "total_count" ], "title": "FamilyMembersResponse", "type": "object" }, "FeatureFlagEntry": { "description": "One registered flag, with this workspace's answer for it.\n\nThe panels iterate this list and render nothing else, so a flag that exists\nin the table but not in the registry cannot reach a user — which is exactly\nwhat the registry-completeness test refuses to let happen.", "properties": { "added_at": { "title": "Added At", "type": "string" }, "debt": { "default": false, "title": "Debt", "type": "boolean" }, "default_on": { "default": false, "title": "Default On", "type": "boolean" }, "description": { "title": "Description", "type": "string" }, "enabled": { "title": "Enabled", "type": "boolean" }, "enablement": { "default": "tenant_admin", "enum": [ "tenant_admin", "rollout_enrollment" ], "title": "Enablement", "type": "string" }, "enrollment": { "anyOf": [ { "$ref": "#/components/schemas/FlagEnrollment" }, { "type": "null" } ], "default": null }, "is_ops": { "default": false, "title": "Is Ops", "type": "boolean" }, "key": { "title": "Key", "type": "string" }, "label": { "title": "Label", "type": "string" }, "last_changed_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Last Changed At" }, "last_changed_by": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Last Changed By" }, "last_changed_to": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "title": "Last Changed To" }, "lifecycle": { "enum": [ "beta", "ga" ], "title": "Lifecycle", "type": "string" }, "owner": { "title": "Owner", "type": "string" }, "pending_work_ref": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Pending Work Ref" }, "pending_work_summary": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Pending Work Summary" }, "pending_work_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Pending Work Url" }, "removal_due_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Removal Due At" }, "requires": { "items": { "type": "string" }, "title": "Requires", "type": "array" } }, "required": [ "key", "label", "description", "enabled", "lifecycle", "owner", "added_at" ], "title": "FeatureFlagEntry", "type": "object" }, "FeatureGate": { "description": "Why a workspace lacks a premium feature, and what would unlock it.", "properties": { "feature": { "description": "Entitlement feature key, e.g. 'byo_inference'.", "title": "Feature", "type": "string" }, "kind": { "description": "'tier': a plan change unlocks it (tier_id names the plan). 'operator_override': no plan does — Tidy enables it per workspace.", "enum": [ "tier", "operator_override" ], "title": "Kind", "type": "string" }, "override_dimension": { "description": "The account_overrides dimension a Tidy operator writes for this workspace to enable the feature.", "title": "Override Dimension", "type": "string" }, "tier_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "The lowest plan carrying the feature; null when no plan does. With kind='operator_override' it is the plan an override switched off here.", "title": "Tier Id" }, "tier_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "That plan's display name.", "title": "Tier Name" } }, "required": [ "feature", "kind", "override_dimension" ], "title": "FeatureGate", "type": "object" }, "FeatureSpend": { "properties": { "calls": { "title": "Calls", "type": "integer" }, "cost_usd": { "title": "Cost Usd", "type": "number" }, "feature": { "title": "Feature", "type": "string" } }, "required": [ "feature", "cost_usd", "calls" ], "title": "FeatureSpend", "type": "object" }, "FeatureSwitchEvaluation": { "properties": { "enabled": { "title": "Enabled", "type": "boolean" }, "key": { "title": "Key", "type": "string" } }, "required": [ "key", "enabled" ], "title": "FeatureSwitchEvaluation", "type": "object" }, "FeatureSwitchLandscapeResponse": { "properties": { "cache_ttl_seconds": { "title": "Cache Ttl Seconds", "type": "number" }, "switches": { "items": { "$ref": "#/components/schemas/AdminFeatureSwitchEntry" }, "title": "Switches", "type": "array" } }, "required": [ "switches", "cache_ttl_seconds" ], "title": "FeatureSwitchLandscapeResponse", "type": "object" }, "FeaturedPodcastCreate": { "properties": { "artwork_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Artwork Url" }, "author": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Author" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "feed_id": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Feed Id" }, "rss_feed_url": { "title": "Rss Feed Url", "type": "string" }, "sort_order": { "default": 0, "title": "Sort Order", "type": "integer" }, "title": { "title": "Title", "type": "string" } }, "required": [ "title", "rss_feed_url" ], "title": "FeaturedPodcastCreate", "type": "object" }, "FeaturedPodcastResponse": { "properties": { "added_by_account_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Added By Account Id" }, "artwork_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Artwork Url" }, "author": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Author" }, "created_at": { "title": "Created At", "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "feed_id": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Feed Id" }, "id": { "title": "Id", "type": "string" }, "rss_feed_url": { "title": "Rss Feed Url", "type": "string" }, "sort_order": { "default": 0, "title": "Sort Order", "type": "integer" }, "title": { "title": "Title", "type": "string" }, "updated_at": { "title": "Updated At", "type": "string" } }, "required": [ "title", "rss_feed_url", "id", "created_at", "updated_at" ], "title": "FeaturedPodcastResponse", "type": "object" }, "FederatedResult": { "properties": { "account_badge": { "additionalProperties": true, "title": "Account Badge", "type": "object" }, "account_id": { "format": "uuid", "title": "Account Id", "type": "string" }, "account_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Account Name" }, "highlights": { "items": { "type": "string" }, "title": "Highlights", "type": "array" }, "pg_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Pg Id" }, "provenance": { "additionalProperties": true, "title": "Provenance", "type": "object" }, "score": { "default": 0.0, "title": "Score", "type": "number" }, "snippet": { "default": "", "title": "Snippet", "type": "string" }, "source_type": { "default": "", "title": "Source Type", "type": "string" } }, "required": [ "account_id" ], "title": "FederatedResult", "type": "object" }, "FederatedSearchRequest": { "properties": { "include_accounts": { "anyOf": [ { "items": { "format": "uuid", "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Include Accounts" }, "include_bm25": { "default": true, "title": "Include Bm25", "type": "boolean" }, "include_graph": { "default": true, "title": "Include Graph", "type": "boolean" }, "limit": { "default": 10, "maximum": 100.0, "minimum": 1.0, "title": "Limit", "type": "integer" }, "query": { "maxLength": 1000, "minLength": 1, "title": "Query", "type": "string" } }, "required": [ "query" ], "title": "FederatedSearchRequest", "type": "object" }, "FederatedSearchResponse": { "properties": { "accounts_searched": { "items": { "$ref": "#/components/schemas/AccountSearchStatus" }, "title": "Accounts Searched", "type": "array" }, "latency_ms": { "default": 0.0, "title": "Latency Ms", "type": "number" }, "query_expanded": { "default": "", "title": "Query Expanded", "type": "string" }, "query_id": { "format": "uuid", "title": "Query Id", "type": "string" }, "results": { "items": { "$ref": "#/components/schemas/FederatedResult" }, "title": "Results", "type": "array" }, "total_count": { "default": 0, "title": "Total Count", "type": "integer" } }, "required": [ "results", "accounts_searched", "query_id" ], "title": "FederatedSearchResponse", "type": "object" }, "FeedArchiveRequest": { "description": "Request to archive a feed card.\n\nAttributes:\n cardType: Type of card to archive\n sourceId: UUID of the source entity\n swipeDirection: Direction of swipe for feedback (KCC-2990)", "properties": { "cardType": { "$ref": "#/components/schemas/FeedCardType", "description": "Type of card to archive" }, "sourceId": { "description": "UUID of the source entity", "title": "Sourceid", "type": "string" }, "swipeDirection": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Swipe direction: 'left' (thumbs down) or 'right' (thumbs up)", "title": "Swipedirection" } }, "required": [ "cardType", "sourceId" ], "title": "FeedArchiveRequest", "type": "object" }, "FeedArchiveResponse": { "description": "Response after archiving/unarchiving a card.\n\nAttributes:\n success: Whether the operation succeeded\n cardType: Type of card affected\n sourceId: UUID of the source entity\n archived: Whether the card is now archived\n archivedAt: When the card was archived (null if unarchived)", "properties": { "archived": { "description": "Whether the card is now archived", "title": "Archived", "type": "boolean" }, "archivedAt": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "description": "When the card was archived", "title": "Archivedat" }, "cardType": { "$ref": "#/components/schemas/FeedCardType", "description": "Type of card affected" }, "sourceId": { "description": "UUID of the source entity", "title": "Sourceid", "type": "string" }, "success": { "default": true, "description": "Whether the operation succeeded", "title": "Success", "type": "boolean" } }, "required": [ "cardType", "sourceId", "archived" ], "title": "FeedArchiveResponse", "type": "object" }, "FeedArtwork": { "properties": { "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "defects": { "items": { "type": "string" }, "title": "Defects", "type": "array" }, "facet_type": { "title": "Facet Type", "type": "string" }, "has_text": { "title": "Has Text", "type": "boolean" }, "height": { "title": "Height", "type": "integer" }, "id": { "title": "Id", "type": "string" }, "image_model": { "title": "Image Model", "type": "string" }, "image_url": { "description": "A short-lived signed URL for the image.", "title": "Image Url", "type": "string" }, "mood": { "title": "Mood", "type": "string" }, "rejection_reasons": { "description": "Why the vision gate turned the image away; empty when it passed.", "items": { "type": "string" }, "title": "Rejection Reasons", "type": "array" }, "scene": { "title": "Scene", "type": "string" }, "score": { "title": "Score", "type": "number" }, "scored_by": { "title": "Scored By", "type": "string" }, "season": { "title": "Season", "type": "string" }, "seed_slot": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Seed Slot" }, "source": { "enum": [ "seed", "topup", "operator", "recipe" ], "title": "Source", "type": "string" }, "status": { "enum": [ "active", "rejected", "removed" ], "title": "Status", "type": "string" }, "storage_path": { "title": "Storage Path", "type": "string" }, "subject": { "title": "Subject", "type": "string" }, "time_of_day": { "title": "Time Of Day", "type": "string" }, "updated_at": { "format": "date-time", "title": "Updated At", "type": "string" }, "weather": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Weather" }, "width": { "title": "Width", "type": "integer" } }, "required": [ "id", "facet_type", "subject", "mood", "season", "time_of_day", "weather", "scene", "storage_path", "image_url", "width", "height", "image_model", "score", "scored_by", "has_text", "defects", "rejection_reasons", "status", "source", "seed_slot", "created_at", "updated_at" ], "title": "FeedArtwork", "type": "object" }, "FeedArtworkFamily": { "properties": { "default_mood": { "title": "Default Mood", "type": "string" }, "facet_type": { "title": "Facet Type", "type": "string" }, "subjects": { "items": { "type": "string" }, "title": "Subjects", "type": "array" } }, "required": [ "facet_type", "default_mood", "subjects" ], "title": "FeedArtworkFamily", "type": "object" }, "FeedArtworkGenerateRequest": { "properties": { "count": { "default": 1, "maximum": 6.0, "minimum": 1.0, "title": "Count", "type": "integer" }, "facet_type": { "description": "The family the images join.", "title": "Facet Type", "type": "string" }, "mood": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Defaults to the family's usual mood.", "title": "Mood" }, "prompt": { "description": "The scene to paint.", "maxLength": 300, "minLength": 1, "title": "Prompt", "type": "string" }, "season": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Defaults to any season.", "title": "Season" }, "subject": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Defaults to the family's general subject.", "title": "Subject" }, "time_of_day": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Defaults to any time of day.", "title": "Time Of Day" } }, "required": [ "prompt", "facet_type" ], "title": "FeedArtworkGenerateRequest", "type": "object" }, "FeedArtworkPage": { "properties": { "counts": { "$ref": "#/components/schemas/FeedArtworkStatusCounts", "description": "Per status, under every filter except the status one." }, "items": { "items": { "$ref": "#/components/schemas/FeedArtwork" }, "title": "Items", "type": "array" }, "total": { "title": "Total", "type": "integer" } }, "required": [ "items", "total", "counts" ], "title": "FeedArtworkPage", "type": "object" }, "FeedArtworkStatusCounts": { "properties": { "active": { "title": "Active", "type": "integer" }, "rejected": { "title": "Rejected", "type": "integer" }, "removed": { "title": "Removed", "type": "integer" } }, "required": [ "active", "rejected", "removed" ], "title": "FeedArtworkStatusCounts", "type": "object" }, "FeedArtworkStatusRequest": { "properties": { "status": { "description": "`removed` takes an active image out; `active` restores a removed one.", "enum": [ "active", "removed" ], "title": "Status", "type": "string" } }, "required": [ "status" ], "title": "FeedArtworkStatusRequest", "type": "object" }, "FeedArtworkVocabulary": { "properties": { "any": { "description": "The season / time-of-day tag that matches every card.", "title": "Any", "type": "string" }, "families": { "items": { "$ref": "#/components/schemas/FeedArtworkFamily" }, "title": "Families", "type": "array" }, "generation_disabled_message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Why the gallery cannot paint here; null when it can.", "title": "Generation Disabled Message" }, "generation_enabled": { "description": "Whether this environment paints new artwork (FEED_ARTWORK_GENERATION_ENABLED).", "title": "Generation Enabled", "type": "boolean" }, "max_images_per_request": { "title": "Max Images Per Request", "type": "integer" }, "max_prompt_length": { "title": "Max Prompt Length", "type": "integer" }, "moods": { "items": { "type": "string" }, "title": "Moods", "type": "array" }, "seasons": { "items": { "type": "string" }, "title": "Seasons", "type": "array" }, "times_of_day": { "items": { "type": "string" }, "title": "Times Of Day", "type": "array" } }, "required": [ "families", "moods", "seasons", "times_of_day", "any", "max_prompt_length", "max_images_per_request", "generation_enabled", "generation_disabled_message" ], "title": "FeedArtworkVocabulary", "type": "object" }, "FeedCard": { "description": "Unified feed card for mobile display.\n\nRepresents any item (news, event, task, reminder) in a consistent format\noptimized for mobile list rendering.\n\nAttributes:\n id: Unique card identifier (format: {cardType}_{sourceId})\n cardType: Type of source entity\n sourceId: UUID of the source entity\n title: Primary display text\n subtitle: Secondary display text (optional)\n body: Extended content preview (optional)\n icon: Material icon name for card type\n accentColor: Hex color code for card accent\n badge: Optional badge text (e.g., \"Due Today\", \"New\")\n timestamp: When the source entity was created/published\n displayDate: Formatted date for display\n isTimeSensitive: Whether this card is time-critical\n priority: Card priority for sorting\n confidence: AI extraction confidence score (0.0-1.0)\n category: Category for filtering\n isArchived: Whether user has archived this card\n isRead: Whether user has read/viewed this card\n shareText: Text for share functionality\n deepLink: Deep link URL for navigation", "properties": { "accentColor": { "default": "#6366F1", "description": "Hex color code for card accent", "examples": [ "#6366F1", "#10B981", "#F59E0B" ], "title": "Accentcolor", "type": "string" }, "aiInsight": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "AI-generated insight or response for display", "examples": [ "Based on your calendar, you have 3 events tomorrow..." ], "title": "Aiinsight" }, "badge": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Optional badge text", "examples": [ "Due Today", "New", "Urgent" ], "title": "Badge" }, "body": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Extended content preview (truncated)", "examples": [ "Remember to bring your order form..." ], "title": "Body" }, "cardType": { "$ref": "#/components/schemas/FeedCardType", "description": "Type of feed card", "examples": [ "news", "event" ] }, "category": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Primary category for filtering", "examples": [ "school", "activity", "health" ], "title": "Category" }, "clickAction": { "$ref": "#/components/schemas/ClickAction", "default": "none", "description": "What happens when card is tapped" }, "clickTarget": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Target for click action: route path, sheet type, or card ID", "examples": [ "/event/abc123", "weather", "recipe_abc123" ], "title": "Clicktarget" }, "confidence": { "anyOf": [ { "maximum": 1.0, "minimum": 0.0, "type": "number" }, { "type": "null" } ], "default": null, "description": "AI extraction confidence score (0.0-1.0)", "title": "Confidence" }, "deepLink": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Deep link URL for navigation", "examples": [ "tidy://U-550e8400-e29b-41d4-a716-446655440000", "tidy://V-550e8400-e29b-41d4-a716-446655440000" ], "title": "Deeplink" }, "displayDate": { "description": "Formatted date for display", "examples": [ "Today", "Tomorrow", "Dec 28" ], "title": "Displaydate", "type": "string" }, "emailProvider": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Email provider for source (google, zoho, generic_imap)", "examples": [ "google", "zoho" ], "title": "Emailprovider" }, "icon": { "default": "article", "description": "Material icon name for card type", "examples": [ "article", "event", "task_alt", "notifications" ], "title": "Icon", "type": "string" }, "id": { "description": "Unique card identifier (format: {cardType}_{sourceId})", "examples": [ "news_a1b2c3d4-..." ], "title": "Id", "type": "string" }, "isArchived": { "default": false, "description": "Whether user has archived this card", "title": "Isarchived", "type": "boolean" }, "isRead": { "default": false, "description": "Whether user has read/viewed this card", "title": "Isread", "type": "boolean" }, "isTimeSensitive": { "default": false, "description": "Whether this card is time-critical", "title": "Istimesensitive", "type": "boolean" }, "messageId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Original IMAP message ID for email deep links", "examples": [ "" ], "title": "Messageid" }, "metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "description": "Card metadata including attachments, location, and processing status", "title": "Metadata" }, "priority": { "$ref": "#/components/schemas/FeedCardPriority", "default": "medium", "description": "Card priority for sorting" }, "sections": { "anyOf": [ { "items": {}, "type": "array" }, { "type": "null" } ], "default": null, "description": "Conversation sections for user cards (ask, note, journal)", "title": "Sections" }, "shareText": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Text for share functionality", "title": "Sharetext" }, "sourceId": { "description": "UUID of the source entity", "examples": [ "a1b2c3d4-..." ], "title": "Sourceid", "type": "string" }, "sourceType": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Card source type for styling (ai_recipe = sparkles) or external source (email, calendar)", "examples": [ "ai_recipe", "mandatory_recipe", "primitive", "email", "calendar" ], "title": "Sourcetype" }, "subtitle": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Secondary display text", "examples": [ "Lincoln Elementary School" ], "title": "Subtitle" }, "tags": { "description": "Additional classification tags", "examples": [ [ "instagram", "notification", "social_media" ] ], "items": { "type": "string" }, "title": "Tags", "type": "array" }, "timestamp": { "description": "When the source entity was created/published", "format": "date-time", "title": "Timestamp", "type": "string" }, "title": { "description": "Primary display text", "examples": [ "School Picture Day Tomorrow" ], "title": "Title", "type": "string" }, "webViewUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Internal web app URL for viewing source (for web clients)", "examples": [ "/email/view?id=abc123" ], "title": "Webviewurl" } }, "required": [ "id", "cardType", "sourceId", "title", "timestamp", "displayDate" ], "title": "FeedCard", "type": "object" }, "FeedCardPriority": { "description": "Feed card priority levels for sorting.\n\nHigher priority cards appear first in the feed.", "enum": [ "critical", "high", "medium", "low" ], "title": "FeedCardPriority", "type": "string" }, "FeedCardType": { "description": "Feed card type constants.\n\nSource types:\n - news: news_updates table\n - event: events table\n - task: tasks table\n - reminder: reminders table\n - note: User-created note cards (distinct from notes table)\n\nUser-created capture types (018-unified-card-architecture):\n - ask: User question routed to MRS agent for AI response\n - journal: Reflection/diary entry (future coaching agent)\n\nRecipe-generated types:\n - travel: Travel time card from recipe engine\n - conflict: Calendar conflict card from recipe engine\n - alert: Alert card from recipe engine (important notifications)\n - recipe: Generic recipe-generated card (AI recipes)", "enum": [ "news", "event", "task", "reminder", "note", "ask", "journal", "weather", "travel", "conflict", "alert", "recipe", "approval", "invite", "time_proposal" ], "title": "FeedCardType", "type": "string" }, "FeedResponse": { "description": "Paginated feed response.\n\nAttributes:\n cards: List of feed cards\n nextCursor: Cursor for next page (null if no more pages)\n hasMore: Whether more cards are available\n totalCount: Total number of cards matching filters\n weather: Current weather data for header display (optional)", "properties": { "cards": { "description": "List of feed cards", "items": { "$ref": "#/components/schemas/FeedCard" }, "title": "Cards", "type": "array" }, "hasMore": { "default": false, "description": "Whether more cards are available", "title": "Hasmore", "type": "boolean" }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Cursor for next page pagination", "title": "Nextcursor" }, "totalCount": { "default": 0, "description": "Total number of cards matching filters", "title": "Totalcount", "type": "integer" }, "weather": { "anyOf": [ { "$ref": "#/components/schemas/WeatherData" }, { "type": "null" } ], "description": "Current weather data for feed header" } }, "title": "FeedResponse", "type": "object" }, "FeedbackBatchItemResult": { "description": "One batch event's outcome — per-item isolation (TIDY-14827 re-fix):\na failed sibling never sinks the batch; failures are reported here.", "properties": { "error_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Error Code" }, "error_message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Error Message" }, "feedback_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "default": null, "title": "Feedback Id" }, "run_id": { "format": "uuid", "title": "Run Id", "type": "string" }, "scope": { "title": "Scope", "type": "string" }, "signal": { "title": "Signal", "type": "string" }, "status": { "enum": [ "recorded", "failed" ], "title": "Status", "type": "string" } }, "required": [ "run_id", "signal", "scope", "status" ], "title": "FeedbackBatchItemResult", "type": "object" }, "FeedbackBatchRequest": { "properties": { "events": { "items": { "$ref": "#/components/schemas/FeedbackRequest" }, "title": "Events", "type": "array" } }, "required": [ "events" ], "title": "FeedbackBatchRequest", "type": "object" }, "FeedbackBatchResponse": { "properties": { "results": { "items": { "$ref": "#/components/schemas/FeedbackBatchItemResult" }, "title": "Results", "type": "array" } }, "required": [ "results" ], "title": "FeedbackBatchResponse", "type": "object" }, "FeedbackOutputTarget": { "description": "Client-known identity of the output being judged (TIDY-14829 fix).\n\nAdditive alternative to ``output_index``: the server resolves the ledger\nindex from the run's ``output_refs`` (same matching as the why-endpoint).", "properties": { "field": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Field" }, "id": { "title": "Id", "type": "string" }, "type": { "title": "Type", "type": "string" } }, "required": [ "type", "id" ], "title": "FeedbackOutputTarget", "type": "object" }, "FeedbackRequest": { "properties": { "detail": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Detail" }, "output_index": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Output Index" }, "output_target": { "anyOf": [ { "$ref": "#/components/schemas/FeedbackOutputTarget" }, { "type": "null" } ] }, "run_id": { "format": "uuid", "title": "Run Id", "type": "string" }, "scope": { "enum": [ "output", "whole_result" ], "title": "Scope", "type": "string" }, "signal": { "title": "Signal", "type": "string" } }, "required": [ "run_id", "signal", "scope" ], "title": "FeedbackRequest", "type": "object" }, "FeedbackResult": { "properties": { "feedback_id": { "format": "uuid", "title": "Feedback Id", "type": "string" }, "run_id": { "format": "uuid", "title": "Run Id", "type": "string" }, "scope": { "title": "Scope", "type": "string" }, "signal": { "title": "Signal", "type": "string" } }, "required": [ "feedback_id", "run_id", "signal", "scope" ], "title": "FeedbackResult", "type": "object" }, "FeedbackSubmitRequest": { "properties": { "category": { "description": "User-selected free-text category.", "title": "Category", "type": "string" }, "description": { "anyOf": [ { "maxLength": 10000, "type": "string" }, { "type": "null" } ], "title": "Description" }, "intent": { "anyOf": [ { "maxLength": 2000, "type": "string" }, { "type": "null" } ], "description": "Plugin requests only: what they were trying to do.", "title": "Intent" }, "journey": { "anyOf": [ { "maxLength": 100, "type": "string" }, { "type": "null" } ], "description": "Plugin requests only: the journey the ask came from.", "title": "Journey" }, "journey_step": { "anyOf": [ { "maxLength": 100, "type": "string" }, { "type": "null" } ], "description": "Plugin requests only: the step within that journey.", "title": "Journey Step" }, "offered": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "description": "Plugin requests only: the providers that WERE on offer.", "title": "Offered" }, "requested_provider": { "anyOf": [ { "maxLength": 200, "type": "string" }, { "type": "null" } ], "description": "Plugin requests only: the provider the member asked for.", "title": "Requested Provider" }, "severity": { "anyOf": [ { "enum": [ "low", "medium", "high", "critical" ], "type": "string" }, { "type": "null" } ], "description": "Required when type='bug'.", "title": "Severity" }, "title": { "maxLength": 500, "minLength": 1, "title": "Title", "type": "string" }, "type": { "enum": [ "bug", "feature", "feedback", "plugin_request" ], "title": "Type", "type": "string" } }, "required": [ "type", "category", "title" ], "title": "FeedbackSubmitRequest", "type": "object" }, "FeedbackSubmitResponse": { "properties": { "event_type": { "enum": [ "feedback.submitted", "bug.reported" ], "title": "Event Type", "type": "string" }, "feedback_id": { "title": "Feedback Id", "type": "string" } }, "required": [ "feedback_id", "event_type" ], "title": "FeedbackSubmitResponse", "type": "object" }, "FeedbackSummaryRow": { "description": "One row of ``get_feedback_summary(NULL, 30)``.", "properties": { "card_type": { "title": "Card Type", "type": "string" }, "negative_count": { "default": 0, "title": "Negative Count", "type": "integer" }, "positive_count": { "default": 0, "title": "Positive Count", "type": "integer" }, "total_count": { "default": 0, "title": "Total Count", "type": "integer" }, "unknown_count": { "default": 0, "title": "Unknown Count", "type": "integer" } }, "required": [ "card_type" ], "title": "FeedbackSummaryRow", "type": "object" }, "FieldLock": { "description": "Represents a lock on a single field.", "properties": { "locked_at": { "format": "date-time", "title": "Locked At", "type": "string" }, "locked_by": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Locked By" } }, "required": [ "locked_at" ], "title": "FieldLock", "type": "object" }, "FieldLocksResponse": { "description": "Response for field locks queries.", "properties": { "contact_id": { "title": "Contact Id", "type": "string" }, "field_locks": { "additionalProperties": { "$ref": "#/components/schemas/FieldLock" }, "title": "Field Locks", "type": "object" } }, "required": [ "contact_id" ], "title": "FieldLocksResponse", "type": "object" }, "FieldOrigin": { "description": "Origin of a field value in the merged result.", "enum": [ "primary", "secondary", "combined", "none" ], "title": "FieldOrigin", "type": "string" }, "FieldOrigins": { "description": "Tracks which contact each field value came from.\n\nUsed in MergePreview to show color-coded field origins:\n- Blue: from primary contact\n- Green: from secondary contact\n- Purple: combined from both", "properties": { "addresses": { "$ref": "#/components/schemas/FieldOrigin", "default": "combined" }, "child_associations": { "$ref": "#/components/schemas/FieldOrigin", "default": "combined" }, "display_name": { "$ref": "#/components/schemas/FieldOrigin", "default": "primary" }, "email_addresses": { "$ref": "#/components/schemas/FieldOrigin", "default": "combined" }, "first_name": { "$ref": "#/components/schemas/FieldOrigin", "default": "primary" }, "household_relationship": { "$ref": "#/components/schemas/FieldOrigin", "default": "none" }, "last_name": { "$ref": "#/components/schemas/FieldOrigin", "default": "primary" }, "metadata": { "$ref": "#/components/schemas/FieldOrigin", "default": "combined" }, "middle_name": { "$ref": "#/components/schemas/FieldOrigin", "default": "none" }, "nickname": { "$ref": "#/components/schemas/FieldOrigin", "default": "none" }, "notes_history": { "$ref": "#/components/schemas/FieldOrigin", "default": "combined" }, "organization": { "$ref": "#/components/schemas/FieldOrigin", "default": "none" }, "organizations": { "$ref": "#/components/schemas/FieldOrigin", "default": "none" }, "phone_numbers": { "$ref": "#/components/schemas/FieldOrigin", "default": "combined" }, "relation_type": { "$ref": "#/components/schemas/FieldOrigin", "default": "none" }, "role": { "$ref": "#/components/schemas/FieldOrigin", "default": "none" }, "tags": { "$ref": "#/components/schemas/FieldOrigin", "default": "combined" } }, "title": "FieldOrigins", "type": "object" }, "FileActionRequestCreate": { "properties": { "client_request_id": { "description": "Stable client-generated id making offline retries idempotent (D5).", "maxLength": 200, "minLength": 1, "title": "Client Request Id", "type": "string" }, "instruction": { "description": "Free-text action instruction. Unicode 15.1 White_Space edge-trimmed; max 4,000 code points after trim; blank means no request (422).", "title": "Instruction", "type": "string" }, "locale": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Device BCP 47 locale; validated device→en-US precedence applies.", "title": "Locale" }, "supersedes_request_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Correction CAS: id of the caller's own failed/needs_input request on this file. At most one successor; a concurrent loser gets HTTP 409 with the active successor id.", "title": "Supersedes Request Id" }, "timezone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Device IANA timezone; preference→device→UTC precedence applies.", "title": "Timezone" } }, "required": [ "client_request_id", "instruction" ], "title": "FileActionRequestCreate", "type": "object" }, "FileActionRequestResponse": { "properties": { "attempt_count": { "title": "Attempt Count", "type": "integer" }, "caller_account_id": { "title": "Caller Account Id", "type": "string" }, "client_request_id": { "title": "Client Request Id", "type": "string" }, "created": { "default": true, "description": "False when an idempotent replay returned the existing row", "title": "Created", "type": "boolean" }, "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "file_id": { "title": "File Id", "type": "string" }, "id": { "description": "Request id (UUID)", "title": "Id", "type": "string" }, "instruction": { "title": "Instruction", "type": "string" }, "last_error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Last Error" }, "locale": { "description": "Effective locale persisted at create", "title": "Locale", "type": "string" }, "needs_input": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "description": "Structured needs_input detail {reason_code, question} (TIDY-15285)", "title": "Needs Input" }, "plan": { "description": "Ordered per-action plan", "items": {}, "title": "Plan", "type": "array" }, "results": { "description": "Ordered per-action results", "items": {}, "title": "Results", "type": "array" }, "status": { "description": "pending | running | succeeded | partial | failed | needs_input", "title": "Status", "type": "string" }, "supersedes_request_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Supersedes Request Id" }, "timezone": { "description": "Effective IANA timezone persisted at create", "title": "Timezone", "type": "string" }, "updated_at": { "format": "date-time", "title": "Updated At", "type": "string" } }, "required": [ "id", "file_id", "caller_account_id", "client_request_id", "instruction", "timezone", "locale", "status", "attempt_count", "created_at", "updated_at" ], "title": "FileActionRequestResponse", "type": "object" }, "FileContentResponse": { "properties": { "content": { "description": "Raw stored text content, UTF-8 decoded (replacement characters for stray bytes).", "title": "Content", "type": "string" }, "id": { "title": "Id", "type": "string" }, "mime_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Mime Type" }, "name": { "title": "Name", "type": "string" }, "size_bytes": { "title": "Size Bytes", "type": "integer" } }, "required": [ "id", "name", "size_bytes", "content" ], "title": "FileContentResponse", "type": "object" }, "FileContentUpdateRequest": { "properties": { "content": { "description": "Full replacement text content for the file.", "minLength": 1, "title": "Content", "type": "string" } }, "required": [ "content" ], "title": "FileContentUpdateRequest", "type": "object" }, "FileExtractedTextResponse": { "description": "Docling-extracted markdown for an uploaded file (TIDY-14968).\n\nMirrors the email-attachment reader contract (TIDY-13457 / TIDY-14782):\nwhen the pipeline has processed the file, ``text`` holds the extracted\nmarkdown; otherwise ``processed`` is False and — with\n``queue_if_missing=true`` — extraction is dispatched on demand and\n``extraction_state`` + ``retry_after_seconds`` tell the caller when to\nre-poll.", "properties": { "extraction_state": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "On-demand extraction dispatch state when text is unavailable: 'queued' (extraction was just dispatched), 'processing' (a run is already in flight).", "title": "Extraction State" }, "full_length": { "default": 0, "description": "Character length of the untruncated text", "title": "Full Length", "type": "integer" }, "id": { "description": "File id", "title": "Id", "type": "string" }, "message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Human-readable state when text is unavailable", "title": "Message" }, "mime_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "File MIME type", "title": "Mime Type" }, "name": { "description": "File name", "title": "Name", "type": "string" }, "pages_used": { "anyOf": [ { "items": { "type": "integer" }, "type": "array" }, { "type": "null" } ], "default": null, "description": "Deep extract only: the 1-based pages the variant was built from", "title": "Pages Used" }, "processed": { "default": false, "description": "True when extracted text is available", "title": "Processed", "type": "boolean" }, "processor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Which extractor produced `text`: absent for the standard Docling read; 'deep_vision' for a raster+VLM deep variant", "title": "Processor" }, "retry_after_seconds": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Suggested delay before re-calling this endpoint for the result", "title": "Retry After Seconds" }, "text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Extracted markdown text (present when processed)", "title": "Text" }, "trace_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Pipeline trace id of the queued/in-flight extraction run", "title": "Trace Id" }, "truncated": { "default": false, "description": "True when text was cut to the length cap", "title": "Truncated", "type": "boolean" } }, "required": [ "id", "name" ], "title": "FileExtractedTextResponse", "type": "object" }, "FileId": { "description": "Typed primitive ID for files (prefix 'F').", "examples": [ "F-550e8400-e29b-41d4-a716-446655440000" ], "pattern": "^F-[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "title": "FileId", "type": "string", "x-tidy-typed-id-prefix": "F", "x-tidy-typed-id-table": "files" }, "FileListResponse": { "properties": { "files": { "items": { "$ref": "#/components/schemas/FileResponse" }, "title": "Files", "type": "array" } }, "required": [ "files" ], "title": "FileListResponse", "type": "object" }, "FileResponse": { "properties": { "access_scope_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Access Scope Id" }, "content_sha256": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "SHA-256 (hex) of the file's current stored bytes.", "title": "Content Sha256" }, "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "deduplicated": { "default": false, "description": "True when the request resolved to a file the caller already had with the same content, instead of storing a second copy.", "title": "Deduplicated", "type": "boolean" }, "folder_path": { "title": "Folder Path", "type": "string" }, "id": { "title": "Id", "type": "string" }, "import_metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "title": "Import Metadata" }, "import_source": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Import Source" }, "import_source_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Import Source Id" }, "import_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": "ready", "title": "Import Status" }, "last_published_commit": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Last Published Commit" }, "mime_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Mime Type" }, "name": { "title": "Name", "type": "string" }, "owner_id": { "title": "Owner Id", "type": "string" }, "project_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Project Id" }, "repo_full_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Repo Full Name" }, "repo_path": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Repo Path" }, "repo_provider": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Repo Provider" }, "size_bytes": { "title": "Size Bytes", "type": "integer" }, "storage_ref": { "title": "Storage Ref", "type": "string" }, "storage_type": { "title": "Storage Type", "type": "string" }, "tags": { "items": { "type": "string" }, "title": "Tags", "type": "array" }, "tenant_id": { "title": "Tenant Id", "type": "string" }, "updated_at": { "format": "date-time", "title": "Updated At", "type": "string" }, "visibility": { "title": "Visibility", "type": "string" } }, "required": [ "id", "tenant_id", "owner_id", "visibility", "name", "folder_path", "storage_type", "storage_ref", "size_bytes", "created_at", "updated_at" ], "title": "FileResponse", "type": "object" }, "FileResult": { "properties": { "event_id": { "title": "Event Id", "type": "string" }, "filename": { "title": "Filename", "type": "string" }, "room_id": { "title": "Room Id", "type": "string" }, "room_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Room Name" }, "score": { "title": "Score", "type": "number" }, "sender_name": { "title": "Sender Name", "type": "string" }, "ts": { "format": "date-time", "title": "Ts", "type": "string" } }, "required": [ "event_id", "room_id", "room_name", "sender_name", "filename", "ts", "score" ], "title": "FileResult", "type": "object" }, "FileSummary": { "description": "Summary of a related file.\n\nTIDY-15687: a generated artifact can BE a file (audio, image), so the\nreverse \"used to generate this\" view has to resolve one.", "properties": { "id": { "description": "File ID (UUID)", "title": "Id", "type": "string" }, "link_direction": { "default": "outgoing", "description": "Direction of the edge relative to the primitive you asked about: 'outgoing' (the edge starts there and points at this one) or 'incoming' (this one points AT it). TIDY-15687.", "title": "Link Direction", "type": "string" }, "link_type": { "description": "How this file is related", "title": "Link Type", "type": "string" }, "mime_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "MIME type", "title": "Mime Type" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "File name", "title": "Name" }, "size_bytes": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Size in bytes", "title": "Size Bytes" }, "type": { "const": "file", "default": "file", "title": "Type", "type": "string" } }, "required": [ "id", "link_type" ], "title": "FileSummary", "type": "object" }, "FileUpdateRequest": { "properties": { "folder_path": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Folder Path" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name" }, "project_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Project Id" }, "tags": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Tags" }, "visibility": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Visibility" } }, "title": "FileUpdateRequest", "type": "object" }, "FileUploadTicketCreate": { "properties": { "client_upload_id": { "anyOf": [ { "maxLength": 200, "type": "string" }, { "type": "null" } ], "description": "Stable id for this upload (TIDY-15284). Asking again with it answers with the file that landed; a different file under it is a 409. Omitted: the answer names one to retry with.", "title": "Client Upload Id" }, "filename": { "description": "The file's name in Files.", "maxLength": 255, "minLength": 1, "title": "Filename", "type": "string" }, "folder_path": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "description": "Virtual folder. Omitted: /Uploads.", "title": "Folder Path" }, "mime_type": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "description": "MIME type. Omitted: guessed from the filename.", "title": "Mime Type" }, "sha256": { "description": "The file's SHA-256, hex. The upload is refused unless the bytes match it.", "pattern": "^[0-9a-fA-F]{64}$", "title": "Sha256", "type": "string" }, "size_bytes": { "description": "The file's exact size in bytes (at most 52428800).", "exclusiveMinimum": 0.0, "maximum": 52428800.0, "title": "Size Bytes", "type": "integer" } }, "required": [ "filename", "size_bytes", "sha256" ], "title": "FileUploadTicketCreate", "type": "object" }, "FileUploadTicketResponse": { "properties": { "client_upload_id": { "title": "Client Upload Id", "type": "string" }, "deduplicated": { "default": false, "description": "uploaded: the caller already had these exact bytes; this is that file.", "title": "Deduplicated", "type": "boolean" }, "file_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "uploaded: the file's F-.", "title": "File Id" }, "folder_path": { "title": "Folder Path", "type": "string" }, "max_size_bytes": { "description": "The largest file an upload may carry.", "title": "Max Size Bytes", "type": "integer" }, "message": { "title": "Message", "type": "string" }, "mime_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Mime Type" }, "name": { "title": "Name", "type": "string" }, "sha256": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "awaiting_upload: the SHA-256 the bytes must match. uploaded: the SHA-256 of what landed, computed by Tidy from the stored bytes.", "title": "Sha256" }, "size_bytes": { "title": "Size Bytes", "type": "integer" }, "state": { "enum": [ "awaiting_upload", "uploaded" ], "title": "State", "type": "string" }, "ticket_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Ticket Id" }, "upload_command": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "The curl command that sends the bytes; replace .", "title": "Upload Command" }, "upload_expires_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Upload Expires At" }, "upload_token": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Send it in the X-Tidy-Upload-Token header, never in the URL.", "title": "Upload Token" }, "upload_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Upload Url" } }, "required": [ "state", "client_upload_id", "name", "folder_path", "size_bytes", "max_size_bytes", "message" ], "title": "FileUploadTicketResponse", "type": "object" }, "FileVersionListResponse": { "description": "Newest-first history plus the file-level provider links.", "properties": { "file_id": { "title": "File Id", "type": "string" }, "links": { "$ref": "#/components/schemas/DeliverableProviderLinks" }, "repo_full_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Repo Full Name" }, "repo_path": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Repo Path" }, "repo_provider": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Repo Provider" }, "versions": { "items": { "$ref": "#/components/schemas/FileVersionResponse" }, "title": "Versions", "type": "array" } }, "required": [ "file_id", "links", "versions" ], "title": "FileVersionListResponse", "type": "object" }, "FileVersionResponse": { "description": "One version of a file, with the provenance the Observability AC names.", "properties": { "commit_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Deep link to this version's commit on the provider, when known.", "title": "Commit Url" }, "content_sha256": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Content Sha256" }, "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "mime_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Mime Type" }, "published_by_account_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Published By Account Id" }, "published_by_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Published By Name" }, "published_commit": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Published Commit" }, "size_bytes": { "title": "Size Bytes", "type": "integer" }, "source": { "description": "publish | pull_latest | user_upload — how this version came to exist.", "title": "Source", "type": "string" }, "version": { "title": "Version", "type": "integer" } }, "required": [ "version", "size_bytes", "source", "created_at" ], "title": "FileVersionResponse", "type": "object" }, "FileVersionScmReferenceResponse": { "description": "The `S-` reference minted for one version (TIDY-17133 / S6, R19/R4).\n\n``display_text`` is the D13 vocabulary — `` · v`` — and is what\nthe chip shows on every surface; the caller pastes ``[[|]]``\nto carry the same reference into any editor.", "properties": { "display_text": { "title": "Display Text", "type": "string" }, "id": { "description": "Typed `S-` id of the version reference.", "title": "Id", "type": "string" }, "project_id": { "title": "Project Id", "type": "string" }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Where the reference opens at the provider, when it builds web links.", "title": "Url" } }, "required": [ "id", "display_text", "project_id" ], "title": "FileVersionScmReferenceResponse", "type": "object" }, "FinalizeDeepCutRequest": { "properties": { "dictation_failed": { "default": false, "title": "Dictation Failed", "type": "boolean" }, "personal_dictation": { "default": "", "maxLength": 5000, "title": "Personal Dictation", "type": "string" } }, "title": "FinalizeDeepCutRequest", "type": "object" }, "FinalizeResponse": { "properties": { "chunks_received": { "title": "Chunks Received", "type": "integer" }, "diarization_mode": { "title": "Diarization Mode", "type": "string" }, "diarization_note": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Diarization Note" }, "duration_seconds": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "title": "Duration Seconds" }, "language": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Language" }, "model": { "title": "Model", "type": "string" }, "provider": { "title": "Provider", "type": "string" }, "recording_id": { "title": "Recording Id", "type": "string" }, "segments": { "items": { "additionalProperties": true, "type": "object" }, "title": "Segments", "type": "array" }, "transcript": { "title": "Transcript", "type": "string" }, "words": { "items": { "additionalProperties": true, "type": "object" }, "title": "Words", "type": "array" } }, "required": [ "recording_id", "transcript", "provider", "model", "diarization_mode", "chunks_received" ], "title": "FinalizeResponse", "type": "object" }, "FindEmailResponse": { "properties": { "count": { "title": "Count", "type": "integer" }, "rows": { "items": { "$ref": "#/components/schemas/FindEmailRow" }, "title": "Rows", "type": "array" } }, "required": [ "rows", "count" ], "title": "FindEmailResponse", "type": "object" }, "FindEmailRow": { "properties": { "disposition": { "enum": [ "delivered", "done", "quarantined", "blocked", "screened" ], "title": "Disposition", "type": "string" }, "email_id": { "title": "Email Id", "type": "string" }, "firing_rule_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Firing Rule Id" }, "firing_rule_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Firing Rule Name" }, "from_address": { "title": "From Address", "type": "string" }, "inbox_split": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Inbox Split" }, "sent_at": { "format": "date-time", "title": "Sent At", "type": "string" }, "subject": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Subject" } }, "required": [ "email_id", "from_address", "sent_at", "disposition" ], "title": "FindEmailRow", "type": "object" }, "FinishDepartureRequest": { "properties": { "conversation_id": { "maxLength": 36, "minLength": 36, "title": "Conversation Id", "type": "string" } }, "required": [ "conversation_id" ], "title": "FinishDepartureRequest", "type": "object" }, "FinishDepartureResponse": { "properties": { "continued_conversation_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Continued Conversation Id" }, "departed": { "title": "Departed", "type": "boolean" } }, "required": [ "departed" ], "title": "FinishDepartureResponse", "type": "object" }, "FirstRunSyncResponse": { "description": "Response from first-run sync trigger.", "properties": { "config_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Config Id" }, "connection_id": { "title": "Connection Id", "type": "string" }, "message": { "default": "", "title": "Message", "type": "string" }, "status": { "description": "accepted, already_synced, or error", "title": "Status", "type": "string" } }, "required": [ "connection_id", "status" ], "title": "FirstRunSyncResponse", "type": "object" }, "FixActionResponse": { "description": "A suggested fix action.", "properties": { "command": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Command" }, "description": { "title": "Description", "type": "string" }, "endpoint": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Endpoint" }, "label": { "title": "Label", "type": "string" }, "params": { "additionalProperties": true, "default": {}, "title": "Fix Action Params", "type": "object" }, "severity": { "default": "info", "title": "Severity", "type": "string" }, "type": { "title": "Type", "type": "string" } }, "required": [ "type", "label", "description" ], "title": "FixActionResponse", "type": "object" }, "FlagBetaRequest": { "properties": { "exempt": { "title": "Exempt", "type": "boolean" } }, "required": [ "exempt" ], "title": "FlagBetaRequest", "type": "object" }, "FlagEnrollment": { "description": "This workspace's evaluated rollout enrolment for one gated flag.\n\nPresent only on flags whose ``enablement`` is ``rollout_enrollment``.\n``enrolled`` is exactly \"an Owner/Admin turning this on would be allowed\";\nwhen it is not, ``refusal`` is the sentence the write would refuse with.", "properties": { "enrolled": { "title": "Enrolled", "type": "boolean" }, "mode": { "enum": [ "dogfood", "general", "disabled" ], "title": "Mode", "type": "string" }, "policy_version": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Policy Version" }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Reason" }, "refusal": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Refusal" } }, "required": [ "enrolled", "mode" ], "title": "FlagEnrollment", "type": "object" }, "FocusDayOfWeek": { "properties": { "avg_focus_hours": { "title": "Avg Focus Hours", "type": "number" }, "day_of_week": { "title": "Day Of Week", "type": "integer" } }, "required": [ "day_of_week", "avg_focus_hours" ], "title": "FocusDayOfWeek", "type": "object" }, "FocusPeriod": { "properties": { "blocks": { "title": "Blocks", "type": "integer" }, "focus_hours": { "title": "Focus Hours", "type": "number" }, "period": { "title": "Period", "type": "string" } }, "required": [ "period", "focus_hours", "blocks" ], "title": "FocusPeriod", "type": "object" }, "FocusQueueItem": { "properties": { "added_at": { "format": "date-time", "title": "Added At", "type": "string" }, "display_subject": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Display Subject" }, "draft_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "default": null, "title": "Draft Id" }, "draft_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Draft Status" }, "email_id": { "format": "uuid", "title": "Email Id", "type": "string" }, "from_address": { "title": "From Address", "type": "string" }, "from_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "From Name" }, "id": { "format": "uuid", "title": "Id", "type": "string" }, "position": { "title": "Position", "type": "integer" }, "sent_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Sent At" }, "subject": { "title": "Subject", "type": "string" } }, "required": [ "id", "email_id", "subject", "from_address", "position", "added_at" ], "title": "FocusQueueItem", "type": "object" }, "FocusQueueResponse": { "properties": { "count": { "default": 0, "title": "Count", "type": "integer" }, "items": { "items": { "$ref": "#/components/schemas/FocusQueueItem" }, "title": "Items", "type": "array" } }, "title": "FocusQueueResponse", "type": "object" }, "FocusTimeResponse": { "properties": { "avg_block_duration_minutes": { "title": "Avg Block Duration Minutes", "type": "integer" }, "avg_daily_focus_hours": { "title": "Avg Daily Focus Hours", "type": "number" }, "best_focus_day": { "title": "Best Focus Day", "type": "string" }, "by_day_of_week": { "items": { "$ref": "#/components/schemas/FocusDayOfWeek" }, "title": "By Day Of Week", "type": "array" }, "by_period": { "items": { "$ref": "#/components/schemas/FocusPeriod" }, "title": "By Period", "type": "array" }, "total_focus_hours": { "title": "Total Focus Hours", "type": "number" }, "uninterrupted_blocks": { "title": "Uninterrupted Blocks", "type": "integer" } }, "required": [ "total_focus_hours", "avg_daily_focus_hours", "uninterrupted_blocks", "avg_block_duration_minutes", "best_focus_day", "by_period", "by_day_of_week" ], "title": "FocusTimeResponse", "type": "object" }, "FolderCountsResponse": { "description": "Response for folder counts endpoint.\n\nTIDY-8898 (S4): adds ``drafts``, ``outbox``, ``done`` counts (the\nnew Tidy-default folders introduced in the folder-mapping model).\nThe legacy ``archive`` field continues to mirror ``done`` for\nbackwards compat with existing clients.", "properties": { "all": { "description": "Total emails count", "title": "All", "type": "integer" }, "archive": { "description": "DEPRECATED: alias for `done`", "title": "Archive", "type": "integer" }, "done": { "default": 0, "description": "tidy_folder='done' emails", "title": "Done", "type": "integer" }, "drafts": { "default": 0, "description": "tidy_folder='drafts' emails", "title": "Drafts", "type": "integer" }, "inbox": { "description": "tidy_folder='inbox' emails (live, non-header)", "title": "Inbox", "type": "integer" }, "outbox": { "default": 0, "description": "tidy_folder='outbox' emails", "title": "Outbox", "type": "integer" }, "screening_count": { "default": 0, "description": "Emails with screening_status='pending'", "title": "Screening Count", "type": "integer" }, "sent": { "default": 0, "description": "tidy_folder='sent' emails", "title": "Sent", "type": "integer" }, "splits": { "anyOf": [ { "additionalProperties": { "$ref": "#/components/schemas/SplitCount" }, "type": "object" }, { "type": "null" } ], "description": "Counts per split: important, feed, paper_trail", "title": "Splits" }, "starred": { "default": 0, "description": "Starred emails count", "title": "Starred", "type": "integer" }, "unread": { "default": 0, "description": "Unread emails in inbox", "title": "Unread", "type": "integer" } }, "required": [ "inbox", "archive", "all" ], "title": "FolderCountsResponse", "type": "object" }, "FolderMappingResponse": { "properties": { "email_source_id": { "format": "uuid", "title": "Email Source Id", "type": "string" }, "provider_folder_path": { "title": "Provider Folder Path", "type": "string" }, "rows_recomputed": { "title": "Rows Recomputed", "type": "integer" }, "tidy_folder": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Tidy Folder" } }, "required": [ "email_source_id", "provider_folder_path", "tidy_folder", "rows_recomputed" ], "title": "FolderMappingResponse", "type": "object" }, "FolderMappingUpdateRequest": { "properties": { "email_source_id": { "format": "uuid", "title": "Email Source Id", "type": "string" }, "provider_folder_path": { "title": "Provider Folder Path", "type": "string" }, "tidy_folder": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "One of inbox/sent/drafts/outbox/done, or null to keep custom", "title": "Tidy Folder" } }, "required": [ "email_source_id", "provider_folder_path" ], "title": "FolderMappingUpdateRequest", "type": "object" }, "FolderProgress": { "properties": { "error_count": { "title": "Error Count", "type": "integer" }, "eta_seconds": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Eta Seconds" }, "folder_name": { "title": "Folder Name", "type": "string" }, "last_error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Last Error" }, "last_processed_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Last Processed At" }, "processed_messages": { "title": "Processed Messages", "type": "integer" }, "provider_expectation": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "title": "Provider Expectation" }, "rate_messages_per_second": { "default": 0, "title": "Rate Messages Per Second", "type": "number" }, "skipped_duplicate": { "default": 0, "title": "Skipped Duplicate", "type": "integer" }, "status": { "title": "Status", "type": "string" }, "total_known": { "default": false, "title": "Total Known", "type": "boolean" }, "total_messages": { "title": "Total Messages", "type": "integer" }, "walk_complete": { "default": false, "title": "Walk Complete", "type": "boolean" } }, "required": [ "folder_name", "status", "processed_messages", "total_messages", "error_count" ], "title": "FolderProgress", "type": "object" }, "FollowUpActionRequest": { "description": "One member correction. Bounded identifiers only — no message content.", "properties": { "action": { "enum": [ "snoozed", "dismissed", "muted_sender", "muted_pattern", "converted_to_task", "replied" ], "title": "Action", "type": "string" }, "channel": { "enum": [ "email", "chat" ], "title": "Channel", "type": "string" }, "operation_id": { "description": "Idempotency key, stable across retries of ONE user action.", "maxLength": 128, "minLength": 1, "title": "Operation Id", "type": "string" }, "pattern_category": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Reviewed reason category for `muted_pattern` — closed vocabulary, never free text.", "title": "Pattern Category" }, "recommendation_id": { "description": "The projection row the action was taken from.", "format": "uuid", "title": "Recommendation Id", "type": "string" }, "snoozed_until": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "Explicit UTC instant a snooze lifts. Required for `snoozed`.", "title": "Snoozed Until" }, "source_message_id": { "description": "The message the card is grounded on (`E-` / Matrix event id).", "maxLength": 512, "minLength": 1, "title": "Source Message Id", "type": "string" } }, "required": [ "operation_id", "channel", "action", "source_message_id", "recommendation_id" ], "title": "FollowUpActionRequest", "type": "object" }, "FollowUpActionResponse": { "description": "The persisted correction. Replaying an `operation_id` returns this same row.", "properties": { "action": { "title": "Action", "type": "string" }, "channel": { "title": "Channel", "type": "string" }, "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "evidence_event_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "default": null, "title": "Evidence Event Id" }, "expires_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Expires At" }, "id": { "format": "uuid", "title": "Id", "type": "string" }, "mute_scope_hash": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Mute Scope Hash" }, "operation_id": { "title": "Operation Id", "type": "string" }, "pattern_category": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Pattern Category" }, "recommendation_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "default": null, "title": "Recommendation Id" }, "reversed_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Reversed At" }, "snoozed_until": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Snoozed Until" }, "source_message_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Source Message Id" } }, "required": [ "id", "action", "channel", "operation_id", "created_at" ], "title": "FollowUpActionResponse", "type": "object" }, "FollowUpCandidateExclusion": { "description": "One message the gate refused, and the rule that refused it.", "properties": { "channel": { "title": "Channel", "type": "string" }, "reason": { "title": "Reason", "type": "string" }, "source_id": { "title": "Source Id", "type": "string" } }, "required": [ "source_id", "channel", "reason" ], "title": "FollowUpCandidateExclusion", "type": "object" }, "FollowUpCandidateItem": { "description": "One message the deterministic gate cleared for classification.\n\nCarries provenance and the member-state facts that cleared it — never\nsubject or body. A recommendation's evidence quote is the classifier's job\n(TIDY-15401), against the latest authored message.", "properties": { "channel": { "title": "Channel", "type": "string" }, "direct_recipient": { "title": "Direct Recipient", "type": "boolean" }, "mentioned": { "title": "Mentioned", "type": "boolean" }, "received_at": { "format": "date-time", "title": "Received At", "type": "string" }, "sender_key": { "description": "Normalized sender addr-spec or Matrix id", "title": "Sender Key", "type": "string" }, "source_id": { "description": "Typed email id (E-) or Matrix event id", "title": "Source Id", "type": "string" }, "thread_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Thread Id" } }, "required": [ "source_id", "channel", "sender_key", "received_at", "direct_recipient", "mentioned" ], "title": "FollowUpCandidateItem", "type": "object" }, "FollowUpCandidatesResponse": { "description": "The gate's full verdict for one member at one instant.\n\nAn empty `candidates` list is a correct, complete answer — the gate abstains\nfreely rather than relaxing a filter to fill the list (R100 / R104).", "properties": { "candidate_limit": { "default": 0, "title": "Candidate Limit", "type": "integer" }, "candidates": { "items": { "$ref": "#/components/schemas/FollowUpCandidateItem" }, "title": "Candidates", "type": "array" }, "evaluated_at": { "format": "date-time", "title": "Evaluated At", "type": "string" }, "evaluated_count": { "default": 0, "title": "Evaluated Count", "type": "integer" }, "excluded": { "items": { "$ref": "#/components/schemas/FollowUpCandidateExclusion" }, "title": "Excluded", "type": "array" }, "recency_window_hours": { "default": 0, "title": "Recency Window Hours", "type": "integer" } }, "required": [ "evaluated_at" ], "title": "FollowUpCandidatesResponse", "type": "object" }, "FollowUpDraftResponse": { "description": "Response from generating follow-up draft.", "properties": { "draft_body": { "title": "Draft Body", "type": "string" }, "draft_subject": { "title": "Draft Subject", "type": "string" }, "follow_up_id": { "format": "uuid", "title": "Follow Up Id", "type": "string" } }, "required": [ "follow_up_id", "draft_subject", "draft_body" ], "title": "FollowUpDraftResponse", "type": "object" }, "FollowUpFlagRequest": { "properties": { "contact_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Contact Id" } }, "title": "FollowUpFlagRequest", "type": "object" }, "FollowUpFlagResponse": { "properties": { "changed": { "title": "Changed", "type": "boolean" }, "contact_id": { "format": "uuid", "title": "Contact Id", "type": "string" }, "email_id": { "format": "uuid", "title": "Email Id", "type": "string" }, "link_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Link Id" } }, "required": [ "email_id", "contact_id", "changed" ], "title": "FollowUpFlagResponse", "type": "object" }, "FollowUpItem": { "description": "A follow-up reminder item.", "properties": { "days_stale": { "title": "Days Stale", "type": "integer" }, "draft_body": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Draft Body" }, "email_id": { "format": "uuid", "title": "Email Id", "type": "string" }, "has_draft": { "title": "Has Draft", "type": "boolean" }, "id": { "format": "uuid", "title": "Id", "type": "string" }, "original_subject": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Original Subject" }, "recipient_email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Recipient Email" }, "recipient_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Recipient Name" }, "sent_at": { "format": "date-time", "title": "Sent At", "type": "string" }, "snooze_until": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Snooze Until" }, "status": { "title": "Status", "type": "string" }, "thread_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Thread Id" } }, "required": [ "id", "email_id", "thread_id", "recipient_email", "recipient_name", "original_subject", "sent_at", "days_stale", "status", "has_draft" ], "title": "FollowUpItem", "type": "object" }, "FollowUpListResponse": { "description": "Response with list of follow-ups.", "properties": { "items": { "items": { "$ref": "#/components/schemas/FollowUpItem" }, "title": "Items", "type": "array" }, "total": { "title": "Total", "type": "integer" } }, "required": [ "items", "total" ], "title": "FollowUpListResponse", "type": "object" }, "FollowUpRecommendationItem": { "description": "One grounded follow-up the classifier is prepared to stand behind.\n\nEvery field a Journal card renders is here, and every one of them is\nevidence: `evidence_quote` is a verbatim span of the message, `reason_code`\nand `reason_text` say which rule fired, `expires_at` says when the\nobligation goes stale, and `confidence` says how sure the model was\n(TIDY-15401 / R102).", "properties": { "confidence": { "title": "Confidence", "type": "number" }, "conversation_id": { "title": "Conversation Id", "type": "string" }, "definition_slug": { "title": "Definition Slug", "type": "string" }, "definition_version": { "title": "Definition Version", "type": "integer" }, "evidence_quote": { "title": "Evidence Quote", "type": "string" }, "expires_at": { "format": "date-time", "title": "Expires At", "type": "string" }, "input_hash": { "title": "Input Hash", "type": "string" }, "proposed_action": { "title": "Proposed Action", "type": "string" }, "rank": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Persisted Journal-day rank 1..3, or null when the recommendation was not materialized (rollout gating) or holds no free rank.", "title": "Rank" }, "reason_code": { "title": "Reason Code", "type": "string" }, "reason_text": { "title": "Reason Text", "type": "string" }, "source_kind": { "description": "email | matrix", "title": "Source Kind", "type": "string" }, "source_message_id": { "title": "Source Message Id", "type": "string" }, "source_timestamp": { "format": "date-time", "title": "Source Timestamp", "type": "string" } }, "required": [ "source_kind", "conversation_id", "source_message_id", "source_timestamp", "reason_code", "reason_text", "evidence_quote", "proposed_action", "confidence", "expires_at", "definition_slug", "definition_version", "input_hash" ], "title": "FollowUpRecommendationItem", "type": "object" }, "FollowUpRecommendationsResponse": { "description": "At most three grounded follow-ups, plus why the rest were declined.\n\nAn empty `recommendations` list is the common and correct answer. The\n`abstentions` map is a bounded reason-code histogram, never per-message\ndetail — it exists so a precision review can see WHY a day was quiet.", "properties": { "abstentions": { "additionalProperties": { "type": "integer" }, "title": "Abstentions", "type": "object" }, "classified_count": { "default": 0, "title": "Classified Count", "type": "integer" }, "daily_cap": { "default": 0, "title": "Daily Cap", "type": "integer" }, "evaluated_at": { "format": "date-time", "title": "Evaluated At", "type": "string" }, "persisted_count": { "default": 0, "description": "How many recommendations became durable rows in the member-owned projection. Zero while the member is outside the follow-up rollout cohort (TIDY-15455) — a suppressed run is correct, not an error.", "title": "Persisted Count", "type": "integer" }, "recommendations": { "items": { "$ref": "#/components/schemas/FollowUpRecommendationItem" }, "title": "Recommendations", "type": "array" } }, "required": [ "evaluated_at" ], "title": "FollowUpRecommendationsResponse", "type": "object" }, "FollowUpUnflagResponse": { "properties": { "changed": { "title": "Changed", "type": "boolean" }, "contact_id": { "format": "uuid", "title": "Contact Id", "type": "string" }, "email_id": { "format": "uuid", "title": "Email Id", "type": "string" } }, "required": [ "email_id", "contact_id", "changed" ], "title": "FollowUpUnflagResponse", "type": "object" }, "ForceTakeoverRequest": { "properties": { "command_target": { "anyOf": [ { "$ref": "#/components/schemas/ProtectedCommandTarget" }, { "type": "null" } ] }, "confirmation_slug": { "maxLength": 80, "minLength": 2, "title": "Confirmation Slug", "type": "string" }, "expected_generation": { "minimum": 0.0, "title": "Expected Generation", "type": "integer" }, "reason": { "maxLength": 500, "minLength": 8, "title": "Reason", "type": "string" } }, "required": [ "expected_generation", "reason", "confirmation_slug" ], "title": "ForceTakeoverRequest", "type": "object" }, "ForceTakeoverResponse": { "properties": { "expires_at": { "format": "date-time", "title": "Expires At", "type": "string" }, "generation": { "title": "Generation", "type": "integer" }, "protected_setup_command": { "anyOf": [ { "$ref": "#/components/schemas/ProtectedSetupCommand" }, { "type": "null" } ], "default": null }, "replacement_claim_token": { "title": "Replacement Claim Token", "type": "string" }, "replacement_installation_id": { "format": "uuid", "title": "Replacement Installation Id", "type": "string" }, "replacement_not_before": { "format": "date-time", "title": "Replacement Not Before", "type": "string" }, "revoked_host": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "default": null, "title": "Revoked Host" }, "server_time": { "format": "date-time", "title": "Server Time", "type": "string" }, "takeover_receipt_id": { "format": "uuid", "title": "Takeover Receipt Id", "type": "string" } }, "required": [ "replacement_installation_id", "takeover_receipt_id", "replacement_claim_token", "generation", "expires_at", "replacement_not_before", "server_time" ], "title": "ForceTakeoverResponse", "type": "object" }, "ForecastPeriod": { "description": "Single forecast period from NWS (e.g., 'Today', 'Tonight', 'Saturday').", "properties": { "detailedForecast": { "description": "Full text forecast", "title": "Detailedforecast", "type": "string" }, "icon": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "NWS weather icon URL", "title": "Icon" }, "isDaytime": { "description": "Whether this is a daytime period", "title": "Isdaytime", "type": "boolean" }, "name": { "description": "Period name (Today, Tonight, Saturday, etc.)", "title": "Name", "type": "string" }, "shortForecast": { "description": "Short forecast (e.g., 'Sunny')", "title": "Shortforecast", "type": "string" }, "temperature": { "description": "Temperature in Fahrenheit", "title": "Temperature", "type": "integer" }, "temperatureUnit": { "default": "F", "description": "Temperature unit", "title": "Temperatureunit", "type": "string" }, "windDirection": { "description": "Wind direction (e.g., 'N', 'SW')", "title": "Winddirection", "type": "string" }, "windSpeed": { "description": "Wind speed (e.g., '10 mph')", "title": "Windspeed", "type": "string" } }, "required": [ "name", "temperature", "windSpeed", "windDirection", "shortForecast", "detailedForecast", "isDaytime" ], "title": "ForecastPeriod", "type": "object" }, "ForgetLeadRequest": { "properties": { "contact_id": { "description": "contacts.id of the lead to forget.", "title": "Contact Id", "type": "string" }, "lead_facet_slug": { "description": "The lead facet whose data is erased. Required: the caller resolves it from the tenant's installed facet definition — the platform holds no default lead vocabulary (TIDY-16774).", "minLength": 1, "title": "Lead Facet Slug", "type": "string" } }, "required": [ "contact_id", "lead_facet_slug" ], "title": "ForgetLeadRequest", "type": "object" }, "ForgetLeadResponse": { "properties": { "contact_deleted": { "description": "True when the contact existed solely as a lead and was deleted outright; False when only its lead/enrichment data was stripped from a fuller contact.", "title": "Contact Deleted", "type": "boolean" }, "contact_id": { "title": "Contact Id", "type": "string" }, "engagement_records_deleted": { "title": "Engagement Records Deleted", "type": "integer" }, "enrichment_notes_deleted": { "title": "Enrichment Notes Deleted", "type": "integer" }, "suppressed_emails": { "description": "Every address of the contact, now on the suppression list (a forgotten lead is never emailed again).", "items": { "type": "string" }, "title": "Suppressed Emails", "type": "array" } }, "required": [ "contact_id", "contact_deleted", "suppressed_emails", "enrichment_notes_deleted", "engagement_records_deleted" ], "title": "ForgetLeadResponse", "type": "object" }, "FormBindingMove": { "description": "One facet whose bindings a delete handed to the deleted copy's source\n(TIDY-18070). ``slots`` are the binding slots that moved — ``default``, a\nsurface key, ``@`` or ``template`` for the\nfacet's default template.", "properties": { "facet_id": { "format": "uuid", "title": "Facet Id", "type": "string" }, "facet_name": { "title": "Facet Name", "type": "string" }, "facet_slug": { "title": "Facet Slug", "type": "string" }, "slots": { "items": { "type": "string" }, "title": "Slots", "type": "array" }, "to_id": { "format": "uuid", "title": "To Id", "type": "string" }, "to_name": { "title": "To Name", "type": "string" } }, "required": [ "facet_id", "facet_slug", "facet_name", "slots", "to_id", "to_name" ], "title": "FormBindingMove", "type": "object" }, "FormBundle": { "description": "The compiled, self-contained public form (R17/R18).", "properties": { "branding_slots": { "items": { "type": "string" }, "title": "Branding Slots", "type": "array" }, "bundle_version": { "const": 1, "default": 1, "title": "Bundle Version", "type": "integer" }, "field_groups": { "items": { "$ref": "#/components/schemas/FormBundleFieldGroup" }, "title": "Field Groups", "type": "array" }, "fields": { "items": { "$ref": "#/components/schemas/FormBundleField" }, "title": "Fields", "type": "array" }, "form": { "$ref": "#/components/schemas/FormBundleForm" }, "pages": { "items": { "$ref": "#/components/schemas/FormBundlePage" }, "title": "Pages", "type": "array" }, "repeating_sections": { "items": { "$ref": "#/components/schemas/FormRepeatingSectionDef" }, "title": "Repeating Sections", "type": "array" }, "rules": { "items": { "$ref": "#/components/schemas/FormBundleRule" }, "title": "Rules", "type": "array" }, "submit": { "$ref": "#/components/schemas/FormBundleSubmit" } }, "required": [ "form", "pages", "fields" ], "title": "FormBundle", "type": "object" }, "FormBundleField": { "description": "One public field: the schema subset a renderer needs, nothing more.", "properties": { "group": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Group" }, "key": { "title": "Key", "type": "string" }, "label": { "title": "Label", "type": "string" }, "layout": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Layout" }, "options": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Options" }, "type": { "title": "Type", "type": "string" }, "type_options": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Type Options" }, "validation": { "additionalProperties": true, "title": "Validation", "type": "object" } }, "required": [ "key", "label", "type" ], "title": "FormBundleField", "type": "object" }, "FormBundleFieldGroup": { "properties": { "key": { "title": "Key", "type": "string" }, "label": { "title": "Label", "type": "string" } }, "required": [ "key", "label" ], "title": "FormBundleFieldGroup", "type": "object" }, "FormBundleForm": { "description": "Identity of the compiled form — pinned by reference, never by copy.", "properties": { "facet_slug": { "title": "Facet Slug", "type": "string" }, "target_table": { "title": "Target Table", "type": "string" }, "template_id": { "title": "Template Id", "type": "string" }, "template_version_id": { "title": "Template Version Id", "type": "string" }, "template_version_label": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Template Version Label" }, "title": { "title": "Title", "type": "string" } }, "required": [ "facet_slug", "target_table", "template_id", "template_version_id", "title" ], "title": "FormBundleForm", "type": "object" }, "FormBundlePage": { "description": "One page of the presentation tree (split at authored pageBreaks).\n\n``nodes`` is the PM-JSON subset: standard prose (paragraph/heading/lists/\ncallout/columnLayout/column/text/image with public-safe URLs) plus\n``boundField`` markers. Renderers must honor a ``stale: true`` attr on a\nboundField by showing an explicit marker (D19) — freshly compiled bundles\nnever carry it, but a drifted published bundle may.", "properties": { "index": { "title": "Index", "type": "integer" }, "nodes": { "items": { "additionalProperties": true, "type": "object" }, "title": "Nodes", "type": "array" } }, "required": [ "index", "nodes" ], "title": "FormBundlePage", "type": "object" }, "FormBundleRule": { "description": "Flattened conditional rule: `scope`+`key` name the field or group the\nrule attaches to; `when` is a FacetPredicate (shared semantics).", "properties": { "effect": { "enum": [ "visibility", "requiredness", "options" ], "title": "Effect", "type": "string" }, "key": { "title": "Key", "type": "string" }, "options": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Options" }, "scope": { "enum": [ "field", "group" ], "title": "Scope", "type": "string" }, "when": { "additionalProperties": true, "title": "When", "type": "object" } }, "required": [ "scope", "key", "effect", "when" ], "title": "FormBundleRule", "type": "object" }, "FormBundleSubmit": { "properties": { "payload_schema_ref": { "default": "FormSubmissionPayload@1", "description": "The submission shape this bundle expects back.", "title": "Payload Schema Ref", "type": "string" } }, "title": "FormBundleSubmit", "type": "object" }, "FormCapabilities": { "description": "The declarative-forms authoring vocabulary — node types a template body\nmay carry, the checklist field type, and the keys the server owns.", "properties": { "checklist_field_type": { "title": "Checklist Field Type", "type": "string" }, "derived_keys": { "items": { "type": "string" }, "title": "Derived Keys", "type": "array" }, "embed_modes": { "items": { "type": "string" }, "title": "Embed Modes", "type": "array" }, "node_types": { "items": { "type": "string" }, "title": "Node Types", "type": "array" }, "repeating_section_layouts": { "items": { "type": "string" }, "title": "Repeating Section Layouts", "type": "array" }, "server_owned_keys": { "items": { "type": "string" }, "title": "Server Owned Keys", "type": "array" }, "standard_node_types": { "items": { "type": "string" }, "title": "Standard Node Types", "type": "array" }, "tab_predicate_operators": { "items": { "type": "string" }, "title": "Tab Predicate Operators", "type": "array" } }, "required": [ "node_types", "checklist_field_type", "derived_keys" ], "title": "FormCapabilities", "type": "object" }, "FormCreateRequest": { "description": "Create a form. The server SCAFFOLDS the doc from `page_type` — the\nclient never posts a body on create, which is what keeps every surface's\nscaffold identical (R4: never a blank canvas).", "properties": { "facet_slug": { "maxLength": 128, "minLength": 1, "title": "Facet Slug", "type": "string" }, "forked_from_template_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Forked From Template Id" }, "name": { "maxLength": 200, "minLength": 1, "title": "Name", "type": "string" }, "page_type": { "default": "default_form", "maxLength": 32, "title": "Page Type", "type": "string" }, "visibility": { "default": "private", "maxLength": 16, "title": "Visibility", "type": "string" } }, "required": [ "facet_slug", "name" ], "title": "FormCreateRequest", "type": "object" }, "FormDeleteResponse": { "description": "What a delete did to the surfaces that showed the document.\n\nA deletion never leaves a dangling pin and never rebinds silently: a copy\nwith a live source hands its bindings back to that source (listed here,\nso the client can say which surface now shows what); a bound original\nwith no source is refused with ``409 form_bound`` instead, naming the\nsurfaces the member has to reassign first.", "properties": { "rebound": { "items": { "$ref": "#/components/schemas/FormBindingMove" }, "title": "Rebound", "type": "array" } }, "title": "FormDeleteResponse", "type": "object" }, "FormDetail": { "properties": { "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "doc": { "additionalProperties": true, "title": "Doc", "type": "object" }, "facet_slug": { "title": "Facet Slug", "type": "string" }, "forked_from_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "default": null, "title": "Forked From Id" }, "forked_from_template_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "default": null, "title": "Forked From Template Id" }, "id": { "format": "uuid", "title": "Id", "type": "string" }, "is_system": { "title": "Is System", "type": "boolean" }, "name": { "title": "Name", "type": "string" }, "overrides_form_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "default": null, "title": "Overrides Form Id" }, "owner_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "default": null, "title": "Owner Id" }, "page_type": { "title": "Page Type", "type": "string" }, "publish_config": { "additionalProperties": true, "title": "Publish Config", "type": "object" }, "published": { "title": "Published", "type": "boolean" }, "read_only": { "title": "Read Only", "type": "boolean" }, "tenant_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "default": null, "title": "Tenant Id" }, "updated_at": { "format": "date-time", "title": "Updated At", "type": "string" }, "visibility": { "title": "Visibility", "type": "string" } }, "required": [ "id", "facet_slug", "name", "page_type", "read_only", "visibility", "is_system", "published", "created_at", "updated_at", "doc" ], "title": "FormDetail", "type": "object" }, "FormForkRequest": { "description": "Fork a form into an editable copy.\n\n``facet_slug`` and ``doc`` are the R20 inheritance path (TIDY-16219): a\nchild facet starts from its primitive's base composition, so the fork is\nRE-TARGETED at the child and carries the document the client already\nrebound through the child's merged schema (`base-form-fork.ts`). Omit both\nand the fork is a plain copy for the same facet, as before.", "properties": { "doc": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Doc" }, "facet_slug": { "anyOf": [ { "maxLength": 128, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Facet Slug" }, "name": { "anyOf": [ { "maxLength": 200, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Name" } }, "title": "FormForkRequest", "type": "object" }, "FormList": { "properties": { "forms": { "items": { "$ref": "#/components/schemas/FormSummary" }, "title": "Forms", "type": "array" } }, "required": [ "forms" ], "title": "FormList", "type": "object" }, "FormOfflineResponse": { "properties": { "publication_id": { "format": "uuid", "title": "Publication Id", "type": "string" }, "status": { "title": "Status", "type": "string" } }, "required": [ "publication_id", "status" ], "title": "FormOfflineResponse", "type": "object" }, "FormProtections": { "description": "Write-path protection knobs (R19). Enforcement is CRM runtime scope.", "properties": { "cors_origins": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Cors Origins" }, "honeypot": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Honeypot" }, "rate_limit": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Rate Limit" }, "turnstile": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Turnstile" } }, "title": "FormProtections", "type": "object" }, "FormPublicationConfig": { "description": "Definition-level publication config (D3 — the one genuinely new object).\n\nMODEL ONLY in TIDY-14327 (P19): the CRM epic creates the storage, token\nissuance, and status lifecycle together against this frozen shape.\n``allowed_fields`` is authoritative — the compiled bundle's fields are\nalways a subset of it (a bound field outside it is a compile ERROR).", "properties": { "allowed_fields": { "items": { "type": "string" }, "title": "Allowed Fields", "type": "array" }, "facet_slug": { "title": "Facet Slug", "type": "string" }, "protections": { "$ref": "#/components/schemas/FormProtections" }, "redirect_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Redirect Url" }, "target_table": { "default": "records", "title": "Target Table", "type": "string" }, "template_id": { "title": "Template Id", "type": "string" }, "template_version_id": { "description": "The exact pinned version to compile — a published form is immutable-by-reference (P4). The publish flow snapshots first, then compiles.", "title": "Template Version Id", "type": "string" }, "thanks_message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Thanks Message" } }, "required": [ "facet_slug", "template_id", "template_version_id", "allowed_fields" ], "title": "FormPublicationConfig", "type": "object" }, "FormPublicationDetail": { "properties": { "blocked_count": { "title": "Blocked Count", "type": "integer" }, "bundle": { "additionalProperties": true, "description": "The published FormBundle snapshot — the Embed tab generates the widget HTML/snippet from it (TIDY-14690), never hand-maintained.", "title": "Bundle", "type": "object" }, "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "daily_stats": { "description": "Last 30 UTC days with activity.", "items": { "$ref": "#/components/schemas/DailyStat" }, "title": "Daily Stats", "type": "array" }, "facet_slug": { "title": "Facet Slug", "type": "string" }, "id": { "title": "Id", "type": "string" }, "protections": { "additionalProperties": true, "description": "Effective protection config (Turnstile secret redacted).", "title": "Protections", "type": "object" }, "public_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Built from the token, so NULL wherever the token is.", "title": "Public Url" }, "redirect_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Redirect Url" }, "revoked_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Revoked At" }, "status": { "title": "Status", "type": "string" }, "submit_count": { "title": "Submit Count", "type": "integer" }, "target_table": { "title": "Target Table", "type": "string" }, "template_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Template Id" }, "template_version_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Template Version Id" }, "thanks_message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Thanks Message" }, "token": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The plaintext publish token, and NULL for a first-class publication (TIDY-16220): those store only a SHA-256 digest, so the plaintext exists exactly once — in the publish response. Re-issue it by rotating, never by reading.", "title": "Token" } }, "required": [ "id", "facet_slug", "target_table", "status", "token", "public_url", "template_id", "template_version_id", "submit_count", "blocked_count", "created_at", "protections" ], "title": "FormPublicationDetail", "type": "object" }, "FormPublicationList": { "properties": { "publications": { "items": { "$ref": "#/components/schemas/FormPublicationSummary" }, "title": "Publications", "type": "array" } }, "required": [ "publications" ], "title": "FormPublicationList", "type": "object" }, "FormPublicationSummary": { "properties": { "blocked_count": { "title": "Blocked Count", "type": "integer" }, "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "facet_slug": { "title": "Facet Slug", "type": "string" }, "id": { "title": "Id", "type": "string" }, "public_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Built from the token, so NULL wherever the token is.", "title": "Public Url" }, "revoked_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Revoked At" }, "status": { "title": "Status", "type": "string" }, "submit_count": { "title": "Submit Count", "type": "integer" }, "target_table": { "title": "Target Table", "type": "string" }, "template_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Template Id" }, "template_version_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Template Version Id" }, "token": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The plaintext publish token, and NULL for a first-class publication (TIDY-16220): those store only a SHA-256 digest, so the plaintext exists exactly once — in the publish response. Re-issue it by rotating, never by reading.", "title": "Token" } }, "required": [ "id", "facet_slug", "target_table", "status", "token", "public_url", "template_id", "template_version_id", "submit_count", "blocked_count", "created_at" ], "title": "FormPublicationSummary", "type": "object" }, "FormPublishRequest": { "properties": { "allowed_origins": { "items": { "type": "string" }, "maxItems": 50, "title": "Allowed Origins", "type": "array" } }, "title": "FormPublishRequest", "type": "object" }, "FormPublishResponse": { "properties": { "api_url": { "title": "Api Url", "type": "string" }, "child_scopes": { "items": { "additionalProperties": true, "type": "object" }, "title": "Child Scopes", "type": "array" }, "declared_fields": { "items": { "type": "string" }, "title": "Declared Fields", "type": "array" }, "hosted_url": { "title": "Hosted Url", "type": "string" }, "publication_id": { "format": "uuid", "title": "Publication Id", "type": "string" }, "token": { "title": "Token", "type": "string" } }, "required": [ "publication_id", "token", "hosted_url", "api_url", "declared_fields" ], "title": "FormPublishResponse", "type": "object" }, "FormRepeatingSectionDef": { "description": "A 0..N entry section, self-contained (child schema subset embedded).", "properties": { "facet_slug": { "title": "Facet Slug", "type": "string" }, "fields": { "items": { "$ref": "#/components/schemas/FormBundleField" }, "title": "Fields", "type": "array" }, "max": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Max" }, "min": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Min" }, "node_id": { "title": "Node Id", "type": "string" }, "target_table": { "title": "Target Table", "type": "string" } }, "required": [ "node_id", "facet_slug", "target_table", "fields" ], "title": "FormRepeatingSectionDef", "type": "object" }, "FormSubmissionRequest": { "description": "Body for POST /api/v1/records/{record_id}/form-submissions.\n\n``values`` is the submitted field map (opaque to the sandbox document —\nthe host validates it). ``ai_expand`` is an OPTIONAL per-submission override\nhonored ONLY when the block author declared the ``form_ai_expand`` property;\notherwise its presence is rejected 422 ``ai_expand_not_permitted``.", "properties": { "ai_expand": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Per-submission AI-expansion override. Only permitted when the block declares the form_ai_expand property; otherwise 422.", "title": "Ai Expand" }, "values": { "additionalProperties": true, "description": "Submitted form field values.", "title": "FormSubmissionValues", "type": "object" } }, "title": "FormSubmissionRequest", "type": "object" }, "FormSubmissionResponse": { "description": "Result of a form submission.", "properties": { "created_record_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Created record id (create mode); null for self mode.", "title": "Created Record Id" }, "mode": { "description": "Submission mode that ran.", "enum": [ "create", "self" ], "title": "Mode", "type": "string" }, "ok": { "description": "True when the submission was accepted and written.", "title": "Ok", "type": "boolean" }, "target_facet": { "description": "Facet slug the submission created; 'html_block' for self mode.", "title": "Target Facet", "type": "string" } }, "required": [ "ok", "mode", "target_facet" ], "title": "FormSubmissionResponse", "type": "object" }, "FormSummary": { "description": "One form's metadata.\n\nIds and timestamps are typed as `UUID` / `datetime` rather than `str`\nbecause that is what asyncpg hands back, and `TidyResponseModel`\ncanonicalizes both on dump — declaring them `str` made every list response\na 500.", "properties": { "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "facet_slug": { "title": "Facet Slug", "type": "string" }, "forked_from_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "default": null, "title": "Forked From Id" }, "forked_from_template_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "default": null, "title": "Forked From Template Id" }, "id": { "format": "uuid", "title": "Id", "type": "string" }, "is_system": { "title": "Is System", "type": "boolean" }, "name": { "title": "Name", "type": "string" }, "overrides_form_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "default": null, "title": "Overrides Form Id" }, "owner_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "default": null, "title": "Owner Id" }, "page_type": { "title": "Page Type", "type": "string" }, "published": { "title": "Published", "type": "boolean" }, "read_only": { "title": "Read Only", "type": "boolean" }, "tenant_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "default": null, "title": "Tenant Id" }, "updated_at": { "format": "date-time", "title": "Updated At", "type": "string" }, "visibility": { "title": "Visibility", "type": "string" } }, "required": [ "id", "facet_slug", "name", "page_type", "read_only", "visibility", "is_system", "published", "created_at", "updated_at" ], "title": "FormSummary", "type": "object" }, "FormUpdateRequest": { "description": "Patch a form. Every field optional; omitted fields are untouched.\n\nA `doc` change mints an `artifact_versions` row inside the same\ntransaction as the UPDATE.", "properties": { "doc": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Doc" }, "name": { "anyOf": [ { "maxLength": 200, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Name" }, "read_only": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Read Only" }, "version_label": { "anyOf": [ { "maxLength": 200, "type": "string" }, { "type": "null" } ], "title": "Version Label" }, "visibility": { "anyOf": [ { "maxLength": 16, "type": "string" }, { "type": "null" } ], "title": "Visibility" } }, "title": "FormUpdateRequest", "type": "object" }, "FormerCustomerBillingLookupResponse": { "properties": { "found": { "title": "Found", "type": "boolean" }, "promos_redeemed": { "default": [], "items": { "type": "string" }, "title": "Promos Redeemed", "type": "array" }, "refs": { "default": [], "items": { "$ref": "#/components/schemas/FormerCustomerBillingRef" }, "title": "Refs", "type": "array" }, "retain_until": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Retain Until" }, "retention_policy_version": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Retention Policy Version" }, "returning_customer": { "default": false, "title": "Returning Customer", "type": "boolean" }, "review_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Review At" }, "was_paying": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "title": "Was Paying" } }, "required": [ "found" ], "title": "FormerCustomerBillingLookupResponse", "type": "object" }, "FormerCustomerBillingRef": { "properties": { "amount_minor": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Amount Minor" }, "currency": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Currency" }, "legal_hold_until": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Legal Hold Until" }, "record_type": { "title": "Record Type", "type": "string" }, "retain_until": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Retain Until" }, "retention_policy_version": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Retention Policy Version" }, "review_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Review At" }, "status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Status" }, "stripe_charge_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Stripe Charge Id" }, "stripe_customer_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Stripe Customer Id" }, "stripe_dispute_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Stripe Dispute Id" }, "stripe_env": { "title": "Stripe Env", "type": "string" }, "stripe_invoice_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Stripe Invoice Id" }, "stripe_payment_intent_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Stripe Payment Intent Id" }, "stripe_refund_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Stripe Refund Id" }, "transaction_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Transaction At" } }, "required": [ "record_type", "stripe_env" ], "title": "FormerCustomerBillingRef", "type": "object" }, "ForwardMessageRequest": { "properties": { "comment": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Comment" }, "source_event_id": { "title": "Source Event Id", "type": "string" }, "source_room_id": { "title": "Source Room Id", "type": "string" } }, "required": [ "source_room_id", "source_event_id" ], "title": "ForwardMessageRequest", "type": "object" }, "ForwardMessageResponse": { "properties": { "event_id": { "title": "Event Id", "type": "string" } }, "required": [ "event_id" ], "title": "ForwardMessageResponse", "type": "object" }, "ForwardRequest": { "description": "Request body for creating a forward.", "properties": { "bcc_recipients": { "description": "Forward Bcc recipients", "items": { "$ref": "#/components/schemas/EmailRecipient" }, "title": "Bcc Recipients", "type": "array" }, "body_html": { "default": "", "description": "Cover message HTML", "title": "Body Html", "type": "string" }, "body_text": { "default": "", "description": "Cover message text", "title": "Body Text", "type": "string" }, "cc_recipients": { "description": "Forward Cc recipients", "items": { "$ref": "#/components/schemas/EmailRecipient" }, "title": "Cc Recipients", "type": "array" }, "include_original_attachments": { "default": false, "description": "Re-attach the forwarded message's attachments to the new draft server-side (TIDY-15633). Bytes are resolved through the same locator chain as the attachment download endpoint, so they never round-trip the client. Attachments that cannot be resolved are skipped, not fatal.", "title": "Include Original Attachments", "type": "boolean" }, "quoted_body_text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Editable plain-text forwarded-message override", "title": "Quoted Body Text" }, "subject": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Editable forward subject override", "title": "Subject" }, "to_recipients": { "description": "Forward recipients", "items": { "$ref": "#/components/schemas/EmailRecipient" }, "title": "To Recipients", "type": "array" } }, "title": "ForwardRequest", "type": "object" }, "FtsResponse": { "description": "Merged, rank-sorted FTS result envelope.", "properties": { "query": { "title": "Query", "type": "string" }, "results": { "items": { "$ref": "#/components/schemas/FtsResult" }, "title": "Results", "type": "array" }, "total": { "title": "Total", "type": "integer" } }, "required": [ "results", "total", "query" ], "title": "FtsResponse", "type": "object" }, "FtsResult": { "description": "One hit from cross-table full-text search.", "properties": { "archived": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "title": "Archived" }, "due_date": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Due Date" }, "from_address": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "From Address" }, "has_attachments": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "title": "Has Attachments" }, "id": { "title": "Id", "type": "string" }, "location": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Location" }, "match_ranges": { "items": { "maxItems": 2, "minItems": 2, "prefixItems": [ { "type": "integer" }, { "type": "integer" } ], "type": "array" }, "title": "Match Ranges", "type": "array" }, "name": { "title": "Name", "type": "string" }, "note_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Note Type" }, "organization": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Organization" }, "parent_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Parent Id" }, "parent_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Parent Type" }, "rank": { "title": "Rank", "type": "number" }, "role": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Role" }, "sent_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Sent At" }, "snippet": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Snippet" }, "source_type": { "enum": [ "note", "journal", "news_update", "contact", "activity", "event", "project", "organization", "email", "drawing", "conversation", "comment" ], "title": "Source Type", "type": "string" }, "start_time": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Start Time" }, "status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Status" }, "subject": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Subject" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Title" } }, "required": [ "id", "source_type", "name", "rank" ], "title": "FtsResult", "type": "object" }, "FunnelCounts": { "description": "Hire conversion over the window: distinct hires reaching each step.", "properties": { "assigned": { "default": 0, "title": "Assigned", "type": "integer" }, "by_path": { "default": [], "items": { "$ref": "#/components/schemas/FunnelPathCounts" }, "title": "By Path", "type": "array" }, "completed": { "default": 0, "title": "Completed", "type": "integer" }, "completion_pct": { "default": 0.0, "title": "Completion Pct", "type": "number" }, "defined": { "default": 0, "title": "Defined", "type": "integer" }, "opened": { "default": 0, "title": "Opened", "type": "integer" }, "prefilled": { "default": 0, "title": "Prefilled", "type": "integer" }, "setup_required": { "default": 0, "title": "Setup Required", "type": "integer" } }, "title": "FunnelCounts", "type": "object" }, "FunnelPathCounts": { "description": "One path's per-step hire counts.", "properties": { "assigned": { "default": 0, "title": "Assigned", "type": "integer" }, "completed": { "default": 0, "title": "Completed", "type": "integer" }, "defined": { "default": 0, "title": "Defined", "type": "integer" }, "opened": { "default": 0, "title": "Opened", "type": "integer" }, "path": { "title": "Path", "type": "string" }, "prefilled": { "default": 0, "title": "Prefilled", "type": "integer" }, "setup_required": { "default": 0, "title": "Setup Required", "type": "integer" } }, "required": [ "path" ], "title": "FunnelPathCounts", "type": "object" }, "FunnelStepRequest": { "properties": { "blocked_on": { "items": { "additionalProperties": true, "type": "object" }, "title": "Blocked On", "type": "array" }, "harness": { "anyOf": [ { "enum": [ "pi", "claude-code", "codex", "hermes", "opencode", "openclaw", "antigravity", "local_connector" ], "type": "string" }, { "type": "null" } ], "title": "Harness" }, "hire_id": { "title": "Hire Id", "type": "string" }, "path_chosen": { "anyOf": [ { "enum": [ "hosted", "workshop" ], "type": "string" }, { "type": "null" } ], "title": "Path Chosen" }, "role_title": { "anyOf": [ { "maxLength": 160, "type": "string" }, { "type": "null" } ], "title": "Role Title" }, "step": { "title": "Step", "type": "string" }, "template_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Template Id" }, "template_key": { "maxLength": 120, "title": "Template Key", "type": "string" } }, "required": [ "hire_id", "template_key", "step" ], "title": "FunnelStepRequest", "type": "object" }, "FunnelStepResponse": { "properties": { "recorded": { "title": "Recorded", "type": "boolean" } }, "required": [ "recorded" ], "title": "FunnelStepResponse", "type": "object" }, "FunnelSummaryResponse": { "properties": { "attempts": { "title": "Attempts", "type": "integer" }, "completion_rate": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "title": "Completion Rate" }, "steps": { "items": { "additionalProperties": true, "type": "object" }, "title": "Steps", "type": "array" }, "window_days": { "title": "Window Days", "type": "integer" } }, "required": [ "window_days", "attempts", "steps" ], "title": "FunnelSummaryResponse", "type": "object" }, "GatekeeperLedgerResponse": { "properties": { "history_from": { "title": "History From", "type": "string" }, "months": { "items": { "$ref": "#/components/schemas/LedgerMonth" }, "title": "Months", "type": "array" } }, "required": [ "history_from", "months" ], "title": "GatekeeperLedgerResponse", "type": "object" }, "GatheredReference": { "description": "One member-visible reference the assistant can cite / serialize.", "properties": { "primitive_id": { "title": "Primitive Id", "type": "string" }, "primitive_type": { "title": "Primitive Type", "type": "string" }, "title": { "title": "Title", "type": "string" }, "wiki_link": { "title": "Wiki Link", "type": "string" } }, "required": [ "primitive_type", "primitive_id", "title", "wiki_link" ], "title": "GatheredReference", "type": "object" }, "GenerateCodesRequest": { "properties": { "comp_plan_tier": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Comp Plan Tier" }, "count": { "default": 3, "title": "Count", "type": "integer" }, "prefix": { "default": "FOUNDER", "title": "Prefix", "type": "string" }, "stripe_promotion_code_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Stripe Promotion Code Id" }, "trial_days": { "anyOf": [ { "maximum": 366.0, "minimum": 1.0, "type": "integer" }, { "type": "null" } ], "title": "Trial Days" } }, "title": "GenerateCodesRequest", "type": "object" }, "GenerateDraftRequest": { "description": "Request to generate AI draft.", "properties": { "context_hint": { "anyOf": [ { "maxLength": 500, "type": "string" }, { "type": "null" } ], "description": "Additional context for generation (e.g., 'confirm attendance')", "title": "Context Hint" }, "tone": { "anyOf": [ { "$ref": "#/components/schemas/ToneLevel" }, { "type": "null" } ], "description": "Override tone (auto-detect if not provided)" } }, "title": "GenerateDraftRequest", "type": "object" }, "GenerateDraftResponse": { "description": "Response from AI draft generation.", "properties": { "confidence": { "title": "Confidence", "type": "number" }, "generated_body": { "title": "Generated Body", "type": "string" }, "generated_subject": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Generated Subject" }, "generation_id": { "format": "uuid", "title": "Generation Id", "type": "string" }, "tone_detected": { "title": "Tone Detected", "type": "string" } }, "required": [ "generated_body", "tone_detected", "confidence", "generation_id" ], "title": "GenerateDraftResponse", "type": "object" }, "GenerateFocusDraftResponse": { "description": "Response for focus reply AI draft generation.", "properties": { "body_html": { "title": "Body Html", "type": "string" }, "draft_id": { "format": "uuid", "title": "Draft Id", "type": "string" }, "model_used": { "title": "Model Used", "type": "string" }, "style_profile_version": { "title": "Style Profile Version", "type": "integer" } }, "required": [ "draft_id", "body_html", "model_used", "style_profile_version" ], "title": "GenerateFocusDraftResponse", "type": "object" }, "GenerateImageRequest": { "properties": { "aspect": { "anyOf": [ { "enum": [ "square", "landscape", "portrait" ], "type": "string" }, { "type": "null" } ], "description": "Shape of a general `image` target (square, landscape, portrait). Every other target has a fixed shape.", "title": "Aspect" }, "context_excerpt": { "anyOf": [ { "maxLength": 1200, "type": "string" }, { "type": "null" } ], "description": "Fallback bounded context when generating for a saved view or other non-note surface", "title": "Context Excerpt" }, "context_title": { "anyOf": [ { "maxLength": 200, "type": "string" }, { "type": "null" } ], "description": "Fallback title when generating for a saved view or other non-note surface", "title": "Context Title" }, "note_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "UUID of the page (note/journal) to generate for", "title": "Note Id" }, "prompt": { "anyOf": [ { "maxLength": 2000, "type": "string" }, { "type": "null" } ], "title": "Prompt" }, "quality": { "default": "simple", "enum": [ "simple", "rich" ], "title": "Quality", "type": "string" }, "target": { "enum": [ "icon", "banner", "illustration", "slide_image", "cover_art", "infographic_element", "avatar_portrait", "avatar_storefront", "image" ], "title": "Target", "type": "string" }, "title": { "anyOf": [ { "maxLength": 120, "type": "string" }, { "type": "null" } ], "description": "Name for the stored file in My Files (without extension).", "title": "Title" } }, "required": [ "target" ], "title": "GenerateImageRequest", "type": "object" }, "GenerateImageResponse": { "properties": { "bucket": { "title": "Bucket", "type": "string" }, "file_id": { "title": "File Id", "type": "string" }, "folder_path": { "title": "Folder Path", "type": "string" }, "model": { "title": "Model", "type": "string" }, "name": { "title": "Name", "type": "string" }, "path": { "title": "Path", "type": "string" }, "signed_url": { "title": "Signed Url", "type": "string" } }, "required": [ "file_id", "bucket", "path", "signed_url", "name", "folder_path", "model" ], "title": "GenerateImageResponse", "type": "object" }, "GenerateInviteCodeResponse": { "properties": { "code": { "$ref": "#/components/schemas/GeneratedInviteCode" }, "effective_allowance": { "title": "Effective Allowance", "type": "integer" }, "remaining": { "title": "Remaining", "type": "integer" } }, "required": [ "code", "remaining", "effective_allowance" ], "title": "GenerateInviteCodeResponse", "type": "object" }, "GeneratePortraitRequest": { "description": "Body for POST /api/v1/avatars/portraits.", "properties": { "avatar_schema": { "additionalProperties": true, "description": "The composed avatar schema the portrait is derived from. The prompt is built from this descriptor alone — never from a photograph and never from the entity's name.", "title": "Avatar Schema", "type": "object" }, "display_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The entity's display name, passed ONLY as an exclusion so it cannot survive out of the instructions into the provider prompt.", "title": "Display Name" }, "entity_id": { "description": "Typed ID of the entity (C-/O-/R- prefixed); a bare UUID is still accepted during the typed-ID deprecation window.", "examples": [ "C-2e3f8b35-0000-0000-0000-000000000000" ], "title": "Entity Id", "type": "string" }, "entity_type": { "description": "One of: contact, organization, record.", "examples": [ "contact" ], "title": "Entity Type", "type": "string" }, "instructions": { "anyOf": [ { "maxLength": 280, "type": "string" }, { "type": "null" } ], "description": "Optional free-text direction. Sanitized server-side; prompt-override attempts and rendered-text requests are dropped.", "title": "Instructions" }, "style_preset": { "default": "photorealistic", "description": "One of the ids from GET /api/v1/avatars/portraits/options.", "title": "Style Preset", "type": "string" } }, "required": [ "entity_type", "entity_id", "avatar_schema" ], "title": "GeneratePortraitRequest", "type": "object" }, "GeneratePortraitResponse": { "properties": { "portrait": { "$ref": "#/components/schemas/PortraitModel" }, "quota": { "$ref": "#/components/schemas/QuotaStatusModel" } }, "required": [ "portrait", "quota" ], "title": "GeneratePortraitResponse", "type": "object" }, "GenerateResponse": { "properties": { "anomalies": { "items": { "additionalProperties": true, "type": "object" }, "title": "Anomalies", "type": "array" }, "coaching_cards": { "items": { "additionalProperties": true, "type": "object" }, "title": "Coaching Cards", "type": "array" }, "generated_at": { "title": "Generated At", "type": "string" }, "highlights": { "items": { "type": "string" }, "title": "Highlights", "type": "array" }, "narrative_text": { "title": "Narrative Text", "type": "string" }, "period_end": { "title": "Period End", "type": "string" }, "period_start": { "title": "Period Start", "type": "string" }, "record_id": { "title": "Record Id", "type": "string" } }, "required": [ "record_id", "period_start", "period_end", "narrative_text", "highlights", "anomalies", "coaching_cards", "generated_at" ], "title": "GenerateResponse", "type": "object" }, "GeneratedInviteCode": { "properties": { "code": { "title": "Code", "type": "string" }, "expires_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Expires At" }, "id": { "title": "Id", "type": "string" }, "status": { "title": "Status", "type": "string" } }, "required": [ "id", "code", "status" ], "title": "GeneratedInviteCode", "type": "object" }, "GenerationBuildLogEntry": { "description": "One line of a generation's build log (TIDY-15716).", "properties": { "attempt": { "default": 0, "description": "0 = the run itself; 1..n = one code-write-and-run attempt", "title": "Attempt", "type": "integer" }, "created_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Created At" }, "detail": { "additionalProperties": true, "default": {}, "title": "Detail", "type": "object" }, "event": { "description": "run_started | code_authored | sandbox_result | egress_attempt | artifact_accepted | artifact_refused | build_failed | run_completed", "title": "Event", "type": "string" }, "level": { "default": "info", "description": "info | warn | error", "title": "Level", "type": "string" }, "message": { "title": "Message", "type": "string" }, "seq": { "title": "Seq", "type": "integer" } }, "required": [ "seq", "event", "message" ], "title": "GenerationBuildLogEntry", "type": "object" }, "GenerationBuildLogResponse": { "description": "A generation's build log, in reading order.\n\n``entries`` is empty for a tier that keeps no build log — that is a fact\nabout the tier, not an error, and the surface says \"no build log for this\noutput type\" rather than showing an empty panel that reads like a stall.", "properties": { "entries": { "default": [], "items": { "$ref": "#/components/schemas/GenerationBuildLogEntry" }, "title": "Entries", "type": "array" }, "job_id": { "title": "Job Id", "type": "string" }, "producer_tier": { "title": "Producer Tier", "type": "string" }, "stage": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Stage" }, "status": { "title": "Status", "type": "string" } }, "required": [ "job_id", "producer_tier", "status" ], "title": "GenerationBuildLogResponse", "type": "object" }, "GenerationCapabilitiesResponse": { "description": "What a generation contract may legally declare, right now.\n\nTIDY-15682 (F2-S4, R10). The facet editor authors the same contract S1\nvalidates, so it reads the vocabulary from the registry rather than\nmirroring it: a modality with no producer is never OFFERED (preventing the\n422 instead of reporting it), and a lane this deployment cannot call is\nshown unavailable with the reason before the author declares it.", "properties": { "content_producers": { "items": { "$ref": "#/components/schemas/ContentProducerOption" }, "title": "Content Producers", "type": "array" }, "cost_classes": { "items": { "type": "string" }, "title": "Cost Classes", "type": "array" }, "lanes": { "items": { "$ref": "#/components/schemas/LaneCapability" }, "title": "Lanes", "type": "array" }, "modalities": { "items": { "$ref": "#/components/schemas/ModalityCapability" }, "title": "Modalities", "type": "array" }, "producer_tiers": { "items": { "type": "string" }, "title": "Producer Tiers", "type": "array" } }, "required": [ "modalities", "producer_tiers", "cost_classes", "lanes", "content_producers" ], "title": "GenerationCapabilitiesResponse", "type": "object" }, "GenerationEstimateResponse": { "description": "A pre-flight estimate (TIDY-15710 / D19).\n\nTwo figures, because a generation has two costs. `estimated_cost_micros` is\nwhat TIDY is charged — zero on a BYO lane, where the account pays its own\nprovider. `estimated_provider_cost_micros` is what the call costs the payer,\nand it is the number that is never zero for real work. `billed_to` is the\nsentence the UI must show so a zero is never read as \"free\".", "properties": { "billed_to": { "title": "Billed To", "type": "string" }, "breakdown": { "default": [], "items": { "$ref": "#/components/schemas/CostLineResponse" }, "title": "Breakdown", "type": "array" }, "byo_routed": { "description": "Whether the run is CONFIRMED to bill the account's own provider. Never true merely because a BYO key exists for the lane — the divergence TIDY-15874 fixed.", "title": "Byo Routed", "type": "boolean" }, "cost_class": { "title": "Cost Class", "type": "string" }, "estimate_fingerprint": { "default": "", "description": "Canonical `sha256:` digest over the sources, the reviewed instruction, the resolved producer options, the route, the breakdown and the exact provider cost (TIDY-17831 / R8). Echo it on submit alongside the price: the server recomputes it and refuses on ANY difference, so a quote cannot be spent on a different configuration that happens to cost the same or less.", "title": "Estimate Fingerprint", "type": "string" }, "estimated_cost_micros": { "title": "Estimated Cost Micros", "type": "integer" }, "estimated_provider_cost_micros": { "title": "Estimated Provider Cost Micros", "type": "integer" }, "is_estimate": { "default": true, "title": "Is Estimate", "type": "boolean" }, "lane": { "title": "Lane", "type": "string" }, "modality": { "title": "Modality", "type": "string" }, "model": { "title": "Model", "type": "string" }, "requires_confirmation": { "title": "Requires Confirmation", "type": "boolean" }, "routing_confirmed": { "default": true, "description": "Whether the payer is settled before the run. False means the lane picks its provider at execution time; `routing_note` says how.", "title": "Routing Confirmed", "type": "boolean" }, "routing_note": { "default": "", "description": "Plain-language explanation when routing is not confirmed", "title": "Routing Note", "type": "string" } }, "required": [ "estimated_cost_micros", "estimated_provider_cost_micros", "cost_class", "modality", "lane", "model", "byo_routed", "requires_confirmation", "billed_to" ], "title": "GenerationEstimateResponse", "type": "object" }, "GenerationInputResponse": { "description": "Answer what a paused generation is waiting on (TIDY-15699).\n\nToday the only pause is the data table's column proposal, so `columns` is\nthe answer. The envelope carries `kind` anyway: the next modality that needs\nto ask something will answer through this endpoint too, and a client that\nhas to guess which question it is answering is a client that will guess\nwrong once.", "properties": { "columns": { "description": "The approved columns, in order — the proposal as-is, or adjusted.", "items": { "type": "string" }, "title": "Columns", "type": "array" }, "kind": { "default": "column_proposal", "description": "What is being answered; must match the pause.", "title": "Kind", "type": "string" } }, "title": "GenerationInputResponse", "type": "object" }, "GenerationJobListResponse": { "properties": { "jobs": { "default": [], "items": { "$ref": "#/components/schemas/GenerationJobResponse" }, "title": "Jobs", "type": "array" } }, "title": "GenerationJobListResponse", "type": "object" }, "GenerationJobResponse": { "description": "A durable generation job.\n\n``stuck`` / ``stuck_detail`` render the SERVER-STAMPED ``stuck_at``\n(D17, TIDY-15967): a running job that has stopped reporting is stuck at\n``stage``, which is what makes it distinguishable from one that is merely\nslow. They used to be derived here at read time and stored nowhere, so\nthis endpoint was the ONLY reader that could see stuckness — a direct SQL\npoll and a PowerSync client both read `running` while the server could\nalready tell the producer was gone. ``result_link`` is where the finished\nartifact opens.", "properties": { "bundle_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Bundle Id" }, "cancel_requested": { "title": "Cancel Requested", "type": "boolean" }, "completed_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Completed At" }, "created_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Created At" }, "error_message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Error Message" }, "error_stage": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Error Stage" }, "estimated_cost_micros": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Estimated Cost Micros" }, "facet_slug": { "title": "Facet Slug", "type": "string" }, "heartbeat_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Heartbeat At" }, "id": { "title": "Id", "type": "string" }, "input_deadline_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Input Deadline At" }, "instructions": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Instructions" }, "modality": { "title": "Modality", "type": "string" }, "notice": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "title": "Notice" }, "pending_input": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "title": "Pending Input" }, "producer_tier": { "title": "Producer Tier", "type": "string" }, "progress_pct": { "title": "Progress Pct", "type": "integer" }, "result_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Result Id" }, "result_link": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Result Link" }, "result_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Result Type" }, "stage": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Stage" }, "started_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Started At" }, "status": { "title": "Status", "type": "string" }, "stuck": { "default": false, "title": "Stuck", "type": "boolean" }, "stuck_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Stuck At" }, "stuck_detail": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Stuck Detail" }, "style": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Style" }, "updated_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Updated At" } }, "required": [ "id", "facet_slug", "modality", "producer_tier", "status", "progress_pct", "cancel_requested" ], "title": "GenerationJobResponse", "type": "object" }, "GenerationPlaybackRequest": { "description": "One playback moment for a generated media artifact (R15 observability).", "properties": { "event": { "description": "'started' when playback begins, 'completed' when it reaches the end", "title": "Event", "type": "string" } }, "required": [ "event" ], "title": "GenerationPlaybackRequest", "type": "object" }, "GenerationPlaybackResponse": { "description": "Whether the moment counted, and under which shape.", "properties": { "recorded": { "title": "Recorded", "type": "boolean" }, "shape": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Shape" } }, "required": [ "recorded" ], "title": "GenerationPlaybackResponse", "type": "object" }, "GenerationPreviewResponse": { "description": "What the bundle's override will and will not do, before anything runs.\n\nThe generate step reads this to show the user, up front, that their words\nwere understood — and which parts of them the output type will not honour\n(R11 edge case). Modality, producer tier and target primitive are read from\nthe definition's generation contract and are NOT influenced by the override\n(D4); that is why they appear here as facts rather than as choices.", "properties": { "facet_slug": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Facet Slug" }, "instruction_conflicts": { "default": [], "items": { "type": "string" }, "title": "Instruction Conflicts", "type": "array" }, "instruction_layers": { "default": [], "items": { "type": "string" }, "title": "Instruction Layers", "type": "array" }, "instructions": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Instructions" }, "modality": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Modality" }, "producer_instruction_field": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Producer Instruction Field" }, "producer_instructions": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Producer Instructions" }, "producer_tier": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Producer Tier" }, "target_primitive": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Target Primitive" } }, "title": "GenerationPreviewResponse", "type": "object" }, "GenerationQuotaRequest": { "description": "Set the caps. An explicit null clears that cap (unbounded).", "properties": { "hard_stop": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Refuse (true) or warn-and-record (false) when a cap is exceeded.", "title": "Hard Stop" }, "tenant_provider_cap_micros": { "anyOf": [ { "minimum": 0.0, "type": "integer" }, { "type": "null" } ], "description": "Workspace ceiling on provider spend per period.", "title": "Tenant Provider Cap Micros" }, "user_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Member the per-user cap applies to; defaults to the caller.", "title": "User Id" }, "user_provider_cap_micros": { "anyOf": [ { "minimum": 0.0, "type": "integer" }, { "type": "null" } ], "description": "Per-member ceiling on provider spend per period.", "title": "User Provider Cap Micros" } }, "title": "GenerationQuotaRequest", "type": "object" }, "GenerationQuotaResponse": { "description": "Every configured cap plus period-to-date usage against it.", "properties": { "billing_period_start": { "title": "Billing Period Start", "type": "string" }, "can_manage": { "description": "Whether THIS caller may change the caps (owner/tenant_admin).", "title": "Can Manage", "type": "boolean" }, "hard_stop": { "description": "When true, exceeding a cap refuses the generation instead of warning.", "title": "Hard Stop", "type": "boolean" }, "reset_at": { "title": "Reset At", "type": "string" }, "tenant_provider_cap_micros": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Tenant Provider Cap Micros" }, "tenant_provider_used_micros": { "title": "Tenant Provider Used Micros", "type": "integer" }, "user_credit_cap": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "title": "User Credit Cap" }, "user_credit_used": { "title": "User Credit Used", "type": "number" }, "user_provider_cap_micros": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "User Provider Cap Micros" }, "user_provider_used_micros": { "title": "User Provider Used Micros", "type": "integer" } }, "required": [ "billing_period_start", "reset_at", "hard_stop", "can_manage", "tenant_provider_used_micros", "user_provider_used_micros", "user_credit_used" ], "title": "GenerationQuotaResponse", "type": "object" }, "GenerationSpendEvent": { "description": "One cost event this generation minted.", "properties": { "byo_routed": { "default": false, "description": "Whether this event was billed to the account's own provider", "title": "Byo Routed", "type": "boolean" }, "completion_tokens": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Completion Tokens" }, "cost_micros": { "title": "Cost Micros", "type": "integer" }, "kind": { "description": "llm | service", "title": "Kind", "type": "string" }, "model": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Model (llm) or provider (service)", "title": "Model" }, "occurred_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Occurred At" }, "prompt_tokens": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Prompt Tokens" }, "requested_model": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "The route this call asked for (LiteLLM model_group) — the string an estimate names. Differs from `model`, which is the upstream model that answered. Null on a metered service event and on rows written before 2026-07-28, where the route was never recorded.", "title": "Requested Model" }, "service_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Service Name" } }, "required": [ "kind", "cost_micros" ], "title": "GenerationSpendEvent", "type": "object" }, "GenerationSpendResponse": { "description": "What this generation was quoted, what it actually spent, and the gap.\n\nThe answer to \"you said 12,096 and it cost 18,621 — why?\" (TIDY-15874).\n`actual_*` comes from the cost ledger joined on this job's id; a completed\njob whose ledger names no events reports `actual_funding='unattributed'`\nwith `cost_event_count=0` rather than a zero that reads as free.", "properties": { "actual_cost_micros": { "default": 0, "title": "Actual Cost Micros", "type": "integer" }, "actual_funding": { "default": "unattributed", "description": "tidy | byo | mixed | unattributed", "title": "Actual Funding", "type": "string" }, "actual_model": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Actual Model" }, "actual_model_lane": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Actual Model Lane" }, "actual_route": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "The route that served (LiteLLM model_group of the last LLM leg) — the only string comparable with `estimated_model`. `actual_model` is the upstream model that answered and is a different name for any proxied lane. Null when no LLM event recorded a route.", "title": "Actual Route" }, "cost_event_count": { "default": 0, "title": "Cost Event Count", "type": "integer" }, "divergence_micros": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "actual − estimated; null until at least one cost event lands", "title": "Divergence Micros" }, "divergence_pct": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "title": "Divergence Pct" }, "estimated_byo_routed": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "title": "Estimated Byo Routed" }, "estimated_cost_micros": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Estimated Cost Micros" }, "estimated_model": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Estimated Model" }, "estimated_routing_confirmed": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "title": "Estimated Routing Confirmed" }, "events": { "default": [], "items": { "$ref": "#/components/schemas/GenerationSpendEvent" }, "title": "Events", "type": "array" }, "job_id": { "title": "Job Id", "type": "string" }, "route_diverged": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "description": "The run went somewhere the estimate did not name — a different payer, or a different route (`actual_route` vs `estimated_model`). Null means NOT COMPARABLE (no cost event, or the serving route was never recorded), which is not the same claim as false.", "title": "Route Diverged" }, "status": { "title": "Status", "type": "string" } }, "required": [ "job_id", "status" ], "title": "GenerationSpendResponse", "type": "object" }, "GeocodeRequest": { "properties": { "address": { "description": "Free-text street address to resolve to a point", "maxLength": 500, "minLength": 1, "title": "Address", "type": "string" } }, "required": [ "address" ], "title": "GeocodeRequest", "type": "object" }, "GeocodeResponse": { "properties": { "formatted_address": { "description": "Provider's canonical rendering of the address", "title": "Formatted Address", "type": "string" }, "lat": { "description": "Latitude of the resolved address", "title": "Lat", "type": "number" }, "lng": { "description": "Longitude of the resolved address", "title": "Lng", "type": "number" }, "source": { "description": "Which side answered: 'cache' or 'google'", "title": "Source", "type": "string" } }, "required": [ "lat", "lng", "formatted_address", "source" ], "title": "GeocodeResponse", "type": "object" }, "GitHubAccountConnection": { "description": "One connected GitHub account — one installation, one plugin (TIDY-19699).\n\nThe fields mean what the same-named fields of\n:class:`GitHubConnectionResponse` mean, for this account alone; ``usable``\nis the use gate's verdict for the caller on THIS installation.", "properties": { "account_login": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Account Login" }, "account_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Account Type" }, "connected_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Connected At" }, "github_user_login": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Github User Login" }, "identity_bound": { "default": false, "title": "Identity Bound", "type": "boolean" }, "installation_id": { "title": "Installation Id", "type": "integer" }, "last_error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Last Error" }, "last_verified_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Last Verified At" }, "plugin_id": { "title": "Plugin Id", "type": "string" }, "refusal_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Refusal Code" }, "refusal_message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Refusal Message" }, "repository_selection": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Repository Selection" }, "status": { "enum": [ "not_connected", "working", "needs_reauth", "disconnected", "pending" ], "title": "Status", "type": "string" }, "usable": { "default": false, "title": "Usable", "type": "boolean" } }, "required": [ "plugin_id", "status", "installation_id" ], "title": "GitHubAccountConnection", "type": "object" }, "GitHubAgentTokenRequest": { "description": "A virtual employee's request for a git credential (TIDY-17032).\n\n``repository`` is REQUIRED and is the whole point of this model. The VE's\ncredential helper learns which repository git is talking to from the\ncredential protocol's path and passes it here, so the token it receives\nreaches that repository and no other. There is deliberately no way to ask\nfor an unbounded token on this route: an optional field would make the\nbound a convention, and every caller that forgot it would silently hold a\ncredential for every repository the tenant ever installed the App on.", "properties": { "repository": { "title": "Repository", "type": "string" } }, "required": [ "repository" ], "title": "GitHubAgentTokenRequest", "type": "object" }, "GitHubBranch": { "description": "One branch on a repository, read live.", "properties": { "commit_sha": { "title": "Commit Sha", "type": "string" }, "name": { "title": "Name", "type": "string" }, "protected": { "default": false, "title": "Protected", "type": "boolean" } }, "required": [ "name", "commit_sha" ], "title": "GitHubBranch", "type": "object" }, "GitHubBranchListResponse": { "properties": { "branches": { "items": { "$ref": "#/components/schemas/GitHubBranch" }, "title": "Branches", "type": "array" }, "default_branch": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Default Branch" } }, "required": [ "branches" ], "title": "GitHubBranchListResponse", "type": "object" }, "GitHubConnectionResponse": { "description": "The tenant's GitHub App connection, as the settings card reads it.\n\n`configured` and `status` answer two different questions and must not be\ncollapsed. `configured=False` means THIS DEPLOYMENT has no GitHub App\n(no client id, or no readable private key) — nothing the user can fix.\n`configured=True, status='not_connected'` means the deployment is ready and\nthe tenant simply has not connected yet — one button away. A single\n\"not connected\" would send the first user down the wrong path.", "properties": { "account_login": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Account Login" }, "account_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Account Type" }, "configured": { "title": "Configured", "type": "boolean" }, "connected_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Connected At" }, "connections": { "default": [], "items": { "$ref": "#/components/schemas/GitHubAccountConnection" }, "title": "Connections", "type": "array" }, "github_user_login": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Github User Login" }, "identity_bound": { "default": false, "title": "Identity Bound", "type": "boolean" }, "installation_id": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Installation Id" }, "last_error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Last Error" }, "last_verified_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Last Verified At" }, "plugin_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Plugin Id" }, "refusal_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Refusal Code" }, "refusal_message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Refusal Message" }, "repository_selection": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Repository Selection" }, "status": { "enum": [ "not_connected", "working", "needs_reauth", "disconnected", "pending" ], "title": "Status", "type": "string" }, "usable": { "default": false, "title": "Usable", "type": "boolean" } }, "required": [ "configured", "status" ], "title": "GitHubConnectionResponse", "type": "object" }, "GitHubCreateBranchRequest": { "description": "Create `branch` at whatever `from_ref` points at right now.", "properties": { "branch": { "title": "Branch", "type": "string" }, "from_ref": { "title": "From Ref", "type": "string" } }, "required": [ "branch", "from_ref" ], "title": "GitHubCreateBranchRequest", "type": "object" }, "GitHubCreateRepositoryRequest": { "description": "Create a repository through the App (TIDY-16333 / S22).\n\nPrivate by default — a VE's first repository should not become public\nbecause a checkbox defaulted the other way.", "properties": { "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "name": { "title": "Name", "type": "string" }, "owner": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Owner" }, "private": { "default": true, "title": "Private", "type": "boolean" } }, "required": [ "name" ], "title": "GitHubCreateRepositoryRequest", "type": "object" }, "GitHubInstallOutcomeResponse": { "description": "Did the install ceremony this state started ever reach Tidy?\n\nTIDY-19102. A connect begun on dev1 completed GitHub's install UI and then\nlanded on **tidy.engineering** — Cloudflare Pages serving the marketing\nsite, which answers HTTP 200. The browser showed a normal page, no error\nwas raised anywhere, and the installation existed on GitHub with no row in\nTidy. `installations/new` honours ``redirect_uri`` only for an install it\nactually performs; when the App is already installed on the chosen account\nit short-circuits to the App's own setup URL, which is ONE environment for\nall of dev1/QA/production.\n\nTidy cannot make github.com honour a callback the App does not have\nregistered. What it can do is stop the silence: the state it minted is\nstill unspent, which is proof the ceremony did not come back here.", "properties": { "callback_url": { "title": "Callback Url", "type": "string" }, "pending": { "title": "Pending", "type": "boolean" }, "settled": { "title": "Settled", "type": "boolean" } }, "required": [ "settled", "pending", "callback_url" ], "title": "GitHubInstallOutcomeResponse", "type": "object" }, "GitHubInstallUrlResponse": { "description": "Where to send the browser to install the App, with one-shot state.", "properties": { "callback_url": { "default": "", "title": "Callback Url", "type": "string" }, "install_url": { "title": "Install Url", "type": "string" }, "state": { "title": "State", "type": "string" } }, "required": [ "install_url", "state" ], "title": "GitHubInstallUrlResponse", "type": "object" }, "GitHubInstallationCandidate": { "description": "One installation the connecting person is entitled to (TIDY-18055).\n\n`allowed=False` carries a `refusal` code — another workspace already holds\nthe installation — and is shown disabled with the reason rather than\nhidden, so the person understands why they cannot pick it.", "properties": { "account_login": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Account Login" }, "account_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Account Type" }, "allowed": { "title": "Allowed", "type": "boolean" }, "connected_here": { "default": false, "title": "Connected Here", "type": "boolean" }, "installation_id": { "title": "Installation Id", "type": "integer" }, "refusal": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Refusal" }, "repository_selection": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Repository Selection" } }, "required": [ "installation_id", "allowed" ], "title": "GitHubInstallationCandidate", "type": "object" }, "GitHubInstallationTokenRequest": { "description": "Which repository a ``gh`` mint is for (TIDY-19699). Optional.\n\nThe token stays installation-wide — ``gh`` names no repository the way git\ndoes — but with several GitHub accounts connected, the repository is how\nTidy knows WHICH account's installation to mint from. A request without\none is served when the caller has exactly one account to use.", "properties": { "repository": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Repository" } }, "title": "GitHubInstallationTokenRequest", "type": "object" }, "GitHubInstallationTokenResponse": { "description": "A freshly minted installation access token (TIDY-16314 / S29).\n\nThis is the ONLY response in the codebase that carries a GitHub secret, and\nit exists because git needs a password on stdin — there is no way to push\nwithout one reaching the host.\n\nWhat keeps that acceptable is that the secret is short-lived and re-minted\nrather than stored: the credential helper on the VE calls this per operation\nand never writes the value to disk. `expires_at` is returned so a caller can\nsee how briefly it lives, NOT so anyone can cache against it.\n\n`username` is fixed by GitHub's protocol (`x-access-token`); returning it\nmeans the helper never has to hardcode a convention that could change.", "properties": { "account_login": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Account Login" }, "expires_at": { "format": "date-time", "title": "Expires At", "type": "string" }, "repositories": { "default": [], "items": { "type": "string" }, "title": "Repositories", "type": "array" }, "repository_selection": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Repository Selection" }, "token": { "title": "Token", "type": "string" }, "username": { "default": "x-access-token", "title": "Username", "type": "string" } }, "required": [ "token", "expires_at" ], "title": "GitHubInstallationTokenResponse", "type": "object" }, "GitHubPendingInstallationsResponse": { "description": "The \"choose which workspace may use it\" state (TIDY-18055).\n\nProduced when the authorizing person's token lists more than one\ninstallation of the App. Nothing has been written; `choice` is the one-shot\ntoken the selection must present.", "properties": { "candidates": { "items": { "$ref": "#/components/schemas/GitHubInstallationCandidate" }, "title": "Candidates", "type": "array" }, "github_login": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Github Login" } }, "required": [ "candidates" ], "title": "GitHubPendingInstallationsResponse", "type": "object" }, "GitHubRepository": { "description": "One repository the tenant's installation may touch (TIDY-16333 / S22).\n\n`repo_id` is GitHub's numeric id and is what a session binding stores: a\nrepository that is renamed or transferred keeps it, so a bound checkout does\nnot orphan itself the day somebody renames the repo.", "properties": { "archived": { "title": "Archived", "type": "boolean" }, "clone_url": { "title": "Clone Url", "type": "string" }, "default_branch": { "title": "Default Branch", "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Description" }, "full_name": { "title": "Full Name", "type": "string" }, "html_url": { "title": "Html Url", "type": "string" }, "name": { "title": "Name", "type": "string" }, "owner_login": { "title": "Owner Login", "type": "string" }, "private": { "title": "Private", "type": "boolean" }, "repo_id": { "title": "Repo Id", "type": "integer" } }, "required": [ "repo_id", "full_name", "name", "owner_login", "private", "default_branch", "clone_url", "html_url", "archived" ], "title": "GitHubRepository", "type": "object" }, "GitHubRepositoryAccount": { "description": "One connected account's share of the picker (TIDY-19699).", "properties": { "account_login": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Account Login" }, "account_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Account Type" }, "can_create_repository": { "default": false, "title": "Can Create Repository", "type": "boolean" }, "create_refusal": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Create Refusal" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Error" }, "plugin_id": { "title": "Plugin Id", "type": "string" }, "repository_selection": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Repository Selection" } }, "required": [ "plugin_id" ], "title": "GitHubRepositoryAccount", "type": "object" }, "GitHubRepositoryListResponse": { "description": "The live repository picker payload (TIDY-16333 / S22).\n\nNever cached in Tidy. Grants change on github.com with no webhook in v1, so\na stored list goes wrong silently — as a VE cloning a repo it no longer has\naccess to, or a picker missing the repo just granted.\n\n`can_create_repository` comes from the SAME live read: the create button\nmust not render on an installation that cannot create, and the reason for a\nrefusal is GitHub's or the org's, passed through rather than paraphrased.", "properties": { "account_login": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Account Login" }, "account_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Account Type" }, "accounts": { "default": [], "items": { "$ref": "#/components/schemas/GitHubRepositoryAccount" }, "title": "Accounts", "type": "array" }, "can_create_repository": { "default": false, "title": "Can Create Repository", "type": "boolean" }, "create_refusal": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Create Refusal" }, "repositories": { "items": { "$ref": "#/components/schemas/GitHubRepository" }, "title": "Repositories", "type": "array" }, "repository_selection": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Repository Selection" } }, "required": [ "repositories" ], "title": "GitHubRepositoryListResponse", "type": "object" }, "GitHubSelectInstallationRequest": { "description": "Bind ONE of the pending candidates to the caller's workspace.", "properties": { "choice": { "title": "Choice", "type": "string" }, "installation_id": { "title": "Installation Id", "type": "integer" } }, "required": [ "choice", "installation_id" ], "title": "GitHubSelectInstallationRequest", "type": "object" }, "GitLabAccountConnection": { "description": "One connected GitLab account — its own connection and plugin (TIDY-19699).", "properties": { "account_login": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Account Login" }, "auth_kind": { "anyOf": [ { "enum": [ "oauth", "project_token" ], "type": "string" }, { "type": "null" } ], "default": null, "title": "Auth Kind" }, "base_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Base Url" }, "connection_id": { "title": "Connection Id", "type": "string" }, "last_error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Last Error" }, "last_verified_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Last Verified At" }, "plugin_id": { "title": "Plugin Id", "type": "string" }, "status": { "enum": [ "not_configured", "not_connected", "pending", "working", "disconnected", "needs_reauth" ], "title": "Status", "type": "string" }, "webhook_secret_set": { "default": false, "title": "Webhook Secret Set", "type": "boolean" } }, "required": [ "connection_id", "plugin_id", "status" ], "title": "GitLabAccountConnection", "type": "object" }, "GitLabAgentTokenRequest": { "description": "A virtual employee's request for a git credential.\n\n`repository` is REQUIRED (`owner/repo`) — same bound-or-nothing rule as\nGitHub's agent token: the helper names what git is talking to, and Tidy\nrefuses to mint without it.", "properties": { "repository": { "title": "Repository", "type": "string" } }, "required": [ "repository" ], "title": "GitLabAgentTokenRequest", "type": "object" }, "GitLabAgentTokenResponse": { "description": "One per-op git-HTTPS credential. Never stored, never cached.", "properties": { "base_url": { "title": "Base Url", "type": "string" }, "expires_at": { "format": "date-time", "title": "Expires At", "type": "string" }, "token": { "title": "Token", "type": "string" }, "username": { "title": "Username", "type": "string" } }, "required": [ "username", "token", "expires_at", "base_url" ], "title": "GitLabAgentTokenResponse", "type": "object" }, "GitLabConnectionResponse": { "description": "The tenant's GitLab connection, as the settings card reads it.\n\nSame two-questions contract as GitHub's: `configured=False` means THIS\nDEPLOYMENT has no GitLab OAuth application (nothing the user can fix);\n`status` is the tenant's own connection state. A project-token connection\nworks even when `configured` is False — that distinction is WHY both are\nreported.", "properties": { "account_login": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Account Login" }, "auth_kind": { "anyOf": [ { "enum": [ "oauth", "project_token" ], "type": "string" }, { "type": "null" } ], "default": null, "title": "Auth Kind" }, "base_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Base Url" }, "configured": { "title": "Configured", "type": "boolean" }, "connection_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Connection Id" }, "connections": { "default": [], "items": { "$ref": "#/components/schemas/GitLabAccountConnection" }, "title": "Connections", "type": "array" }, "last_error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Last Error" }, "last_verified_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Last Verified At" }, "plugin_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Plugin Id" }, "status": { "enum": [ "not_configured", "not_connected", "pending", "working", "disconnected", "needs_reauth" ], "title": "Status", "type": "string" }, "webhook_secret_set": { "default": false, "title": "Webhook Secret Set", "type": "boolean" } }, "required": [ "configured", "status" ], "title": "GitLabConnectionResponse", "type": "object" }, "GitLabStartRequest": { "description": "Begin a connect flow.\n\n`mode='oauth'` creates the pending connection and returns the instance's\nauthorize URL (derived from `base_url` — self-managed included). The\nproject-token lane skips OAuth entirely and posts to `/token` instead.", "properties": { "base_url": { "default": "https://gitlab.com", "title": "Base Url", "type": "string" }, "desktop": { "default": false, "title": "Desktop", "type": "boolean" }, "mode": { "const": "oauth", "default": "oauth", "title": "Mode", "type": "string" }, "return_to": { "default": "/automations/plugins?connect=gitlab", "title": "Return To", "type": "string" } }, "title": "GitLabStartRequest", "type": "object" }, "GitLabStartResponse": { "description": "The authorize URL to redirect the browser to, with one-shot state.", "properties": { "authorize_url": { "title": "Authorize Url", "type": "string" }, "connection_id": { "title": "Connection Id", "type": "string" }, "state": { "title": "State", "type": "string" } }, "required": [ "authorize_url", "state", "connection_id" ], "title": "GitLabStartResponse", "type": "object" }, "GitLabTokenRequest": { "description": "Paste a project/group access token (the Advanced lane).\n\nThe token rides TLS-protected request body straight into the unified\nvault; it is never logged and never mirrored onto the connection row.", "properties": { "base_url": { "default": "https://gitlab.com", "title": "Base Url", "type": "string" }, "token": { "title": "Token", "type": "string" } }, "required": [ "token" ], "title": "GitLabTokenRequest", "type": "object" }, "GitLabTokenResponse": { "description": "Outcome of a live verification — honest, per TIDY-16297.", "properties": { "account_login": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Account Login" }, "connection_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Connection Id" }, "last_error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Last Error" }, "status": { "enum": [ "not_configured", "not_connected", "pending", "working", "disconnected", "needs_reauth" ], "title": "Status", "type": "string" } }, "required": [ "status" ], "title": "GitLabTokenResponse", "type": "object" }, "GitLabVerifyResponse": { "description": "Outcome of re-probing the instance live.", "properties": { "account_login": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Account Login" }, "connection_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Connection Id" }, "last_error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Last Error" }, "status": { "enum": [ "not_configured", "not_connected", "pending", "working", "disconnected", "needs_reauth" ], "title": "Status", "type": "string" } }, "required": [ "status" ], "title": "GitLabVerifyResponse", "type": "object" }, "GitLabWebhookSecretResponse": { "description": "A freshly rotated webhook secret. Shown EXACTLY once.", "properties": { "secret": { "title": "Secret", "type": "string" }, "webhook_url": { "title": "Webhook Url", "type": "string" } }, "required": [ "secret", "webhook_url" ], "title": "GitLabWebhookSecretResponse", "type": "object" }, "GlobalDefaultRequest": { "properties": { "beta_tenants": { "anyOf": [ { "items": { "format": "uuid", "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Beta Tenants" }, "default": { "enum": [ "on", "off", "unset" ], "title": "Default", "type": "string" } }, "required": [ "default" ], "title": "GlobalDefaultRequest", "type": "object" }, "GlobalDefaultResponse": { "properties": { "beta_tenants": { "items": { "type": "string" }, "title": "Beta Tenants", "type": "array" }, "default": { "enum": [ "on", "off", "unset" ], "title": "Default", "type": "string" }, "enablement": { "$ref": "#/components/schemas/SwitchEnablement" }, "key": { "title": "Key", "type": "string" } }, "required": [ "key", "default", "beta_tenants", "enablement" ], "title": "GlobalDefaultResponse", "type": "object" }, "GlobalSearchResponse": { "properties": { "excluded_encrypted": { "default": false, "title": "Excluded Encrypted", "type": "boolean" }, "expanded_query": { "title": "Expanded Query", "type": "string" }, "groups": { "$ref": "#/components/schemas/GroupedResults" }, "latency_ms": { "title": "Latency Ms", "type": "integer" }, "partial": { "default": false, "title": "Partial", "type": "boolean" }, "query_id": { "format": "uuid", "title": "Query Id", "type": "string" } }, "required": [ "query_id", "expanded_query", "latency_ms", "groups" ], "title": "GlobalSearchResponse", "type": "object" }, "GoalCreate": { "properties": { "assignee_agent_account_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Assign the objective to this virtual employee.", "title": "Assignee Agent Account Id" }, "description": { "anyOf": [ { "maxLength": 20000, "type": "string" }, { "type": "null" } ], "title": "Description" }, "horizon": { "default": "quarter", "description": "quarter | year | ongoing", "title": "Horizon", "type": "string" }, "human_owner_account_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The person accountable for the objective — the member's ACCOUNT id, the account_member reference id space.", "title": "Human Owner Account Id" }, "success_signal": { "anyOf": [ { "maxLength": 4000, "type": "string" }, { "type": "null" } ], "description": "Free text: how you will know this objective was met.", "title": "Success Signal" }, "title": { "maxLength": 200, "minLength": 1, "title": "Title", "type": "string" } }, "required": [ "title" ], "title": "GoalCreate", "type": "object" }, "GoalDetailResponse": { "properties": { "compliance": { "$ref": "#/components/schemas/ComplianceInfo" }, "contact_email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Contact Email" }, "contact_frequency": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Contact Frequency" }, "contact_id": { "title": "Contact Id", "type": "string" }, "contact_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Contact Name" }, "meeting_cadence": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Meeting Cadence" }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Notes" }, "record_id": { "title": "Record Id", "type": "string" }, "response_time_target_hours": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Response Time Target Hours" }, "timeline": { "items": { "$ref": "#/components/schemas/TimelinePeriod" }, "title": "Timeline", "type": "array" } }, "required": [ "record_id", "contact_id", "contact_name", "contact_email", "contact_frequency", "response_time_target_hours", "meeting_cadence", "notes", "compliance", "timeline" ], "title": "GoalDetailResponse", "type": "object" }, "GoalList": { "properties": { "enabled": { "title": "Enabled", "type": "boolean" }, "goals": { "items": { "additionalProperties": true, "type": "object" }, "title": "Goals", "type": "array" } }, "required": [ "goals", "enabled" ], "title": "GoalList", "type": "object" }, "GoalListItem": { "properties": { "compliance": { "$ref": "#/components/schemas/ComplianceInfo" }, "contact_email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Contact Email" }, "contact_frequency": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Contact Frequency" }, "contact_id": { "title": "Contact Id", "type": "string" }, "contact_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Contact Name" }, "meeting_cadence": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Meeting Cadence" }, "record_id": { "title": "Record Id", "type": "string" }, "response_time_target_hours": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Response Time Target Hours" } }, "required": [ "record_id", "contact_id", "contact_name", "contact_email", "contact_frequency", "response_time_target_hours", "meeting_cadence", "compliance" ], "title": "GoalListItem", "type": "object" }, "GoalReorder": { "properties": { "ordered_ids": { "description": "Objective ids in the order the human wants them.", "items": { "type": "string" }, "minItems": 1, "title": "Ordered Ids", "type": "array" } }, "required": [ "ordered_ids" ], "title": "GoalReorder", "type": "object" }, "GoalResponse": { "properties": { "goal": { "additionalProperties": true, "title": "Goal", "type": "object" } }, "required": [ "goal" ], "title": "GoalResponse", "type": "object" }, "GoalUpdate": { "properties": { "assignee_agent_account_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Assignee Agent Account Id" }, "clear_assignee": { "default": false, "title": "Clear Assignee", "type": "boolean" }, "description": { "anyOf": [ { "maxLength": 20000, "type": "string" }, { "type": "null" } ], "title": "Description" }, "horizon": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Horizon" }, "human_owner_account_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Empty string (\"\") clears the owner.", "title": "Human Owner Account Id" }, "status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "active | paused | achieved | abandoned", "title": "Status" }, "success_signal": { "anyOf": [ { "maxLength": 4000, "type": "string" }, { "type": "null" } ], "title": "Success Signal" }, "title": { "anyOf": [ { "maxLength": 200, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Title" } }, "title": "GoalUpdate", "type": "object" }, "GoogleConnectionStatus": { "description": "Per-Google-connection sync state for the Contacts Sync UI (TIDY-8379).", "properties": { "auth_method": { "default": "oauth", "title": "Auth Method", "type": "string" }, "contact_count": { "default": 0, "title": "Contact Count", "type": "integer" }, "email": { "title": "Email", "type": "string" }, "last_sync_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Sync At" }, "provider_connection_id": { "title": "Provider Connection Id", "type": "string" }, "scopes": { "items": { "type": "string" }, "title": "Scopes", "type": "array" }, "status": { "title": "Status", "type": "string" }, "sync_error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Sync Error" } }, "required": [ "provider_connection_id", "email", "status" ], "title": "GoogleConnectionStatus", "type": "object" }, "GoogleSyncResult": { "description": "Result of a Google contact sync operation.", "properties": { "created": { "default": 0, "title": "Created", "type": "integer" }, "errors": { "items": { "type": "string" }, "title": "Errors", "type": "array" }, "merged": { "default": 0, "title": "Merged", "type": "integer" }, "skipped": { "default": 0, "title": "Skipped", "type": "integer" }, "success": { "title": "Success", "type": "boolean" }, "total_fetched": { "default": 0, "title": "Total Fetched", "type": "integer" } }, "required": [ "success" ], "title": "GoogleSyncResult", "type": "object" }, "GpodderDeviceResponse": { "properties": { "caption": { "title": "Caption", "type": "string" }, "id": { "title": "Id", "type": "string" }, "subscriptions": { "title": "Subscriptions", "type": "integer" }, "type": { "enum": [ "desktop", "laptop", "mobile", "server", "other" ], "title": "Type", "type": "string" } }, "required": [ "id", "caption", "type", "subscriptions" ], "title": "GpodderDeviceResponse", "type": "object" }, "GpodderDeviceUpdateRequest": { "properties": { "caption": { "anyOf": [ { "maxLength": 200, "type": "string" }, { "type": "null" } ], "title": "Caption" }, "type": { "anyOf": [ { "enum": [ "desktop", "laptop", "mobile", "server", "other" ], "type": "string" }, { "type": "null" } ], "title": "Type" } }, "title": "GpodderDeviceUpdateRequest", "type": "object" }, "GpodderEpisodeActionOut": { "properties": { "action": { "enum": [ "new", "download", "play", "delete" ], "title": "Action", "type": "string" }, "device": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Device" }, "episode": { "title": "Episode", "type": "string" }, "guid": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Guid" }, "podcast": { "title": "Podcast", "type": "string" }, "position": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Position" }, "started": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Started" }, "timestamp": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Timestamp" }, "total": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Total" } }, "required": [ "podcast", "episode", "action" ], "title": "GpodderEpisodeActionOut", "type": "object" }, "GpodderEpisodesResponse": { "properties": { "actions": { "items": { "$ref": "#/components/schemas/GpodderEpisodeActionOut" }, "title": "Actions", "type": "array" }, "timestamp": { "title": "Timestamp", "type": "integer" } }, "required": [ "timestamp" ], "title": "GpodderEpisodesResponse", "type": "object" }, "GpodderSubscriptionChangesRequest": { "properties": { "add": { "items": { "type": "string" }, "title": "Add", "type": "array" }, "remove": { "items": { "type": "string" }, "title": "Remove", "type": "array" } }, "title": "GpodderSubscriptionChangesRequest", "type": "object" }, "GpodderSubscriptionsDeltaResponse": { "properties": { "add": { "items": { "type": "string" }, "title": "Add", "type": "array" }, "remove": { "items": { "type": "string" }, "title": "Remove", "type": "array" }, "timestamp": { "title": "Timestamp", "type": "integer" } }, "required": [ "timestamp" ], "title": "GpodderSubscriptionsDeltaResponse", "type": "object" }, "GpodderUpdatedUrlsResponse": { "properties": { "timestamp": { "title": "Timestamp", "type": "integer" }, "update_urls": { "items": { "items": { "type": "string" }, "type": "array" }, "title": "Update Urls", "type": "array" } }, "required": [ "timestamp" ], "title": "GpodderUpdatedUrlsResponse", "type": "object" }, "GrammarCheckRequest": { "description": "Request to check grammar and spelling via AI.", "properties": { "text": { "description": "Text to check", "maxLength": 50000, "minLength": 1, "title": "Text", "type": "string" } }, "required": [ "text" ], "title": "GrammarCheckRequest", "type": "object" }, "GrammarCheckResponse": { "description": "Response from AI grammar/spelling check.", "properties": { "corrected_text": { "description": "Full text with all corrections applied", "title": "Corrected Text", "type": "string" }, "corrections": { "description": "List of individual corrections made", "items": { "$ref": "#/components/schemas/GrammarCorrection" }, "title": "Corrections", "type": "array" }, "has_corrections": { "description": "Whether any corrections were found", "title": "Has Corrections", "type": "boolean" } }, "required": [ "corrected_text", "has_corrections" ], "title": "GrammarCheckResponse", "type": "object" }, "GrammarCorrection": { "description": "A single grammar/spelling correction.", "properties": { "corrected": { "description": "The corrected text segment", "title": "Corrected", "type": "string" }, "explanation": { "description": "Brief explanation of the correction", "title": "Explanation", "type": "string" }, "original": { "description": "The original text segment with the issue", "title": "Original", "type": "string" } }, "required": [ "original", "corrected", "explanation" ], "title": "GrammarCorrection", "type": "object" }, "GrantListResponse": { "properties": { "grants": { "items": { "$ref": "#/components/schemas/GrantResponse" }, "title": "Grants", "type": "array" } }, "required": [ "grants" ], "title": "GrantListResponse", "type": "object" }, "GrantResponse": { "properties": { "action": { "enum": [ "read", "read_write" ], "title": "Action", "type": "string" }, "container_ref": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "default": null, "title": "Container Ref" }, "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "created_by": { "format": "uuid", "title": "Created By", "type": "string" }, "delegatee_account_id": { "format": "uuid", "title": "Delegatee Account Id", "type": "string" }, "delegatee_member_type": { "enum": [ "human", "virtual_employee" ], "title": "Delegatee Member Type", "type": "string" }, "delegator_account_id": { "format": "uuid", "title": "Delegator Account Id", "type": "string" }, "expires_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Expires At" }, "facet_keys": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "default": null, "title": "Facet Keys" }, "granted_via": { "anyOf": [ { "const": "approval_routing", "type": "string" }, { "type": "null" } ], "default": null, "title": "Granted Via" }, "id": { "format": "uuid", "title": "Id", "type": "string" }, "last_used_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Last Used At" }, "resource_type": { "enum": [ "calendar", "notes", "projects", "contacts", "activities", "inbox", "photos", "podcasts", "files", "structure", "sessions", "records" ], "title": "Resource Type", "type": "string" }, "revoked_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Revoked At" }, "tenant_id": { "format": "uuid", "title": "Tenant Id", "type": "string" } }, "required": [ "id", "tenant_id", "delegator_account_id", "delegatee_account_id", "delegatee_member_type", "resource_type", "action", "created_by", "created_at" ], "title": "GrantResponse", "type": "object" }, "GraphFact": { "description": "A single fact about the contact entity sourced from the knowledge graph.", "properties": { "object": { "description": "Object entity / value the fact relates to.", "title": "Object", "type": "string" }, "observed_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Observed At" }, "predicate": { "description": "Natural-language verb phrase.", "title": "Predicate", "type": "string" }, "source_email_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "The email this fact was extracted from, when known.", "title": "Source Email Id" } }, "required": [ "predicate", "object" ], "title": "GraphFact", "type": "object" }, "GraphSyncSummary": { "description": "Most recent merge's graph-sync state (TIDY-8726).\n\nReplaces the bare ``graph_sync_status`` string so the UI receives the\ncorrect ``contact_merge_audit.id`` for the retry endpoint without\nfalling back to ``audit_log.id`` (which the retry endpoint rejects).", "properties": { "attempted_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "description": "merged_at of the most-recent merge row.", "title": "Attempted At" }, "merge_audit_id": { "description": "contact_merge_audit.id — the retry endpoint's path arg.", "title": "Merge Audit Id", "type": "string" }, "status": { "description": "Most-recent merge's graph_sync state.", "enum": [ "completed", "pending", "failed", "dead_letter", "skipped" ], "title": "Status", "type": "string" } }, "required": [ "status", "merge_audit_id" ], "title": "GraphSyncSummary", "type": "object" }, "GravatarRefreshResponse": { "description": "Response for the gravatar refresh trigger.", "properties": { "contact_ids": { "items": { "type": "string" }, "title": "Contact Ids", "type": "array" }, "message": { "title": "Message", "type": "string" }, "queued_count": { "title": "Queued Count", "type": "integer" }, "skipped_count": { "title": "Skipped Count", "type": "integer" }, "updated": { "title": "Updated", "type": "integer" } }, "required": [ "queued_count", "skipped_count", "updated", "message" ], "title": "GravatarRefreshResponse", "type": "object" }, "GroupCreate": { "properties": { "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "name": { "title": "Name", "type": "string" }, "visibility": { "default": "private", "description": "Private to you unless shared with the workspace.", "enum": [ "private", "shared" ], "title": "Visibility", "type": "string" } }, "required": [ "name" ], "title": "GroupCreate", "type": "object" }, "GroupEmailRecipient": { "properties": { "email": { "title": "Email", "type": "string" }, "kind": { "default": "contact", "enum": [ "contact", "organization" ], "title": "Kind", "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name" }, "source": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Source" } }, "required": [ "email" ], "title": "GroupEmailRecipient", "type": "object" }, "GroupEmailsResponse": { "properties": { "group_name": { "title": "Group Name", "type": "string" }, "recipients": { "items": { "$ref": "#/components/schemas/GroupEmailRecipient" }, "title": "Recipients", "type": "array" }, "unaddressable": { "default": [], "items": { "$ref": "#/components/schemas/UnaddressableMember" }, "title": "Unaddressable", "type": "array" } }, "required": [ "group_name", "recipients" ], "title": "GroupEmailsResponse", "type": "object" }, "GroupListResponse": { "properties": { "groups": { "items": { "$ref": "#/components/schemas/GroupResponse" }, "title": "Groups", "type": "array" } }, "required": [ "groups" ], "title": "GroupListResponse", "type": "object" }, "GroupMemberAdd": { "properties": { "contact_ids": { "default": [], "items": { "type": "string" }, "title": "Contact Ids", "type": "array" }, "organization_ids": { "default": [], "items": { "type": "string" }, "title": "Organization Ids", "type": "array" } }, "title": "GroupMemberAdd", "type": "object" }, "GroupMemberResponse": { "properties": { "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Email" }, "id": { "format": "uuid", "title": "Id", "type": "string" }, "kind": { "default": "contact", "enum": [ "contact", "organization" ], "title": "Kind", "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name" }, "photo_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Photo Url" } }, "required": [ "id" ], "title": "GroupMemberResponse", "type": "object" }, "GroupResponse": { "properties": { "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Description" }, "group_type": { "title": "Group Type", "type": "string" }, "id": { "format": "uuid", "title": "Id", "type": "string" }, "member_count": { "default": 0, "title": "Member Count", "type": "integer" }, "members": { "anyOf": [ { "items": { "$ref": "#/components/schemas/GroupMemberResponse" }, "type": "array" }, { "type": "null" } ], "default": null, "title": "Members" }, "name": { "title": "Name", "type": "string" }, "updated_at": { "format": "date-time", "title": "Updated At", "type": "string" }, "visibility": { "default": "private", "enum": [ "private", "shared" ], "title": "Visibility", "type": "string" } }, "required": [ "id", "name", "group_type", "created_at", "updated_at" ], "title": "GroupResponse", "type": "object" }, "GroupUpdate": { "properties": { "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name" }, "team_wear": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Team Wear" }, "visibility": { "anyOf": [ { "enum": [ "private", "shared" ], "type": "string" }, { "type": "null" } ], "description": "Who sees the group. Only its creator can change this.", "title": "Visibility" } }, "title": "GroupUpdate", "type": "object" }, "GroupedResults": { "properties": { "channels": { "items": { "$ref": "#/components/schemas/ChannelResult" }, "title": "Channels", "type": "array" }, "embeds": { "items": { "$ref": "#/components/schemas/EmbedResult" }, "title": "Embeds", "type": "array" }, "files": { "items": { "$ref": "#/components/schemas/FileResult" }, "title": "Files", "type": "array" }, "messages": { "items": { "$ref": "#/components/schemas/MessageResult" }, "title": "Messages", "type": "array" }, "people": { "items": { "$ref": "#/components/schemas/PersonResult" }, "title": "People", "type": "array" } }, "title": "GroupedResults", "type": "object" }, "GuestActivityResponse": { "properties": { "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Next Cursor" }, "rows": { "items": { "$ref": "#/components/schemas/GuestActivityRow" }, "title": "Rows", "type": "array" } }, "required": [ "rows" ], "title": "GuestActivityResponse", "type": "object" }, "GuestActivityRow": { "properties": { "action": { "title": "Action", "type": "string" }, "audit_id": { "title": "Audit Id", "type": "string" }, "expires_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Expires At" }, "guest_account_id": { "title": "Guest Account Id", "type": "string" }, "invited_email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Invited Email" }, "occurred_at": { "format": "date-time", "title": "Occurred At", "type": "string" }, "payload": { "additionalProperties": true, "title": "Payload", "type": "object" }, "revoked_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Revoked At" }, "scoped_room_ids": { "items": { "type": "string" }, "title": "Scoped Room Ids", "type": "array" }, "seq": { "title": "Seq", "type": "integer" } }, "required": [ "audit_id", "seq", "guest_account_id", "action", "occurred_at" ], "title": "GuestActivityRow", "type": "object" }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "title": "Detail", "type": "array" } }, "title": "HTTPValidationError", "type": "object" }, "HabitLogRequest": { "properties": { "duration_seconds": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Duration Seconds" }, "event_type": { "enum": [ "inbox_open", "session_end", "email_action" ], "title": "Event Type", "type": "string" } }, "required": [ "event_type" ], "title": "HabitLogRequest", "type": "object" }, "HabitLogResponse": { "properties": { "ok": { "title": "Ok", "type": "boolean" } }, "required": [ "ok" ], "title": "HabitLogResponse", "type": "object" }, "HandedReferenceIn": { "description": "One reference a message carried, as the message showed it.", "properties": { "id": { "description": "The typed id the message cited (`SK-`).", "title": "Id", "type": "string" }, "label": { "description": "The title the message showed for it — the sender's, not the item's.", "maxLength": 300, "minLength": 1, "title": "Label", "type": "string" } }, "required": [ "id", "label" ], "title": "HandedReferenceIn", "type": "object" }, "HandedReferenceResponse": { "description": "A reference as the caller was handed it — nothing read from the item.", "properties": { "handed_by": { "description": "Who sent it: the person to ask for access.", "title": "Handed By", "type": "string" }, "id": { "description": "The typed id, exactly as asked for.", "title": "Id", "type": "string" }, "label": { "description": "The title the message showed.", "title": "Label", "type": "string" }, "primitive": { "description": "Canonical primitive type (`skill`, `note`, …).", "title": "Primitive", "type": "string" } }, "required": [ "id", "primitive", "label", "handed_by" ], "title": "HandedReferenceResponse", "type": "object" }, "HandedReferencesRequest": { "description": "The references one connector turn was handed (TIDY-19452).", "properties": { "credential_id": { "description": "The turn credential this runtime minted for the turn that carried them.", "format": "uuid", "title": "Credential Id", "type": "string" }, "references": { "items": { "$ref": "#/components/schemas/HandedReferenceIn" }, "maxItems": 32, "minItems": 1, "title": "References", "type": "array" } }, "required": [ "credential_id", "references" ], "title": "HandedReferencesRequest", "type": "object" }, "HandedReferencesResponse": { "properties": { "recorded": { "title": "Recorded", "type": "integer" } }, "required": [ "recorded" ], "title": "HandedReferencesResponse", "type": "object" }, "HandoffRequest": { "properties": { "boot_id": { "format": "uuid", "title": "Boot Id", "type": "string" }, "generation": { "minimum": 1.0, "title": "Generation", "type": "integer" }, "installation_id": { "format": "uuid", "title": "Installation Id", "type": "string" }, "request_id": { "format": "uuid", "title": "Request Id", "type": "string" }, "target_boot_id": { "format": "uuid", "title": "Target Boot Id", "type": "string" } }, "required": [ "installation_id", "boot_id", "generation", "target_boot_id", "request_id" ], "title": "HandoffRequest", "type": "object" }, "HandoffResponse": { "properties": { "expires_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Expires At" }, "generation": { "title": "Generation", "type": "integer" }, "handoff_token": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Handoff Token" }, "matrix_access_token": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Matrix Access Token" }, "matrix_device_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Matrix Device Id" }, "status": { "title": "Status", "type": "string" } }, "required": [ "status", "generation" ], "title": "HandoffResponse", "type": "object" }, "HandoffStatusRequest": { "properties": { "installation_id": { "format": "uuid", "title": "Installation Id", "type": "string" }, "request_id": { "format": "uuid", "title": "Request Id", "type": "string" }, "target_boot_id": { "format": "uuid", "title": "Target Boot Id", "type": "string" } }, "required": [ "installation_id", "target_boot_id", "request_id" ], "title": "HandoffStatusRequest", "type": "object" }, "HandoffTokenRequest": { "properties": { "handoff_token": { "maxLength": 512, "minLength": 32, "title": "Handoff Token", "type": "string" }, "installation_id": { "format": "uuid", "title": "Installation Id", "type": "string" }, "prior_boot_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Prior Boot Id" }, "request_id": { "format": "uuid", "title": "Request Id", "type": "string" }, "target_boot_id": { "format": "uuid", "title": "Target Boot Id", "type": "string" } }, "required": [ "installation_id", "target_boot_id", "request_id", "handoff_token" ], "title": "HandoffTokenRequest", "type": "object" }, "HarnessAccountJobResponse": { "properties": { "created_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Created At" }, "job_id": { "format": "uuid", "title": "Job Id", "type": "string" }, "state": { "title": "State", "type": "string" }, "verb": { "title": "Verb", "type": "string" } }, "required": [ "job_id", "verb", "state" ], "title": "HarnessAccountJobResponse", "type": "object" }, "HarnessAccountReadiness": { "description": "TIDY-19928 (F4) — one stored account's sign-in and its evidence.", "properties": { "active": { "title": "Active", "type": "boolean" }, "check_status": { "anyOf": [ { "enum": [ "verified", "rejected", "unavailable", "unsupported" ], "type": "string" }, { "type": "null" } ], "default": null, "title": "Check Status" }, "checked_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Checked At" }, "label": { "title": "Label", "type": "string" }, "last_good_turn_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Last Good Turn At" }, "method": { "title": "Method", "type": "string" }, "profile_id": { "title": "Profile Id", "type": "string" }, "proven_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Proven At" }, "reading": { "enum": [ "verified", "working", "signed_in", "limited", "rejected", "signed_out", "not_checked", "check_unavailable" ], "title": "Reading", "type": "string" }, "state": { "enum": [ "ok", "fail", "unknown" ], "title": "State", "type": "string" } }, "required": [ "profile_id", "label", "method", "active", "state", "reading" ], "title": "HarnessAccountReadiness", "type": "object" }, "HarnessAccountRemediesResponse": { "description": "The server-computed remedy contract for ONE harness account row\n(TIDY-18906, P14). Clients render only `eligible` rows.", "properties": { "account_label": { "title": "Account Label", "type": "string" }, "is_active": { "title": "Is Active", "type": "boolean" }, "profile_id": { "title": "Profile Id", "type": "string" }, "remedies": { "items": { "additionalProperties": true, "type": "object" }, "title": "Remedies", "type": "array" }, "runtime": { "title": "Runtime", "type": "string" }, "state": { "title": "State", "type": "string" } }, "required": [ "runtime", "profile_id", "account_label", "state", "is_active" ], "title": "HarnessAccountRemediesResponse", "type": "object" }, "HarnessAccountReport": { "additionalProperties": false, "properties": { "active": { "title": "Active", "type": "boolean" }, "identity": { "anyOf": [ { "$ref": "#/components/schemas/AccountIdentity" }, { "type": "null" } ] }, "label": { "maxLength": 260, "minLength": 1, "title": "Label", "type": "string" }, "method": { "enum": [ "subscription", "api_key", "bedrock", "vertex", "existing", "tidy_inference" ], "title": "Method", "type": "string" }, "profile_id": { "maxLength": 38, "pattern": "^p-[0-9a-f-]{36}$", "title": "Profile Id", "type": "string" }, "state": { "enum": [ "authenticated", "absent", "expired", "rate_limited", "unknown", "unreadable" ], "title": "State", "type": "string" } }, "required": [ "profile_id", "method", "label", "active", "state" ], "title": "HarnessAccountReport", "type": "object" }, "HarnessAccountSessionSummary": { "description": "One conversation bound to a harness account (P15/F8) — the row the\nemployee-scoped remedies section offers its per-session switch on.", "properties": { "bound_via": { "enum": [ "harness_session", "requested" ], "title": "Bound Via", "type": "string" }, "conversation_id": { "format": "uuid", "title": "Conversation Id", "type": "string" }, "last_active_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Last Active At" }, "matrix_room_id": { "title": "Matrix Room Id", "type": "string" }, "status": { "title": "Status", "type": "string" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Title" } }, "required": [ "conversation_id", "matrix_room_id", "status", "bound_via" ], "title": "HarnessAccountSessionSummary", "type": "object" }, "HarnessAccountSessionsResponse": { "properties": { "profile_id": { "title": "Profile Id", "type": "string" }, "runtime": { "title": "Runtime", "type": "string" }, "sessions": { "items": { "$ref": "#/components/schemas/HarnessAccountSessionSummary" }, "title": "Sessions", "type": "array" } }, "required": [ "runtime", "profile_id" ], "title": "HarnessAccountSessionsResponse", "type": "object" }, "HarnessCapabilityModel": { "properties": { "id": { "title": "Id", "type": "string" }, "label": { "title": "Label", "type": "string" } }, "required": [ "id", "label" ], "title": "HarnessCapabilityModel", "type": "object" }, "HarnessCatalogModel": { "description": "TIDY-20125 F2 — one model of a harness's catalog as its conversations'\nmodel picker shows it: the harness's own token, what it runs, its name.", "properties": { "context_limit_tokens": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Context Limit Tokens" }, "id": { "title": "Id", "type": "string" }, "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Label" }, "model_id": { "title": "Model Id", "type": "string" }, "provider_id": { "title": "Provider Id", "type": "string" }, "provider_label": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Provider Label" }, "reasoning_levels": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "default": null, "title": "Reasoning Levels" } }, "required": [ "id", "provider_id", "model_id" ], "title": "HarnessCatalogModel", "type": "object" }, "HarnessCompaction": { "properties": { "automatic": { "title": "Automatic", "type": "boolean" }, "on_request": { "title": "On Request", "type": "boolean" } }, "required": [ "automatic", "on_request" ], "title": "HarnessCompaction", "type": "object" }, "HarnessCredentialAssignment": { "properties": { "base_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Base Url" }, "credential_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Credential Id" }, "env_key": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Env Key" }, "method": { "enum": [ "api_key", "oauth", "native_box_login", "tidy_inference" ], "title": "Method", "type": "string" }, "name": { "title": "Name", "type": "string" }, "native_connection_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Native Connection Id" }, "native_provider_slug": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Native Provider Slug" }, "runtime": { "title": "Runtime", "type": "string" }, "status": { "title": "Status", "type": "string" } }, "required": [ "runtime", "method", "name", "status" ], "title": "HarnessCredentialAssignment", "type": "object" }, "HarnessCredentialAssignments": { "properties": { "assignments": { "items": { "$ref": "#/components/schemas/HarnessCredentialAssignment" }, "title": "Assignments", "type": "array" }, "method_env_keys": { "additionalProperties": { "additionalProperties": { "items": { "type": "string" }, "type": "array" }, "type": "object" }, "title": "Method Env Keys", "type": "object" }, "source_capacity": { "additionalProperties": { "$ref": "#/components/schemas/HarnessSourceCapacity" }, "title": "Source Capacity", "type": "object" }, "sources": { "additionalProperties": { "items": { "$ref": "#/components/schemas/HarnessModelSource" }, "type": "array" }, "title": "Sources", "type": "object" }, "supported_env_keys": { "additionalProperties": { "items": { "type": "string" }, "type": "array" }, "title": "Supported Env Keys", "type": "object" }, "supported_methods": { "additionalProperties": { "items": { "type": "string" }, "type": "array" }, "title": "Supported Methods", "type": "object" } }, "title": "HarnessCredentialAssignments", "type": "object" }, "HarnessCredentialMethod": { "properties": { "copy": { "title": "Copy", "type": "string" }, "env_keys": { "items": { "type": "string" }, "title": "Env Keys", "type": "array" }, "label": { "title": "Label", "type": "string" }, "method": { "enum": [ "api_key", "oauth", "native_box_login", "tidy_inference" ], "title": "Method", "type": "string" }, "native_connections": { "items": { "$ref": "#/components/schemas/NativeHarnessConnection" }, "title": "Native Connections", "type": "array" }, "value_label": { "title": "Value Label", "type": "string" } }, "required": [ "method", "label", "copy", "value_label", "env_keys", "native_connections" ], "title": "HarnessCredentialMethod", "type": "object" }, "HarnessCredentialMethods": { "properties": { "methods": { "items": { "$ref": "#/components/schemas/HarnessCredentialMethod" }, "title": "Methods", "type": "array" } }, "required": [ "methods" ], "title": "HarnessCredentialMethods", "type": "object" }, "HarnessCredentialsSet": { "properties": { "credential_ids": { "items": { "format": "uuid", "type": "string" }, "maxItems": 8, "title": "Credential Ids", "type": "array" }, "method": { "default": "api_key", "enum": [ "api_key", "oauth", "native_box_login", "tidy_inference" ], "title": "Method", "type": "string" }, "models": { "anyOf": [ { "items": { "type": "string" }, "maxItems": 8, "type": "array" }, { "type": "null" } ], "title": "Models" }, "native_connection_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Native Connection Id" }, "reasoning_level": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Reasoning Level" }, "sign_in_method": { "anyOf": [ { "enum": [ "subscription", "bedrock", "vertex" ], "type": "string" }, { "type": "null" } ], "title": "Sign In Method" } }, "title": "HarnessCredentialsSet", "type": "object" }, "HarnessExecutionReceipt": { "properties": { "expires_at": { "format": "date-time", "title": "Expires At", "type": "string" }, "funding": { "enum": [ "platform", "tidy", "byo" ], "title": "Funding", "type": "string" }, "id": { "format": "uuid", "title": "Id", "type": "string" }, "model": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Model" }, "route": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Route" } }, "required": [ "id", "model", "funding", "route", "expires_at" ], "title": "HarnessExecutionReceipt", "type": "object" }, "HarnessExecutionRequest": { "additionalProperties": false, "properties": { "conversation_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Conversation Id" }, "health_job_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Health Job Id" }, "kind": { "enum": [ "health", "turn" ], "title": "Kind", "type": "string" }, "phase": { "anyOf": [ { "enum": [ "auth", "hello" ], "type": "string" }, { "type": "null" } ], "title": "Phase" }, "runtime": { "maxLength": 64, "minLength": 1, "title": "Runtime", "type": "string" }, "turn_ref": { "anyOf": [ { "maxLength": 512, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Turn Ref" } }, "required": [ "kind", "runtime" ], "title": "HarnessExecutionRequest", "type": "object" }, "HarnessFramesExportRequest": { "properties": { "capture_hours": { "anyOf": [ { "maximum": 168.0, "minimum": 1.0, "type": "integer" }, { "type": "null" } ], "description": "Also record the conversation's next turns for this long (the box caps it at a week).", "title": "Capture Hours" } }, "title": "HarnessFramesExportRequest", "type": "object" }, "HarnessHolder": { "properties": { "id": { "title": "Id", "type": "string" }, "kind": { "enum": [ "employee", "conversation" ], "title": "Kind", "type": "string" }, "name": { "title": "Name", "type": "string" } }, "required": [ "kind", "id", "name" ], "title": "HarnessHolder", "type": "object" }, "HarnessMaterializeRequest": { "properties": { "execution_context": { "anyOf": [ { "$ref": "#/components/schemas/HarnessExecutionRequest" }, { "type": "null" } ] }, "health_job_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Health Job Id" }, "runtime": { "maxLength": 64, "minLength": 1, "title": "Runtime", "type": "string" }, "session_ref": { "anyOf": [ { "maxLength": 256, "type": "string" }, { "type": "null" } ], "title": "Session Ref" } }, "required": [ "runtime" ], "title": "HarnessMaterializeRequest", "type": "object" }, "HarnessMaterializeResponse": { "properties": { "catalog_sources": { "items": { "$ref": "#/components/schemas/CatalogSource" }, "title": "Catalog Sources", "type": "array" }, "credentials": { "items": { "$ref": "#/components/schemas/MaterializedCredential" }, "title": "Credentials", "type": "array" }, "execution": { "anyOf": [ { "$ref": "#/components/schemas/HarnessExecutionReceipt" }, { "type": "null" } ], "default": null }, "method": { "anyOf": [ { "enum": [ "api_key", "oauth", "native_box_login", "tidy_inference" ], "type": "string" }, { "type": "null" } ], "default": null, "title": "Method" }, "runtime": { "title": "Runtime", "type": "string" } }, "required": [ "runtime" ], "title": "HarnessMaterializeResponse", "type": "object" }, "HarnessModelCatalogEntryReport": { "description": "TIDY-19215 — one model of a harness's own catalog (the connector's\n`HarnessModelCatalogEntryWireV1`). `id` is the exact token the harness is\nhanded back; `model_id` what it resolves to; `label` its display name.", "properties": { "auth_method": { "anyOf": [ { "enum": [ "oauth", "api_key" ], "type": "string" }, { "type": "null" } ], "title": "Auth Method" }, "context_limit_tokens": { "anyOf": [ { "minimum": 1.0, "type": "integer" }, { "type": "null" } ], "title": "Context Limit Tokens" }, "id": { "maxLength": 255, "minLength": 1, "title": "Id", "type": "string" }, "label": { "anyOf": [ { "maxLength": 255, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Label" }, "model_id": { "maxLength": 255, "minLength": 1, "title": "Model Id", "type": "string" }, "provider_id": { "maxLength": 128, "minLength": 1, "title": "Provider Id", "type": "string" }, "provider_label": { "anyOf": [ { "maxLength": 255, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Provider Label" }, "reasoning_levels": { "anyOf": [ { "items": { "enum": [ "off", "minimal", "low", "medium", "high", "xhigh", "max" ], "type": "string" }, "maxItems": 7, "minItems": 1, "type": "array" }, { "type": "null" } ], "title": "Reasoning Levels" } }, "required": [ "id", "provider_id", "model_id" ], "title": "HarnessModelCatalogEntryReport", "type": "object" }, "HarnessModelListingResponse": { "description": "TIDY-19825 — the workshop check that lists a harness's models.", "properties": { "job_id": { "format": "uuid", "title": "Job Id", "type": "string" }, "state": { "title": "State", "type": "string" }, "workshop_id": { "format": "uuid", "title": "Workshop Id", "type": "string" } }, "required": [ "job_id", "workshop_id", "state" ], "title": "HarnessModelListingResponse", "type": "object" }, "HarnessModelOptionDescriptorsReport": { "description": "TIDY-19594 — the option groups one catalog model declares.", "properties": { "groups": { "items": { "$ref": "#/components/schemas/HarnessOptionGroupReport" }, "maxItems": 16, "minItems": 1, "title": "Groups", "type": "array" }, "model": { "maxLength": 255, "minLength": 1, "pattern": ".*\\S.*", "title": "Model", "type": "string" } }, "required": [ "model", "groups" ], "title": "HarnessModelOptionDescriptorsReport", "type": "object" }, "HarnessModelOwner": { "description": "TIDY-19616 — the source in a harness's set that owns one model.", "properties": { "credential_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Credential Id" }, "kind": { "enum": [ "tidy", "plugin", "own_sign_in" ], "title": "Kind", "type": "string" }, "label": { "title": "Label", "type": "string" } }, "required": [ "kind", "label" ], "title": "HarnessModelOwner", "type": "object" }, "HarnessModelSource": { "description": "TIDY-19616 — one source in a harness's set.\n\n``kind``: ``tidy`` (Tidy inference), ``plugin`` (a provider plugin's key,\nwhose models are ``namespace/…``), or ``own_sign_in`` (the harness's own\nsign-in on its workshop).", "properties": { "credential_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Credential Id" }, "endpoint_workshop_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Endpoint Workshop Id" }, "kind": { "enum": [ "tidy", "plugin", "own_sign_in" ], "title": "Kind", "type": "string" }, "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Label" }, "namespace": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Namespace" }, "native_connection_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Native Connection Id" }, "sign_in_method": { "anyOf": [ { "enum": [ "subscription", "bedrock", "vertex" ], "type": "string" }, { "type": "null" } ], "default": null, "title": "Sign In Method" }, "status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Status" } }, "required": [ "kind" ], "title": "HarnessModelSource", "type": "object" }, "HarnessModelSourceChoice": { "additionalProperties": false, "description": "TIDY-19616 — one source a member puts in a harness's set.", "properties": { "credential_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Credential Id" }, "kind": { "enum": [ "tidy", "plugin", "own_sign_in" ], "title": "Kind", "type": "string" }, "native_connection_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Native Connection Id" }, "sign_in_method": { "anyOf": [ { "enum": [ "subscription", "bedrock", "vertex" ], "type": "string" }, { "type": "null" } ], "title": "Sign In Method" } }, "required": [ "kind" ], "title": "HarnessModelSourceChoice", "type": "object" }, "HarnessModelSourcesSet": { "additionalProperties": false, "description": "TIDY-19616 — replace a harness's whole source set, and (optionally) its\nmodels in the same transaction, as ``HarnessCredentialsSet`` does for one.", "properties": { "models": { "anyOf": [ { "items": { "type": "string" }, "maxItems": 8, "type": "array" }, { "type": "null" } ], "title": "Models" }, "reasoning_level": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Reasoning Level" }, "sources": { "description": "Up to 24 plugins, beside Tidy and the harness's own sign-in.", "items": { "$ref": "#/components/schemas/HarnessModelSourceChoice" }, "maxItems": 26, "title": "Sources", "type": "array" } }, "required": [ "sources" ], "title": "HarnessModelSourcesSet", "type": "object" }, "HarnessOptionChoiceReport": { "description": "TIDY-19594 — one choice of a declared option group (the connector's\n`ModelOptionDescriptorsWireV1` option; runtime-session-v1 schema).", "properties": { "id": { "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]*$", "title": "Id", "type": "string" }, "label": { "maxLength": 255, "minLength": 1, "pattern": ".*\\S.*", "title": "Label", "type": "string" }, "prompt_injected": { "title": "Prompt Injected", "type": "boolean" } }, "required": [ "id", "label", "prompt_injected" ], "title": "HarnessOptionChoiceReport", "type": "object" }, "HarnessOptionGroupReport": { "description": "TIDY-19594 — one per-model knob (`thinking`, `effort`, …).", "properties": { "default": { "anyOf": [ { "type": "string" }, { "type": "boolean" } ], "title": "Default" }, "id": { "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]*$", "title": "Id", "type": "string" }, "kind": { "enum": [ "select", "boolean" ], "title": "Kind", "type": "string" }, "label": { "maxLength": 255, "minLength": 1, "pattern": ".*\\S.*", "title": "Label", "type": "string" }, "options": { "anyOf": [ { "items": { "$ref": "#/components/schemas/HarnessOptionChoiceReport" }, "maxItems": 32, "minItems": 1, "type": "array" }, { "type": "null" } ], "title": "Options" } }, "required": [ "id", "kind", "label", "default" ], "title": "HarnessOptionGroupReport", "type": "object" }, "HarnessOwnSignInsReport": { "description": "TIDY-19709 — the providers a harness holds its OWN sign-in for on the\nbox (pi's `auth.json` keys, never a credential), and a generation the\nconnector bumps each time that store gains a provider. Persisted on the box,\nso a restart or a connector update reports the generation it had.", "properties": { "generation": { "maximum": 9007199254740991.0, "minimum": 0.0, "title": "Generation", "type": "integer" }, "job_id": { "anyOf": [ { "maxLength": 128, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Job Id" }, "observed_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Observed At" }, "providers": { "items": { "maxLength": 128, "minLength": 1, "type": "string" }, "maxItems": 64, "title": "Providers", "type": "array" }, "reported_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Reported At" } }, "required": [ "providers", "generation" ], "title": "HarnessOwnSignInsReport", "type": "object" }, "HarnessReadiness": { "description": "TIDY-19928 (F4) — Installed, Version supported, Signed in, Models, in\nthat order, and the first failing plane's one remedy.", "properties": { "accounts": { "items": { "$ref": "#/components/schemas/HarnessAccountReadiness" }, "title": "Accounts", "type": "array" }, "can_verify_sign_in": { "default": false, "title": "Can Verify Sign In", "type": "boolean" }, "first_failing": { "anyOf": [ { "enum": [ "installed", "version", "signed_in", "models" ], "type": "string" }, { "type": "null" } ], "default": null, "title": "First Failing" }, "planes": { "items": { "$ref": "#/components/schemas/HarnessReadinessPlane" }, "title": "Planes", "type": "array" }, "remedy": { "anyOf": [ { "enum": [ "install", "update", "sign_in", "refresh_models" ], "type": "string" }, { "type": "null" } ], "default": null, "title": "Remedy" }, "shared_sign_in": { "items": { "$ref": "#/components/schemas/HarnessSharedSignIn" }, "title": "Shared Sign In", "type": "array" } }, "required": [ "planes" ], "title": "HarnessReadiness", "type": "object" }, "HarnessReadinessPlane": { "description": "TIDY-19928 (F4) — one plane of a harness's readiness. ``unknown`` is no\nevidence either way and is never a failure.", "properties": { "count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Count" }, "detail": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Detail" }, "minimum": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Minimum" }, "plane": { "enum": [ "installed", "version", "signed_in", "models" ], "title": "Plane", "type": "string" }, "profile_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Profile Id" }, "reading": { "title": "Reading", "type": "string" }, "state": { "enum": [ "ok", "warn", "fail", "unknown" ], "title": "State", "type": "string" }, "version": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Version" } }, "required": [ "plane", "state", "reading" ], "title": "HarnessReadinessPlane", "type": "object" }, "HarnessSettingRow": { "description": "TIDY-20086 F8 — one of a harness's own settings for this employee.", "properties": { "description": { "title": "Description", "type": "string" }, "enable_warning": { "title": "Enable Warning", "type": "string" }, "enabled": { "title": "Enabled", "type": "boolean" }, "key": { "title": "Key", "type": "string" }, "label": { "title": "Label", "type": "string" } }, "required": [ "key", "label", "description", "enable_warning", "enabled" ], "title": "HarnessSettingRow", "type": "object" }, "HarnessSettingsResponse": { "properties": { "runtime": { "title": "Runtime", "type": "string" }, "settings": { "items": { "$ref": "#/components/schemas/HarnessSettingRow" }, "title": "Settings", "type": "array" } }, "required": [ "runtime" ], "title": "HarnessSettingsResponse", "type": "object" }, "HarnessSettingsUpdate": { "additionalProperties": false, "description": "TIDY-20086 F8 — settings to turn on or off, by key; others are left as they are.", "properties": { "settings": { "additionalProperties": { "type": "boolean" }, "title": "Settings", "type": "object" } }, "required": [ "settings" ], "title": "HarnessSettingsUpdate", "type": "object" }, "HarnessSharedSignIn": { "description": "TIDY-19929 (F5) — another employee on the same workshop whose harness\nruns on the very same sign-in (one store on the machine).", "properties": { "account_id": { "title": "Account Id", "type": "string" }, "name": { "title": "Name", "type": "string" } }, "required": [ "account_id", "name" ], "title": "HarnessSharedSignIn", "type": "object" }, "HarnessSignInCheckReport": { "additionalProperties": false, "description": "TIDY-19928 (F4) — the last sign-in check the member asked for.", "properties": { "checked_at": { "format": "date-time", "title": "Checked At", "type": "string" }, "proven_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Proven At" }, "status": { "enum": [ "verified", "rejected", "unavailable", "unsupported" ], "title": "Status", "type": "string" } }, "required": [ "status", "checked_at" ], "title": "HarnessSignInCheckReport", "type": "object" }, "HarnessSignInEvidenceReport": { "additionalProperties": false, "description": "TIDY-19928 (F4) — one stored account's sign-in evidence, keyed by its\nprofile id on the harness entry. A credential's presence is neither.", "properties": { "check": { "anyOf": [ { "$ref": "#/components/schemas/HarnessSignInCheckReport" }, { "type": "null" } ] }, "last_good_turn_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Last Good Turn At" } }, "title": "HarnessSignInEvidenceReport", "type": "object" }, "HarnessSourceCapacity": { "description": "How many sources a harness can hold, and the sentence that says so.", "properties": { "mode": { "enum": [ "set", "tidy_plus_one", "one" ], "title": "Mode", "type": "string" }, "sentence": { "title": "Sentence", "type": "string" } }, "required": [ "mode", "sentence" ], "title": "HarnessSourceCapacity", "type": "object" }, "HarnessUpdateRequiredModel": { "description": "TIDY-19926 F2 — a model a newer release of this harness would bring.\n\nThe workshop's harness lists only the models its installed release knows;\nthis is one it does not, with the release that lists it and the sentence\nthe model picker shows instead of the row being absent.", "properties": { "label": { "title": "Label", "type": "string" }, "minimum": { "title": "Minimum", "type": "string" }, "model": { "title": "Model", "type": "string" }, "reason": { "enum": [ "update", "unsupported_harness" ], "title": "Reason", "type": "string" }, "sentence": { "title": "Sentence", "type": "string" } }, "required": [ "model", "label", "minimum", "reason", "sentence" ], "title": "HarnessUpdateRequiredModel", "type": "object" }, "HarnessUsageRefresh": { "additionalProperties": false, "properties": { "profile_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Profile Id" }, "requested_at": { "format": "date-time", "title": "Requested At", "type": "string" }, "runtime": { "title": "Runtime", "type": "string" }, "verb": { "const": "harness.usage.refresh", "default": "harness.usage.refresh", "title": "Verb", "type": "string" } }, "required": [ "runtime", "requested_at" ], "title": "HarnessUsageRefresh", "type": "object" }, "HarnessUsageRefreshResponse": { "properties": { "requested_at": { "format": "date-time", "title": "Requested At", "type": "string" } }, "required": [ "requested_at" ], "title": "HarnessUsageRefreshResponse", "type": "object" }, "HarnessUsageRequest": { "additionalProperties": false, "properties": { "cache_read_tokens": { "default": 0, "maximum": 1000000000.0, "minimum": 0.0, "title": "Cache Read Tokens", "type": "integer" }, "conversation_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Conversation Id" }, "duration_ms": { "default": 0, "maximum": 86400000.0, "minimum": 0.0, "title": "Duration Ms", "type": "integer" }, "execution_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Execution Id" }, "health_job_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Health Job Id" }, "input_tokens": { "maximum": 1000000000.0, "minimum": 0.0, "title": "Input Tokens", "type": "integer" }, "kind": { "enum": [ "health", "turn" ], "title": "Kind", "type": "string" }, "model": { "maxLength": 256, "minLength": 1, "title": "Model", "type": "string" }, "output_tokens": { "maximum": 1000000000.0, "minimum": 0.0, "title": "Output Tokens", "type": "integer" }, "phase": { "anyOf": [ { "enum": [ "auth", "hello" ], "type": "string" }, { "type": "null" } ], "title": "Phase" }, "runtime": { "maxLength": 64, "minLength": 1, "title": "Runtime", "type": "string" }, "turn_ordinal": { "anyOf": [ { "minimum": 1.0, "type": "integer" }, { "type": "null" } ], "title": "Turn Ordinal" } }, "required": [ "kind", "runtime", "model", "input_tokens", "output_tokens" ], "title": "HarnessUsageRequest", "type": "object" }, "HarnessUsageResponse": { "properties": { "billable": { "default": false, "title": "Billable", "type": "boolean" }, "call_id": { "title": "Call Id", "type": "string" }, "recorded": { "default": true, "title": "Recorded", "type": "boolean" }, "settled": { "default": false, "title": "Settled", "type": "boolean" }, "verification": { "const": "unverified", "default": "unverified", "title": "Verification", "type": "string" } }, "required": [ "call_id" ], "title": "HarnessUsageResponse", "type": "object" }, "HarnessUsageSnapshotV1": { "additionalProperties": false, "properties": { "account_generation": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Account Generation" }, "behaviors": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Behaviors" }, "context": { "anyOf": [ { "$ref": "#/components/schemas/UsageContext-Input" }, { "type": "null" } ] }, "coverage": { "anyOf": [ { "$ref": "#/components/schemas/UsageCoverage-Input" }, { "type": "null" } ] }, "observed_at": { "format": "date-time", "title": "Observed At", "type": "string" }, "partUnavailable": { "anyOf": [ { "additionalProperties": { "$ref": "#/components/schemas/UsageUnavailable-Input" }, "propertyNames": { "enum": [ "windows", "usageFacts", "context", "plan" ] }, "type": "object" }, { "type": "null" } ], "title": "Partunavailable" }, "parts": { "additionalProperties": { "$ref": "#/components/schemas/UsageObservation" }, "propertyNames": { "enum": [ "windows", "usageFacts", "context", "plan" ] }, "title": "Parts", "type": "object" }, "plan": { "anyOf": [ { "$ref": "#/components/schemas/UsagePlan-Input" }, { "type": "null" } ] }, "profile_id": { "anyOf": [ { "maxLength": 100, "type": "string" }, { "type": "null" } ], "title": "Profile Id" }, "runtime": { "maxLength": 40, "minLength": 1, "title": "Runtime", "type": "string" }, "source": { "enum": [ "codex-app-server", "claude-agent-sdk", "pi-session-store", "hermes-state-db", "adapter-telemetry" ], "title": "Source", "type": "string" }, "spend": { "anyOf": [ { "$ref": "#/components/schemas/UsageSpend" }, { "type": "null" } ] }, "unavailable": { "anyOf": [ { "$ref": "#/components/schemas/UsageUnavailable-Input" }, { "type": "null" } ] }, "usageFacts": { "anyOf": [ { "items": { "$ref": "#/components/schemas/UsageFact" }, "maxItems": 10000, "type": "array" }, { "type": "null" } ], "title": "Usagefacts" }, "v": { "const": 1, "title": "V", "type": "integer" }, "windows": { "items": { "$ref": "#/components/schemas/UsageWindow-Input" }, "maxItems": 100, "title": "Windows", "type": "array" } }, "required": [ "v", "runtime", "profile_id", "observed_at", "source", "windows", "parts" ], "title": "HarnessUsageSnapshotV1", "type": "object" }, "HeaderBackfillStatusResponse": { "properties": { "can_continue": { "default": false, "title": "Can Continue", "type": "boolean" }, "connection_id": { "title": "Connection Id", "type": "string" }, "connection_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Connection Status" }, "email_address": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Email Address" }, "folders": { "items": { "$ref": "#/components/schemas/FolderProgress" }, "title": "Folders", "type": "array" }, "last_error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Last Error" }, "overall_completed_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Overall Completed At" }, "overall_started_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Overall Started At" }, "overall_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Overall Status" }, "provider_type": { "title": "Provider Type", "type": "string" } }, "required": [ "connection_id", "provider_type" ], "title": "HeaderBackfillStatusResponse", "type": "object" }, "HealthCheckRateRow": { "description": "Health-check pass rate for one harness/provider pair (R44).", "properties": { "harness": { "title": "Harness", "type": "string" }, "pass_rate_pct": { "title": "Pass Rate Pct", "type": "number" }, "passed": { "title": "Passed", "type": "integer" }, "provider": { "title": "Provider", "type": "string" }, "total": { "title": "Total", "type": "integer" } }, "required": [ "harness", "provider", "total", "passed", "pass_rate_pct" ], "title": "HealthCheckRateRow", "type": "object" }, "HealthCheckResponse": { "properties": { "alerts": { "items": { "$ref": "#/components/schemas/AlertDetail" }, "title": "Alerts", "type": "array" }, "alerts_generated": { "title": "Alerts Generated", "type": "integer" }, "contacts_checked": { "title": "Contacts Checked", "type": "integer" }, "reminders_created": { "title": "Reminders Created", "type": "integer" } }, "required": [ "contacts_checked", "alerts_generated", "reminders_created", "alerts" ], "title": "HealthCheckResponse", "type": "object" }, "HealthContactSummary": { "properties": { "contact_id": { "title": "Contact Id", "type": "string" }, "contact_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Contact Name" }, "days_since_last_contact": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Days Since Last Contact" }, "goal_frequency": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Goal Frequency" }, "status": { "title": "Status", "type": "string" } }, "required": [ "contact_id", "contact_name", "status", "days_since_last_contact", "goal_frequency" ], "title": "HealthContactSummary", "type": "object" }, "HealthResponse": { "description": "Health check response model.\n\nAttributes:\n status: Overall service health ('ok' | 'degraded')\n service: Service name identifier\n version: Service version (semantic versioning)\n database: Database connectivity status ('connected' | 'disconnected' | 'unknown')\n\nExample:\n {\n \"status\": \"ok\",\n \"service\": \"api-service\",\n \"version\": \"1.0.0\",\n \"database\": \"connected\"\n }\n\nRelated: FR-003", "properties": { "background_tasks": { "additionalProperties": { "type": "boolean" }, "title": "Background Tasks", "type": "object" }, "database": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Database connectivity status", "examples": [ "connected", "disconnected", "unknown" ], "title": "Database" }, "role": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Process role this instance booted as (API_ROLE)", "examples": [ "all", "http", "worker" ], "title": "Role" }, "service": { "description": "Service identifier", "examples": [ "api-service" ], "title": "Service", "type": "string" }, "status": { "description": "Overall service health status", "examples": [ "ok", "degraded" ], "title": "Status", "type": "string" }, "version": { "description": "Service version (semantic versioning)", "examples": [ "1.0.0" ], "title": "Version", "type": "string" } }, "required": [ "status", "service", "version" ], "title": "HealthResponse", "type": "object" }, "HealthSignal": { "properties": { "action": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Action" }, "at": { "title": "At", "type": "string" }, "evidence_email_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Evidence Email Id" }, "polarity": { "title": "Polarity", "type": "integer" }, "signal": { "title": "Signal", "type": "string" }, "summary": { "title": "Summary", "type": "string" } }, "required": [ "signal", "polarity", "at", "summary" ], "title": "HealthSignal", "type": "object" }, "HealthSummaryResponse": { "properties": { "at_risk": { "title": "At Risk", "type": "integer" }, "contacts": { "items": { "$ref": "#/components/schemas/HealthContactSummary" }, "title": "Contacts", "type": "array" }, "on_track": { "title": "On Track", "type": "integer" }, "overdue": { "title": "Overdue", "type": "integer" }, "total_goals": { "title": "Total Goals", "type": "integer" } }, "required": [ "total_goals", "on_track", "at_risk", "overdue", "contacts" ], "title": "HealthSummaryResponse", "type": "object" }, "HeatmapCell": { "properties": { "day_of_week": { "title": "Day Of Week", "type": "integer" }, "hour": { "title": "Hour", "type": "integer" }, "received": { "title": "Received", "type": "integer" }, "sent": { "title": "Sent", "type": "integer" }, "total": { "title": "Total", "type": "integer" } }, "required": [ "day_of_week", "hour", "received", "sent", "total" ], "title": "HeatmapCell", "type": "object" }, "HeatmapDay": { "properties": { "achieved": { "title": "Achieved", "type": "boolean" }, "date": { "title": "Date", "type": "string" }, "excluded": { "default": false, "title": "Excluded", "type": "boolean" }, "value": { "default": 0, "title": "Value", "type": "integer" } }, "required": [ "date", "achieved" ], "title": "HeatmapDay", "type": "object" }, "HeatmapResponse": { "properties": { "best_streak": { "title": "Best Streak", "type": "integer" }, "current_streak": { "title": "Current Streak", "type": "integer" }, "days": { "items": { "$ref": "#/components/schemas/HeatmapDay" }, "title": "Days", "type": "array" }, "total_achieved_days": { "title": "Total Achieved Days", "type": "integer" }, "total_days": { "title": "Total Days", "type": "integer" }, "type": { "title": "Type", "type": "string" }, "year": { "title": "Year", "type": "integer" } }, "required": [ "type", "year", "days", "current_streak", "best_streak", "total_achieved_days", "total_days" ], "title": "HeatmapResponse", "type": "object" }, "Highlight": { "properties": { "event_id": { "title": "Event Id", "type": "string" }, "text": { "title": "Text", "type": "string" } }, "required": [ "text", "event_id" ], "title": "Highlight", "type": "object" }, "HirePrefillResponse": { "description": "The define-employee journey's starting state, and what is missing.", "properties": { "display_name": { "title": "Display Name", "type": "string" }, "harness": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Harness" }, "harness_rationale": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Harness Rationale" }, "hire_id": { "title": "Hire Id", "type": "string" }, "hired_from": { "additionalProperties": true, "title": "Hired From", "type": "object" }, "manners_markdown": { "title": "Manners Markdown", "type": "string" }, "provider_profile": { "items": { "additionalProperties": true, "type": "object" }, "title": "Provider Profile", "type": "array" }, "setup_steps": { "items": { "$ref": "#/components/schemas/SetupStep" }, "title": "Setup Steps", "type": "array" }, "skills": { "items": { "type": "string" }, "title": "Skills", "type": "array" }, "soul_markdown": { "title": "Soul Markdown", "type": "string" }, "starter_objectives": { "items": { "additionalProperties": true, "type": "object" }, "title": "Starter Objectives", "type": "array" }, "template_id": { "title": "Template Id", "type": "string" }, "template_key": { "title": "Template Key", "type": "string" }, "template_name": { "title": "Template Name", "type": "string" }, "template_version": { "title": "Template Version", "type": "integer" } }, "required": [ "template_id", "template_key", "template_name", "template_version", "display_name", "soul_markdown", "manners_markdown", "skills", "provider_profile", "starter_objectives", "setup_steps", "hired_from", "hire_id" ], "title": "HirePrefillResponse", "type": "object" }, "HoldAccountOption": { "properties": { "account_id": { "title": "Account Id", "type": "string" }, "display_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Display Name" }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Email" } }, "required": [ "account_id" ], "title": "HoldAccountOption", "type": "object" }, "HoldRoomOption": { "properties": { "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Name" }, "room_id": { "title": "Room Id", "type": "string" } }, "required": [ "room_id" ], "title": "HoldRoomOption", "type": "object" }, "HostDeprovisionState": { "properties": { "detail": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Detail" }, "installation_id": { "title": "Installation Id", "type": "string" }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Reason" }, "reported_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Reported At" }, "requested_at": { "format": "date-time", "title": "Requested At", "type": "string" }, "state": { "enum": [ "pending", "completed", "failed" ], "title": "State", "type": "string" } }, "required": [ "installation_id", "requested_at", "state" ], "title": "HostDeprovisionState", "type": "object" }, "HostInstallationInconsistency": { "description": "A host carrying an installation the roster cannot account for.\n\nTIDY-16772 (HC-R12). Report-only, and it has to be: the runtime credential\nfor a removed employee is revoked, so the server cannot look at that machine\nand must not delete anything on the strength of an inference. It names the\ninstallation, the machine, and the command a human runs on that box.", "properties": { "agent_account_id": { "title": "Agent Account Id", "type": "string" }, "artifact_version": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Artifact Version" }, "display_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Display Name" }, "host_instance_id": { "title": "Host Instance Id", "type": "string" }, "installation_id": { "title": "Installation Id", "type": "string" }, "last_reported_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Last Reported At" }, "reason": { "enum": [ "no_roster_employee", "removed_without_deprovision" ], "title": "Reason", "type": "string" } }, "required": [ "installation_id", "agent_account_id", "host_instance_id", "reason" ], "title": "HostInstallationInconsistency", "type": "object" }, "HostRebindRequest": { "properties": { "command_target": { "anyOf": [ { "$ref": "#/components/schemas/ProtectedCommandTarget" }, { "type": "null" } ] }, "confirmation_slug": { "maxLength": 80, "minLength": 2, "title": "Confirmation Slug", "type": "string" }, "expected_host_instance_id": { "format": "uuid", "title": "Expected Host Instance Id", "type": "string" }, "new_machine_fingerprint": { "maxLength": 512, "minLength": 16, "title": "New Machine Fingerprint", "type": "string" }, "reason": { "maxLength": 500, "minLength": 8, "title": "Reason", "type": "string" } }, "required": [ "expected_host_instance_id", "reason", "confirmation_slug", "new_machine_fingerprint" ], "title": "HostRebindRequest", "type": "object" }, "HostRebindResponse": { "properties": { "credential_recovery_token": { "title": "Credential Recovery Token", "type": "string" }, "host_continuity_token": { "title": "Host Continuity Token", "type": "string" }, "host_instance_id": { "format": "uuid", "title": "Host Instance Id", "type": "string" }, "installation_id": { "format": "uuid", "title": "Installation Id", "type": "string" }, "native_refs_quarantined": { "title": "Native Refs Quarantined", "type": "boolean" }, "protected_setup_command": { "anyOf": [ { "$ref": "#/components/schemas/ProtectedSetupCommand" }, { "type": "null" } ], "default": null }, "recovery_expires_at": { "format": "date-time", "title": "Recovery Expires At", "type": "string" } }, "required": [ "installation_id", "host_instance_id", "host_continuity_token", "native_refs_quarantined", "credential_recovery_token", "recovery_expires_at" ], "title": "HostRebindResponse", "type": "object" }, "HostedCredentialItem": { "properties": { "api_flavor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Api Flavor" }, "base_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Base Url" }, "env_key": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Env Key" }, "id": { "title": "Id", "type": "string" }, "provider_slug": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Provider Slug" }, "value": { "title": "Value", "type": "string" } }, "required": [ "id", "value" ], "title": "HostedCredentialItem", "type": "object" }, "HostedCredentialRequest": { "properties": { "agent_account_id": { "title": "Agent Account Id", "type": "string" }, "runtime": { "default": "pi", "title": "Runtime", "type": "string" }, "session_ref": { "title": "Session Ref", "type": "string" }, "tenant_id": { "title": "Tenant Id", "type": "string" } }, "required": [ "tenant_id", "agent_account_id", "session_ref" ], "title": "HostedCredentialRequest", "type": "object" }, "HostedCredentialResponse": { "properties": { "credentials": { "items": { "$ref": "#/components/schemas/HostedCredentialItem" }, "title": "Credentials", "type": "array" }, "method": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Method" }, "model_allowed": { "items": { "type": "string" }, "title": "Model Allowed", "type": "array" }, "model_default": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Model Default" }, "runtime": { "title": "Runtime", "type": "string" } }, "required": [ "runtime" ], "title": "HostedCredentialResponse", "type": "object" }, "HostedHireContext": { "description": "Hiring this Tidy-compute employee FROM a bench template (TIDY-17550).\n\nPresent only when the define journey was opened from the bench. It is what\nturns an ordinary hosted create into a hire: the template's requirements are\nre-checked and refused here, its skills are copied onto the employee, and\nthe attempt's funnel steps are recorded server-side.", "properties": { "hire_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Hire Id" }, "template_id": { "title": "Template Id", "type": "string" } }, "required": [ "template_id" ], "title": "HostedHireContext", "type": "object" }, "HostedThreadRequest": { "description": "POST /api/v1/internal/matrix/hosted-thread body.", "properties": { "account_id": { "minLength": 1, "title": "Account Id", "type": "string" }, "agent_account_id": { "minLength": 1, "title": "Agent Account Id", "type": "string" }, "tenant_id": { "minLength": 1, "title": "Tenant Id", "type": "string" }, "title": { "maxLength": 500, "minLength": 1, "title": "Title", "type": "string" } }, "required": [ "tenant_id", "agent_account_id", "account_id", "title" ], "title": "HostedThreadRequest", "type": "object" }, "HostedThreadResponse": { "properties": { "conversation_id": { "title": "Conversation Id", "type": "string" }, "matrix_room_id": { "title": "Matrix Room Id", "type": "string" }, "matrix_thread_root_event_id": { "title": "Matrix Thread Root Event Id", "type": "string" }, "matrix_user_id": { "title": "Matrix User Id", "type": "string" } }, "required": [ "conversation_id", "matrix_room_id", "matrix_thread_root_event_id", "matrix_user_id" ], "title": "HostedThreadResponse", "type": "object" }, "HotTenant": { "properties": { "pct": { "title": "Pct", "type": "number" }, "tenant_id": { "title": "Tenant Id", "type": "string" }, "tenant_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Tenant Name" }, "tier": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Tier" } }, "required": [ "tenant_id", "pct" ], "title": "HotTenant", "type": "object" }, "HourlyWeatherRefreshResponse": { "description": "What a refresh of the Feed sky's hourly weather found. The weather\nitself reaches the client through sync (``feed_weather_days``).", "properties": { "coverage": { "description": "`nws`: hourly weather for the home location; `outside_us`: the location is outside NWS coverage, so only sunrise and sunset; `no_location`: the account has no home location.", "enum": [ "nws", "outside_us", "no_location" ], "title": "Coverage", "type": "string" }, "days_changed": { "description": "Synced day rows that changed.", "title": "Days Changed", "type": "integer" } }, "required": [ "coverage", "days_changed" ], "title": "HourlyWeatherRefreshResponse", "type": "object" }, "HtmlPreviewResponse": { "properties": { "sanitized_html": { "description": "nh3-sanitized document HTML (style preserved, all script vectors stripped) for rendering in a sandboxed srcdoc iframe.", "title": "Sanitized Html", "type": "string" } }, "required": [ "sanitized_html" ], "title": "HtmlPreviewResponse", "type": "object" }, "HuddleCallPreferences": { "description": "The member's voice settings a call with an employee runs under (TIDY-20000).\n\nRead once at huddle start and stamped on the call's voice session, where the\nvoice-agent reads them (``voice_sessions.metadata.call_preferences``).", "properties": { "shorten_long_replies": { "default": false, "title": "Shorten Long Replies", "type": "boolean" }, "thinking": { "$ref": "#/components/schemas/HuddleCallThinking" } }, "required": [ "thinking" ], "title": "HuddleCallPreferences", "type": "object" }, "HuddleCallThinking": { "description": "How much the employee thinks on this call's turns (TIDY-20000).", "properties": { "applied": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The option of the conversation's model the call's turns run at; null = the conversation's own.", "title": "Applied" }, "label": { "description": "What the call shows, e.g. `Off` or `Same as chat`.", "title": "Label", "type": "string" }, "note": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Why it differs from the setting.", "title": "Note" }, "setting": { "anyOf": [ { "enum": [ "low", "off" ], "type": "string" }, { "type": "null" } ], "description": "The member's call setting; null = the same as in chat.", "title": "Setting" } }, "required": [ "label" ], "title": "HuddleCallThinking", "type": "object" }, "HuddleCompositeRequest": { "description": "One rendered contact sheet, uploaded once at huddle end (TIDY-15371).\n\nBase64 rather than multipart because this is an evaluation path with a hard\nsize bar (500 KB) that we WANT to reject loudly at the contract edge — a\ncomposite that needed a streaming upload has already failed the experiment.", "properties": { "image_base64": { "title": "Image Base64", "type": "string" }, "missing_tracks": { "default": 0, "maximum": 200.0, "minimum": 0.0, "title": "Missing Tracks", "type": "integer" }, "participant_count": { "maximum": 200.0, "minimum": 0.0, "title": "Participant Count", "type": "integer" }, "render_ms": { "maximum": 600000.0, "minimum": 0.0, "title": "Render Ms", "type": "integer" } }, "required": [ "image_base64", "render_ms", "participant_count" ], "title": "HuddleCompositeRequest", "type": "object" }, "HuddleCompositeResponse": { "properties": { "byte_size": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Byte Size" }, "over_budget": { "default": false, "title": "Over Budget", "type": "boolean" }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Reason" }, "recorded": { "title": "Recorded", "type": "boolean" }, "render_ms": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Render Ms" } }, "required": [ "recorded" ], "title": "HuddleCompositeResponse", "type": "object" }, "HuddleEventRequest": { "properties": { "event_kind": { "title": "Event Kind", "type": "string" }, "payload": { "additionalProperties": true, "title": "Payload", "type": "object" } }, "required": [ "event_kind" ], "title": "HuddleEventRequest", "type": "object" }, "HuddleEventResponse": { "properties": { "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "event_kind": { "title": "Event Kind", "type": "string" }, "huddle_id": { "format": "uuid", "title": "Huddle Id", "type": "string" }, "id": { "format": "uuid", "title": "Id", "type": "string" }, "payload": { "additionalProperties": true, "title": "Payload", "type": "object" } }, "required": [ "id", "huddle_id", "event_kind", "payload", "created_at" ], "title": "HuddleEventResponse", "type": "object" }, "HuddleNotesResponse": { "properties": { "content": { "title": "Content", "type": "string" }, "note_id": { "title": "Note Id", "type": "string" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Title" } }, "required": [ "note_id", "content" ], "title": "HuddleNotesResponse", "type": "object" }, "HuddleParticipant": { "properties": { "account_id": { "format": "uuid", "title": "Account Id", "type": "string" }, "audio": { "title": "Audio", "type": "boolean" }, "client_kind": { "title": "Client Kind", "type": "string" }, "joined_at": { "format": "date-time", "title": "Joined At", "type": "string" }, "left_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Left At" }, "sharing_screen": { "title": "Sharing Screen", "type": "boolean" }, "video": { "title": "Video", "type": "boolean" } }, "required": [ "account_id", "joined_at", "left_at", "audio", "video", "sharing_screen", "client_kind" ], "title": "HuddleParticipant", "type": "object" }, "HuddleParticipantUpdateResponse": { "properties": { "participant": { "$ref": "#/components/schemas/HuddleParticipant" } }, "required": [ "participant" ], "title": "HuddleParticipantUpdateResponse", "type": "object" }, "HuddleResponse": { "properties": { "call_preferences": { "anyOf": [ { "$ref": "#/components/schemas/HuddleCallPreferences" }, { "type": "null" } ], "default": null }, "connected_participants": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Connected Participants" }, "conversation_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "default": null, "description": "The caller's conversation this live call continues. A joining device shows it before connecting; null when no caller-owned voice session exists.", "title": "Conversation Id" }, "ended_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Ended At" }, "huddle_id": { "format": "uuid", "title": "Huddle Id", "type": "string" }, "matrix_call_id": { "title": "Matrix Call Id", "type": "string" }, "media_plane": { "default": "livekit", "title": "Media Plane", "type": "string" }, "meet_join_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Meet Join Url" }, "notes_enabled": { "default": false, "title": "Notes Enabled", "type": "boolean" }, "participants": { "items": { "$ref": "#/components/schemas/HuddleParticipant" }, "title": "Participants", "type": "array" }, "plane_notice": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Plane Notice" }, "room_id": { "title": "Room Id", "type": "string" }, "scheduled_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Scheduled At" }, "sfu_required": { "title": "Sfu Required", "type": "boolean" }, "signaling": { "anyOf": [ { "$ref": "#/components/schemas/HuddleSignaling" }, { "type": "null" } ], "default": null }, "started_at": { "format": "date-time", "title": "Started At", "type": "string" }, "thread_event_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Thread Event Id" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Title" }, "title_override": { "default": false, "title": "Title Override", "type": "boolean" }, "title_source": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Title Source" }, "transcription_status": { "title": "Transcription Status", "type": "string" } }, "required": [ "huddle_id", "room_id", "matrix_call_id", "thread_event_id", "started_at", "ended_at", "transcription_status", "participants", "sfu_required" ], "title": "HuddleResponse", "type": "object" }, "HuddleSfuTokenResponse": { "properties": { "huddle_id": { "format": "uuid", "title": "Huddle Id", "type": "string" }, "livekit": { "anyOf": [ { "additionalProperties": { "type": "string" }, "type": "object" }, { "type": "null" } ], "default": null, "title": "Livekit" }, "mode": { "title": "Mode", "type": "string" } }, "required": [ "huddle_id", "mode" ], "title": "HuddleSfuTokenResponse", "type": "object" }, "HuddleSignaling": { "properties": { "livekit": { "anyOf": [ { "additionalProperties": { "type": "string" }, "type": "object" }, { "type": "null" } ], "title": "Livekit" }, "mode": { "title": "Mode", "type": "string" } }, "required": [ "mode" ], "title": "HuddleSignaling", "type": "object" }, "HuddleTranscriptResponse": { "properties": { "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "duration": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "title": "Duration" }, "huddle_id": { "format": "uuid", "title": "Huddle Id", "type": "string" }, "language": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Language" }, "partial": { "default": false, "title": "Partial", "type": "boolean" }, "room_id": { "title": "Room Id", "type": "string" }, "segments": { "items": { "$ref": "#/components/schemas/HuddleTranscriptSegment" }, "title": "Segments", "type": "array" }, "speaker_map": { "additionalProperties": true, "title": "Speaker Map", "type": "object" }, "updated_at": { "format": "date-time", "title": "Updated At", "type": "string" } }, "required": [ "huddle_id", "room_id", "segments", "speaker_map", "created_at", "updated_at" ], "title": "HuddleTranscriptResponse", "type": "object" }, "HuddleTranscriptSegment": { "properties": { "confidence": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "title": "Confidence" }, "end": { "title": "End", "type": "number" }, "id": { "title": "Id", "type": "integer" }, "speaker_label": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Speaker Label" }, "speaker_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Speaker Name" }, "start": { "title": "Start", "type": "number" }, "text": { "title": "Text", "type": "string" } }, "required": [ "id", "start", "end", "text" ], "title": "HuddleTranscriptSegment", "type": "object" }, "HumanCheckRequest": { "properties": { "token": { "maxLength": 4096, "minLength": 1, "title": "Token", "type": "string" } }, "required": [ "token" ], "title": "HumanCheckRequest", "type": "object" }, "HumanCheckResponse": { "properties": { "counted": { "title": "Counted", "type": "boolean" }, "passed": { "title": "Passed", "type": "boolean" } }, "required": [ "passed", "counted" ], "title": "HumanCheckResponse", "type": "object" }, "HydratePhotoThumbnailsResponse": { "description": "Summary of one inline-thumbnail hydration pass (TIDY-10636 S1).", "properties": { "hydrated": { "title": "Hydrated", "type": "integer" }, "pending": { "title": "Pending", "type": "integer" }, "skipped": { "title": "Skipped", "type": "integer" } }, "required": [ "hydrated", "skipped", "pending" ], "title": "HydratePhotoThumbnailsResponse", "type": "object" }, "IdempotencyKey": { "additionalProperties": false, "description": "TIDY-16828 (R1/D1): a rule-level dedup key. ``expression`` is written in\nthe SAME binding grammar the actions use, so the vocabulary is the\nmember's: ``{{trigger.item.source_event_id}}``. A firing whose resolved key\nwas already seen is SKIPPED and says so in the run log; an expression that\nresolves empty does not dedupe (an absent key is not a key).", "properties": { "expression": { "description": "Binding expression over the trigger context, e.g. '{{trigger.item.source_event_id}}'.", "maxLength": 500, "minLength": 1, "title": "Expression", "type": "string" } }, "required": [ "expression" ], "title": "IdempotencyKey", "type": "object" }, "IdentityCheckResponse": { "description": "Response model for email identity availability check.", "properties": { "available": { "description": "Whether the local part is available", "title": "Available", "type": "boolean" }, "local_part": { "description": "The local part checked", "title": "Local Part", "type": "string" } }, "required": [ "local_part", "available" ], "title": "IdentityCheckResponse", "type": "object" }, "IdentityClaimRequest": { "description": "Request model for claiming email identity.", "properties": { "local_part": { "description": "Local part of email (e.g., 'smith' for smith@domain)", "maxLength": 50, "minLength": 1, "title": "Local Part", "type": "string" } }, "required": [ "local_part" ], "title": "IdentityClaimRequest", "type": "object" }, "IdentityClaimResponse": { "description": "Response model for email identity claim.", "properties": { "email_address": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Full email address if successful", "title": "Email Address" }, "error_message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Error message if failed", "title": "Error Message" }, "success": { "description": "Whether the claim was successful", "title": "Success", "type": "boolean" } }, "required": [ "success" ], "title": "IdentityClaimResponse", "type": "object" }, "IdentitySuggestionsResponse": { "description": "Response model for email identity suggestions.", "properties": { "domain": { "description": "Email domain", "title": "Domain", "type": "string" }, "suggestions": { "description": "Suggested local parts", "items": { "type": "string" }, "title": "Suggestions", "type": "array" } }, "required": [ "domain" ], "title": "IdentitySuggestionsResponse", "type": "object" }, "ImageObject": { "description": "Image reference object (MinIO URL with metadata).\n\nAttributes:\n url: MinIO URL for the image\n alt: Alt text for accessibility\n caption: Optional caption text\n\nExample:\n {\n \"url\": \"https://minio.example.com/tenant-bucket/play-poster.png\",\n \"alt\": \"Wizard of Oz poster\",\n \"caption\": \"This year's school play\"\n }", "properties": { "alt": { "description": "Alt text for accessibility", "examples": [ "School play poster" ], "title": "Alt", "type": "string" }, "caption": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional caption text", "examples": [ "This year's school play" ], "title": "Caption" }, "url": { "description": "MinIO URL for the image", "examples": [ "https://minio.example.com/bucket/image.png" ], "title": "Url", "type": "string" } }, "required": [ "url", "alt" ], "title": "ImageObject", "type": "object" }, "ImageQuotaResponse": { "properties": { "is_admin": { "title": "Is Admin", "type": "boolean" }, "limit": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Limit" }, "resets_on": { "title": "Resets On", "type": "string" }, "used": { "title": "Used", "type": "integer" } }, "required": [ "used", "is_admin", "resets_on" ], "title": "ImageQuotaResponse", "type": "object" }, "ImapSearchProxyRequest": { "description": "Structured mail-server search filters (IMAP, Gmail API or Microsoft Graph).", "properties": { "body_contains": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Keywords to search in the email body.", "title": "Body Contains" }, "date_end": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Latest date (YYYY-MM-DD).", "title": "Date End" }, "date_start": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Earliest date (YYYY-MM-DD).", "title": "Date Start" }, "from_email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Sender email or domain (e.g. 'school@example.com').", "title": "From Email" }, "has_attachment": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Filter by attachment presence.", "title": "Has Attachment" }, "max_full_emails": { "default": 5, "description": "Maximum full emails to fetch.", "maximum": 10.0, "minimum": 1.0, "title": "Max Full Emails", "type": "integer" }, "search_all_accounts": { "default": false, "description": "Search all connected accounts and standard folders.", "title": "Search All Accounts", "type": "boolean" }, "subject_contains": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Keywords to search in the subject line.", "title": "Subject Contains" }, "to_email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Recipient email address.", "title": "To Email" } }, "title": "ImapSearchProxyRequest", "type": "object" }, "ImapSearchProxyResponse": { "description": "Mail-server search results across the member's searched mailboxes.", "properties": { "emails": { "description": "Fully processed emails.", "items": { "additionalProperties": true, "type": "object" }, "title": "Emails", "type": "array" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Error message if the search failed.", "title": "Error" }, "headers": { "description": "Email headers from the search.", "items": { "additionalProperties": true, "type": "object" }, "title": "Headers", "type": "array" }, "search_count": { "default": 0, "description": "Number of server searches executed.", "title": "Search Count", "type": "integer" } }, "title": "ImapSearchProxyResponse", "type": "object" }, "ImportConfirmRequest": { "description": "Body for POST /api/v1/import/{id}/confirm.", "properties": { "mapping": { "additionalProperties": { "type": "string" }, "title": "Mapping", "type": "object" }, "options": { "additionalProperties": true, "title": "Options", "type": "object" } }, "title": "ImportConfirmRequest", "type": "object" }, "ImportCreateResponse": { "properties": { "job_id": { "title": "Job Id", "type": "string" }, "phase": { "default": "parsing", "enum": [ "parsing", "previewing", "mapping", "importing", "complete", "failed", "cancelled" ], "title": "Phase", "type": "string" } }, "required": [ "job_id" ], "title": "ImportCreateResponse", "type": "object" }, "ImportJobCreateRequest": { "properties": { "file_size_bytes": { "exclusiveMinimum": 0.0, "title": "File Size Bytes", "type": "integer" }, "format": { "enum": [ "logseq", "obsidian", "notion" ], "title": "Format", "type": "string" }, "original_filename": { "maxLength": 512, "minLength": 1, "title": "Original Filename", "type": "string" }, "task_import_mode": { "default": "all", "enum": [ "all", "open_only", "none" ], "title": "Task Import Mode", "type": "string" } }, "required": [ "format", "original_filename", "file_size_bytes" ], "title": "ImportJobCreateRequest", "type": "object" }, "ImportJobCreateResponse": { "properties": { "id": { "title": "Id", "type": "string" }, "phase": { "enum": [ "configuring", "uploading", "analyzing", "review", "executing", "completed", "failed", "cancelled" ], "title": "Phase", "type": "string" }, "quota": { "$ref": "#/components/schemas/ImportQuotaResponse" } }, "required": [ "id", "phase", "quota" ], "title": "ImportJobCreateResponse", "type": "object" }, "ImportJobResponse": { "properties": { "account_id": { "title": "Account Id", "type": "string" }, "analysis_results": { "additionalProperties": true, "title": "Analysis Results", "type": "object" }, "candidate_facets": { "items": { "additionalProperties": true, "type": "object" }, "title": "Candidate Facets", "type": "array" }, "completed_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Completed At" }, "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "error_message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Error Message" }, "execution_progress": { "additionalProperties": true, "title": "Execution Progress", "type": "object" }, "file_size_bytes": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "File Size Bytes" }, "format": { "enum": [ "logseq", "obsidian", "notion" ], "title": "Format", "type": "string" }, "id": { "title": "Id", "type": "string" }, "original_filename": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Original Filename" }, "phase": { "enum": [ "configuring", "uploading", "analyzing", "review", "executing", "completed", "failed", "cancelled" ], "title": "Phase", "type": "string" }, "progress_pct": { "default": 0, "title": "Progress Pct", "type": "integer" }, "storage_path": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Storage Path" }, "task_import_mode": { "default": "all", "enum": [ "all", "open_only", "none" ], "title": "Task Import Mode", "type": "string" }, "tenant_id": { "title": "Tenant Id", "type": "string" }, "updated_at": { "format": "date-time", "title": "Updated At", "type": "string" }, "user_facet_selections": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "default": null, "title": "User Facet Selections" } }, "required": [ "id", "tenant_id", "account_id", "format", "phase", "created_at", "updated_at" ], "title": "ImportJobResponse", "type": "object" }, "ImportJobReviewRequest": { "properties": { "confirm_no_facets": { "default": false, "title": "Confirm No Facets", "type": "boolean" }, "entity_merge_selections": { "items": { "$ref": "#/components/schemas/EntityMergeSelection" }, "title": "Entity Merge Selections", "type": "array" }, "facet_selections": { "items": { "$ref": "#/components/schemas/FacetSelection" }, "title": "Facet Selections", "type": "array" }, "phantom_threshold": { "default": 3, "maximum": 1000.0, "minimum": 1.0, "title": "Phantom Threshold", "type": "integer" } }, "title": "ImportJobReviewRequest", "type": "object" }, "ImportJobTransitionResponse": { "properties": { "id": { "title": "Id", "type": "string" }, "message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Message" }, "phase": { "enum": [ "configuring", "uploading", "analyzing", "review", "executing", "completed", "failed", "cancelled" ], "title": "Phase", "type": "string" } }, "required": [ "id", "phase" ], "title": "ImportJobTransitionResponse", "type": "object" }, "ImportQuotaResponse": { "properties": { "limit_bytes": { "description": "Maximum bytes allowed for imports", "title": "Limit Bytes", "type": "integer" }, "max_upload_bytes": { "description": "Maximum allowed size for a single archive", "title": "Max Upload Bytes", "type": "integer" }, "remaining_bytes": { "description": "Bytes still available for upload", "title": "Remaining Bytes", "type": "integer" }, "tier": { "description": "Current tenant plan tier", "title": "Tier", "type": "string" }, "upload_allowed": { "description": "Whether another upload can be started", "title": "Upload Allowed", "type": "boolean" }, "used_bytes": { "description": "Bytes currently used by stored imports", "title": "Used Bytes", "type": "integer" } }, "required": [ "used_bytes", "limit_bytes", "remaining_bytes", "max_upload_bytes", "tier", "upload_allowed" ], "title": "ImportQuotaResponse", "type": "object" }, "ImportUploadAbortRequest": { "properties": { "upload_id": { "minLength": 1, "title": "Upload Id", "type": "string" } }, "required": [ "upload_id" ], "title": "ImportUploadAbortRequest", "type": "object" }, "ImportUploadCompleteRequest": { "properties": { "parts": { "items": { "$ref": "#/components/schemas/ImportUploadPart" }, "minItems": 1, "title": "Parts", "type": "array" }, "upload_id": { "minLength": 1, "title": "Upload Id", "type": "string" } }, "required": [ "upload_id", "parts" ], "title": "ImportUploadCompleteRequest", "type": "object" }, "ImportUploadCompleteResponse": { "properties": { "ok": { "default": true, "title": "Ok", "type": "boolean" } }, "title": "ImportUploadCompleteResponse", "type": "object" }, "ImportUploadInitiateResponse": { "description": "Server-minted multipart handle: the browser PUTs each part URL directly.", "properties": { "object_key": { "description": "Storage object key the parts assemble into", "title": "Object Key", "type": "string" }, "part_size_bytes": { "description": "Byte size of every part except the last", "title": "Part Size Bytes", "type": "integer" }, "part_urls": { "description": "Presigned upload_part URLs, 1-indexed by list position", "items": { "type": "string" }, "title": "Part Urls", "type": "array" }, "upload_id": { "description": "S3 multipart UploadId", "title": "Upload Id", "type": "string" } }, "required": [ "upload_id", "part_size_bytes", "part_urls", "object_key" ], "title": "ImportUploadInitiateResponse", "type": "object" }, "ImportUploadPart": { "properties": { "etag": { "description": "ETag returned by the part PUT", "minLength": 1, "title": "Etag", "type": "string" }, "part_number": { "description": "1-indexed part number", "minimum": 1.0, "title": "Part Number", "type": "integer" } }, "required": [ "part_number", "etag" ], "title": "ImportUploadPart", "type": "object" }, "ImportantTeach": { "description": "A standing \"this is important\" teach on a matched email (undoable).", "properties": { "email_id": { "title": "Email Id", "type": "string" }, "match_value": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Match Value" }, "rule_id": { "title": "Rule Id", "type": "string" }, "subject": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Subject" }, "taught_at": { "format": "date-time", "title": "Taught At", "type": "string" } }, "required": [ "email_id", "taught_at", "rule_id" ], "title": "ImportantTeach", "type": "object" }, "InAppAlert": { "properties": { "account_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "default": null, "title": "Account Id" }, "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "event_type": { "title": "Event Type", "type": "string" }, "href": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Href" }, "id": { "format": "uuid", "title": "Id", "type": "string" }, "message": { "title": "Message", "type": "string" }, "payload": { "additionalProperties": true, "default": {}, "title": "Payload", "type": "object" }, "severity": { "title": "Severity", "type": "string" } }, "required": [ "id", "event_type", "severity", "message", "created_at" ], "title": "InAppAlert", "type": "object" }, "InProgressBadge": { "properties": { "badge_type": { "title": "Badge Type", "type": "string" }, "current_days": { "title": "Current Days", "type": "integer" }, "description": { "title": "Description", "type": "string" }, "icon": { "title": "Icon", "type": "string" }, "name": { "title": "Name", "type": "string" }, "progress_pct": { "title": "Progress Pct", "type": "integer" }, "required_days": { "title": "Required Days", "type": "integer" } }, "required": [ "badge_type", "name", "description", "icon", "current_days", "required_days", "progress_pct" ], "title": "InProgressBadge", "type": "object" }, "InboxActionRequest": { "properties": { "action": { "title": "Action", "type": "string" }, "applied_facets": { "default": [], "items": { "type": "string" }, "title": "Applied Facets", "type": "array" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Title" } }, "required": [ "action" ], "title": "InboxActionRequest", "type": "object" }, "InboxActionResponse": { "properties": { "inbox_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Inbox Status" }, "note_id": { "title": "Note Id", "type": "string" } }, "required": [ "note_id", "inbox_status" ], "title": "InboxActionResponse", "type": "object" }, "InboxAddonQuoteResponse": { "description": "Stripe's prices for add-on inboxes, before anything is charged.", "properties": { "billing_interval": { "enum": [ "monthly", "annual" ], "title": "Billing Interval", "type": "string" }, "currency": { "title": "Currency", "type": "string" }, "has_subscription": { "description": "True: the quote changes the subscription's add-on item. False: the add-ons are bought with the plan in one Checkout.", "title": "Has Subscription", "type": "boolean" }, "plan_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Without a subscription: the plan.", "title": "Plan Id" }, "plan_quantity": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Without a subscription: the seats the plan line carries.", "title": "Plan Quantity" }, "plan_unit_amount_cents": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Without a subscription: the plan per seat, per interval.", "title": "Plan Unit Amount Cents" }, "prorated_amount_cents": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "With a subscription: the prorated charge an increase adds to the next invoice (0 for a decrease, or during a Stripe trial).", "title": "Prorated Amount Cents" }, "proration_date": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Pass back to POST …/addons/inboxes to be charged this quote.", "title": "Proration Date" }, "quantity": { "description": "The total add-on inboxes quoted.", "title": "Quantity", "type": "integer" }, "unit_amount_cents": { "description": "One add-on inbox, per billing interval.", "title": "Unit Amount Cents", "type": "integer" } }, "required": [ "quantity", "has_subscription", "billing_interval", "currency", "unit_amount_cents" ], "title": "InboxAddonQuoteResponse", "type": "object" }, "InboxAddonRequest": { "properties": { "proration_date": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "The quote's proration_date (unix seconds), so an increase is charged exactly the prorated amount the owner confirmed.", "title": "Proration Date" }, "quantity": { "description": "Total authorized add-on inboxes (account-level).", "minimum": 0.0, "title": "Quantity", "type": "integer" } }, "required": [ "quantity" ], "title": "InboxAddonRequest", "type": "object" }, "InboxAddonResponse": { "properties": { "addon_inboxes": { "title": "Addon Inboxes", "type": "integer" }, "inboxes_allowed": { "title": "Inboxes Allowed", "type": "integer" } }, "required": [ "addon_inboxes", "inboxes_allowed" ], "title": "InboxAddonResponse", "type": "object" }, "InboxCompositionSlice": { "properties": { "count": { "title": "Count", "type": "integer" }, "label": { "title": "Label", "type": "string" }, "percentage": { "title": "Percentage", "type": "number" } }, "required": [ "label", "count", "percentage" ], "title": "InboxCompositionSlice", "type": "object" }, "InboxProcessResponse": { "properties": { "facet_suggestions": { "default": [], "items": { "additionalProperties": true, "type": "object" }, "title": "Facet Suggestions", "type": "array" }, "note_id": { "title": "Note Id", "type": "string" }, "summary": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Summary" }, "title_suggestion": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Title Suggestion" }, "urls_found": { "default": [], "items": { "type": "string" }, "title": "Urls Found", "type": "array" } }, "required": [ "note_id" ], "title": "InboxProcessResponse", "type": "object" }, "InboxSplitCounts": { "properties": { "feed": { "default": 0, "title": "Feed", "type": "integer" }, "important": { "default": 0, "title": "Important", "type": "integer" }, "paper_trail": { "default": 0, "title": "Paper Trail", "type": "integer" } }, "title": "InboxSplitCounts", "type": "object" }, "Incident": { "description": "One firing alert, shaped for the console's severity-sorted list.", "properties": { "grafana_url": { "title": "Grafana Url", "type": "string" }, "service": { "title": "Service", "type": "string" }, "severity": { "title": "Severity", "type": "string" }, "started_at": { "title": "Started At", "type": "string" }, "summary": { "default": "", "title": "Summary", "type": "string" } }, "required": [ "severity", "service", "started_at", "grafana_url" ], "title": "Incident", "type": "object" }, "IncidentsResponse": { "description": "Incident list — or the typed unreachable envelope.\n\n``error`` is present INSTEAD of raising a non-2xx on Grafana failure so\nthe console can render a per-tile monitoring-unavailable state without\nthe whole console call failing. It is the ONLY failure shape this\nendpoint produces for Grafana-side trouble.", "properties": { "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Error" }, "incidents": { "default": [], "items": { "$ref": "#/components/schemas/Incident" }, "title": "Incidents", "type": "array" } }, "title": "IncidentsResponse", "type": "object" }, "IngestRequest": { "description": "Batch ingestion request (LLM extractor → API).\n\nUsed in POST /api/v1/news-updates/ingest.\n\nAttributes:\n updates: Array of NewsUpdateCreate objects\n\nExample:\n {\n \"updates\": [\n {\"title\": \"Update 1\", \"content\": \"Content 1...\", ...},\n {\"title\": \"Update 2\", \"content\": \"Content 2...\", ...}\n ]\n }", "properties": { "updates": { "description": "Array of news updates to ingest", "items": { "$ref": "#/components/schemas/NewsUpdateCreate" }, "minItems": 1, "title": "Updates", "type": "array" } }, "required": [ "updates" ], "title": "IngestRequest", "type": "object" }, "IngestResponse": { "description": "Batch ingestion response.\n\nUsed in POST /api/v1/news-updates/ingest (201 Created).\n\nAttributes:\n status: Status (success, partial_success, error)\n message: Human-readable message\n created_ids: Array of created update UUIDs\n tenant_id: Tenant UUID\n errors: Optional array of error details (for partial_success)\n\nExample (Success):\n {\n \"status\": \"success\",\n \"message\": \"3 news updates ingested successfully\",\n \"created_ids\": [\"uuid1\", \"uuid2\", \"uuid3\"],\n \"tenant_id\": \"tenant-uuid-here\"\n }", "properties": { "created_ids": { "description": "Array of created update UUIDs", "items": { "format": "uuid", "type": "string" }, "title": "Created Ids", "type": "array" }, "errors": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "description": "Optional array of error details", "title": "Errors" }, "message": { "description": "Human-readable message", "examples": [ "3 news updates ingested successfully" ], "title": "Message", "type": "string" }, "status": { "description": "Status (success, partial_success, error)", "examples": [ "success" ], "title": "Status", "type": "string" }, "tenant_id": { "description": "Tenant UUID", "format": "uuid", "title": "Tenant Id", "type": "string" } }, "required": [ "status", "message", "created_ids", "tenant_id" ], "title": "IngestResponse", "type": "object" }, "InsertColumnOp": { "additionalProperties": false, "properties": { "after": { "maxLength": 400, "minLength": 1, "title": "After", "type": "string" }, "header": { "anyOf": [ { "maxLength": 10000, "type": "string" }, { "type": "null" } ], "title": "Header" }, "op": { "const": "insert_column", "title": "Op", "type": "string" }, "sheet": { "anyOf": [ { "maxLength": 400, "type": "string" }, { "type": "null" } ], "title": "Sheet" } }, "required": [ "op", "after" ], "title": "InsertColumnOp", "type": "object" }, "InsertEmbedOp": { "additionalProperties": false, "description": "Place ONE embeddable primitive as a node in a prose body.\n\nGeneric by construction: the comment this story exists for is one value of\n``typed_id``, and every other embeddable prefix rides the same op. The\nNODE shape is derived server-side from the prefix, so a caller can never\nname a node type, an entity table, or an attr set.", "properties": { "facet_slug": { "anyOf": [ { "maxLength": 128, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Facet Slug" }, "op": { "const": "insert_embed", "title": "Op", "type": "string" }, "placement": { "discriminator": { "mapping": { "after_span": "#/components/schemas/AfterSpanPlacement", "append": "#/components/schemas/AppendPlacement", "before_span": "#/components/schemas/BeforeSpanPlacement", "prepend": "#/components/schemas/PrependPlacement", "under_heading": "#/components/schemas/UnderHeadingPlacement" }, "propertyName": "mode" }, "oneOf": [ { "$ref": "#/components/schemas/AppendPlacement" }, { "$ref": "#/components/schemas/PrependPlacement" }, { "$ref": "#/components/schemas/AfterSpanPlacement" }, { "$ref": "#/components/schemas/BeforeSpanPlacement" }, { "$ref": "#/components/schemas/UnderHeadingPlacement" } ], "title": "Placement" }, "typed_id": { "maxLength": 64, "minLength": 3, "title": "Typed Id", "type": "string" } }, "required": [ "op", "typed_id", "placement" ], "title": "InsertEmbedOp", "type": "object" }, "InsertRowOp": { "additionalProperties": false, "properties": { "after": { "maximum": 1048575.0, "minimum": 1.0, "title": "After", "type": "integer" }, "op": { "const": "insert_row", "title": "Op", "type": "string" }, "sheet": { "anyOf": [ { "maxLength": 400, "type": "string" }, { "type": "null" } ], "title": "Sheet" } }, "required": [ "op", "after" ], "title": "InsertRowOp", "type": "object" }, "InsertSlideImageRequest": { "description": "Place an already-stored image into a slide cell, by path OR by file id.\n\n``file_id`` is the additive half (TIDY-15713): a caller that generated an\nimage through a pipeline holds a FILE ID, not a storage path, and the\nmapping from one to the other is not something a model can be expected to\ninvent — the composed infographic's loop invented an attribute shape\ninstead, and four image blocks rendered nothing. The route resolves the id\nto the durable proxy path in the one place that knows how, so no caller\never authors image attributes itself.", "properties": { "alt": { "anyOf": [ { "maxLength": 500, "type": "string" }, { "type": "null" } ], "title": "Alt" }, "cell_path": { "description": "Flat gridCell index within the slide (from read).", "title": "Cell Path", "type": "integer" }, "file_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Id of an already-stored image file; resolved server-side to its durable storage-proxy src. Give this OR src.", "title": "File Id" }, "slide_index": { "title": "Slide Index", "type": "integer" }, "src": { "anyOf": [ { "maxLength": 2000, "minLength": 1, "type": "string" }, { "type": "null" } ], "description": "Stable storage-proxy path of a stored image (/api/v1/storage/user-files/...), e.g. from POST /images/generate. Give this OR file_id.", "title": "Src" } }, "required": [ "slide_index", "cell_path" ], "title": "InsertSlideImageRequest", "type": "object" }, "InsertSlideOp": { "additionalProperties": false, "description": "Insert one new slide after slide number ``after`` (0 = at the front).", "properties": { "after": { "maximum": 500.0, "minimum": 0.0, "title": "After", "type": "integer" }, "layout": { "maxLength": 64, "minLength": 1, "title": "Layout", "type": "string" }, "op": { "const": "insert_slide", "title": "Op", "type": "string" } }, "required": [ "op", "after", "layout" ], "title": "InsertSlideOp", "type": "object" }, "InsertSlideSvgRequest": { "properties": { "alt": { "anyOf": [ { "maxLength": 500, "type": "string" }, { "type": "null" } ], "title": "Alt" }, "cell_path": { "description": "Flat gridCell index within the slide (from read).", "title": "Cell Path", "type": "integer" }, "slide_index": { "title": "Slide Index", "type": "integer" }, "svg": { "maxLength": 200000, "minLength": 1, "title": "Svg", "type": "string" } }, "required": [ "slide_index", "cell_path", "svg" ], "title": "InsertSlideSvgRequest", "type": "object" }, "InsightFacetItem": { "description": "A single Insight Facet in a user's entity overlay.", "properties": { "confidence": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "title": "Confidence" }, "derivation_source_visibility": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Derivation Source Visibility" }, "id": { "format": "uuid", "title": "Id", "type": "string" }, "observation_prefix": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Observation Prefix" }, "owner_attribution": { "anyOf": [ { "$ref": "#/components/schemas/FacetOwnerAttribution" }, { "type": "null" } ], "default": null }, "owner_id": { "format": "uuid", "title": "Owner Id", "type": "string" }, "source_message_ids": { "default": [], "items": { "type": "string" }, "title": "Source Message Ids", "type": "array" }, "text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Text" }, "updated_at": { "format": "date-time", "title": "Updated At", "type": "string" }, "visibility": { "title": "Visibility", "type": "string" } }, "required": [ "id", "visibility", "owner_id", "updated_at" ], "title": "InsightFacetItem", "type": "object" }, "InsightOverlayResponse": { "description": "Entity overlay: the caller's visible Insight Facets for one entity.", "properties": { "cap": { "title": "Cap", "type": "integer" }, "facets": { "items": { "$ref": "#/components/schemas/InsightFacetItem" }, "title": "Facets", "type": "array" }, "used": { "title": "Used", "type": "integer" } }, "required": [ "facets", "cap", "used" ], "title": "InsightOverlayResponse", "type": "object" }, "InsightSeedRequest": { "description": "User-authored belief seeded into the single living Insights facet.\n\nTIDY-12175 / S3 — when the user types a belief into a contact's (empty or\nexisting) Insights facet, the local-first seed CREATE for a\n``note_kind='insight'`` row cannot route through the public ``NoteCreate``\nAPI (insight rows are server-side-only, owned by ``InsightFacetWriter``).\nThis request carries the typed belief so the seed routes through\n``InsightFacetWriter.upsert_living_facet`` instead — the human principal\nauthoring their own substrate.", "properties": { "target_entity_id": { "description": "The entity the belief is about", "format": "uuid", "title": "Target Entity Id", "type": "string" }, "target_entity_type": { "description": "contact | organization | account | … (singular form)", "title": "Target Entity Type", "type": "string" }, "text": { "description": "The user's typed belief", "minLength": 1, "title": "Text", "type": "string" } }, "required": [ "target_entity_type", "target_entity_id", "text" ], "title": "InsightSeedRequest", "type": "object" }, "InsightSeedResponse": { "description": "The single living Insights facet row id after a user seed.", "properties": { "created": { "title": "Created", "type": "boolean" }, "id": { "format": "uuid", "title": "Id", "type": "string" }, "insight_count": { "title": "Insight Count", "type": "integer" } }, "required": [ "id", "created", "insight_count" ], "title": "InsightSeedResponse", "type": "object" }, "InstallItemResponse": { "properties": { "created_state_hash": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Created State Hash" }, "definition_ref": { "title": "Definition Ref", "type": "string" }, "disposition": { "title": "Disposition", "type": "string" }, "item_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Item Id" }, "item_kind": { "title": "Item Kind", "type": "string" }, "item_table": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Item Table" }, "natural_key": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Natural Key" }, "pending_correction": { "default": false, "title": "Pending Correction", "type": "boolean" }, "presence": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Presence" } }, "required": [ "item_kind", "item_table", "item_id", "definition_ref", "natural_key", "created_state_hash", "disposition" ], "title": "InstallItemResponse", "type": "object" }, "InstallListItem": { "properties": { "applied_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Applied At" }, "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "health": { "default": "ok", "title": "Health", "type": "string" }, "id": { "format": "uuid", "title": "Id", "type": "string" }, "item_count": { "title": "Item Count", "type": "integer" }, "modified_count": { "default": 0, "title": "Modified Count", "type": "integer" }, "pending_correction_count": { "default": 0, "title": "Pending Correction Count", "type": "integer" }, "removed_count": { "default": 0, "title": "Removed Count", "type": "integer" }, "status": { "title": "Status", "type": "string" }, "template_slug": { "title": "Template Slug", "type": "string" }, "template_version": { "title": "Template Version", "type": "integer" }, "uninstalled_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Uninstalled At" } }, "required": [ "id", "template_slug", "template_version", "status", "created_at", "item_count" ], "title": "InstallListItem", "type": "object" }, "InstallResponse": { "properties": { "already_installed": { "default": false, "title": "Already Installed", "type": "boolean" }, "applied_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Applied At" }, "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "created_count": { "default": 0, "title": "Created Count", "type": "integer" }, "error_message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error Message" }, "health": { "default": "ok", "title": "Health", "type": "string" }, "id": { "format": "uuid", "title": "Id", "type": "string" }, "items": { "items": { "$ref": "#/components/schemas/InstallItemResponse" }, "title": "Items", "type": "array" }, "modified_count": { "default": 0, "title": "Modified Count", "type": "integer" }, "pending_correction_count": { "default": 0, "title": "Pending Correction Count", "type": "integer" }, "removed_count": { "default": 0, "title": "Removed Count", "type": "integer" }, "renamed_count": { "default": 0, "title": "Renamed Count", "type": "integer" }, "skipped_count": { "default": 0, "title": "Skipped Count", "type": "integer" }, "status": { "title": "Status", "type": "string" }, "template_slug": { "title": "Template Slug", "type": "string" }, "template_version": { "title": "Template Version", "type": "integer" }, "uninstalled_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Uninstalled At" } }, "required": [ "id", "template_slug", "template_version", "status", "created_at" ], "title": "InstallResponse", "type": "object" }, "InstallSuccessRequest": { "properties": { "instance_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Instance Name" }, "user": { "additionalProperties": true, "title": "User", "type": "object" } }, "required": [ "user" ], "title": "InstallSuccessRequest", "type": "object" }, "InstallationManifestRequest": { "properties": { "artifact_version": { "maxLength": 80, "minLength": 1, "title": "Artifact Version", "type": "string" }, "host_instance_id": { "format": "uuid", "title": "Host Instance Id", "type": "string" }, "installation_id": { "format": "uuid", "title": "Installation Id", "type": "string" }, "manifest_sha256": { "pattern": "^[0-9a-f]{64}$", "title": "Manifest Sha256", "type": "string" }, "request_id": { "format": "uuid", "title": "Request Id", "type": "string" } }, "required": [ "installation_id", "host_instance_id", "manifest_sha256", "artifact_version", "request_id" ], "title": "InstallationManifestRequest", "type": "object" }, "InstanceSummary": { "properties": { "config": { "additionalProperties": true, "title": "Config", "type": "object" }, "granted_categories": { "items": { "type": "string" }, "title": "Granted Categories", "type": "array" }, "id": { "title": "Id", "type": "string" }, "instance_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Instance Name" }, "last_served_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Last Served At" }, "plugin_setting_id": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Plugin Setting Id" }, "screen_type": { "title": "Screen Type", "type": "string" }, "tenant_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Tenant Id" }, "trmnl_uuid": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Trmnl Uuid" } }, "required": [ "id", "screen_type", "config" ], "title": "InstanceSummary", "type": "object" }, "InstantiateTemplateRequest": { "properties": { "room_id": { "minLength": 1, "title": "Room Id", "type": "string" } }, "required": [ "room_id" ], "title": "InstantiateTemplateRequest", "type": "object" }, "IntakeFieldDef": { "description": "One intake field the visitor fills in when booking.", "properties": { "key": { "maxLength": 64, "minLength": 1, "pattern": "^[a-z][a-z0-9_]*$", "title": "Key", "type": "string" }, "label": { "maxLength": 200, "minLength": 1, "title": "Label", "type": "string" }, "required": { "default": false, "title": "Required", "type": "boolean" }, "type": { "default": "text", "enum": [ "text", "textarea", "email", "phone", "address" ], "title": "Type", "type": "string" } }, "required": [ "key", "label" ], "title": "IntakeFieldDef", "type": "object" }, "IntegrationFamiliesResponse": { "description": "TIDY-19942 (F18): the ONE integration each of Tidy's own tool families\n(``mail``, ``calendar``, ``drive``, ``source_control``) reaches for the\ncaller — what a tool row's mark and a turn's summary name. A family with\nno live connection, or with two different ones, is absent.", "properties": { "families": { "additionalProperties": { "$ref": "#/components/schemas/McpToolSource" }, "title": "Integration Families", "type": "object" } }, "title": "IntegrationFamiliesResponse", "type": "object" }, "IntegrityResponse": { "properties": { "anchor_date": { "format": "date", "title": "Anchor Date", "type": "string" }, "entry_count": { "title": "Entry Count", "type": "integer" }, "first_entry_id": { "format": "uuid", "title": "First Entry Id", "type": "string" }, "kid": { "title": "Kid", "type": "string" }, "last_entry_id": { "format": "uuid", "title": "Last Entry Id", "type": "string" }, "root_hash": { "title": "Root Hash", "type": "string" }, "signature": { "title": "Signature", "type": "string" }, "tenant_id": { "format": "uuid", "title": "Tenant Id", "type": "string" } }, "required": [ "anchor_date", "tenant_id", "root_hash", "signature", "kid", "first_entry_id", "last_entry_id", "entry_count" ], "title": "IntegrityResponse", "type": "object" }, "IntendedRetentionModel": { "properties": { "basis": { "title": "Basis", "type": "string" }, "count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Count" }, "detail": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Detail" }, "store": { "title": "Store", "type": "string" } }, "required": [ "store", "basis" ], "title": "IntendedRetentionModel", "type": "object" }, "InteractionBatchIn": { "properties": { "batch_id": { "description": "Client-generated idempotency key for the batch.", "title": "Batch Id", "type": "string" }, "events": { "items": { "$ref": "#/components/schemas/InteractionEventIn" }, "title": "Events", "type": "array" } }, "required": [ "batch_id" ], "title": "InteractionBatchIn", "type": "object" }, "InteractionBatchResponse": { "properties": { "accepted": { "title": "Accepted", "type": "integer" }, "duplicate": { "title": "Duplicate", "type": "boolean" } }, "required": [ "accepted", "duplicate" ], "title": "InteractionBatchResponse", "type": "object" }, "InteractionEventIn": { "description": "One client-instrumented interaction event.\n\n``duration_bucket`` is the ONLY temporal field — a coarse bucket, never a\nraw millisecond value (R7 privacy). Reply latency is server-derived and is\nNOT a field here.", "properties": { "duration_bucket": { "anyOf": [ { "enum": [ "lt5s", "5_30s", "30s_2m", "2_10m", "gt10m" ], "type": "string" }, { "type": "null" } ], "title": "Duration Bucket" }, "email_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Email Id" }, "event_type": { "enum": [ "open", "read_time", "reply", "archive", "move", "delete", "snooze", "extract", "label", "unarchive", "search_open", "dismiss" ], "title": "Event Type", "type": "string" }, "occurred_at": { "format": "date-time", "title": "Occurred At", "type": "string" }, "sender_key": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Normalized sender address/domain; lowercased server-side.", "title": "Sender Key" }, "surface": { "enum": [ "web", "android" ], "title": "Surface", "type": "string" }, "thread_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Thread Id" } }, "required": [ "event_type", "occurred_at", "surface" ], "title": "InteractionEventIn", "type": "object" }, "InternalEmailBodiesRequest": { "description": "Read decrypted bodies for a set of email_canonical ids under one principal.\n\nProvide EITHER ``system_job`` (a tenant-scoped system caller — pipeline stage\n/ re-extraction) OR ``principal_account_id`` (the delegating human, account-\nscoped). Supplying both, or two conflicting user identities, is rejected\n(single-principal invariant).", "properties": { "caller": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional caller label for a user principal's audit.", "title": "Caller" }, "email_ids": { "description": "email_canonical UUIDs to read.", "items": { "type": "string" }, "title": "Email Ids", "type": "array" }, "principal_account_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Delegating user's account UUID (account-scoped read).", "title": "Principal Account Id" }, "reason": { "description": "Audit reason for the decrypt.", "title": "Reason", "type": "string" }, "system_job": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "System caller job name (tenant-scoped read).", "title": "System Job" }, "tenant_id": { "description": "Tenant UUID owning the emails.", "title": "Tenant Id", "type": "string" } }, "required": [ "tenant_id", "email_ids", "reason" ], "title": "InternalEmailBodiesRequest", "type": "object" }, "InternalEmailBodiesResponse": { "properties": { "bodies": { "items": { "$ref": "#/components/schemas/InternalEmailBody" }, "title": "Bodies", "type": "array" } }, "required": [ "bodies" ], "title": "InternalEmailBodiesResponse", "type": "object" }, "InternalEmailBody": { "properties": { "body_html_sanitized": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Body Html Sanitized" }, "body_markdown": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Body Markdown" }, "body_text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Body Text" }, "id": { "title": "Id", "type": "string" }, "message_content": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Message Content" }, "message_content_html": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Message Content Html" } }, "required": [ "id" ], "title": "InternalEmailBody", "type": "object" }, "InternalRecordGrantRequest": { "description": "TIDY-16675 — the LIVE-path mint, posted by assistant-service's /resolve.\n\nThe resolver identity here is the one assistant-service AUTHENTICATED\n(``assertCallerInRoom``), which is what makes this leg trustworthy where the\nconnector's live leg is not: the web client's Matrix envelope can never\ncarry a resolver stamp the connector may believe. ``granted_by_account_id``\nmust equal ``member_account_id`` — the human who clicked IS the grantor —\nand a caller that disagrees is refused rather than reinterpreted.", "properties": { "action": { "maxLength": 256, "title": "Action", "type": "string" }, "agent_account_id": { "description": "The virtual employee's account UUID", "title": "Agent Account Id", "type": "string" }, "conversation_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Required for scope=session", "title": "Conversation Id" }, "granted_by_account_id": { "description": "Must equal member_account_id", "title": "Granted By Account Id", "type": "string" }, "matched_rule_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Matched Rule Id" }, "member_account_id": { "description": "The authenticated resolver", "title": "Member Account Id", "type": "string" }, "request_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Request Id" }, "scope": { "description": "session | always ('once' is never stored)", "title": "Scope", "type": "string" }, "target": { "default": "", "maxLength": 256, "title": "Target", "type": "string" }, "tenant_id": { "description": "Tenant UUID", "title": "Tenant Id", "type": "string" } }, "required": [ "tenant_id", "agent_account_id", "member_account_id", "granted_by_account_id", "scope", "action" ], "title": "InternalRecordGrantRequest", "type": "object" }, "IntrospectRequest": { "properties": { "token": { "title": "Token", "type": "string" }, "token_type_hint": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Token Type Hint" } }, "required": [ "token" ], "title": "IntrospectRequest", "type": "object" }, "IntrospectResponse": { "description": "RFC 7662 introspection response.\n\nPer the RFC, inactive tokens return only `{\"active\": false}`; active tokens\ninclude additional claim fields.", "properties": { "active": { "title": "Active", "type": "boolean" }, "aud": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Aud" }, "exp": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Exp" }, "iat": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Iat" }, "jti": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Jti" }, "scope": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Scope" }, "sub": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Sub" }, "tenant_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Tenant Id" }, "typ": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Typ" } }, "required": [ "active" ], "title": "IntrospectResponse", "type": "object" }, "InvitationAcceptResponse": { "description": "Response model for accepting a tenant invitation.", "properties": { "role": { "description": "Role assigned in the tenant", "title": "Role", "type": "string" }, "tenant_id": { "description": "UUID of the tenant joined", "title": "Tenant Id", "type": "string" }, "tenant_name": { "description": "Display name of the tenant joined", "title": "Tenant Name", "type": "string" } }, "required": [ "tenant_id", "tenant_name", "role" ], "title": "InvitationAcceptResponse", "type": "object" }, "InvitationItem": { "properties": { "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "email": { "title": "Email", "type": "string" }, "expires_at": { "format": "date-time", "title": "Expires At", "type": "string" }, "id": { "title": "Id", "type": "string" }, "status": { "title": "Status", "type": "string" } }, "required": [ "id", "email", "status", "created_at", "expires_at" ], "title": "InvitationItem", "type": "object" }, "InvitationPreviewResponse": { "description": "Public view of a workspace invitation for its signed-out landing page (TIDY-19981).", "properties": { "code": { "description": "7-character invitation code", "title": "Code", "type": "string" }, "email_hint": { "description": "Masked address the invitation was sent to", "title": "Email Hint", "type": "string" }, "expires_at": { "description": "Invitation expiry timestamp", "format": "date-time", "title": "Expires At", "type": "string" }, "inviter_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Name of the member who sent it", "title": "Inviter Name" }, "role": { "description": "Role assigned on accept", "title": "Role", "type": "string" }, "status": { "description": "Whether the invitation can still be accepted", "enum": [ "pending", "accepted", "expired", "revoked" ], "title": "Status", "type": "string" }, "tenant_name": { "description": "Display name of the inviting workspace", "title": "Tenant Name", "type": "string" } }, "required": [ "code", "tenant_name", "role", "email_hint", "status", "expires_at" ], "title": "InvitationPreviewResponse", "type": "object" }, "InvitationResponse": { "description": "Response model for invitation creation.\n\nUsed in:\n - POST /api/v1/tenants/{id}/members (201 Created response)\n\nAttributes:\n invitation_code: Unique 7-character code for accepting invitation\n - Format: Alphanumeric (uppercase A-Z, 0-9)\n - Example: \"ABC1234\"\n - Used by invitee to accept membership\n email: Email address of invitee (from request)\n role: Role to be assigned upon acceptance (from request)\n expires_at: Expiration timestamp (ISO 8601)\n - Invitation expires after 7 days\n - Expired invitations cannot be accepted\n - Example: \"2025-11-15T14:30:22.123Z\" (if created 2025-11-08)\n\nExample (Response Body):\n {\n \"invitation_code\": \"ABC1234\",\n \"email\": \"alice@example.com\",\n \"role\": \"Member\",\n \"expires_at\": \"2025-11-15T14:30:22.123Z\"\n }\n\nRelated: FR-008, KCC-1121, T048", "example": { "email": "alice@example.com", "expires_at": "2025-11-15T14:30:22.123Z", "invitation_code": "ABC1234", "role": "Member" }, "properties": { "email": { "description": "Email address of invitee", "examples": [ "alice@example.com" ], "title": "Email", "type": "string" }, "expires_at": { "description": "Invitation expiration timestamp (ISO 8601, expires after 7 days)", "examples": [ "2025-11-15T14:30:22.123Z" ], "format": "date-time", "title": "Expires At", "type": "string" }, "invitation_code": { "description": "Unique 7-character invitation code (alphanumeric, uppercase)", "examples": [ "ABC1234", "XYZ7890" ], "maxLength": 7, "minLength": 7, "pattern": "^[A-Z0-9]{7}$", "title": "Invitation Code", "type": "string" }, "role": { "description": "Role to be assigned upon acceptance", "enum": [ "Member", "Viewer" ], "examples": [ "Member", "Viewer" ], "title": "Role", "type": "string" } }, "required": [ "invitation_code", "email", "role", "expires_at" ], "title": "InvitationResponse", "type": "object" }, "InviteExternalRequest": { "properties": { "email": { "format": "email", "title": "Email", "type": "string" }, "expires_in_days": { "anyOf": [ { "maximum": 365.0, "minimum": 1.0, "type": "integer" }, { "type": "null" } ], "title": "Expires In Days" }, "scoped_additional_room_ids": { "items": { "type": "string" }, "title": "Scoped Additional Room Ids", "type": "array" } }, "required": [ "email" ], "title": "InviteExternalRequest", "type": "object" }, "InviteExternalResponse": { "properties": { "expires_at": { "format": "date-time", "title": "Expires At", "type": "string" }, "guest_account_id": { "format": "uuid", "title": "Guest Account Id", "type": "string" }, "invited_email": { "title": "Invited Email", "type": "string" }, "scoped_room_ids": { "items": { "type": "string" }, "title": "Scoped Room Ids", "type": "array" } }, "required": [ "guest_account_id", "invited_email", "scoped_room_ids", "expires_at" ], "title": "InviteExternalResponse", "type": "object" }, "InviteGenerationEligibilityResponse": { "description": "Per-user gate + allowance state that drives the Invites page + banner.", "properties": { "can_generate": { "title": "Can Generate", "type": "boolean" }, "effective_allowance": { "title": "Effective Allowance", "type": "integer" }, "enablement_key": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Enablement Key" }, "is_subscribed": { "title": "Is Subscribed", "type": "boolean" }, "master_enabled": { "title": "Master Enabled", "type": "boolean" }, "remaining": { "title": "Remaining", "type": "integer" }, "requires_subscription": { "title": "Requires Subscription", "type": "boolean" }, "used": { "title": "Used", "type": "integer" } }, "required": [ "master_enabled", "requires_subscription", "is_subscribed", "can_generate", "remaining", "effective_allowance", "used" ], "title": "InviteGenerationEligibilityResponse", "type": "object" }, "InviteListResponse": { "description": "Response model for listing pending invites.", "properties": { "invites": { "items": { "$ref": "#/components/schemas/PendingInvite" }, "title": "Invites", "type": "array" }, "total": { "description": "Total number of pending invites", "title": "Total", "type": "integer" } }, "required": [ "total" ], "title": "InviteListResponse", "type": "object" }, "InviteMemberRequest": { "properties": { "account_id": { "maxLength": 64, "minLength": 1, "title": "Account Id", "type": "string" } }, "required": [ "account_id" ], "title": "InviteMemberRequest", "type": "object" }, "InviteResponseRequest": { "description": "Request model for responding to a calendar invite.", "example": { "action": "accept", "comment": "Looking forward to it!", "send_email": true }, "properties": { "action": { "description": "Response action: accept, decline, maybe, or tentative", "enum": [ "accept", "decline", "maybe", "tentative" ], "examples": [ "accept", "decline", "maybe" ], "title": "Action", "type": "string" }, "comment": { "anyOf": [ { "maxLength": 1000, "type": "string" }, { "type": "null" } ], "description": "Optional comment to include in response", "title": "Comment" }, "send_email": { "default": true, "description": "Whether to send ICS REPLY via email to organizer", "title": "Send Email", "type": "boolean" } }, "required": [ "action" ], "title": "InviteResponseRequest", "type": "object" }, "InviteResponseResponse": { "description": "Response model after responding to a calendar invite.", "example": { "event_id": "550e8400-e29b-41d4-a716-446655440000", "event_status": "approved", "ics_uid": "abc123@google.com", "our_partstat": "ACCEPTED", "response_sent": true, "response_sent_at": "2024-01-15T10:30:00Z" }, "properties": { "event_id": { "description": "Calendar event UUID", "title": "Event Id", "type": "string" }, "event_status": { "description": "Updated event status in calendar", "title": "Event Status", "type": "string" }, "ics_uid": { "description": "ICS UID of the event", "title": "Ics Uid", "type": "string" }, "our_partstat": { "description": "Our participation status after response", "enum": [ "NEEDS-ACTION", "ACCEPTED", "DECLINED", "TENTATIVE" ], "title": "Our Partstat", "type": "string" }, "response_sent": { "description": "Whether ICS REPLY was sent via email", "title": "Response Sent", "type": "boolean" }, "response_sent_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "description": "Timestamp when ICS REPLY was sent", "title": "Response Sent At" } }, "required": [ "event_id", "ics_uid", "our_partstat", "response_sent", "event_status" ], "title": "InviteResponseResponse", "type": "object" }, "InviteSendCapabilityResponse": { "description": "Whether the tenant's invite-send source can physically send (TIDY-17050 D5).\n\nComputed from the same source resolution and send decision the actual\nsend path uses, so the UI's gate and the backend's send never disagree.", "properties": { "can_send": { "description": "Whether an ICS invite can actually be sent", "title": "Can Send", "type": "boolean" }, "email_address": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The From address an invite would carry", "title": "Email Address" }, "email_source_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The source an invite would send from", "title": "Email Source Id" }, "provider": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The send source's provider type", "title": "Provider" }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Why sending is impossible: invalid_source (named source missing/inactive), no_active_source (no active email source at all), or no_send_credentials (no SMTP credentials and no Zoho connection). None when can_send is true.", "title": "Reason" }, "send_method": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "How an invite would be sent: smtp or zoho; None when it cannot", "title": "Send Method" } }, "required": [ "can_send" ], "title": "InviteSendCapabilityResponse", "type": "object" }, "InviteToConversationChannelRequest": { "properties": { "invitee_account_ids": { "items": { "type": "string" }, "maxItems": 20, "minItems": 1, "title": "Invitee Account Ids", "type": "array" }, "message": { "$ref": "#/components/schemas/SendMatrixRoomMessageRequest" } }, "required": [ "invitee_account_ids", "message" ], "title": "InviteToConversationChannelRequest", "type": "object" }, "InvoiceCreateRequest": { "properties": { "amount_usd": { "minimum": 0.0, "title": "Amount Usd", "type": "number" }, "external_amount_usd": { "default": 0, "minimum": 0.0, "title": "External Amount Usd", "type": "number" }, "notes": { "anyOf": [ { "maxLength": 1000, "type": "string" }, { "type": "null" } ], "title": "Notes" }, "period_end": { "format": "date", "title": "Period End", "type": "string" }, "period_start": { "format": "date", "title": "Period Start", "type": "string" }, "provider": { "maxLength": 50, "minLength": 1, "title": "Provider", "type": "string" } }, "required": [ "provider", "period_start", "period_end", "amount_usd" ], "title": "InvoiceCreateRequest", "type": "object" }, "InvoiceItem": { "properties": { "amount_cents": { "title": "Amount Cents", "type": "integer" }, "date": { "format": "date-time", "title": "Date", "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "id": { "title": "Id", "type": "string" }, "pdf_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Pdf Url" }, "status": { "title": "Status", "type": "string" } }, "required": [ "id", "date", "amount_cents", "status" ], "title": "InvoiceItem", "type": "object" }, "InvoiceResponse": { "properties": { "amount_usd": { "title": "Amount Usd", "type": "number" }, "external_amount_usd": { "title": "External Amount Usd", "type": "number" }, "id": { "title": "Id", "type": "string" }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Notes" }, "period_end": { "format": "date", "title": "Period End", "type": "string" }, "period_start": { "format": "date", "title": "Period Start", "type": "string" }, "provider": { "title": "Provider", "type": "string" } }, "required": [ "id", "provider", "period_start", "period_end", "amount_usd", "external_amount_usd" ], "title": "InvoiceResponse", "type": "object" }, "InvoicesResponse": { "properties": { "invoices": { "items": { "$ref": "#/components/schemas/InvoiceItem" }, "title": "Invoices", "type": "array" } }, "required": [ "invoices" ], "title": "InvoicesResponse", "type": "object" }, "InvokeActionRequest": { "description": "Request body for ``POST /api/v1/facet-actions/invoke``.", "properties": { "call_in_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Client-supplied invocation UUID; server generates if absent", "title": "Call In Id" }, "chain": { "anyOf": [ { "items": { "$ref": "#/components/schemas/ChainAction" }, "type": "array" }, { "type": "null" } ], "description": "Automation verb chain to apply per subject", "title": "Chain" }, "confirm": { "default": false, "description": "False -> preview the affected set; True -> execute the chain", "title": "Confirm", "type": "boolean" }, "facet_slug": { "description": "Facet definition slug owning the action", "title": "Facet Slug", "type": "string" }, "handler": { "description": "Handler ref: 'builtin:' | 'workflow:' | 'action:' | 'rule:' | 'automation:chain' | a legacy client kind ('toggle_boolean' | 'update_property' | 'delete_row' | 'duplicate_row')", "title": "Handler", "type": "string" }, "params": { "description": "Param specs from the action definition", "items": { "$ref": "#/components/schemas/ActionParamSpec" }, "title": "Params", "type": "array" }, "prompt_values": { "additionalProperties": true, "description": "Values collected by the client prompt modal", "title": "Prompt Values", "type": "object" }, "subjects": { "description": "1..N subject row UUIDs (multi-select)", "items": { "type": "string" }, "title": "Subjects", "type": "array" }, "subjects_filter": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "View-header mode: the current view filter (condition group)", "title": "Subjects Filter" } }, "required": [ "facet_slug", "handler" ], "title": "InvokeActionRequest", "type": "object" }, "InvokeActionResponse": { "description": "Response body for ``POST /api/v1/facet-actions/invoke``.", "properties": { "affected_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Affected Count" }, "affected_item_ids": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Affected Item Ids" }, "call_in_id": { "title": "Call In Id", "type": "string" }, "message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Message" }, "missing_params": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Missing Params" }, "per_item_outcomes": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "title": "Per Item Outcomes" }, "prompt_needed": { "anyOf": [ { "items": { "$ref": "#/components/schemas/PromptNeededInput" }, "type": "array" }, { "type": "null" } ], "title": "Prompt Needed" }, "resolved_preview": { "anyOf": [ { "items": { "$ref": "#/components/schemas/ResolvedParamPreview" }, "type": "array" }, { "type": "null" } ], "title": "Resolved Preview" }, "result": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Result" }, "status": { "enum": [ "ok", "queued", "noop", "error", "prompt_needed", "preview" ], "title": "Status", "type": "string" } }, "required": [ "call_in_id", "status" ], "title": "InvokeActionResponse", "type": "object" }, "IrreversibleOutput": { "properties": { "detail": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Detail" }, "output_index": { "title": "Output Index", "type": "integer" }, "point_of_no_return": { "default": true, "title": "Point Of No Return", "type": "boolean" }, "type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Type" } }, "required": [ "output_index" ], "title": "IrreversibleOutput", "type": "object" }, "JobDetailResponse": { "properties": { "account_id": { "format": "uuid", "title": "Account Id", "type": "string" }, "audio_minutes": { "title": "Audio Minutes", "type": "number" }, "co_requesters": { "items": { "$ref": "#/components/schemas/CoRequester" }, "title": "Co Requesters", "type": "array" }, "completed_at": { "title": "Completed At" }, "completed_count": { "title": "Completed Count", "type": "integer" }, "created_at": { "title": "Created At" }, "estimated_cost_usd": { "title": "Estimated Cost Usd", "type": "number" }, "failed_count": { "title": "Failed Count", "type": "integer" }, "is_auto_transcribe": { "title": "Is Auto Transcribe", "type": "boolean" }, "job_id": { "format": "uuid", "title": "Job Id", "type": "string" }, "provider": { "title": "Provider", "type": "string" }, "provider_model": { "title": "Provider Model", "type": "string" }, "related_cut_ids": { "items": { "format": "uuid", "type": "string" }, "title": "Related Cut Ids", "type": "array" }, "requested_count": { "title": "Requested Count", "type": "integer" }, "status": { "title": "Status", "type": "string" }, "submitted_at": { "title": "Submitted At" }, "tenant_id": { "format": "uuid", "title": "Tenant Id", "type": "string" } }, "required": [ "job_id", "tenant_id", "account_id", "provider", "provider_model", "status", "requested_count", "completed_count", "failed_count", "is_auto_transcribe", "submitted_at", "completed_at", "created_at", "audio_minutes", "estimated_cost_usd", "co_requesters", "related_cut_ids" ], "title": "JobDetailResponse", "type": "object" }, "JoinHuddleRequest": { "properties": { "audio": { "default": true, "title": "Audio", "type": "boolean" }, "client_kind": { "default": "web", "pattern": "^(web|android|ios)$", "title": "Client Kind", "type": "string" }, "ring_join_token": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Ring Join Token" }, "video": { "default": false, "title": "Video", "type": "boolean" } }, "title": "JoinHuddleRequest", "type": "object" }, "JoinRequestCreateRequest": { "properties": { "message": { "anyOf": [ { "maxLength": 500, "type": "string" }, { "type": "null" } ], "title": "Message" } }, "title": "JoinRequestCreateRequest", "type": "object" }, "JoinRequestDecisionRequest": { "properties": { "approve": { "title": "Approve", "type": "boolean" }, "reason": { "anyOf": [ { "maxLength": 500, "type": "string" }, { "type": "null" } ], "title": "Reason" } }, "required": [ "approve" ], "title": "JoinRequestDecisionRequest", "type": "object" }, "JoinRequestResponse": { "properties": { "created_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Created At" }, "decided_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Decided At" }, "decided_by": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Decided By" }, "id": { "title": "Id", "type": "string" }, "message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Message" }, "requester_id": { "title": "Requester Id", "type": "string" }, "room_id": { "title": "Room Id", "type": "string" }, "status": { "title": "Status", "type": "string" } }, "required": [ "id", "room_id", "requester_id", "status" ], "title": "JoinRequestResponse", "type": "object" }, "JournalAppendMarkdownRequest": { "properties": { "markdown": { "description": "Markdown content to splice into the journal body.", "minLength": 1, "title": "Markdown", "type": "string" }, "position": { "default": "append", "description": "Where to insert the new content. Defaults to 'append'.", "pattern": "^(append|prepend)$", "title": "Position", "type": "string" } }, "required": [ "markdown" ], "title": "JournalAppendMarkdownRequest", "type": "object" }, "JournalCreateRequest": { "description": "Request body for creating a journal.", "properties": { "feed_target_date": { "description": "Date to create journal for", "format": "date", "title": "Feed Target Date", "type": "string" }, "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Client-provided deterministic journal UUID for idempotent creates", "title": "Id" }, "journal_type": { "default": "daily", "description": "daily|weekly|monthly", "title": "Journal Type", "type": "string" }, "plain_text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional plain-text body", "title": "Plain Text" }, "tags": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "description": "Tag slugs", "title": "Tags" }, "template_config": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "Template configuration", "title": "Template Config" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional title override", "title": "Title" }, "visibility": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "private|shared|tenant", "title": "Visibility" }, "yaml_frontmatter": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "YAML frontmatter as JSON", "title": "Yaml Frontmatter" } }, "required": [ "feed_target_date" ], "title": "JournalCreateRequest", "type": "object" }, "JournalEmbedBlockRequest": { "properties": { "primitive_id": { "description": "Typed id (e.g. A-, C-) or bare uuid of the row to embed.", "minLength": 1, "title": "Primitive Id", "type": "string" }, "primitive_type": { "description": "Kind of row to embed: note, task/activity, contact, event/calendar_event, organization, journal, or reminder.", "minLength": 1, "title": "Primitive Type", "type": "string" } }, "required": [ "primitive_type", "primitive_id" ], "title": "JournalEmbedBlockRequest", "type": "object" }, "JournalId": { "description": "Typed primitive ID for journals (prefix 'J').", "examples": [ "J-550e8400-e29b-41d4-a716-446655440000" ], "pattern": "^J-[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "title": "JournalId", "type": "string", "x-tidy-typed-id-prefix": "J", "x-tidy-typed-id-table": "journals" }, "JournalListItem": { "description": "Summary item for journal page listing.", "properties": { "feed_target_date": { "format": "date", "title": "Feed Target Date", "type": "string" }, "has_content": { "title": "Has Content", "type": "boolean" }, "id": { "title": "Id", "type": "string" }, "slug": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Slug" }, "title": { "title": "Title", "type": "string" } }, "required": [ "id", "feed_target_date", "title", "has_content" ], "title": "JournalListItem", "type": "object" }, "JournalListResponse": { "description": "Response for listing journals.", "properties": { "journals": { "items": { "$ref": "#/components/schemas/JournalResponse" }, "title": "Journals", "type": "array" }, "total": { "default": 0, "title": "Total", "type": "integer" } }, "title": "JournalListResponse", "type": "object" }, "JournalResponse": { "description": "Journal entry returned by API endpoints.", "properties": { "aliases": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "default": null, "description": "Page aliases (resolution keys, not display labels)", "title": "Aliases" }, "banner_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Page banner image URL/ref", "title": "Banner Url" }, "body_markdown": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "GET /journals/by-id/{id} only: the body rendered as Markdown — `-` bullets, `1.` ordered items, `- [ ]`/`- [x]` tasks, pipe tables with a header row, fenced code with its language, `>` quotes, `---` rules — in the dialect body_edit and markdown writes parse. Null on other routes, and when the body could not be read.", "title": "Body Markdown" }, "body_markdown_unsupported": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "default": null, "description": "GET /journals/by-id/{id} only: node types and marks (`mark:underline`) the Markdown rendering could not express. Their text is still rendered; only the wrapper is lost. Empty when the Markdown is complete.", "title": "Body Markdown Unsupported" }, "created_at": { "description": "Creation timestamp", "format": "date-time", "title": "Created At", "type": "string" }, "custom_properties": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "description": "Tracker/facet property bag", "title": "Custom Properties" }, "embeds": { "anyOf": [ { "items": { "$ref": "#/components/schemas/DocumentEmbed" }, "type": "array" }, { "type": "null" } ], "default": null, "description": "GET /journals/by-id/{id} only: every embed in the body in document order — saved database views, charts, dashboards and item cards. Null on other routes, and when the body could not be read.", "title": "Embeds" }, "facets": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "default": null, "description": "Facet slugs", "title": "Facets" }, "feed_target_date": { "description": "Date this journal is anchored to", "format": "date", "title": "Feed Target Date", "type": "string" }, "icon": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Page icon — serialized IconValue", "title": "Icon" }, "icon_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Resolved image ref for image-kind icons", "title": "Icon Url" }, "id": { "description": "Unique journal identifier (UUID)", "title": "Id", "type": "string" }, "journal_type": { "default": "daily", "description": "daily|weekly|monthly", "title": "Journal Type", "type": "string" }, "notebook_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Parent notebook UUID", "title": "Notebook Id" }, "owner_id": { "description": "Journal owner account id (UUID)", "title": "Owner Id", "type": "string" }, "plain_text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Plain-text for search indexing", "title": "Plain Text" }, "short_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Display short ID (the journal's date in YYYY-MM-DD)", "title": "Short Id" }, "slug": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "URL-safe slug", "title": "Slug" }, "tags": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "default": null, "description": "Tags", "title": "Tags" }, "template_config": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "description": "Template configuration", "title": "Template Config" }, "template_notice": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "One-time notice when the bound journal template could not be applied", "title": "Template Notice" }, "tenant_id": { "description": "Associated tenant identifier (UUID)", "title": "Tenant Id", "type": "string" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Journal title (usually the date)", "title": "Title" }, "updated_at": { "description": "Last modification timestamp", "format": "date-time", "title": "Updated At", "type": "string" }, "version": { "default": 0, "description": "Optimistic locking version", "title": "Version", "type": "integer" }, "visibility": { "default": "private", "description": "private|shared|tenant", "title": "Visibility", "type": "string" }, "yjs_state": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Base64-encoded Yjs CRDT state", "title": "Yjs State" } }, "required": [ "id", "tenant_id", "owner_id", "feed_target_date", "created_at", "updated_at" ], "title": "JournalResponse", "type": "object" }, "JournalTemplateSectionRequest": { "properties": { "content_markdown": { "description": "The section's body as Markdown, without the heading. `![[R-]]` embeds a record live.", "maxLength": 16000, "minLength": 1, "title": "Content Markdown", "type": "string" }, "heading": { "description": "The section's heading, plain text. A section already under it is replaced.", "maxLength": 120, "minLength": 1, "title": "Heading", "type": "string" }, "journal_type": { "default": "daily", "title": "Journal Type", "type": "string" }, "name": { "anyOf": [ { "maxLength": 200, "minLength": 1, "type": "string" }, { "type": "null" } ], "description": "The name of the member's new template, when one is made.", "title": "Name" } }, "required": [ "heading", "content_markdown" ], "title": "JournalTemplateSectionRequest", "type": "object" }, "JournalTemplateSectionResponse": { "properties": { "changed": { "title": "Changed", "type": "boolean" }, "journal_type": { "title": "Journal Type", "type": "string" }, "member_account_id": { "title": "Member Account Id", "type": "string" }, "section": { "title": "Section", "type": "string" }, "template_created": { "title": "Template Created", "type": "boolean" }, "template_id": { "title": "Template Id", "type": "string" }, "template_name": { "title": "Template Name", "type": "string" } }, "required": [ "journal_type", "member_account_id", "template_id", "template_name", "template_created", "section", "changed" ], "title": "JournalTemplateSectionResponse", "type": "object" }, "JournalTemplateTierState": { "properties": { "template_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Template Id" }, "tier": { "title": "Tier", "type": "string" }, "winning": { "title": "Winning", "type": "boolean" } }, "required": [ "tier", "template_id", "winning" ], "title": "JournalTemplateTierState", "type": "object" }, "JournalTemplateWidgetUpdate": { "properties": { "enabled": { "title": "Enabled", "type": "boolean" }, "journal_type": { "default": "daily", "title": "Journal Type", "type": "string" }, "widget_id": { "title": "Widget Id", "type": "string" } }, "required": [ "widget_id", "enabled" ], "title": "JournalTemplateWidgetUpdate", "type": "object" }, "JournalTemplateWidgetsResponse": { "properties": { "derived_from_template": { "title": "Derived From Template", "type": "boolean" }, "journal_type": { "title": "Journal Type", "type": "string" }, "template_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Template Id" }, "template_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Template Name" }, "tiers": { "items": { "$ref": "#/components/schemas/JournalTemplateTierState" }, "title": "Tiers", "type": "array" }, "widgets": { "items": { "$ref": "#/components/schemas/JournalWidgetState" }, "title": "Widgets", "type": "array" } }, "required": [ "journal_type", "template_id", "derived_from_template", "widgets", "tiers" ], "title": "JournalTemplateWidgetsResponse", "type": "object" }, "JournalUpdateRequest": { "description": "Request body for updating a journal (partial update).", "properties": { "aliases": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "description": "Page aliases (resolution keys, not display labels)", "title": "Aliases" }, "banner_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Page banner image URL/ref", "title": "Banner Url" }, "custom_properties": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "Tracker/facet property bag", "title": "Custom Properties" }, "facets": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "description": "Facet slugs", "title": "Facets" }, "icon": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Page icon — serialized IconValue", "title": "Icon" }, "icon_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Resolved image ref for image-kind icons", "title": "Icon Url" }, "plain_text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Plain-text for search indexing", "title": "Plain Text" }, "tags": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "description": "Tags", "title": "Tags" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Journal title", "title": "Title" }, "yaml_frontmatter": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "YAML frontmatter as JSON", "title": "Yaml Frontmatter" } }, "title": "JournalUpdateRequest", "type": "object" }, "JournalWidgetState": { "properties": { "enabled": { "title": "Enabled", "type": "boolean" }, "title": { "title": "Title", "type": "string" }, "widget_id": { "title": "Widget Id", "type": "string" } }, "required": [ "widget_id", "title", "enabled" ], "title": "JournalWidgetState", "type": "object" }, "JourneyCounts": { "properties": { "authored_rules": { "default": 0, "title": "Authored Rules", "type": "integer" }, "militia_pending": { "default": 0, "title": "Militia Pending", "type": "integer" }, "seeded_rules": { "default": 0, "title": "Seeded Rules", "type": "integer" }, "suggestions_pending": { "default": 0, "title": "Suggestions Pending", "type": "integer" }, "workflow_rules": { "default": 0, "title": "Workflow Rules", "type": "integer" } }, "title": "JourneyCounts", "type": "object" }, "JourneyStateResponse": { "properties": { "counts": { "$ref": "#/components/schemas/JourneyCounts" }, "first_run_seen": { "default": false, "title": "First Run Seen", "type": "boolean" }, "founded_packs": { "items": { "type": "string" }, "title": "Founded Packs", "type": "array" }, "stage": { "title": "Stage", "type": "integer" } }, "required": [ "stage", "founded_packs", "counts" ], "title": "JourneyStateResponse", "type": "object" }, "JudgmentRequest": { "description": "TIDY-17535 — one borderline call for the classifier to answer.", "properties": { "command": { "anyOf": [ { "maxLength": 4096, "type": "string" }, { "type": "null" } ], "title": "Command" }, "conversation_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Conversation Id" }, "kind": { "description": "command_execution_approval | file_change_approval | ...", "maxLength": 64, "title": "Kind", "type": "string" }, "paths": { "anyOf": [ { "items": { "type": "string" }, "maxItems": 32, "type": "array" }, { "type": "null" } ], "title": "Paths" }, "request_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Request Id" }, "tool_name": { "anyOf": [ { "maxLength": 256, "type": "string" }, { "type": "null" } ], "title": "Tool Name" } }, "required": [ "kind" ], "title": "JudgmentRequest", "type": "object" }, "JudgmentResponse": { "properties": { "confidence": { "title": "Confidence", "type": "number" }, "decision": { "description": "allow | escalate", "title": "Decision", "type": "string" }, "model": { "title": "Model", "type": "string" }, "reason": { "title": "Reason", "type": "string" } }, "required": [ "decision", "confidence", "reason", "model" ], "title": "JudgmentResponse", "type": "object" }, "JunkKeyOut": { "properties": { "account_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Account Id" }, "bare": { "title": "Bare", "type": "string" }, "email_address": { "title": "Email Address", "type": "string" }, "email_count": { "default": 0, "title": "Email Count", "type": "integer" }, "id": { "title": "Id", "type": "string" }, "last_seen_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Last Seen At" }, "screening_status": { "title": "Screening Status", "type": "string" } }, "required": [ "id", "email_address", "bare", "screening_status" ], "title": "JunkKeyOut", "type": "object" }, "JwksResponse": { "properties": { "keys": { "items": { "additionalProperties": true, "type": "object" }, "title": "Keys", "type": "array" } }, "required": [ "keys" ], "title": "JwksResponse", "type": "object" }, "KeyEscrowBootstrapResponse": { "description": "POST bootstrap response — the account's one recovery key + metadata.", "properties": { "created": { "title": "Created", "type": "boolean" }, "cross_signing_bootstrapped": { "title": "Cross Signing Bootstrapped", "type": "boolean" }, "key_backup_version": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Key Backup Version" }, "recovery_key": { "title": "Recovery Key", "type": "string" } }, "required": [ "recovery_key", "cross_signing_bootstrapped", "created" ], "title": "KeyEscrowBootstrapResponse", "type": "object" }, "KeyEscrowMaterialResponse": { "description": "GET response — the decrypted recovery key + metadata.", "properties": { "cross_signing_bootstrapped": { "title": "Cross Signing Bootstrapped", "type": "boolean" }, "key_backup_version": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Key Backup Version" }, "recovery_key": { "title": "Recovery Key", "type": "string" } }, "required": [ "recovery_key", "cross_signing_bootstrapped" ], "title": "KeyEscrowMaterialResponse", "type": "object" }, "KeyEscrowStashRequest": { "description": "PUT /api/v1/matrix/key-escrow body.", "properties": { "cross_signing_bootstrapped": { "default": false, "title": "Cross Signing Bootstrapped", "type": "boolean" }, "key_backup_version": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Key Backup Version" }, "recovery_key": { "title": "Recovery Key", "type": "string" } }, "required": [ "recovery_key" ], "title": "KeyEscrowStashRequest", "type": "object" }, "KeyEscrowStatusResponse": { "description": "PUT response — status only, NEVER the recovery key.", "properties": { "cross_signing_bootstrapped": { "title": "Cross Signing Bootstrapped", "type": "boolean" }, "escrowed": { "title": "Escrowed", "type": "boolean" }, "key_backup_version": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Key Backup Version" }, "updated_at": { "format": "date-time", "title": "Updated At", "type": "string" } }, "required": [ "escrowed", "cross_signing_bootstrapped", "updated_at" ], "title": "KeyEscrowStatusResponse", "type": "object" }, "KeyRequirement": { "description": "Names one carried skill version requires that only a secret file\nanswers — the skill's own variables, no catalogue connection's\n(TIDY-20019 F9). Met by exactly one of the person's own secret files lent\nto the employee, per name, on every harness that carries it.", "properties": { "file_offers": { "items": { "$ref": "#/components/schemas/PluginAccessFileOffer" }, "title": "File Offers", "type": "array" }, "file_sources": { "items": { "$ref": "#/components/schemas/PluginAccessFileSource" }, "title": "File Sources", "type": "array" }, "grant_hint": { "title": "Grant Hint", "type": "string" }, "met_by": { "anyOf": [ { "const": "secret_file", "type": "string" }, { "type": "null" } ], "default": null, "title": "Met By" }, "required": { "title": "Required", "type": "boolean" }, "required_env": { "items": { "type": "string" }, "title": "Required Env", "type": "array" }, "runtimes": { "items": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "title": "Runtimes", "type": "array" }, "skill": { "title": "Skill", "type": "string" }, "skill_id": { "title": "Skill Id", "type": "string" }, "skill_versions": { "items": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" }, { "type": "null" } ] }, "type": "array" }, "title": "Skill Versions", "type": "array" }, "skills": { "items": { "type": "string" }, "title": "Skills", "type": "array" }, "status": { "enum": [ "met", "ambiguous", "needs_access" ], "title": "Status", "type": "string" }, "unreachable": { "items": { "type": "string" }, "title": "Unreachable", "type": "array" }, "version": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Version" } }, "required": [ "skill_id", "skill", "skills", "skill_versions", "required", "required_env", "runtimes", "status", "grant_hint" ], "title": "KeyRequirement", "type": "object" }, "KeywordAlertResponse": { "description": "One keyword alert row. Mirrors ``user_keyword_alerts`` columns.", "properties": { "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "enabled": { "title": "Enabled", "type": "boolean" }, "id": { "format": "uuid", "title": "Id", "type": "string" }, "keyword": { "title": "Keyword", "type": "string" }, "updated_at": { "format": "date-time", "title": "Updated At", "type": "string" } }, "required": [ "id", "keyword", "enabled", "created_at", "updated_at" ], "title": "KeywordAlertResponse", "type": "object" }, "KillSwitchRequest": { "properties": { "expected_config_version": { "description": "The configuration the caller believes is active (CAS).", "format": "uuid", "title": "Expected Config Version", "type": "string" }, "reason": { "maxLength": 500, "minLength": 1, "title": "Reason", "type": "string" }, "surface": { "description": "The ranking surface to roll back.", "title": "Surface", "type": "string" } }, "required": [ "surface", "reason", "expected_config_version" ], "title": "KillSwitchRequest", "type": "object" }, "KillSwitchResult": { "properties": { "active_config_version": { "format": "uuid", "title": "Active Config Version", "type": "string" }, "active_scope": { "title": "Active Scope", "type": "string" }, "already_active": { "default": false, "title": "Already Active", "type": "boolean" }, "current_is_baseline": { "default": false, "title": "Current Is Baseline", "type": "boolean" }, "surface": { "title": "Surface", "type": "string" } }, "required": [ "surface", "active_config_version", "active_scope" ], "title": "KillSwitchResult", "type": "object" }, "KindBreakdown": { "properties": { "by_source": { "default": [], "items": { "$ref": "#/components/schemas/KindSourceBreakdown" }, "title": "By Source", "type": "array" }, "calls": { "default": 0, "title": "Calls", "type": "integer" }, "cost_usd": { "default": 0.0, "title": "Cost Usd", "type": "number" }, "tokens": { "default": 0, "title": "Tokens", "type": "integer" }, "usage_kind": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Usage Kind" } }, "title": "KindBreakdown", "type": "object" }, "KindSourceBreakdown": { "description": "Per-(usage_kind, import_source) sub-breakdown row.", "properties": { "calls": { "default": 0, "title": "Calls", "type": "integer" }, "cost_usd": { "default": 0.0, "title": "Cost Usd", "type": "number" }, "import_source": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Import Source" } }, "title": "KindSourceBreakdown", "type": "object" }, "LLMLogEntry": { "properties": { "account_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Account Id" }, "attribution_class": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Attribution Class" }, "audio_duration_seconds": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "title": "Audio Duration Seconds" }, "audio_input_characters": { "default": 0, "title": "Audio Input Characters", "type": "integer" }, "audio_output_bytes": { "default": 0, "title": "Audio Output Bytes", "type": "integer" }, "batch_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Batch Id" }, "cache_hit": { "default": false, "title": "Cache Hit", "type": "boolean" }, "cached_tokens": { "default": 0, "title": "Cached Tokens", "type": "integer" }, "call_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Call Id" }, "call_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Call Type" }, "completion_tokens": { "default": 0, "title": "Completion Tokens", "type": "integer" }, "cost": { "default": 0.0, "title": "Cost", "type": "number" }, "cost_basis": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Cost Basis" }, "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "error_message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Error Message" }, "id": { "title": "Id", "type": "integer" }, "job_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Job Id" }, "latency_ms": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "title": "Latency Ms" }, "model": { "title": "Model", "type": "string" }, "model_tier": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Model Tier" }, "payload_policy": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Payload Policy" }, "pipeline_step": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Pipeline Step" }, "prompt_tokens": { "default": 0, "title": "Prompt Tokens", "type": "integer" }, "request_messages": { "anyOf": [ {}, { "type": "null" } ], "default": null, "title": "Request Messages" }, "response_text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Response Text" }, "service_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Service Name" }, "source_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Source Type" }, "status": { "default": "success", "title": "Status", "type": "string" }, "tenant_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Tenant Id" }, "total_tokens": { "default": 0, "title": "Total Tokens", "type": "integer" }, "trace_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Trace Id" }, "usage_units": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Usage Units" } }, "required": [ "id", "created_at", "model" ], "title": "LLMLogEntry", "type": "object" }, "LLMLogsResponse": { "properties": { "has_more": { "title": "Has More", "type": "boolean" }, "logs": { "items": { "$ref": "#/components/schemas/LLMLogEntry" }, "title": "Logs", "type": "array" }, "page": { "title": "Page", "type": "integer" }, "page_size": { "title": "Page Size", "type": "integer" }, "total": { "title": "Total", "type": "integer" } }, "required": [ "logs", "total", "page", "page_size", "has_more" ], "title": "LLMLogsResponse", "type": "object" }, "LLMUsageResponse": { "properties": { "by_model": { "items": { "$ref": "#/components/schemas/ModelBreakdown" }, "title": "By Model", "type": "array" }, "by_service": { "items": { "$ref": "#/components/schemas/ServiceBreakdown" }, "title": "By Service", "type": "array" }, "by_source_type": { "default": [], "items": { "$ref": "#/components/schemas/SourceTypeBreakdown" }, "title": "By Source Type", "type": "array" }, "cache": { "$ref": "#/components/schemas/CacheStats" }, "daily_trend": { "items": { "$ref": "#/components/schemas/DailyTrend" }, "title": "Daily Trend", "type": "array" }, "total_calls": { "default": 0, "title": "Total Calls", "type": "integer" }, "total_cost_usd": { "default": 0.0, "title": "Total Cost Usd", "type": "number" }, "total_tokens": { "default": 0, "title": "Total Tokens", "type": "integer" } }, "required": [ "cache", "by_model", "by_service", "daily_trend" ], "title": "LLMUsageResponse", "type": "object" }, "Label": { "description": "A mail label or folder from the provider.", "properties": { "id": { "description": "Provider-specific label/folder ID", "title": "Id", "type": "string" }, "name": { "description": "Display name", "title": "Name", "type": "string" }, "type": { "$ref": "#/components/schemas/LabelType", "description": "System or user label" } }, "required": [ "id", "name", "type" ], "title": "Label", "type": "object" }, "LabelCreate": { "additionalProperties": false, "description": "Request to create a custom label.", "properties": { "ai_instructions": { "anyOf": [ { "maxLength": 256, "type": "string" }, { "type": "null" } ], "description": "Optional guidance for AI email labeling", "title": "Ai Instructions" }, "background_color": { "default": "#4285F4", "description": "Hex color for background (e.g., #4285F4)", "pattern": "^#[0-9A-Fa-f]{6}$", "title": "Background Color", "type": "string" }, "icon": { "anyOf": [ { "maxLength": 50, "type": "string" }, { "type": "null" } ], "description": "Optional lucide icon name", "title": "Icon" }, "imap_label_name": { "anyOf": [ { "maxLength": 100, "type": "string" }, { "type": "null" } ], "description": "Custom IMAP label name (defaults to name)", "title": "Imap Label Name" }, "name": { "description": "Display name", "maxLength": 50, "minLength": 1, "title": "Name", "type": "string" }, "provider_label_sync_enabled": { "default": false, "description": "Whether to sync this label to the source provider", "title": "Provider Label Sync Enabled", "type": "boolean" }, "text_color": { "default": "#FFFFFF", "description": "Hex color for text (e.g., #FFFFFF)", "pattern": "^#[0-9A-Fa-f]{6}$", "title": "Text Color", "type": "string" } }, "required": [ "name" ], "title": "LabelCreate", "type": "object" }, "LabelListResponse": { "description": "Response with list of labels.", "properties": { "labels": { "items": { "$ref": "#/components/schemas/LabelResponse" }, "title": "Labels", "type": "array" }, "total": { "title": "Total", "type": "integer" } }, "required": [ "labels", "total" ], "title": "LabelListResponse", "type": "object" }, "LabelResponse": { "description": "Response with label details.", "properties": { "ai_instructions": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Ai Instructions" }, "background_color": { "title": "Background Color", "type": "string" }, "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "email_count": { "default": 0, "title": "Email Count", "type": "integer" }, "icon": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Icon" }, "id": { "format": "uuid", "title": "Id", "type": "string" }, "imap_label_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Imap Label Name" }, "is_active": { "title": "Is Active", "type": "boolean" }, "label_type": { "enum": [ "system", "user", "extracted" ], "title": "Label Type", "type": "string" }, "name": { "title": "Name", "type": "string" }, "provider_label_sync_enabled": { "title": "Provider Label Sync Enabled", "type": "boolean" }, "slug": { "title": "Slug", "type": "string" }, "sort_order": { "title": "Sort Order", "type": "integer" }, "text_color": { "title": "Text Color", "type": "string" }, "updated_at": { "format": "date-time", "title": "Updated At", "type": "string" } }, "required": [ "id", "name", "slug", "background_color", "text_color", "icon", "label_type", "provider_label_sync_enabled", "imap_label_name", "ai_instructions", "sort_order", "is_active", "created_at", "updated_at" ], "title": "LabelResponse", "type": "object" }, "LabelType": { "description": "Label/folder type.", "enum": [ "system", "user" ], "title": "LabelType", "type": "string" }, "LabelUpdate": { "additionalProperties": false, "description": "Request to update a label.", "properties": { "ai_instructions": { "anyOf": [ { "maxLength": 256, "type": "string" }, { "type": "null" } ], "title": "Ai Instructions" }, "background_color": { "anyOf": [ { "pattern": "^#[0-9A-Fa-f]{6}$", "type": "string" }, { "type": "null" } ], "title": "Background Color" }, "icon": { "anyOf": [ { "maxLength": 50, "type": "string" }, { "type": "null" } ], "title": "Icon" }, "imap_label_name": { "anyOf": [ { "maxLength": 100, "type": "string" }, { "type": "null" } ], "title": "Imap Label Name" }, "is_active": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is Active" }, "name": { "anyOf": [ { "maxLength": 50, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Name" }, "provider_label_sync_enabled": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Provider Label Sync Enabled" }, "sort_order": { "anyOf": [ { "minimum": 0.0, "type": "integer" }, { "type": "null" } ], "title": "Sort Order" }, "text_color": { "anyOf": [ { "pattern": "^#[0-9A-Fa-f]{6}$", "type": "string" }, { "type": "null" } ], "title": "Text Color" } }, "title": "LabelUpdate", "type": "object" }, "LabelUpdateRequest": { "description": "Request body for label management endpoint.\n\nAttributes:\n add: Labels to add to the email\n remove: Labels to remove from the email\n\nExample:\n {\"add\": [\"important\", \"school\"], \"remove\": [\"temp\"]}", "properties": { "add": { "description": "Labels to add", "items": { "type": "string" }, "title": "Add", "type": "array" }, "remove": { "description": "Labels to remove", "items": { "type": "string" }, "title": "Remove", "type": "array" } }, "title": "LabelUpdateRequest", "type": "object" }, "LabelUpdateResponse": { "description": "Response for label update endpoint.\n\nAttributes:\n id: Email UUID\n user_labels: Updated labels array (sorted alphabetically)\n\nExample:\n {\"id\": \"uuid-here\", \"user_labels\": [\"important\", \"school\"]}", "properties": { "id": { "description": "Email UUID", "format": "uuid", "title": "Id", "type": "string" }, "user_labels": { "description": "Updated labels array", "items": { "type": "string" }, "title": "User Labels", "type": "array" } }, "required": [ "id", "user_labels" ], "title": "LabelUpdateResponse", "type": "object" }, "LaneCapability": { "description": "One model lane, and whether this deployment can call it.", "properties": { "available": { "title": "Available", "type": "boolean" }, "lane": { "title": "Lane", "type": "string" }, "unavailable_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Unavailable Reason" }, "unavailable_reason_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Unavailable Reason Code" } }, "required": [ "lane", "available" ], "title": "LaneCapability", "type": "object" }, "LastMessageModel": { "properties": { "body": { "title": "Body", "type": "string" }, "origin_server_ts": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Origin Server Ts" }, "sender_display_name": { "title": "Sender Display Name", "type": "string" } }, "required": [ "sender_display_name", "body" ], "title": "LastMessageModel", "type": "object" }, "LeadCaptureRequest": { "properties": { "consent": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "The submission's EXPLICIT consent flag (TIDY-14683 / R13). True is one of the only two resubscribe paths: it removes any suppression for the address, flips consent_state to subscribed, and emits the resubscribed engagement event. Absent/False never changes stored consent.", "title": "Consent" }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Identity key — required; a submission without one is a 400.", "title": "Email" }, "facet_slug": { "description": "Contact-inheriting facet the lead attaches to.", "title": "Facet Slug", "type": "string" }, "fields": { "additionalProperties": true, "description": "Mapped facet field values (the capture workflow's output).", "title": "Fields", "type": "object" }, "raw_payload": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "Full original submission — unknown fields preserved here verbatim.", "title": "Raw Payload" }, "source": { "default": "", "description": "Capture source label. Free-form by design — the CRM pack's vocabulary is 'form', 'alias-email' and 'discord' (TIDY-16718 / D6), and a tenant's own capture door may use any other label.", "title": "Source", "type": "string" }, "source_email_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The inbound message this lead arrived in (TIDY-16718 / R9). Links the created/updated lead to that email, in the same transaction as the upsert. Accepts a typed 'E-' id or a bare UUID.", "title": "Source Email Id" }, "submitted_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "Submission timestamp (tz-aware ISO 8601); part of the replay key. Defaults to now — pass the form's own timestamp for replay-safe delivery.", "title": "Submitted At" }, "utm": { "additionalProperties": true, "description": "UTM parameters — first-touch write-once, last-touch always updated.", "title": "Utm", "type": "object" }, "webhook_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The Custom webhook plugin whose event delivered this capture — recorded on the capture receipt.", "title": "Webhook Id" } }, "required": [ "facet_slug" ], "title": "LeadCaptureRequest", "type": "object" }, "LeadCaptureResponse": { "properties": { "contact_id": { "title": "Contact Id", "type": "string" }, "facet_slug": { "title": "Facet Slug", "type": "string" }, "outcome": { "enum": [ "created", "updated", "replay" ], "title": "Outcome", "type": "string" }, "source_event_id": { "description": "Deterministic id of the form_submitted engagement event.", "title": "Source Event Id", "type": "string" } }, "required": [ "contact_id", "outcome", "facet_slug", "source_event_id" ], "title": "LeadCaptureResponse", "type": "object" }, "LeaderboardEntry": { "properties": { "display_name": { "title": "Display Name", "type": "string" }, "lambda": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Lambda" }, "minutes_saved": { "title": "Minutes Saved", "type": "number" } }, "required": [ "display_name", "minutes_saved" ], "title": "LeaderboardEntry", "type": "object" }, "LeaderboardResponse": { "properties": { "entries": { "items": { "$ref": "#/components/schemas/LeaderboardEntry" }, "title": "Entries", "type": "array" }, "opted_in": { "title": "Opted In", "type": "boolean" } }, "required": [ "opted_in", "entries" ], "title": "LeaderboardResponse", "type": "object" }, "LeaveConversationChannelRequest": { "properties": { "carry_on": { "anyOf": [ { "maxLength": 4000, "type": "string" }, { "type": "null" } ], "title": "Carry On" } }, "title": "LeaveConversationChannelRequest", "type": "object" }, "LedgerEntryResponse": { "properties": { "definition_ref": { "title": "Definition Ref", "type": "string" }, "item_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Item Id" }, "item_kind": { "title": "Item Kind", "type": "string" }, "user_instance_count": { "default": 0, "title": "User Instance Count", "type": "integer" } }, "required": [ "item_kind", "definition_ref" ], "title": "LedgerEntryResponse", "type": "object" }, "LedgerEvent": { "properties": { "actor_account_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Actor Account Id" }, "conversation_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Conversation Id" }, "evidence_ref": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Evidence Ref" }, "execution_digest": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Execution Digest" }, "id": { "format": "uuid", "title": "Id", "type": "string" }, "kind": { "title": "Kind", "type": "string" }, "occurred_at": { "format": "date-time", "title": "Occurred At", "type": "string" }, "principal_key": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Principal Key" }, "skill_version": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Skill Version" }, "subject_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Subject Id" }, "subject_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Subject Type" }, "summary": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Summary" }, "title": { "title": "Title", "type": "string" }, "workshop_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Workshop Id" } }, "required": [ "id", "principal_key", "workshop_id", "kind", "occurred_at", "title", "summary", "conversation_id", "actor_account_id", "subject_type", "subject_id", "skill_version", "execution_digest", "evidence_ref" ], "title": "LedgerEvent", "type": "object" }, "LedgerMonth": { "properties": { "month": { "title": "Month", "type": "string" }, "types": { "$ref": "#/components/schemas/LedgerTypes" } }, "required": [ "month", "types" ], "title": "LedgerMonth", "type": "object" }, "LedgerOutcomes": { "description": "Outcome counts for one entity type in one month.", "properties": { "accepted": { "default": 0, "title": "Accepted", "type": "integer" }, "aged_out": { "default": 0, "title": "Aged Out", "type": "integer" }, "dismissed": { "default": 0, "title": "Dismissed", "type": "integer" }, "recommended": { "default": 0, "title": "Recommended", "type": "integer" }, "rejected": { "default": 0, "title": "Rejected", "type": "integer" } }, "title": "LedgerOutcomes", "type": "object" }, "LedgerPage": { "properties": { "events": { "items": { "$ref": "#/components/schemas/LedgerEvent" }, "title": "Events", "type": "array" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Next Cursor" } }, "required": [ "events" ], "title": "LedgerPage", "type": "object" }, "LedgerTypes": { "description": "Per-type outcome buckets — always all six keys, zero-filled.", "properties": { "advisor_rule": { "$ref": "#/components/schemas/LedgerOutcomes" }, "contact": { "$ref": "#/components/schemas/LedgerOutcomes" }, "event": { "$ref": "#/components/schemas/LedgerOutcomes" }, "note": { "$ref": "#/components/schemas/LedgerOutcomes" }, "organization": { "$ref": "#/components/schemas/LedgerOutcomes" }, "task": { "$ref": "#/components/schemas/LedgerOutcomes" } }, "title": "LedgerTypes", "type": "object" }, "LegacyEnrollmentRequest": { "properties": { "agent_account_id": { "format": "uuid", "title": "Agent Account Id", "type": "string" }, "idempotency_key": { "format": "uuid", "title": "Idempotency Key", "type": "string" }, "legacy_bundle_fingerprint": { "maxLength": 512, "minLength": 16, "title": "Legacy Bundle Fingerprint", "type": "string" }, "legacy_device_id": { "maxLength": 255, "minLength": 1, "title": "Legacy Device Id", "type": "string" }, "legacy_matrix_user_id": { "maxLength": 255, "minLength": 3, "title": "Legacy Matrix User Id", "type": "string" }, "machine_fingerprint": { "maxLength": 512, "minLength": 16, "title": "Machine Fingerprint", "type": "string" }, "requested_installation_id": { "format": "uuid", "title": "Requested Installation Id", "type": "string" } }, "required": [ "agent_account_id", "requested_installation_id", "machine_fingerprint", "legacy_matrix_user_id", "legacy_device_id", "legacy_bundle_fingerprint", "idempotency_key" ], "title": "LegacyEnrollmentRequest", "type": "object" }, "LegacyEnrollmentResponse": { "properties": { "connector_bundle_v2": { "$ref": "#/components/schemas/ConnectorBundleV2" }, "host_continuity_token": { "title": "Host Continuity Token", "type": "string" }, "host_instance_id": { "format": "uuid", "title": "Host Instance Id", "type": "string" }, "installation_id": { "format": "uuid", "title": "Installation Id", "type": "string" }, "recovered_existing": { "default": false, "title": "Recovered Existing", "type": "boolean" } }, "required": [ "installation_id", "host_instance_id", "host_continuity_token", "connector_bundle_v2" ], "title": "LegacyEnrollmentResponse", "type": "object" }, "LegacyValidationRefusal": { "description": "The pre-problem+json 422 body (FastAPI's default HTTPValidationError).\n\nTIDY-18662 F3 — an OLD api-service answers a validation 422 with a bare\n``{\"detail\": [...]}``, not a problem envelope. Declaring it as the OTHER\nmember of the routes' 422 union makes the generated SDKs TOLERATE that body\n(try the problem model, fall back to this) instead of raising ``KeyError``,\nwhile the HTTP status is still surfaced on the ``Response``. A NEW server\nnever emits this, but the SDK must not crash on a release-order skew.", "properties": { "detail": { "items": { "additionalProperties": true, "type": "object" }, "title": "Detail", "type": "array" } }, "required": [ "detail" ], "title": "LegacyValidationRefusal", "type": "object" }, "LegalHoldRequest": { "properties": { "account_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Account Id" }, "reason": { "maxLength": 2000, "minLength": 1, "title": "Reason", "type": "string" }, "room_id": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "title": "Room Id" }, "scope": { "enum": [ "room", "account" ], "title": "Scope", "type": "string" } }, "required": [ "scope", "reason" ], "title": "LegalHoldRequest", "type": "object" }, "LegalHoldResponse": { "properties": { "account_display_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Account Display Name" }, "account_email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Account Email" }, "account_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Account Id" }, "applied_at": { "format": "date-time", "title": "Applied At", "type": "string" }, "applied_by_account_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Applied By Account Id" }, "id": { "title": "Id", "type": "string" }, "reason": { "title": "Reason", "type": "string" }, "released_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Released At" }, "released_by_account_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Released By Account Id" }, "room_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Room Id" }, "room_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Room Name" }, "scope": { "enum": [ "room", "account" ], "title": "Scope", "type": "string" }, "tenant_id": { "title": "Tenant Id", "type": "string" } }, "required": [ "id", "tenant_id", "scope", "reason", "applied_at" ], "title": "LegalHoldResponse", "type": "object" }, "LendRequest": { "properties": { "capability_scope": { "items": { "type": "string" }, "maxItems": 64, "minItems": 1, "title": "Capability Scope", "type": "array" }, "conversation_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Conversation Id" }, "employee_account_id": { "title": "Employee Account Id", "type": "string" }, "expires_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Expires At" }, "scope": { "enum": [ "once", "session", "standing" ], "title": "Scope", "type": "string" } }, "required": [ "employee_account_id", "scope", "capability_scope" ], "title": "LendRequest", "type": "object" }, "LendResponse": { "properties": { "grant_id": { "title": "Grant Id", "type": "string" }, "lend": { "$ref": "#/components/schemas/PluginLend" } }, "required": [ "grant_id", "lend" ], "title": "LendResponse", "type": "object" }, "LibraryResponse": { "properties": { "libraryItems": { "items": {}, "title": "Libraryitems", "type": "array" } }, "title": "LibraryResponse", "type": "object" }, "LightsailRoleSetup": { "properties": { "external_id": { "title": "External Id", "type": "string" }, "role_arn": { "title": "Role Arn", "type": "string" }, "template_body": { "title": "Template Body", "type": "string" } }, "required": [ "role_arn", "external_id", "template_body" ], "title": "LightsailRoleSetup", "type": "object" }, "LimitPostureResponse": { "properties": { "dimensions": { "items": { "$ref": "#/components/schemas/DimensionPosture" }, "title": "Dimensions", "type": "array" } }, "required": [ "dimensions" ], "title": "LimitPostureResponse", "type": "object" }, "LinkAddedTrigger": { "additionalProperties": false, "properties": { "kind": { "const": "link_added", "title": "Kind", "type": "string" }, "target_facet": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Target Facet" }, "target_item": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Target Item" } }, "required": [ "kind" ], "title": "LinkAddedTrigger", "type": "object" }, "LinkCountsResponse": { "description": "Counts of related primitives by type.\n\nUsed in:\n - GET /api/v1/links/counts", "properties": { "contact": { "default": 0, "description": "Count of related contacts", "title": "Contact", "type": "integer" }, "event": { "default": 0, "description": "Count of related events", "title": "Event", "type": "integer" }, "news_update": { "default": 0, "description": "Count of related news updates", "title": "News Update", "type": "integer" }, "note": { "default": 0, "description": "Count of related notes", "title": "Note", "type": "integer" }, "task": { "default": 0, "description": "Count of related tasks", "title": "Task", "type": "integer" }, "total": { "default": 0, "description": "Total count of all related primitives", "title": "Total", "type": "integer" } }, "title": "LinkCountsResponse", "type": "object" }, "LinkCreate": { "description": "Input model for creating new links.\n\nUsed in:\n - POST /api/v1/links\n\nField aliases (TIDY-7590):\n Source identifiers accept either the legacy `source_type`/`source_id`\n names (used by the unified panel's `createLink()` client) OR the\n canonical column-aligned `source_container_type`/`source_container_id`\n names (used by collab-service-style writers and the wiki backlink\n Playwright spec). Both populate the same canonical schema columns.\n\nWiki-link provenance (TIDY-7590):\n `display_text`, `source_block_excerpt`, and `source_block_id` are\n accepted on POST so wiki-link rows can be created with the same\n provenance the GET response carries. When `source_block_id` is\n provided, `provenance_status='precise'` is enforced (per the\n `linked_references_check` constraint); otherwise rows are\n `legacy_container`.", "properties": { "confidence": { "anyOf": [ { "maximum": 1.0, "minimum": 0.0, "type": "number" }, { "type": "null" } ], "default": 1.0, "description": "Confidence score (defaults to 1.0 for user_created links)", "title": "Confidence" }, "display_text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Rendered inline label captured from the editor (e.g. the [[X]] text)", "title": "Display Text" }, "link_source": { "anyOf": [ { "enum": [ "wiki_link_sync", "content_embed", "user_created", "llm_extracted", "system", "pipeline_auto", "agent", "date_binding", "email_send", "facet_field_sync", "title_token_sync", "comment" ], "type": "string" }, { "type": "null" } ], "default": "user_created", "description": "How the link was created (defaults to user_created)", "title": "Link Source" }, "link_type": { "description": "Relationship type", "enum": [ "wiki_link", "related_to", "parent_of", "depends_on", "blocks", "duplicates", "synthesized_from", "reply_to", "extracted_with", "mentioned_in", "about", "embeds", "automated_from", "MENTIONS", "MENTIONED_IN", "CO_OCCURS_WITH", "WORKS_AT", "ATTENDED", "RELATED_TO", "DERIVED_FROM", "ABOUT", "WIKI_DERIVATION", "implements", "implemented_by", "governs", "governed_by", "supersedes", "superseded_by", "evidences", "evidenced_by", "GENERATED_FROM" ], "title": "Link Type", "type": "string" }, "metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "Optional additional context", "title": "Metadata" }, "predicate": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Human relationship label (e.g. a custom relationship type)", "title": "Predicate" }, "source_block_excerpt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Cached excerpt of the source block where the wiki link was authored", "title": "Source Block Excerpt" }, "source_block_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Stable source block UUID; when set, the row is created with provenance_status='precise'", "title": "Source Block Id" }, "source_id": { "description": "ID of source primitive (UUID)", "title": "Source Id", "type": "string" }, "source_type": { "description": "Type of source primitive", "enum": [ "event", "contact", "task", "activity", "note", "journal", "news_update", "email", "reminder", "organization", "calendar_event", "podcast_episode", "project", "comment", "record", "file", "canonical_document", "processed_attachment", "crawled_content", "entity", "chunk", "insight", "email_canonical", "scm_object", "skill" ], "title": "Source Type", "type": "string" }, "target_id": { "description": "ID of target primitive (UUID)", "title": "Target Id", "type": "string" }, "target_type": { "description": "Type of target primitive", "enum": [ "event", "contact", "task", "activity", "note", "journal", "news_update", "email", "reminder", "organization", "calendar_event", "podcast_episode", "project", "comment", "record", "file", "canonical_document", "processed_attachment", "crawled_content", "entity", "chunk", "insight", "email_canonical", "scm_object" ], "title": "Target Type", "type": "string" } }, "required": [ "source_type", "source_id", "target_type", "target_id", "link_type" ], "title": "LinkCreate", "type": "object" }, "LinkFaceRequest": { "properties": { "contact_id": { "format": "uuid", "title": "Contact Id", "type": "string" } }, "required": [ "contact_id" ], "title": "LinkFaceRequest", "type": "object" }, "LinkFullItem": { "description": "One canonical linked_references row returned by /api/v1/links/full.", "properties": { "confidence": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "description": "Extraction confidence", "title": "Confidence" }, "created_at": { "description": "Row creation timestamp", "format": "date-time", "title": "Created At", "type": "string" }, "display_text": { "description": "Rendered inline label", "title": "Display Text", "type": "string" }, "id": { "description": "linked_references row UUID", "title": "Id", "type": "string" }, "link_source": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "How the link was created", "title": "Link Source" }, "link_type": { "description": "Relationship type", "title": "Link Type", "type": "string" }, "source_block_excerpt": { "description": "Cached excerpt of source block", "title": "Source Block Excerpt", "type": "string" }, "source_block_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Source block UUID when provenance is precise", "title": "Source Block Id" }, "source_container_id": { "description": "Source primitive UUID", "title": "Source Container Id", "type": "string" }, "source_container_type": { "description": "Source primitive surface type", "title": "Source Container Type", "type": "string" }, "target_id": { "description": "Target primitive UUID", "title": "Target Id", "type": "string" }, "target_type": { "description": "Target primitive type", "title": "Target Type", "type": "string" }, "trigger_style": { "description": "Original inline trigger (wiki/at/none)", "title": "Trigger Style", "type": "string" }, "updated_at": { "description": "Row update timestamp", "format": "date-time", "title": "Updated At", "type": "string" } }, "required": [ "id", "source_container_type", "source_container_id", "target_type", "target_id", "link_type", "trigger_style", "display_text", "source_block_excerpt", "created_at", "updated_at" ], "title": "LinkFullItem", "type": "object" }, "LinkListResponse": { "description": "Paginated list of links.\n\nUsed in:\n - GET /api/v1/links", "properties": { "links": { "description": "List of links", "items": { "$ref": "#/components/schemas/LinkResponse" }, "title": "Links", "type": "array" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Cursor for next page", "title": "Next Cursor" }, "total": { "description": "Total count of matching links", "title": "Total", "type": "integer" } }, "required": [ "links", "total" ], "title": "LinkListResponse", "type": "object" }, "LinkResponse": { "description": "Complete link object returned by API endpoints.\n\nUsed in:\n - GET /api/v1/links (list response items)\n - POST /api/v1/links (created link response, 201)\n\nTyped-ID emit (TIDY-8940): ``source_id`` and ``target_id`` are\nrewritten to typed-ID form using the row's ``source_type`` /\n``target_type`` to pick the prefix (D13, R7). The discriminators\nare kept in the response — clients still drive routing/icons off\nthem and the prefix-encoded discriminator goal is satisfied at\nthe collapsed ``linked-references`` endpoint where the type is\nderivable from the path-id prefix.\n\nAttributes:\n id: Unique link identifier (UUID)\n source_type: Type of source primitive\n source_id: ID of source primitive (typed)\n target_type: Type of target primitive\n target_id: ID of target primitive (typed)\n link_type: Relationship type\n link_source: How link was created\n confidence: Confidence score (0.0-1.0)\n metadata: Additional context\n created_at: When link was created\n updated_at: When link was last updated", "properties": { "confidence": { "anyOf": [ { "maximum": 1.0, "minimum": 0.0, "type": "number" }, { "type": "null" } ], "default": 1.0, "description": "Confidence score for LLM-extracted links", "title": "Confidence" }, "created_at": { "description": "When link was created", "format": "date-time", "title": "Created At", "type": "string" }, "display_text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Rendered inline label captured from the editor (e.g. the [[X]] text)", "title": "Display Text" }, "fact_text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Extracted fact sentence backing the link (null when absent)", "title": "Fact Text" }, "id": { "description": "Unique link identifier (UUID)", "title": "Id", "type": "string" }, "link_source": { "description": "How link was created", "enum": [ "wiki_link_sync", "content_embed", "user_created", "llm_extracted", "system", "pipeline_auto", "agent", "date_binding", "email_send", "facet_field_sync", "title_token_sync", "comment" ], "title": "Link Source", "type": "string" }, "link_type": { "description": "Relationship type", "enum": [ "wiki_link", "related_to", "parent_of", "depends_on", "blocks", "duplicates", "synthesized_from", "reply_to", "extracted_with", "mentioned_in", "about", "embeds", "automated_from", "MENTIONS", "MENTIONED_IN", "CO_OCCURS_WITH", "WORKS_AT", "ATTENDED", "RELATED_TO", "DERIVED_FROM", "ABOUT", "WIKI_DERIVATION", "implements", "implemented_by", "governs", "governed_by", "supersedes", "superseded_by", "evidences", "evidenced_by", "GENERATED_FROM", "follow_up", "member_of", "reports_to", "facet_field", "assigned_to_workshop" ], "title": "Link Type", "type": "string" }, "metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "description": "Additional context", "title": "Metadata" }, "predicate": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Normalized human relationship label (null when absent)", "title": "Predicate" }, "source_archived": { "default": false, "description": "True when the source is an archived activity (TIDY-14986 badge)", "title": "Source Archived", "type": "boolean" }, "source_block_excerpt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Cached excerpt of the source block where the wiki link was authored", "title": "Source Block Excerpt" }, "source_block_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Stable source block UUID when precise provenance exists", "title": "Source Block Id" }, "source_icon": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Lucide icon name for source primitive type (mail, check-square, etc.)", "title": "Source Icon" }, "source_id": { "description": "ID of source primitive (UUID)", "title": "Source Id", "type": "string" }, "source_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Task/activity status for source if applicable, else null", "title": "Source Status" }, "source_title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Resolved display title of the source primitive (null if soft-deleted or unresolvable)", "title": "Source Title" }, "source_type": { "description": "Type of source primitive", "enum": [ "event", "contact", "task", "activity", "note", "journal", "news_update", "email", "reminder", "organization", "calendar_event", "podcast_episode", "project", "comment", "record", "file", "canonical_document", "processed_attachment", "crawled_content", "entity", "chunk", "insight", "email_canonical", "scm_object", "notebook", "user", "account", "photo", "evidence_commit", "evidence_pull_request", "evidence_validation_run", "evidence_running_work", "employee_dm", "skill" ], "title": "Source Type", "type": "string" }, "target_archived": { "default": false, "description": "True when the target is an archived activity (TIDY-14986 badge)", "title": "Target Archived", "type": "boolean" }, "target_icon": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Lucide icon name for target primitive type (mail, check-square, etc.)", "title": "Target Icon" }, "target_id": { "description": "ID of target primitive (UUID)", "title": "Target Id", "type": "string" }, "target_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Task/activity status for target if applicable, else null", "title": "Target Status" }, "target_title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Resolved display title of the target primitive (null if soft-deleted or unresolvable)", "title": "Target Title" }, "target_type": { "description": "Type of target primitive", "enum": [ "event", "contact", "task", "activity", "note", "journal", "news_update", "email", "reminder", "organization", "calendar_event", "podcast_episode", "project", "comment", "record", "file", "canonical_document", "processed_attachment", "crawled_content", "entity", "chunk", "insight", "email_canonical", "scm_object", "photo", "tab", "attachment" ], "title": "Target Type", "type": "string" }, "updated_at": { "description": "When link was last updated", "format": "date-time", "title": "Updated At", "type": "string" } }, "required": [ "id", "source_type", "source_id", "target_type", "target_id", "link_type", "link_source", "created_at", "updated_at" ], "title": "LinkResponse", "type": "object" }, "LinkSummary": { "properties": { "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "granted_categories": { "items": { "type": "string" }, "title": "Granted Categories", "type": "array" }, "granted_scopes": { "items": { "type": "string" }, "title": "Granted Scopes", "type": "array" }, "id": { "title": "Id", "type": "string" }, "instances": { "items": { "$ref": "#/components/schemas/InstanceSummary" }, "title": "Instances", "type": "array" }, "tenant_id": { "title": "Tenant Id", "type": "string" } }, "required": [ "id", "tenant_id", "granted_categories", "granted_scopes", "created_at", "instances" ], "title": "LinkSummary", "type": "object" }, "LinkableAgent": { "description": "One actor the link picker can grant a connection to — an AI Assistant or\na virtual employee. TIDY-14147 / S5.", "properties": { "display_name": { "title": "Display Name", "type": "string" }, "id": { "title": "Id", "type": "string" }, "kind": { "enum": [ "assistant", "virtual_employee" ], "title": "Kind", "type": "string" }, "mention_handle": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Mention Handle" } }, "required": [ "id", "kind", "display_name" ], "title": "LinkableAgent", "type": "object" }, "LinkedEntity": { "description": "One (type, id) reference the F3 popup attaches to a captured note.\n\nSee TIDY-9731 / F3 S3. The note-create handler turns each entry into\na linked_references row pointing from the new note to the entity.\nCurrently supports contacts and projects — additional entity types\nmay be added when their tag-aggregation surface is ready.\n\nTargets that do not exist in the calling tenant (stale popup cache,\ndeleted entity) are skipped at insert time with an INFO log; they\ndo NOT fail the note insert.", "properties": { "id": { "format": "uuid", "title": "Id", "type": "string" }, "type": { "enum": [ "contact", "project" ], "title": "Type", "type": "string" } }, "required": [ "type", "id" ], "title": "LinkedEntity", "type": "object" }, "LinksApprovalBatchRequest": { "properties": { "action": { "const": "reject", "title": "Action", "type": "string" }, "link_ids": { "items": { "format": "uuid", "type": "string" }, "maxItems": 500, "minItems": 1, "title": "Link Ids", "type": "array" } }, "required": [ "link_ids", "action" ], "title": "LinksApprovalBatchRequest", "type": "object" }, "LinksApprovalBatchResponse": { "properties": { "skipped": { "title": "Skipped", "type": "integer" }, "updated": { "title": "Updated", "type": "integer" } }, "required": [ "updated", "skipped" ], "title": "LinksApprovalBatchResponse", "type": "object" }, "LinksFullResponse": { "description": "Paginated /api/v1/links/full response.", "properties": { "links": { "description": "Page of linked_references rows", "items": { "$ref": "#/components/schemas/LinkFullItem" }, "title": "Links", "type": "array" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Opaque cursor for the next page (null when no more pages)", "title": "Next Cursor" }, "total": { "description": "Total matching rows ignoring cursor predicate", "title": "Total", "type": "integer" } }, "required": [ "links", "total" ], "title": "LinksFullResponse", "type": "object" }, "LintFindingItem": { "properties": { "category": { "title": "Category", "type": "string" }, "detected_at": { "format": "date-time", "title": "Detected At", "type": "string" }, "finding": { "additionalProperties": true, "title": "Finding", "type": "object" }, "id": { "format": "uuid", "title": "Id", "type": "string" }, "related_target_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "default": null, "title": "Related Target Id" }, "resolved_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Resolved At" }, "severity": { "title": "Severity", "type": "string" }, "target_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "default": null, "title": "Target Id" }, "target_kind": { "title": "Target Kind", "type": "string" } }, "required": [ "id", "category", "severity", "target_kind", "finding", "detected_at" ], "title": "LintFindingItem", "type": "object" }, "LintFindingsResponse": { "properties": { "findings": { "items": { "$ref": "#/components/schemas/LintFindingItem" }, "title": "Findings", "type": "array" }, "tenant_id": { "format": "uuid", "title": "Tenant Id", "type": "string" }, "total": { "title": "Total", "type": "integer" } }, "required": [ "tenant_id", "total", "findings" ], "title": "LintFindingsResponse", "type": "object" }, "ListAdminChannelsResponse": { "properties": { "channels": { "items": { "$ref": "#/components/schemas/AdminChannelResponse" }, "title": "Channels", "type": "array" }, "next_offset": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Next Offset" }, "total": { "title": "Total", "type": "integer" } }, "required": [ "channels", "total" ], "title": "ListAdminChannelsResponse", "type": "object" }, "ListAdminChatUsersResponse": { "properties": { "bot_count": { "default": 0, "title": "Bot Count", "type": "integer" }, "guest_count": { "default": 0, "title": "Guest Count", "type": "integer" }, "human_count": { "default": 0, "title": "Human Count", "type": "integer" }, "users": { "items": { "$ref": "#/components/schemas/AdminChatUserResponse" }, "title": "Users", "type": "array" } }, "required": [ "users" ], "title": "ListAdminChatUsersResponse", "type": "object" }, "ListAdminHuddlesResponse": { "properties": { "huddles": { "items": { "$ref": "#/components/schemas/AdminHuddleResponse" }, "title": "Huddles", "type": "array" }, "next_offset": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Next Offset" } }, "required": [ "huddles" ], "title": "ListAdminHuddlesResponse", "type": "object" }, "ListAdminPollsResponse": { "properties": { "next_offset": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Next Offset" }, "polls": { "items": { "$ref": "#/components/schemas/AdminPollResponse" }, "title": "Polls", "type": "array" } }, "required": [ "polls" ], "title": "ListAdminPollsResponse", "type": "object" }, "ListCapabilityRequestsResponse": { "properties": { "requests": { "items": { "$ref": "#/components/schemas/CapabilityRequestItem" }, "title": "Requests", "type": "array" } }, "required": [ "requests" ], "title": "ListCapabilityRequestsResponse", "type": "object" }, "ListChatExportJobsResponse": { "properties": { "jobs": { "items": { "$ref": "#/components/schemas/ChatExportJobResponse" }, "title": "Jobs", "type": "array" }, "rooms": { "items": { "$ref": "#/components/schemas/ExportRoomOption" }, "title": "Rooms", "type": "array" } }, "required": [ "jobs", "rooms" ], "title": "ListChatExportJobsResponse", "type": "object" }, "ListChatMessageEditsResponse": { "properties": { "items": { "items": { "$ref": "#/components/schemas/ChatMessageEditResponse" }, "title": "Items", "type": "array" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Next Cursor" } }, "required": [ "items" ], "title": "ListChatMessageEditsResponse", "type": "object" }, "ListConnectedAgentsResponse": { "properties": { "agents": { "items": { "$ref": "#/components/schemas/ConnectedAgentItem" }, "title": "Agents", "type": "array" } }, "required": [ "agents" ], "title": "ListConnectedAgentsResponse", "type": "object" }, "ListConnectedAppsResponse": { "properties": { "apps": { "items": { "$ref": "#/components/schemas/ConnectedAppItem" }, "title": "Apps", "type": "array" } }, "required": [ "apps" ], "title": "ListConnectedAppsResponse", "type": "object" }, "ListLegalHoldsResponse": { "properties": { "accounts": { "items": { "$ref": "#/components/schemas/HoldAccountOption" }, "title": "Accounts", "type": "array" }, "holds": { "items": { "$ref": "#/components/schemas/LegalHoldResponse" }, "title": "Holds", "type": "array" }, "rooms": { "items": { "$ref": "#/components/schemas/HoldRoomOption" }, "title": "Rooms", "type": "array" } }, "required": [ "holds", "rooms", "accounts" ], "title": "ListLegalHoldsResponse", "type": "object" }, "ListLinksResponse": { "properties": { "links": { "items": { "$ref": "#/components/schemas/LinkSummary" }, "title": "Links", "type": "array" } }, "required": [ "links" ], "title": "ListLinksResponse", "type": "object" }, "ListMembersResponse": { "properties": { "members": { "items": { "$ref": "#/components/schemas/MemberListItem" }, "title": "Members", "type": "array" } }, "required": [ "members" ], "title": "ListMembersResponse", "type": "object" }, "ListOAuthAppsResponse": { "properties": { "oauth_apps": { "items": { "$ref": "#/components/schemas/OAuthAppPublic" }, "title": "Oauth Apps", "type": "array" } }, "required": [ "oauth_apps" ], "title": "ListOAuthAppsResponse", "type": "object" }, "ListPATsResponse": { "properties": { "pats": { "items": { "$ref": "#/components/schemas/PATPublic" }, "title": "Pats", "type": "array" } }, "required": [ "pats" ], "title": "ListPATsResponse", "type": "object" }, "ListRetentionPoliciesResponse": { "properties": { "policies": { "items": { "$ref": "#/components/schemas/RetentionPolicyResponse" }, "title": "Policies", "type": "array" }, "rooms": { "items": { "$ref": "#/components/schemas/RetentionRoomOption" }, "title": "Rooms", "type": "array" } }, "required": [ "policies", "rooms" ], "title": "ListRetentionPoliciesResponse", "type": "object" }, "ListSeatsResponse": { "properties": { "invitations": { "items": { "$ref": "#/components/schemas/InvitationItem" }, "title": "Invitations", "type": "array" }, "members": { "items": { "$ref": "#/components/schemas/MemberItem" }, "title": "Members", "type": "array" }, "plan_seat": { "anyOf": [ { "$ref": "#/components/schemas/PlanSeatItem" }, { "type": "null" } ] }, "seats": { "default": [], "items": { "$ref": "#/components/schemas/SeatItem" }, "title": "Seats", "type": "array" } }, "required": [ "members", "invitations" ], "title": "ListSeatsResponse", "type": "object" }, "ListServiceAccountsResponse": { "properties": { "service_accounts": { "items": { "$ref": "#/components/schemas/ServiceAccountPublic" }, "title": "Service Accounts", "type": "array" } }, "required": [ "service_accounts" ], "title": "ListServiceAccountsResponse", "type": "object" }, "ListSuggestionsResponse": { "description": "Response for listing pending project suggestions.", "properties": { "suggestions": { "description": "List of pending suggestions", "items": { "$ref": "#/components/schemas/ProjectSuggestionItem" }, "title": "Suggestions", "type": "array" }, "total": { "default": 0, "description": "Total number of pending suggestions", "title": "Total", "type": "integer" } }, "title": "ListSuggestionsResponse", "type": "object" }, "ListTenantPATsResponse": { "properties": { "pats": { "items": { "$ref": "#/components/schemas/TenantPATPublic" }, "title": "Pats", "type": "array" } }, "required": [ "pats" ], "title": "ListTenantPATsResponse", "type": "object" }, "LiveKitWebhookAck": { "properties": { "handled": { "default": false, "title": "Handled", "type": "boolean" }, "ok": { "title": "Ok", "type": "boolean" } }, "required": [ "ok" ], "title": "LiveKitWebhookAck", "type": "object" }, "LivenessConflict": { "properties": { "code": { "const": "collab_liveness_unprovable", "title": "Code", "type": "string" }, "retry_after_seconds": { "title": "Retry After Seconds", "type": "integer" }, "room_id": { "title": "Room Id", "type": "string" } }, "required": [ "code", "retry_after_seconds", "room_id" ], "title": "LivenessConflict", "type": "object" }, "LocalSkillReport": { "description": "A skill folder in the harness's skill root that Tidy did not write.\n\nTIDY-20203 F1: the operator's own copy. Reported so the employee's Skills\nview says it is there; never adopted, pushed, overwritten or removed.\nNames only: the folder and, for a git checkout, its remote and commit.", "properties": { "path": { "maxLength": 1024, "minLength": 1, "title": "Path", "type": "string" }, "repo_commit": { "anyOf": [ { "pattern": "^[0-9a-f]{7,64}$", "type": "string" }, { "type": "null" } ], "title": "Repo Commit" }, "repo_url": { "anyOf": [ { "maxLength": 512, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Repo Url" }, "slug": { "pattern": "^[a-z0-9][a-z0-9-]{0,63}$", "title": "Slug", "type": "string" } }, "required": [ "slug", "path" ], "title": "LocalSkillReport", "type": "object" }, "Location": { "description": "Geographic location for note cards.\n\nAttributes:\n latitude: Latitude coordinate\n longitude: Longitude coordinate\n name: Optional location name (POI/business name from reverse geocoding)\n address: Optional street address\n resolved_at: When the location was reverse geocoded (001-card-ux-rem-sleep)\n\nRelated: migration 154_feed_cards_extensions.sql\nUpdated: 001-card-ux-rem-sleep (added resolved_at tracking)", "properties": { "address": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Full street address", "title": "Address" }, "latitude": { "description": "Latitude coordinate", "maximum": 90.0, "minimum": -90.0, "title": "Latitude", "type": "number" }, "longitude": { "description": "Longitude coordinate", "maximum": 180.0, "minimum": -180.0, "title": "Longitude", "type": "number" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "POI or business name from reverse geocoding", "title": "Name" }, "resolved_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "When the location was reverse geocoded", "title": "Resolved At" } }, "required": [ "latitude", "longitude" ], "title": "Location", "type": "object" }, "LocationPin": { "description": "Geo-location for notes.", "properties": { "address": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Address", "title": "Address" }, "lat": { "description": "Latitude", "title": "Lat", "type": "number" }, "lng": { "description": "Longitude", "title": "Lng", "type": "number" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Location name", "title": "Name" } }, "required": [ "lat", "lng" ], "title": "LocationPin", "type": "object" }, "LocationResolveRequest": { "properties": { "lat": { "description": "Latitude coordinate", "maximum": 90.0, "minimum": -90.0, "title": "Lat", "type": "number" }, "lng": { "description": "Longitude coordinate", "maximum": 180.0, "minimum": -180.0, "title": "Lng", "type": "number" } }, "required": [ "lat", "lng" ], "title": "LocationResolveRequest", "type": "object" }, "LocationResolveResponse": { "properties": { "google_place_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Google Place ID", "title": "Google Place Id" }, "place_address": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Full address", "title": "Place Address" }, "place_category": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Place category", "title": "Place Category" }, "place_name": { "description": "Resolved place name", "title": "Place Name", "type": "string" }, "source": { "default": "cache", "description": "Resolution source: cache, google_places, ors, coordinates", "title": "Source", "type": "string" } }, "required": [ "place_name" ], "title": "LocationResolveResponse", "type": "object" }, "LocationResponse": { "description": "Response model for location data.", "properties": { "address": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Human-readable address", "title": "Address" }, "latitude": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "description": "Home latitude", "title": "Latitude" }, "longitude": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "description": "Home longitude", "title": "Longitude" }, "updated_at": { "description": "Last update timestamp", "format": "date-time", "title": "Updated At", "type": "string" }, "zip_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "ZIP/postal code", "title": "Zip Code" } }, "required": [ "updated_at" ], "title": "LocationResponse", "type": "object" }, "LocationUpdate": { "description": "Request model for updating user's home location.", "properties": { "address": { "anyOf": [ { "maxLength": 500, "type": "string" }, { "type": "null" } ], "description": "Human-readable address", "title": "Address" }, "latitude": { "description": "Home latitude", "maximum": 90.0, "minimum": -90.0, "title": "Latitude", "type": "number" }, "longitude": { "description": "Home longitude", "maximum": 180.0, "minimum": -180.0, "title": "Longitude", "type": "number" }, "zip_code": { "anyOf": [ { "maxLength": 20, "type": "string" }, { "type": "null" } ], "description": "ZIP/postal code", "title": "Zip Code" } }, "required": [ "latitude", "longitude" ], "title": "LocationUpdate", "type": "object" }, "LongestThread": { "properties": { "messages": { "title": "Messages", "type": "integer" }, "subject": { "title": "Subject", "type": "string" } }, "required": [ "subject", "messages" ], "title": "LongestThread", "type": "object" }, "MachineHostFingerprint": { "properties": { "agent_account_id": { "title": "Agent Account Id", "type": "string" }, "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "fingerprint_sha256": { "title": "Fingerprint Sha256", "type": "string" }, "host_label": { "title": "Host Label", "type": "string" }, "id": { "title": "Id", "type": "string" }, "key_type": { "enum": [ "ssh-ed25519", "ssh-rsa", "ecdsa-sha2-nistp256", "ecdsa-sha2-nistp384", "ecdsa-sha2-nistp521" ], "title": "Key Type", "type": "string" }, "recorded_at": { "format": "date-time", "title": "Recorded At", "type": "string" }, "tenant_id": { "title": "Tenant Id", "type": "string" } }, "required": [ "id", "tenant_id", "agent_account_id", "host_label", "key_type", "fingerprint_sha256", "recorded_at", "created_at" ], "title": "MachineHostFingerprint", "type": "object" }, "MachineHostFingerprintsResponse": { "properties": { "fingerprints": { "items": { "$ref": "#/components/schemas/MachineHostFingerprint" }, "title": "Fingerprints", "type": "array" } }, "title": "MachineHostFingerprintsResponse", "type": "object" }, "ManageBookingResponse": { "description": "What the tokenized manage page shows the visitor.", "properties": { "booking_id": { "format": "uuid", "title": "Booking Id", "type": "string" }, "can_cancel": { "title": "Can Cancel", "type": "boolean" }, "can_reschedule": { "title": "Can Reschedule", "type": "boolean" }, "owner_timezone": { "title": "Owner Timezone", "type": "string" }, "page_slug": { "title": "Page Slug", "type": "string" }, "service_name": { "title": "Service Name", "type": "string" }, "slot_end": { "format": "date-time", "title": "Slot End", "type": "string" }, "slot_start": { "format": "date-time", "title": "Slot Start", "type": "string" }, "status": { "title": "Status", "type": "string" } }, "required": [ "booking_id", "status", "service_name", "slot_start", "slot_end", "owner_timezone", "can_reschedule", "can_cancel", "page_slug" ], "title": "ManageBookingResponse", "type": "object" }, "ManualAliasItem": { "description": "One send-as address the member keeps on a mailbox by hand.", "properties": { "address": { "description": "Alias email address", "title": "Address", "type": "string" }, "display_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Name shown with the address", "title": "Display Name" } }, "required": [ "address" ], "title": "ManualAliasItem", "type": "object" }, "ManualAliasesRequest": { "description": "The mailbox's hand-kept aliases, in full (TIDY-19281).", "properties": { "aliases": { "description": "Every alias the mailbox keeps", "items": { "$ref": "#/components/schemas/ManualAliasItem" }, "title": "Aliases", "type": "array" } }, "required": [ "aliases" ], "title": "ManualAliasesRequest", "type": "object" }, "ManualSuppressRequest": { "properties": { "contact_id": { "description": "contacts.id of the lead to suppress.", "title": "Contact Id", "type": "string" }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Address to suppress; defaults to the contact's first address. Must be one of the contact's addresses when given.", "title": "Email" }, "reason": { "default": "", "description": "Member-entered audit note (why this address is suppressed).", "title": "Reason", "type": "string" } }, "required": [ "contact_id" ], "title": "ManualSuppressRequest", "type": "object" }, "ManualSuppressResponse": { "properties": { "cancelled_recipients": { "description": "In-flight queued/retrying recipient rows cancelled.", "title": "Cancelled Recipients", "type": "integer" }, "contact_id": { "title": "Contact Id", "type": "string" }, "email": { "title": "Email", "type": "string" }, "ses_pushed": { "description": "True when the SESv2 account-suppression push succeeded (best-effort; the daily reconcile closes a missed push).", "title": "Ses Pushed", "type": "boolean" }, "suppressed": { "description": "True when the suppression row was newly inserted; False when the address was already suppressed (idempotent no-op).", "title": "Suppressed", "type": "boolean" } }, "required": [ "contact_id", "email", "suppressed", "cancelled_recipients", "ses_pushed" ], "title": "ManualSuppressResponse", "type": "object" }, "ManualUnsuppressRequest": { "properties": { "contact_id": { "description": "contacts.id of the lead to unsuppress.", "title": "Contact Id", "type": "string" }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Address to unsuppress; defaults to the contact's first address.", "title": "Email" }, "reason": { "default": "", "description": "Member-entered audit note (why the suppression is lifted) — recorded on the unsuppressed engagement row (R13 audit).", "title": "Reason", "type": "string" } }, "required": [ "contact_id" ], "title": "ManualUnsuppressRequest", "type": "object" }, "ManualUnsuppressResponse": { "properties": { "contact_id": { "title": "Contact Id", "type": "string" }, "email": { "title": "Email", "type": "string" }, "removed": { "description": "True when a suppression row existed and was deleted.", "title": "Removed", "type": "boolean" }, "ses_pushed": { "description": "True when the SESv2 suppression-removal push succeeded.", "title": "Ses Pushed", "type": "boolean" } }, "required": [ "contact_id", "email", "removed", "ses_pushed" ], "title": "ManualUnsuppressResponse", "type": "object" }, "MappingRule": { "description": "`source_path` is a dot-path with array index (`contact.emails.0`).\nAbsent only on rules whose transforms supply the value (constant/coalesce).", "properties": { "source_path": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Source Path" }, "target_field": { "maxLength": 120, "minLength": 1, "title": "Target Field", "type": "string" }, "transforms": { "items": { "$ref": "#/components/schemas/MappingTransform" }, "title": "Transforms", "type": "array" } }, "required": [ "target_field" ], "title": "MappingRule", "type": "object" }, "MappingRunOutcome": { "description": "TIDY-16814: one declarative mapping's execution outcome on a delivery.\nMirrors the ``payload_mapping_runs`` ledger row; a failed mapping reports\nhere and in the ledger, never as a delivery error.", "properties": { "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Error" }, "mapping_id": { "title": "Mapping Id", "type": "string" }, "outcome": { "anyOf": [ { "enum": [ "created", "updated", "replay" ], "type": "string" }, { "type": "null" } ], "default": null, "title": "Outcome" }, "status": { "enum": [ "ok", "failed" ], "title": "Status", "type": "string" }, "target_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Target Id" } }, "required": [ "mapping_id", "status" ], "title": "MappingRunOutcome", "type": "object" }, "MappingTransform": { "additionalProperties": true, "description": "One transform step. Params are op-specific: constant{value},\nsplit{separator,index}, parse_date{format}, coalesce{paths},\nconditional{equals,write}; trim/lowercase/uppercase take none.", "properties": { "op": { "enum": [ "trim", "lowercase", "uppercase", "constant", "split", "parse_date", "coalesce", "conditional" ], "title": "Op", "type": "string" } }, "required": [ "op" ], "title": "MappingTransform", "type": "object" }, "MarkFailedRequest": { "description": "Request to mark a pipeline as failed.", "properties": { "reason": { "description": "Reason for marking as failed", "minLength": 5, "title": "Reason", "type": "string" } }, "required": [ "reason" ], "title": "MarkFailedRequest", "type": "object" }, "MarkNotSpamResponse": { "properties": { "actions_taken": { "items": { "type": "string" }, "title": "Actions Taken", "type": "array" }, "email_id": { "format": "uuid", "title": "Email Id", "type": "string" }, "success": { "title": "Success", "type": "boolean" } }, "required": [ "success", "email_id", "actions_taken" ], "title": "MarkNotSpamResponse", "type": "object" }, "MarkUnreadRequest": { "properties": { "event_id": { "title": "Event Id", "type": "string" } }, "required": [ "event_id" ], "title": "MarkUnreadRequest", "type": "object" }, "MarkupResponse": { "description": "The four TRMNL view variants. TRMNL rasterizes each into the e-ink PNG.", "properties": { "markup": { "title": "Markup", "type": "string" }, "markup_half_horizontal": { "title": "Markup Half Horizontal", "type": "string" }, "markup_half_vertical": { "title": "Markup Half Vertical", "type": "string" }, "markup_quadrant": { "title": "Markup Quadrant", "type": "string" } }, "required": [ "markup", "markup_half_horizontal", "markup_half_vertical", "markup_quadrant" ], "title": "MarkupResponse", "type": "object" }, "MatchCandidatePreview": { "properties": { "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Email" }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Phone" } }, "title": "MatchCandidatePreview", "type": "object" }, "MatchCondition": { "description": "One AND-term of a rule's match: dimension + operator + value.", "properties": { "dimension": { "$ref": "#/components/schemas/MatchDimension" }, "header_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Header Name" }, "operator": { "$ref": "#/components/schemas/MatchOperator", "default": "equals" }, "value": { "default": "", "title": "Value", "type": "string" } }, "required": [ "dimension" ], "title": "MatchCondition", "type": "object" }, "MatchDimension": { "description": "The dimensions a rule condition can match against.", "enum": [ "sender_address", "sender_domain", "recipient_address", "recipient_domain", "contact_link", "org_link", "subject_pattern", "body_keyword", "header", "url_pattern", "attachment_name", "attachment_content_type", "has_attachment", "has_doc_link", "triage_category", "is_vip" ], "title": "MatchDimension", "type": "string" }, "MatchOperator": { "description": "How a condition's value is compared to the email context.", "enum": [ "equals", "contains", "glob", "regex" ], "title": "MatchOperator", "type": "string" }, "MatchReason": { "description": "Reason why two contacts were flagged as duplicates.", "enum": [ "email_match", "name_similarity", "phone_match", "name_org_match", "name_phone_match" ], "title": "MatchReason", "type": "string" }, "MaterializationSummary": { "properties": { "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Error" }, "status": { "enum": [ "pending", "ready", "error" ], "title": "Status", "type": "string" }, "step": { "anyOf": [ { "enum": [ "harness", "credentials", "mcp", "skills", "roots", "health_check" ], "type": "string" }, { "type": "null" } ], "default": null, "title": "Step" } }, "required": [ "status" ], "title": "MaterializationSummary", "type": "object" }, "MaterializeRequest": { "properties": { "binding_clear_contract": { "anyOf": [ { "const": 2, "type": "integer" }, { "type": "null" } ], "title": "Binding Clear Contract" }, "clear_plugin_bindings": { "default": false, "title": "Clear Plugin Bindings", "type": "boolean" }, "conversation_id": { "format": "uuid", "title": "Conversation Id", "type": "string" }, "credential_ids": { "items": { "format": "uuid", "type": "string" }, "maxItems": 32, "title": "Credential Ids", "type": "array" }, "include_granted_env": { "default": false, "title": "Include Granted Env", "type": "boolean" }, "include_plugin_bindings": { "default": false, "title": "Include Plugin Bindings", "type": "boolean" }, "include_skill_credentials": { "default": false, "title": "Include Skill Credentials", "type": "boolean" }, "include_skill_declarations": { "default": false, "title": "Include Skill Declarations", "type": "boolean" }, "job_activity_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Job Activity Id" }, "protect_skill_credentials": { "default": false, "title": "Protect Skill Credentials", "type": "boolean" }, "room_id": { "maxLength": 512, "minLength": 1, "title": "Room Id", "type": "string" }, "runtime": { "anyOf": [ { "maxLength": 64, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Runtime" }, "session_ref": { "anyOf": [ { "maxLength": 256, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Session Ref" }, "skill_file_credentials": { "default": false, "title": "Skill File Credentials", "type": "boolean" } }, "required": [ "conversation_id", "room_id" ], "title": "MaterializeRequest", "type": "object" }, "MaterializeResponse": { "properties": { "clear_env": { "items": { "type": "string" }, "title": "Clear Env", "type": "array" }, "credentials": { "items": { "$ref": "#/components/schemas/MaterializedCredential" }, "title": "Credentials", "type": "array" }, "public_env": { "items": { "$ref": "#/components/schemas/PublicEnvValue" }, "title": "Public Env", "type": "array" }, "skill_declarations": { "anyOf": [ { "items": { "$ref": "#/components/schemas/SkillEnvDeclaration" }, "type": "array" }, { "type": "null" } ], "default": null, "title": "Skill Declarations" }, "skill_files": { "items": { "$ref": "#/components/schemas/SkillFileValue" }, "title": "Skill Files", "type": "array" }, "withheld": { "items": { "$ref": "#/components/schemas/WithheldSkillCredential" }, "title": "Withheld", "type": "array" } }, "required": [ "credentials" ], "title": "MaterializeResponse", "type": "object" }, "MaterializedCredential": { "properties": { "api_flavor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Api Flavor" }, "base_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Base Url" }, "env_key": { "title": "Env Key", "type": "string" }, "id": { "title": "Id", "type": "string" }, "plugin_kind": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Plugin Kind" }, "provider_slug": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Provider Slug" }, "value": { "title": "Value", "type": "string" } }, "required": [ "id", "env_key", "value" ], "title": "MaterializedCredential", "type": "object" }, "MatrixChannelToggleRequest": { "properties": { "enabled": { "title": "Enabled", "type": "boolean" } }, "required": [ "enabled" ], "title": "MatrixChannelToggleRequest", "type": "object" }, "MatrixChannelToggleResponse": { "properties": { "enabled": { "title": "Enabled", "type": "boolean" }, "room_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Room Id" }, "room_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Room Name" } }, "required": [ "enabled" ], "title": "MatrixChannelToggleResponse", "type": "object" }, "MatrixMentionRequest": { "properties": { "display_name": { "maxLength": 255, "minLength": 1, "title": "Display Name", "type": "string" }, "end": { "minimum": 0.0, "title": "End", "type": "integer" }, "start": { "minimum": 0.0, "title": "Start", "type": "integer" }, "user_id": { "maxLength": 255, "minLength": 3, "title": "User Id", "type": "string" } }, "required": [ "user_id", "display_name", "start", "end" ], "title": "MatrixMentionRequest", "type": "object" }, "MatrixPreflightResponse": { "properties": { "backup_version": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Backup Version" }, "escrow_reachable": { "title": "Escrow Reachable", "type": "boolean" }, "homeserver_reachable": { "title": "Homeserver Reachable", "type": "boolean" }, "matrix_user_id": { "title": "Matrix User Id", "type": "string" } }, "required": [ "matrix_user_id", "homeserver_reachable", "escrow_reachable" ], "title": "MatrixPreflightResponse", "type": "object" }, "MatrixRoomMemberResponse": { "properties": { "account_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Account Id" }, "avatar_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Avatar Url" }, "display_name": { "title": "Display Name", "type": "string" }, "external_workspace": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "External Workspace" }, "is_bot": { "default": false, "title": "Is Bot", "type": "boolean" }, "is_guest": { "default": false, "title": "Is Guest", "type": "boolean" }, "member_kind": { "default": "human", "title": "Member Kind", "type": "string" }, "user_id": { "title": "User Id", "type": "string" } }, "required": [ "user_id", "display_name" ], "title": "MatrixRoomMemberResponse", "type": "object" }, "MatrixRoomMembersResponse": { "properties": { "members": { "items": { "$ref": "#/components/schemas/MatrixRoomMemberResponse" }, "title": "Members", "type": "array" }, "room_id": { "title": "Room Id", "type": "string" } }, "required": [ "room_id" ], "title": "MatrixRoomMembersResponse", "type": "object" }, "MatrixRoomMessageResponse": { "properties": { "body": { "title": "Body", "type": "string" }, "content": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Content" }, "event_id": { "title": "Event Id", "type": "string" }, "msgtype": { "default": "m.text", "title": "Msgtype", "type": "string" }, "origin_server_ts": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Origin Server Ts" }, "room_id": { "title": "Room Id", "type": "string" }, "sender": { "title": "Sender", "type": "string" }, "sender_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Sender Name" } }, "required": [ "event_id", "room_id", "sender", "body" ], "title": "MatrixRoomMessageResponse", "type": "object" }, "MatrixRoomMessagesResponse": { "properties": { "messages": { "items": { "$ref": "#/components/schemas/MatrixRoomMessageResponse" }, "title": "Messages", "type": "array" }, "room_id": { "title": "Room Id", "type": "string" } }, "required": [ "room_id" ], "title": "MatrixRoomMessagesResponse", "type": "object" }, "MatrixTokenResponse": { "properties": { "access_token": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Access Token" }, "device_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Device Id" }, "homeserver_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Homeserver Url" }, "matrix_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Matrix Id" }, "matrix_password": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Matrix Password" }, "presence_visibility_enabled": { "default": true, "title": "Presence Visibility Enabled", "type": "boolean" } }, "required": [ "matrix_id", "access_token", "homeserver_url" ], "title": "MatrixTokenResponse", "type": "object" }, "McpAssistantLinkCreate": { "additionalProperties": false, "description": "Link a connection to exactly one actor: an AI Assistant (``ai_employee_id``)\nor a virtual employee (``agent_member_id``). TIDY-14147 / S5.", "properties": { "active": { "default": true, "title": "Active", "type": "boolean" }, "agent_member_id": { "anyOf": [ { "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Agent Member Id" }, "ai_employee_id": { "anyOf": [ { "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Ai Employee Id" } }, "title": "McpAssistantLinkCreate", "type": "object" }, "McpAssistantLinkResponse": { "properties": { "active": { "title": "Active", "type": "boolean" }, "agent_member_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Agent Member Id" }, "ai_employee_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Ai Employee Id" }, "connection_id": { "title": "Connection Id", "type": "string" }, "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "id": { "title": "Id", "type": "string" }, "tenant_id": { "title": "Tenant Id", "type": "string" }, "updated_at": { "format": "date-time", "title": "Updated At", "type": "string" } }, "required": [ "id", "tenant_id", "connection_id", "active", "created_at", "updated_at" ], "title": "McpAssistantLinkResponse", "type": "object" }, "McpCatalogConnectorResponse": { "description": "One curated catalog connector the user can enable with one toggle.\n\nDeliberately excludes internal columns (transport, enabled, oauth\nauthorize/token URLs, timestamps) and NEVER a secret — the catalog carries\nnone.", "properties": { "auth_method": { "enum": [ "none", "oauth", "bearer_token", "api_key", "pat", "github_app" ], "title": "Auth Method", "type": "string" }, "category": { "title": "Category", "type": "string" }, "connection_mode": { "default": "hosted", "enum": [ "hosted", "endpoint_template", "local_stdio" ], "title": "Connection Mode", "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Description" }, "display_name": { "title": "Display Name", "type": "string" }, "docs_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Docs Url" }, "enableable": { "default": true, "title": "Enableable", "type": "boolean" }, "endpoint_url": { "title": "Endpoint Url", "type": "string" }, "id": { "title": "Id", "type": "string" }, "logo_ref": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Logo Ref" }, "oauth_scope": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Oauth Scope" }, "scopes_note": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Scopes Note" }, "setup_instructions": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Setup Instructions" }, "slug": { "title": "Slug", "type": "string" }, "sort_order": { "title": "Sort Order", "type": "integer" }, "vendor": { "title": "Vendor", "type": "string" } }, "required": [ "id", "slug", "display_name", "vendor", "category", "endpoint_url", "auth_method", "sort_order" ], "title": "McpCatalogConnectorResponse", "type": "object" }, "McpDeploymentAckEntry": { "description": "What the host did with one server block.", "properties": { "config": { "anyOf": [ { "maxLength": 1024, "type": "string" }, { "type": "null" } ], "title": "Config" }, "connection_id": { "maxLength": 64, "title": "Connection Id", "type": "string" }, "error": { "anyOf": [ { "maxLength": 1000, "type": "string" }, { "type": "null" } ], "title": "Error" }, "status": { "enum": [ "deployed", "error", "removed" ], "title": "Status", "type": "string" } }, "required": [ "connection_id", "status" ], "title": "McpDeploymentAckEntry", "type": "object" }, "McpDeploymentEnvError": { "description": "One connection whose auth could not be materialized. Loud by design.", "properties": { "connection_id": { "maxLength": 64, "title": "Connection Id", "type": "string" }, "detail": { "maxLength": 1000, "title": "Detail", "type": "string" } }, "required": [ "connection_id", "detail" ], "title": "McpDeploymentEnvError", "type": "object" }, "McpDeploymentServer": { "description": "One server block the connector writes into the harness's own MCP config.\n\nTransport-shaped: HTTP servers carry ``url`` + ``headers``; stdio servers\ncarry ``command``/``args``/``cwd``/``env``. Every secret-bearing string is\na ``${TIDY_MCP_*}`` reference, resolved from the environment file at\nharness connect time.", "properties": { "args": { "items": { "type": "string" }, "maxItems": 64, "title": "Args", "type": "array" }, "command": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Command" }, "connection_id": { "maxLength": 64, "title": "Connection Id", "type": "string" }, "cwd": { "anyOf": [ { "maxLength": 1024, "type": "string" }, { "type": "null" } ], "default": null, "title": "Cwd" }, "env": { "additionalProperties": { "type": "string" }, "title": "Env", "type": "object" }, "headers": { "additionalProperties": { "type": "string" }, "title": "Headers", "type": "object" }, "name": { "maxLength": 120, "minLength": 1, "title": "Name", "type": "string" }, "scope": { "enum": [ "tenant", "workshop" ], "title": "Scope", "type": "string" }, "tools_policy": { "items": { "$ref": "#/components/schemas/McpDeploymentToolPolicy" }, "maxItems": 512, "title": "Tools Policy", "type": "array" }, "transport": { "enum": [ "http", "stdio" ], "title": "Transport", "type": "string" }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Url" } }, "required": [ "connection_id", "name", "transport", "scope" ], "title": "McpDeploymentServer", "type": "object" }, "McpDeploymentToolPolicy": { "description": "Per-tool policy that travels with a deployed server (R14).\n\nSame shape the runtime resolver serves: name + exposure + execution\npolicy. Never carries write_capable/description — the harness only needs\nthe gate, not the metadata.", "properties": { "execution_policy": { "default": "always_ask", "enum": [ "run_automatically", "always_ask" ], "title": "Execution Policy", "type": "string" }, "exposed": { "default": true, "title": "Exposed", "type": "boolean" }, "tool_name": { "maxLength": 300, "title": "Tool Name", "type": "string" } }, "required": [ "tool_name" ], "title": "McpDeploymentToolPolicy", "type": "object" }, "McpOAuthAuthorizeResponse": { "description": "Returned when an OAuth flow is initiated — the URL the user must visit.", "properties": { "authorization_url": { "title": "Authorization Url", "type": "string" }, "connection_id": { "title": "Connection Id", "type": "string" }, "state": { "title": "State", "type": "string" } }, "required": [ "connection_id", "authorization_url", "state" ], "title": "McpOAuthAuthorizeResponse", "type": "object" }, "McpOAuthCallbackRequest": { "properties": { "code": { "minLength": 1, "title": "Code", "type": "string" }, "state": { "minLength": 1, "title": "State", "type": "string" } }, "required": [ "state", "code" ], "title": "McpOAuthCallbackRequest", "type": "object" }, "McpRuntimeActiveResponse": { "properties": { "servers": { "items": { "$ref": "#/components/schemas/McpRuntimeServer" }, "title": "Servers", "type": "array" } }, "title": "McpRuntimeActiveResponse", "type": "object" }, "McpRuntimeServer": { "description": "One active external MCP server resolved for a runtime turn.\n\n``auth_header`` is the in-memory header the runtime applies to its MCP\nsession; it is empty when the connection could not resolve auth (status\n``error``). The secret value itself is never persisted or logged.", "properties": { "auth_header": { "additionalProperties": { "type": "string" }, "title": "Auth Header", "type": "object" }, "connection_id": { "title": "Connection Id", "type": "string" }, "connection_type": { "enum": [ "internal", "external" ], "title": "Connection Type", "type": "string" }, "endpoint_url": { "title": "Endpoint Url", "type": "string" }, "name": { "title": "Name", "type": "string" }, "status": { "enum": [ "working", "needs_reauth", "disconnected", "pending" ], "title": "Status", "type": "string" }, "status_detail": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Status Detail" }, "tools_policy": { "items": { "$ref": "#/components/schemas/McpToolPolicy" }, "title": "Tools Policy", "type": "array" } }, "required": [ "connection_id", "name", "endpoint_url", "connection_type", "status" ], "title": "McpRuntimeServer", "type": "object" }, "McpServerConnectionCreate": { "properties": { "auth_method": { "default": "none", "enum": [ "none", "oauth", "bearer_token", "api_key", "pat", "github_app" ], "title": "Auth Method", "type": "string" }, "connection_type": { "default": "external", "enum": [ "internal", "external" ], "title": "Connection Type", "type": "string" }, "credential_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Credential Id" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "endpoint_url": { "anyOf": [ { "maxLength": 2048, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Endpoint Url" }, "name": { "maxLength": 120, "minLength": 1, "title": "Name", "type": "string" }, "oauth_authorize_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Oauth Authorize Url" }, "oauth_client_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Oauth Client Id" }, "oauth_client_secret": { "anyOf": [ { "maxLength": 4096, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Oauth Client Secret", "writeOnly": true }, "oauth_scope": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Oauth Scope" }, "oauth_token_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Oauth Token Url" }, "scope": { "default": "tenant", "enum": [ "tenant", "workshop" ], "title": "Scope", "type": "string" }, "secret_value": { "anyOf": [ { "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Secret Value", "writeOnly": true }, "stdio_args": { "items": { "type": "string" }, "title": "Stdio Args", "type": "array" }, "stdio_command": { "anyOf": [ { "maxLength": 1024, "type": "string" }, { "type": "null" } ], "title": "Stdio Command" }, "stdio_cwd": { "anyOf": [ { "maxLength": 1024, "type": "string" }, { "type": "null" } ], "title": "Stdio Cwd" }, "stdio_env_refs": { "additionalProperties": { "type": "string" }, "title": "Stdio Env Refs", "type": "object" }, "visibility": { "default": "private", "enum": [ "private", "shared" ], "title": "Visibility", "type": "string" }, "workshop_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Workshop Id" } }, "required": [ "name" ], "title": "McpServerConnectionCreate", "type": "object" }, "McpServerConnectionResponse": { "properties": { "auth_method": { "enum": [ "none", "oauth", "bearer_token", "api_key", "pat", "github_app" ], "title": "Auth Method", "type": "string" }, "connection_type": { "enum": [ "internal", "external" ], "title": "Connection Type", "type": "string" }, "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "credential_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Credential Id" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Description" }, "enabled": { "title": "Enabled", "type": "boolean" }, "endpoint_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Endpoint Url" }, "has_credential": { "default": false, "title": "Has Credential", "type": "boolean" }, "has_oauth_tokens": { "default": false, "title": "Has Oauth Tokens", "type": "boolean" }, "id": { "title": "Id", "type": "string" }, "last_checked_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Last Checked At" }, "name": { "title": "Name", "type": "string" }, "oauth_authorize_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Oauth Authorize Url" }, "oauth_scope": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Oauth Scope" }, "oauth_token_expires_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Oauth Token Expires At" }, "owner_id": { "title": "Owner Id", "type": "string" }, "plugin_id": { "title": "Plugin Id", "type": "string" }, "scope": { "default": "tenant", "enum": [ "tenant", "workshop" ], "title": "Scope", "type": "string" }, "status": { "enum": [ "working", "needs_reauth", "disconnected", "pending" ], "title": "Status", "type": "string" }, "status_detail": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Status Detail" }, "stdio_args": { "items": { "type": "string" }, "title": "Stdio Args", "type": "array" }, "stdio_command": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Stdio Command" }, "stdio_cwd": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Stdio Cwd" }, "stdio_env_refs": { "additionalProperties": { "type": "string" }, "title": "Stdio Env Refs Response", "type": "object" }, "tenant_id": { "title": "Tenant Id", "type": "string" }, "updated_at": { "format": "date-time", "title": "Updated At", "type": "string" }, "visibility": { "enum": [ "private", "shared" ], "title": "Visibility", "type": "string" }, "workshop_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Workshop Id" } }, "required": [ "id", "tenant_id", "plugin_id", "owner_id", "name", "visibility", "connection_type", "auth_method", "status", "enabled", "created_at", "updated_at" ], "title": "McpServerConnectionResponse", "type": "object" }, "McpServerConnectionUpdate": { "properties": { "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "enabled": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Enabled" }, "endpoint_url": { "anyOf": [ { "maxLength": 2048, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Endpoint Url" }, "name": { "anyOf": [ { "maxLength": 120, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Name" }, "secret_value": { "anyOf": [ { "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Secret Value", "writeOnly": true }, "stdio_args": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Stdio Args" }, "stdio_command": { "anyOf": [ { "maxLength": 1024, "type": "string" }, { "type": "null" } ], "title": "Stdio Command" }, "stdio_cwd": { "anyOf": [ { "maxLength": 1024, "type": "string" }, { "type": "null" } ], "title": "Stdio Cwd" }, "stdio_env_refs": { "anyOf": [ { "additionalProperties": { "type": "string" }, "type": "object" }, { "type": "null" } ], "title": "Stdio Env Refs" }, "visibility": { "anyOf": [ { "enum": [ "private", "shared" ], "type": "string" }, { "type": "null" } ], "title": "Visibility" } }, "title": "McpServerConnectionUpdate", "type": "object" }, "McpServerStatusResponse": { "properties": { "id": { "title": "Id", "type": "string" }, "last_checked_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Last Checked At" }, "status": { "enum": [ "working", "needs_reauth", "disconnected", "pending" ], "title": "Status", "type": "string" }, "status_detail": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Status Detail" } }, "required": [ "id", "status" ], "title": "McpServerStatusResponse", "type": "object" }, "McpToolListItem": { "properties": { "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Description" }, "execution_policy": { "enum": [ "run_automatically", "always_ask" ], "title": "Execution Policy", "type": "string" }, "exposed": { "title": "Exposed", "type": "boolean" }, "tool_name": { "title": "Tool Name", "type": "string" }, "write_capable": { "title": "Write Capable", "type": "boolean" } }, "required": [ "tool_name", "write_capable", "exposed", "execution_policy" ], "title": "McpToolListItem", "type": "object" }, "McpToolListResponse": { "properties": { "connection_id": { "title": "Connection Id", "type": "string" }, "status": { "enum": [ "working", "needs_reauth", "disconnected", "pending" ], "title": "Status", "type": "string" }, "status_detail": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Status Detail" }, "tools": { "items": { "$ref": "#/components/schemas/McpToolListItem" }, "title": "Tools", "type": "array" } }, "required": [ "connection_id", "status" ], "title": "McpToolListResponse", "type": "object" }, "McpToolPolicy": { "description": "Per-tool policy carried on the runtime resolver contract (TIDY-14145 / S3).\n\nThe runtime (S4) drops any ``exposed=false`` tool from the injected surface\nand reads ``execution_policy`` to decide the in-chat approval gate. Additive\non ``McpRuntimeServer`` — an empty list means the runtime applies defaults.", "properties": { "execution_policy": { "enum": [ "run_automatically", "always_ask" ], "title": "Execution Policy", "type": "string" }, "exposed": { "title": "Exposed", "type": "boolean" }, "tool_name": { "title": "Tool Name", "type": "string" } }, "required": [ "tool_name", "exposed", "execution_policy" ], "title": "McpToolPolicy", "type": "object" }, "McpToolPolicyResponse": { "properties": { "connection_id": { "title": "Connection Id", "type": "string" }, "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "execution_policy": { "enum": [ "run_automatically", "always_ask" ], "title": "Execution Policy", "type": "string" }, "exposed": { "title": "Exposed", "type": "boolean" }, "id": { "title": "Id", "type": "string" }, "tenant_id": { "title": "Tenant Id", "type": "string" }, "tool_name": { "title": "Tool Name", "type": "string" }, "updated_at": { "format": "date-time", "title": "Updated At", "type": "string" }, "write_capable": { "title": "Write Capable", "type": "boolean" } }, "required": [ "id", "tenant_id", "connection_id", "tool_name", "exposed", "execution_policy", "write_capable", "created_at", "updated_at" ], "title": "McpToolPolicyResponse", "type": "object" }, "McpToolPolicyUpdate": { "additionalProperties": false, "properties": { "execution_policy": { "enum": [ "run_automatically", "always_ask" ], "title": "Execution Policy", "type": "string" }, "exposed": { "title": "Exposed", "type": "boolean" } }, "required": [ "exposed", "execution_policy" ], "title": "McpToolPolicyUpdate", "type": "object" }, "McpToolSource": { "description": "An integration as a tool row names it (TIDY-19942 / F18).\n\n``key`` is a ``brand_marks_v1.json`` key, the mark both clients draw;\n``name`` is what a turn's summary says (\"Used the HubSpot integration\").", "properties": { "key": { "maxLength": 64, "title": "Key", "type": "string" }, "name": { "maxLength": 120, "title": "Name", "type": "string" } }, "required": [ "key", "name" ], "title": "McpToolSource", "type": "object" }, "McpToolsWitness": { "description": "What one audience's turn actually listed from one deployed server.\n\nTIDY-19557 F2b: written configs prove only that bytes landed; this is the\nserver's own ``tools/list``, observed through exactly the config that\naudience's harness runs with. Recorded per audience and runtime, never as\na workshop-wide \"tools available\".", "properties": { "connection_id": { "maxLength": 64, "title": "Connection Id", "type": "string" }, "error": { "anyOf": [ { "maxLength": 1000, "type": "string" }, { "type": "null" } ], "title": "Error" }, "runtime": { "maxLength": 64, "minLength": 1, "title": "Runtime", "type": "string" }, "tools": { "items": { "maxLength": 300, "type": "string" }, "maxItems": 512, "title": "Tools", "type": "array" } }, "required": [ "connection_id", "runtime" ], "title": "McpToolsWitness", "type": "object" }, "McpTurnConnection": { "description": "A deployed connection this turn's audience may use.", "properties": { "brand": { "anyOf": [ { "$ref": "#/components/schemas/McpToolSource" }, { "type": "null" } ], "default": null }, "connection_id": { "maxLength": 64, "title": "Connection Id", "type": "string" }, "entitlement": { "enum": [ "own", "shared" ], "title": "Entitlement", "type": "string" }, "env_key": { "anyOf": [ { "maxLength": 128, "type": "string" }, { "type": "null" } ], "default": null, "title": "Env Key" }, "name": { "maxLength": 120, "title": "Name", "type": "string" } }, "required": [ "connection_id", "name", "entitlement" ], "title": "McpTurnConnection", "type": "object" }, "McpTurnLend": { "description": "A stdio config the turn's own person lent and shipped to this workshop.", "properties": { "brand": { "anyOf": [ { "$ref": "#/components/schemas/McpToolSource" }, { "type": "null" } ], "default": null }, "connection_id": { "maxLength": 64, "title": "Connection Id", "type": "string" }, "env_key": { "anyOf": [ { "maxLength": 128, "type": "string" }, { "type": "null" } ], "default": null, "title": "Env Key" }, "name": { "maxLength": 120, "title": "Name", "type": "string" }, "plugin_id": { "maxLength": 64, "title": "Plugin Id", "type": "string" } }, "required": [ "plugin_id", "connection_id", "name" ], "title": "McpTurnLend", "type": "object" }, "MeetingAgentCandidate": { "properties": { "agent_account_id": { "title": "Agent Account Id", "type": "string" }, "display_name": { "title": "Display Name", "type": "string" }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Email" }, "mention_handle": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Mention Handle" } }, "required": [ "agent_account_id", "display_name" ], "title": "MeetingAgentCandidate", "type": "object" }, "MeetingAgentCandidates": { "properties": { "agents": { "items": { "$ref": "#/components/schemas/MeetingAgentCandidate" }, "title": "Agents", "type": "array" }, "meeting_wake_enabled": { "description": "The tenant flag. False ⇒ `agents` is empty and no VE may be invited — the picker exposure and the wake share one switch.", "title": "Meeting Wake Enabled", "type": "boolean" } }, "required": [ "meeting_wake_enabled", "agents" ], "title": "MeetingAgentCandidates", "type": "object" }, "MeetingChannel": { "properties": { "archived": { "default": false, "title": "Archived", "type": "boolean" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Name" }, "room_id": { "description": "The Matrix room id of the meeting's channel.", "title": "Room Id", "type": "string" } }, "required": [ "room_id" ], "title": "MeetingChannel", "type": "object" }, "MeetingDetailResponse": { "properties": { "failure_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Failure Reason" }, "filename": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Filename" }, "id": { "title": "Id", "type": "string" }, "language": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Language" }, "partial": { "default": false, "title": "Partial", "type": "boolean" }, "segments": { "items": { "$ref": "#/components/schemas/MeetingTranscriptSegment" }, "title": "Segments", "type": "array" }, "speaker_map": { "additionalProperties": true, "title": "Speaker Map", "type": "object" }, "status": { "title": "Status", "type": "string" }, "summary_note_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Summary Note Id" } }, "required": [ "id", "status" ], "title": "MeetingDetailResponse", "type": "object" }, "MeetingDurationBreakdown": { "properties": { "long_gt_60m": { "title": "Long Gt 60M", "type": "integer" }, "medium_30_60m": { "title": "Medium 30 60M", "type": "integer" }, "short_lt_30m": { "title": "Short Lt 30M", "type": "integer" } }, "required": [ "short_lt_30m", "medium_30_60m", "long_gt_60m" ], "title": "MeetingDurationBreakdown", "type": "object" }, "MeetingQualityResponse": { "properties": { "avg_attendees": { "title": "Avg Attendees", "type": "number" }, "avg_duration_minutes": { "title": "Avg Duration Minutes", "type": "integer" }, "by_duration": { "$ref": "#/components/schemas/MeetingDurationBreakdown" }, "by_size": { "$ref": "#/components/schemas/MeetingSizeBreakdown" }, "external_pct": { "title": "External Pct", "type": "number" }, "recurring_pct": { "title": "Recurring Pct", "type": "number" } }, "required": [ "avg_duration_minutes", "avg_attendees", "by_size", "by_duration", "recurring_pct", "external_pct" ], "title": "MeetingQualityResponse", "type": "object" }, "MeetingSizeBreakdown": { "properties": { "large_9_plus": { "title": "Large 9 Plus", "type": "integer" }, "one_on_one": { "title": "One On One", "type": "integer" }, "small_2_8": { "title": "Small 2 8", "type": "integer" } }, "required": [ "one_on_one", "small_2_8", "large_9_plus" ], "title": "MeetingSizeBreakdown", "type": "object" }, "MeetingTranscriptSegment": { "properties": { "confidence": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "title": "Confidence" }, "end": { "title": "End", "type": "number" }, "id": { "anyOf": [ { "type": "integer" }, { "type": "string" } ], "title": "Id" }, "speaker_label": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Speaker Label" }, "speaker_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Speaker Name" }, "start": { "title": "Start", "type": "number" }, "text": { "title": "Text", "type": "string" } }, "required": [ "id", "start", "end", "text" ], "title": "MeetingTranscriptSegment", "type": "object" }, "MemberCreate": { "description": "Input for adding a member to a project.", "properties": { "permission": { "default": "can_view", "description": "Permission level (can_edit|can_view)", "pattern": "^(can_edit|can_view)$", "title": "Permission", "type": "string" }, "user_id": { "description": "Account UUID of user to add", "title": "User Id", "type": "string" } }, "required": [ "user_id" ], "title": "MemberCreate", "type": "object" }, "MemberDetailResponse": { "properties": { "display_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Display Name" }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Email" }, "granted_capabilities": { "items": { "type": "string" }, "title": "Granted Capabilities", "type": "array" }, "joined_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Joined At" }, "org_chart_employee_contact_ids": { "items": { "type": "string" }, "title": "Org Chart Employee Contact Ids", "type": "array" }, "per_user_granted_capabilities": { "items": { "type": "string" }, "title": "Per User Granted Capabilities", "type": "array" }, "role": { "title": "Role", "type": "string" }, "role_granted_capabilities": { "items": { "type": "string" }, "title": "Role Granted Capabilities", "type": "array" }, "user_id": { "title": "User Id", "type": "string" } }, "required": [ "user_id", "role", "granted_capabilities", "role_granted_capabilities", "per_user_granted_capabilities", "org_chart_employee_contact_ids" ], "title": "MemberDetailResponse", "type": "object" }, "MemberGateStatusResponse": { "description": "What the calling member's own gate resolves to, and why.", "properties": { "allowlisted": { "title": "Allowlisted", "type": "boolean" }, "consented": { "title": "Consented", "type": "boolean" }, "eligible": { "title": "Eligible", "type": "boolean" }, "mode": { "title": "Mode", "type": "string" } }, "required": [ "mode", "allowlisted", "consented", "eligible" ], "title": "MemberGateStatusResponse", "type": "object" }, "MemberInvite": { "description": "Input model for inviting a member to a tenant.\n\nUsed in:\n - POST /api/v1/tenants/{id}/members (member invitation)\n\nAttributes:\n email: Email address of user to invite (must be valid email format)\n role: Role to assign upon acceptance ('Member' or 'Viewer')\n - Owner cannot be invited (must create their own tenant)\n - Default: 'Member' (can read/write, invite others)\n - Alternative: 'Viewer' (read-only access)\n\nValidation:\n - email: Must be valid RFC 5322 format\n - role: Must be exactly 'Member' or 'Viewer'\n\nExample:\n {\n \"email\": \"alice@example.com\",\n \"role\": \"Member\"\n }\n\nRelated: FR-008, KCC-1121, T048", "example": { "email": "alice@example.com", "role": "Member" }, "properties": { "email": { "description": "Email address of user to invite (must be valid)", "examples": [ "alice@example.com", "bob@family.com" ], "format": "email", "title": "Email", "type": "string" }, "role": { "default": "Member", "description": "Role to assign upon acceptance (Member=read/write+invite, Viewer=read-only)", "enum": [ "Member", "Viewer" ], "examples": [ "Member", "Viewer" ], "title": "Role", "type": "string" } }, "required": [ "email" ], "title": "MemberInvite", "type": "object" }, "MemberItem": { "properties": { "account_id": { "title": "Account Id", "type": "string" }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Email" }, "joined_at": { "format": "date-time", "title": "Joined At", "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name" }, "role": { "title": "Role", "type": "string" } }, "required": [ "account_id", "email", "name", "role", "joined_at" ], "title": "MemberItem", "type": "object" }, "MemberItemField": { "properties": { "facet": { "title": "Facet", "type": "string" }, "label": { "title": "Label", "type": "string" }, "value": { "title": "Value", "type": "string" } }, "required": [ "facet", "label", "value" ], "title": "MemberItemField", "type": "object" }, "MemberItemResponse": { "properties": { "assigned_to": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Assigned To" }, "body": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Body" }, "created_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Created At" }, "fields": { "items": { "$ref": "#/components/schemas/MemberItemField" }, "title": "Fields", "type": "array" }, "id": { "title": "Id", "type": "string" }, "item_table": { "title": "Item Table", "type": "string" }, "kind": { "title": "Kind", "type": "string" }, "owner": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Owner" }, "owner_account_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Owner Account Id" }, "seen": { "description": "The reader may see this item as a member anyway; the open was not recorded.", "title": "Seen", "type": "boolean" }, "status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Status" }, "title": { "title": "Title", "type": "string" }, "updated_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Updated At" }, "visibility": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Visibility" } }, "required": [ "id", "item_table", "title", "kind", "seen" ], "title": "MemberItemResponse", "type": "object" }, "MemberListItem": { "properties": { "display_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Display Name" }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Email" }, "granted_capabilities": { "items": { "type": "string" }, "title": "Granted Capabilities", "type": "array" }, "joined_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Joined At" }, "role": { "title": "Role", "type": "string" }, "user_id": { "title": "User Id", "type": "string" } }, "required": [ "user_id", "role", "granted_capabilities" ], "title": "MemberListItem", "type": "object" }, "MemberMessageRequest": { "properties": { "body_text": { "maxLength": 10000, "minLength": 1, "title": "Body Text", "type": "string" }, "client_message_id": { "maxLength": 255, "minLength": 1, "title": "Client Message Id", "type": "string" }, "member_account_id": { "description": "The person's account id.", "format": "uuid", "title": "Member Account Id", "type": "string" } }, "required": [ "member_account_id", "body_text", "client_message_id" ], "title": "MemberMessageRequest", "type": "object" }, "MemberMessageResponse": { "properties": { "conversation_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "The conversation it landed in, for `conversation`.", "title": "Conversation Id" }, "event_id": { "title": "Event Id", "type": "string" }, "landed": { "description": "`conversation`: an employee's message to the person whose conversation it sent it from, posted in that conversation (TIDY-20074 F7). `direct_chat`: the caller's DM with the person.", "enum": [ "conversation", "direct_chat" ], "title": "Landed", "type": "string" }, "notification": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "`conversation`: what telling the person's phone did (`emitted`, a suppression such as quiet hours, or `failed`); null for a retried message.", "title": "Notification" }, "room_id": { "title": "Room Id", "type": "string" } }, "required": [ "room_id", "event_id", "landed" ], "title": "MemberMessageResponse", "type": "object" }, "MemberResponse": { "description": "Response model for member information and listings.\n\nUsed in:\n - GET /api/v1/tenants/{id}/members (list members response items)\n - Nested in tenant detail responses (future enhancement)\n\nAttributes:\n account_id: UUID of member's account (from auth.users)\n email: Email address of member (from auth.users.email)\n role: Current role in this tenant ('Owner', 'Admin', 'Member', or 'Viewer')\n joined_at: Timestamp when member joined this tenant\n - ISO 8601 format\n - Set automatically on first association\n\nExample (Member in Tenant):\n {\n \"account_id\": \"11111111-1111-1111-1111-111111111111\",\n \"email\": \"alice@example.com\",\n \"role\": \"Member\",\n \"joined_at\": \"2025-11-08T10:15:22.123Z\"\n }\n\nExample (Owner in Tenant):\n {\n \"account_id\": \"22222222-2222-2222-2222-222222222222\",\n \"email\": \"dave@heirloomforge.com\",\n \"role\": \"Owner\",\n \"joined_at\": \"2025-11-08T08:00:00.000Z\"\n }\n\nRelated: FR-003, FR-023, KCC-1121, T049", "example": { "account_id": "11111111-1111-1111-1111-111111111111", "email": "alice@example.com", "joined_at": "2025-11-08T10:15:22.123Z", "role": "Member" }, "properties": { "account_id": { "description": "UUID of member's account", "examples": [ "11111111-1111-1111-1111-111111111111" ], "maxLength": 36, "minLength": 36, "title": "Account Id", "type": "string" }, "agent": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "description": "Virtual employee metadata. Null for human members.", "title": "Agent" }, "assignable_roles": { "description": "Roles the requester may give this member from the members roster. Empty when the requester may not change this member's role. Owner is never offered here.", "examples": [ [ "Admin", "Member", "Viewer" ], [ "Member", "Viewer" ], [] ], "items": { "enum": [ "Admin", "Member", "Viewer" ], "type": "string" }, "title": "Assignable Roles", "type": "array" }, "display_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Human or virtual employee display name", "examples": [ "R22 Research Specialist" ], "title": "Display Name" }, "email": { "description": "Email address of member", "examples": [ "alice@example.com", "bob@family.com" ], "title": "Email", "type": "string" }, "joined_at": { "description": "Timestamp when member joined this tenant", "examples": [ "2025-11-08T10:15:22.123Z" ], "format": "date-time", "title": "Joined At", "type": "string" }, "member_status": { "default": "active", "description": "Tenant membership status", "enum": [ "active", "suspended", "revoked" ], "title": "Member Status", "type": "string" }, "member_type": { "default": "human", "description": "Tenant member class", "enum": [ "human", "virtual_employee" ], "title": "Member Type", "type": "string" }, "role": { "description": "Current role in tenant (Owner=full control, Admin=everything but billing, tenant deletion and the Owner role, Member=read/write+invite, Viewer=read-only)", "enum": [ "Owner", "Admin", "Member", "Viewer" ], "examples": [ "Owner", "Admin", "Member", "Viewer" ], "title": "Role", "type": "string" } }, "required": [ "account_id", "email", "role", "joined_at" ], "title": "MemberResponse", "type": "object" }, "MemoryCorrectionRequest": { "description": "Retire one wrong memory row (D1: retire, don't argue).", "properties": { "principal_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Principal Id" }, "reason": { "maxLength": 2000, "minLength": 1, "title": "Reason", "type": "string" }, "replacement_text": { "anyOf": [ { "maxLength": 8000, "type": "string" }, { "type": "null" } ], "title": "Replacement Text" }, "source_id": { "maxLength": 64, "minLength": 1, "title": "Source Id", "type": "string" }, "source_kind": { "enum": [ "insight", "assertion", "linked_reference", "agent_episodic" ], "title": "Source Kind", "type": "string" } }, "required": [ "source_kind", "source_id", "reason" ], "title": "MemoryCorrectionRequest", "type": "object" }, "MemoryCorrectionResponse": { "properties": { "action": { "enum": [ "retired", "expired", "superseded" ], "title": "Action", "type": "string" }, "corrected": { "title": "Corrected", "type": "boolean" }, "replacement_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Replacement Id" }, "source_id": { "title": "Source Id", "type": "string" }, "source_kind": { "title": "Source Kind", "type": "string" } }, "required": [ "corrected", "action", "source_kind", "source_id" ], "title": "MemoryCorrectionResponse", "type": "object" }, "MemoryInterpretationResponse": { "description": "The gate's outcome for one item.", "properties": { "can_promote": { "description": "A gated item the user may promote into the interpretation tier.", "title": "Can Promote", "type": "boolean" }, "id": { "description": "Typed ID of the item", "title": "Id", "type": "string" }, "interpretation": { "description": "Whether the relationship LLM and entity/fact writes may read this item.", "enum": [ "allowed", "gated" ], "title": "Interpretation", "type": "string" }, "promoted": { "description": "The user manually promoted this item.", "title": "Promoted", "type": "boolean" }, "reason": { "description": "Why the gate decided as it did.", "title": "Reason", "type": "string" }, "reason_label": { "description": "User-facing copy for the reason.", "title": "Reason Label", "type": "string" }, "retrieval": { "const": "indexed", "default": "indexed", "description": "Retrieval always runs — the item is searchable regardless of the gate.", "title": "Retrieval", "type": "string" } }, "required": [ "id", "interpretation", "reason", "reason_label", "promoted", "can_promote" ], "title": "MemoryInterpretationResponse", "type": "object" }, "MemoryRememberRequest": { "description": "Remember one user-stated fact into the principal's substrate.", "properties": { "fact_text": { "maxLength": 8000, "minLength": 1, "title": "Fact Text", "type": "string" }, "kind": { "default": "fact", "maxLength": 32, "title": "Kind", "type": "string" }, "principal_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Principal Id" }, "reminder_date": { "anyOf": [ { "maxLength": 40, "type": "string" }, { "type": "null" } ], "title": "Reminder Date" }, "reminder_title": { "anyOf": [ { "maxLength": 500, "type": "string" }, { "type": "null" } ], "title": "Reminder Title" } }, "required": [ "fact_text" ], "title": "MemoryRememberRequest", "type": "object" }, "MemoryRememberResponse": { "properties": { "insight_id": { "title": "Insight Id", "type": "string" }, "observation_prefix": { "title": "Observation Prefix", "type": "string" }, "principal_id": { "title": "Principal Id", "type": "string" }, "remembered": { "title": "Remembered", "type": "boolean" }, "reminder_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Reminder Id" } }, "required": [ "remembered", "insight_id", "principal_id", "observation_prefix" ], "title": "MemoryRememberResponse", "type": "object" }, "MemorySearchHit": { "properties": { "id": { "title": "Id", "type": "string" }, "kind": { "title": "Kind", "type": "string" }, "label": { "title": "Label", "type": "string" }, "level": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Level" }, "snippet": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Snippet" } }, "required": [ "kind", "id", "label" ], "title": "MemorySearchHit", "type": "object" }, "MemorySearchRequest": { "description": "Elect a pull-mode memory search for the current turn.", "properties": { "limit": { "default": 10, "maximum": 50.0, "minimum": 1.0, "title": "Limit", "type": "integer" }, "query": { "maxLength": 4000, "minLength": 1, "title": "Query", "type": "string" }, "scope_level": { "anyOf": [ { "maxLength": 32, "type": "string" }, { "type": "null" } ], "title": "Scope Level" }, "scope_ref_id": { "anyOf": [ { "maxLength": 64, "type": "string" }, { "type": "null" } ], "title": "Scope Ref Id" } }, "required": [ "query" ], "title": "MemorySearchRequest", "type": "object" }, "MemorySearchResponse": { "properties": { "hits": { "items": { "$ref": "#/components/schemas/MemorySearchHit" }, "title": "Hits", "type": "array" }, "result_count": { "title": "Result Count", "type": "integer" } }, "required": [ "hits", "result_count" ], "title": "MemorySearchResponse", "type": "object" }, "MentionedCommentResponse": { "description": "One row of ``GET /comments/mentions`` — a comment the caller is in.\n\nCarries the anchor text + thread root + parent route so S6's Chat Comments\nsection can render and link WITHOUT parent access. NEVER the parent body.", "properties": { "anchor_block_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Anchor Block Id" }, "anchor_text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Anchor Text" }, "author_email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Author Email" }, "author_id": { "format": "uuid", "title": "Author Id", "type": "string" }, "author_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Author Name" }, "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "id": { "format": "uuid", "title": "Id", "type": "string" }, "parent_id": { "format": "uuid", "title": "Parent Id", "type": "string" }, "parent_route": { "title": "Parent Route", "type": "string" }, "parent_type": { "title": "Parent Type", "type": "string" }, "plain_text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Plain Text" }, "thread_root_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Thread Root Id" }, "updated_at": { "format": "date-time", "title": "Updated At", "type": "string" }, "visibility": { "title": "Visibility", "type": "string" } }, "required": [ "id", "parent_type", "parent_id", "parent_route", "author_id", "visibility", "created_at", "updated_at" ], "title": "MentionedCommentResponse", "type": "object" }, "MergeConflict": { "description": "A conflict between two contact field values.\n\nShown in MergePreview when contacts have different values\nfor the same field that cannot be automatically combined.\n\nAttributes:\n field: Field name with conflict\n primary_value: Value from primary contact\n secondary_value: Value from secondary contact\n resolved_value: Auto-resolved value (user can override)\n resolution_reason: Why this resolution was chosen", "properties": { "field": { "description": "Field name", "examples": [ "organization" ], "title": "Field", "type": "string" }, "primary_value": { "description": "Value from primary contact", "title": "Primary Value" }, "resolution_reason": { "description": "Reason for resolution choice", "examples": [ "Primary contact has more data" ], "title": "Resolution Reason", "type": "string" }, "resolved_value": { "description": "Automatically resolved value", "title": "Resolved Value" }, "secondary_value": { "description": "Value from secondary contact", "title": "Secondary Value" } }, "required": [ "field", "primary_value", "secondary_value", "resolved_value", "resolution_reason" ], "title": "MergeConflict", "type": "object" }, "MergeNotesRequest": { "properties": { "source_ids": { "items": { "type": "string" }, "title": "Source Ids", "type": "array" }, "target_id": { "title": "Target Id", "type": "string" } }, "required": [ "target_id", "source_ids" ], "title": "MergeNotesRequest", "type": "object" }, "MergeNotesResponse": { "properties": { "linked_references_redirected": { "title": "Linked References Redirected", "type": "integer" }, "merged_count": { "title": "Merged Count", "type": "integer" }, "skipped_ids": { "items": { "type": "string" }, "title": "Skipped Ids", "type": "array" }, "success": { "title": "Success", "type": "boolean" }, "target_id": { "title": "Target Id", "type": "string" } }, "required": [ "success", "target_id", "merged_count", "skipped_ids", "linked_references_redirected" ], "title": "MergeNotesResponse", "type": "object" }, "MergePreview": { "description": "Three-panel merge preview response.\n\nReturned by POST /api/v1/contacts/merge/preview.\nShows source contacts side-by-side with proposed merged result.\n\nAttributes:\n primary_contact: Contact that will survive (full detail)\n secondary_contact: Contact that will be merged (full detail)\n merged_result: Proposed merged contact (editable)\n field_origins: Which contact each field came from\n mobile_links: Mobile links that will be affected\n conflicts: Fields with conflicting values\n warnings: Warning messages (e.g., \"VIP contact will be merged\")\n\nRelated: apps/mobile/src/lib/components/contacts/MergePreview.svelte", "properties": { "conflicts": { "default": [], "description": "Fields with conflicting values", "items": { "$ref": "#/components/schemas/MergeConflict" }, "title": "Conflicts", "type": "array" }, "field_origins": { "$ref": "#/components/schemas/FieldOrigins", "description": "Origin of each field in merged result" }, "member_merge": { "default": false, "description": "True when either contact is a workspace-member row (TIDY-15266). The member contact always survives; execution auto-swaps orientation when the member is passed as secondary.", "title": "Member Merge", "type": "boolean" }, "merged_result": { "additionalProperties": true, "description": "Proposed merged result - can be edited by user", "title": "Merged Result", "type": "object" }, "mobile_links": { "default": [], "description": "Mobile links that will be affected", "items": { "$ref": "#/components/schemas/MobileLinkPreview" }, "title": "Mobile Links", "type": "array" }, "orientation_swapped": { "default": false, "description": "True when the merge keeps the request's secondary_id: a workspace-member contact, or the Shared contact when the other is Private, always survives (TIDY-15266, TIDY-19981). The caller cannot choose the other orientation.", "title": "Orientation Swapped", "type": "boolean" }, "primary_contact": { "additionalProperties": true, "description": "Primary (surviving) contact - full detail. Always the contact the merge keeps, which may be the request's secondary_id (see orientation_swapped).", "title": "Primary Contact", "type": "object" }, "private_into_shared": { "default": false, "description": "True when one contact is Private (only its owner sees it) and the other Shared (everyone in the workspace sees it) (TIDY-19981). The Shared contact survives, conflicting fields default to its values, and the Private contact's details become visible to everyone in the workspace.", "title": "Private Into Shared", "type": "boolean" }, "reference_counts": { "additionalProperties": { "additionalProperties": { "type": "integer" }, "type": "object" }, "description": "Preflight counts keyed by primary/secondary contact across reference categories that merge must preserve or rehome.", "title": "Reference Counts", "type": "object" }, "secondary_contact": { "additionalProperties": true, "description": "Secondary (merged) contact - full detail", "title": "Secondary Contact", "type": "object" }, "warnings": { "default": [], "description": "Warning messages for user", "items": { "type": "string" }, "title": "Warnings", "type": "array" } }, "required": [ "primary_contact", "secondary_contact", "merged_result", "field_origins" ], "title": "MergePreview", "type": "object" }, "MergePreviewRequest": { "description": "Request for POST /api/v1/contacts/merge/preview.\n\nAttributes:\n primary_id: ID of contact to keep (will survive merge)\n secondary_id: ID of contact to merge into primary", "properties": { "primary_id": { "description": "Contact ID to keep (survives merge)", "title": "Primary Id", "type": "string" }, "secondary_id": { "description": "Contact ID to merge (will be deleted)", "title": "Secondary Id", "type": "string" } }, "required": [ "primary_id", "secondary_id" ], "title": "MergePreviewRequest", "type": "object" }, "MergeResponse": { "description": "Response for project merge.", "properties": { "archived_projects": { "description": "UUIDs of archived source projects", "items": { "type": "string" }, "title": "Archived Projects", "type": "array" }, "items_moved": { "description": "Total number of items moved to target project", "title": "Items Moved", "type": "integer" }, "merged_count": { "description": "Number of source projects merged", "title": "Merged Count", "type": "integer" }, "target_id": { "description": "UUID of the target project", "title": "Target Id", "type": "string" } }, "required": [ "merged_count", "items_moved", "target_id" ], "title": "MergeResponse", "type": "object" }, "MergeResult": { "description": "Response from POST /api/v1/contacts/merge.\n\nReturned after successful merge execution.\n\nAttributes:\n success: Whether merge completed successfully\n merged_contact: The final merged contact\n secondary_contact_id: ID of the merged (soft-deleted) contact\n affected_records: Counts of updated records per table\n merge_audit_id: ID of the audit record\n\nRelated: apps/mobile/src/lib/components/contacts/MergeConfirmDialog.svelte", "properties": { "affected_records": { "$ref": "#/components/schemas/AffectedRecords", "description": "Count of updated records per table" }, "merge_audit_id": { "description": "ID of audit record for this merge", "title": "Merge Audit Id", "type": "string" }, "merged_contact": { "additionalProperties": true, "description": "Final merged contact", "title": "Merged Contact", "type": "object" }, "orientation_swapped": { "default": false, "description": "True when the backend swapped primary/secondary so the workspace-member contact (TIDY-15266), or the Shared contact merged with a Private one (TIDY-19981), survives. secondary_contact_id reflects the ACTUAL merged (soft-deleted) contact after the swap.", "title": "Orientation Swapped", "type": "boolean" }, "secondary_contact_id": { "description": "ID of merged (soft-deleted) contact", "title": "Secondary Contact Id", "type": "string" }, "success": { "description": "Whether merge completed", "title": "Success", "type": "boolean" }, "unresolved_addresses": { "description": "Addresses the merged contact carried that the survivor cannot resolve (TIDY-18067). Always empty on success: a non-empty set rolls the merge back and surfaces as HTTP 409 with the same list.", "items": { "type": "string" }, "title": "Unresolved Addresses", "type": "array" } }, "required": [ "success", "merged_contact", "secondary_contact_id", "affected_records", "merge_audit_id" ], "title": "MergeResult", "type": "object" }, "MergeUndoResponse": { "description": "Response from POST /api/v1/contacts/merge/{merge_audit_id}/undo.\n\nReverses a contact merge from its audit snapshot (S10).\n\nAttributes:\n merge_audit_id: ID of the reversed merge audit record.\n restored: True when this call performed the restore.\n already_restored: True when the merge was already undone (no-op).\n survivor_id: The merge survivor (primary) contact id.\n loser_id: The resurrected loser (secondary) contact id.\n fields_restored: Whether the survivor's pre-merge fields changed.\n rows_reversed: Per-table count of cascade rows repointed back to the loser.", "properties": { "already_restored": { "description": "True when the merge was already undone (idempotent no-op)", "title": "Already Restored", "type": "boolean" }, "fields_restored": { "description": "Whether the survivor's pre-merge fields were restored", "title": "Fields Restored", "type": "boolean" }, "loser_id": { "description": "Resurrected loser (secondary) contact id", "title": "Loser Id", "type": "string" }, "merge_audit_id": { "description": "ID of the reversed merge audit record", "title": "Merge Audit Id", "type": "string" }, "restored": { "description": "True when this call performed the restore", "title": "Restored", "type": "boolean" }, "rows_reversed": { "additionalProperties": { "type": "integer" }, "description": "Per-table count of cascade rows repointed back to the loser", "title": "Rows Reversed", "type": "object" }, "survivor_id": { "description": "Survivor (primary) contact id", "title": "Survivor Id", "type": "string" } }, "required": [ "merge_audit_id", "restored", "already_restored", "survivor_id", "loser_id", "fields_restored" ], "title": "MergeUndoResponse", "type": "object" }, "MessageResult": { "properties": { "embed": { "anyOf": [ { "$ref": "#/components/schemas/EmbedSummary" }, { "type": "null" } ] }, "event_id": { "title": "Event Id", "type": "string" }, "highlights": { "items": { "type": "string" }, "title": "Highlights", "type": "array" }, "room_id": { "title": "Room Id", "type": "string" }, "room_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Room Name" }, "score": { "title": "Score", "type": "number" }, "sender_account_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Sender Account Id" }, "sender_avatar_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Sender Avatar Url" }, "sender_matrix_id": { "title": "Sender Matrix Id", "type": "string" }, "sender_name": { "title": "Sender Name", "type": "string" }, "snippet": { "title": "Snippet", "type": "string" }, "thread_root_event_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Thread Root Event Id" }, "ts": { "format": "date-time", "title": "Ts", "type": "string" } }, "required": [ "event_id", "room_id", "room_name", "sender_account_id", "sender_matrix_id", "sender_name", "ts", "snippet", "score" ], "title": "MessageResult", "type": "object" }, "MessagesResponse": { "properties": { "messages": { "items": { "$ref": "#/components/schemas/RelayMessageModel" }, "title": "Messages", "type": "array" }, "next_from": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Next From" } }, "title": "MessagesResponse", "type": "object" }, "MeteringHealthResponse": { "properties": { "coverage": { "items": { "$ref": "#/components/schemas/ServiceCoverage" }, "title": "Coverage", "type": "array" }, "payload_logging": { "additionalProperties": true, "title": "Payload Logging", "type": "object" }, "reconciliation": { "items": { "$ref": "#/components/schemas/ReconciliationEntry" }, "title": "Reconciliation", "type": "array" }, "untagged_calls": { "title": "Untagged Calls", "type": "integer" }, "window_days": { "title": "Window Days", "type": "integer" } }, "required": [ "window_days", "coverage", "untagged_calls", "payload_logging", "reconciliation" ], "title": "MeteringHealthResponse", "type": "object" }, "MigrationChange": { "properties": { "from_value": { "title": "From Value", "type": "string" }, "row_id": { "title": "Row Id", "type": "string" }, "title": { "title": "Title", "type": "string" }, "to_value": { "title": "To Value", "type": "string" } }, "required": [ "row_id", "title", "from_value", "to_value" ], "title": "MigrationChange", "type": "object" }, "MigrationExecuteRequest": { "properties": { "plan_hash": { "minLength": 1, "title": "Plan Hash", "type": "string" }, "project_id": { "format": "uuid", "title": "Project Id", "type": "string" }, "proposed_mappings": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "title": "Proposed Mappings" }, "recipe_key": { "minLength": 1, "title": "Recipe Key", "type": "string" } }, "required": [ "recipe_key", "project_id", "plan_hash" ], "title": "MigrationExecuteRequest", "type": "object" }, "MigrationPlanRequest": { "properties": { "project_id": { "format": "uuid", "title": "Project Id", "type": "string" }, "proposed_mappings": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "title": "Proposed Mappings" }, "recipe_key": { "minLength": 1, "title": "Recipe Key", "type": "string" } }, "required": [ "recipe_key", "project_id" ], "title": "MigrationPlanRequest", "type": "object" }, "MigrationPlanResponse": { "properties": { "changes": { "items": { "$ref": "#/components/schemas/MigrationChange" }, "title": "Changes", "type": "array" }, "executed": { "default": false, "title": "Executed", "type": "boolean" }, "facet_slug": { "title": "Facet Slug", "type": "string" }, "field": { "title": "Field", "type": "string" }, "install_id": { "format": "uuid", "title": "Install Id", "type": "string" }, "mappings": { "items": { "additionalProperties": { "type": "string" }, "type": "object" }, "title": "Mappings", "type": "array" }, "plan_hash": { "title": "Plan Hash", "type": "string" }, "project_id": { "format": "uuid", "title": "Project Id", "type": "string" }, "prompt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Prompt" }, "recipe_key": { "title": "Recipe Key", "type": "string" }, "unmapped_row_count": { "default": 0, "title": "Unmapped Row Count", "type": "integer" }, "unmapped_values": { "items": { "type": "string" }, "title": "Unmapped Values", "type": "array" } }, "required": [ "install_id", "recipe_key", "project_id", "facet_slug", "field", "plan_hash" ], "title": "MigrationPlanResponse", "type": "object" }, "MigrationRecipeResponse": { "description": "A tier-3 recipe the project can run — the declaration, not a plan.", "properties": { "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "facet_slug": { "title": "Facet Slug", "type": "string" }, "field": { "title": "Field", "type": "string" }, "has_prompt": { "default": false, "title": "Has Prompt", "type": "boolean" }, "key": { "title": "Key", "type": "string" }, "label": { "title": "Label", "type": "string" } }, "required": [ "key", "label", "facet_slug", "field" ], "title": "MigrationRecipeResponse", "type": "object" }, "MintEmployeePtyTicketRequest": { "description": "What an employee's terminal is for. Absent: its own shell.", "properties": { "method": { "anyOf": [ { "maxLength": 128, "type": "string" }, { "type": "null" } ], "description": "Its sign-in method. For an ACP registry agent (`acp:`, TIDY-19931), the id of a terminal method the agent declared, as its workshop reports it, or `subscription` for the terminal login the workshop picks from those.", "title": "Method" }, "purpose": { "default": "shell", "description": "`sign_in` runs one harness's own login instead of a shell (TIDY-19929): the employee's machine runs the login its sign-in matrix declares for `runtime` and `method`; no command is ever named here.", "enum": [ "shell", "sign_in" ], "title": "Purpose", "type": "string" }, "requesting_device": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "description": "This device, as on the employee's jobs: a sign-in already live on another one is refused.", "title": "Requesting Device" }, "runtime": { "anyOf": [ { "maxLength": 64, "type": "string" }, { "type": "null" } ], "description": "The harness to sign in.", "title": "Runtime" } }, "title": "MintEmployeePtyTicketRequest", "type": "object" }, "MintPtyTicketResponse": { "description": "A minted PTY attach ticket. The plaintext is returned exactly once.", "properties": { "expires_at": { "description": "ISO 8601 UTC.", "title": "Expires At", "type": "string" }, "lease_generation": { "description": "The employee lease generation this session is fenced to.", "title": "Lease Generation", "type": "integer" }, "session_id": { "description": "The session this ticket admits, and only this one.", "title": "Session Id", "type": "string" }, "ticket": { "description": "Single-use, 120s. Presented on the WS pty.hello frame.", "title": "Ticket", "type": "string" }, "workshop_id": { "title": "Workshop Id", "type": "string" } }, "required": [ "session_id", "ticket", "expires_at", "workshop_id", "lease_generation" ], "title": "MintPtyTicketResponse", "type": "object" }, "MintRowLinkRequest": { "description": "Which row the link should be about (TIDY-16834 / R1).", "properties": { "item_id": { "description": "The row's id.", "title": "Item Id", "type": "string" }, "item_table": { "description": "The primitive table the row lives in — records | contacts.", "title": "Item Table", "type": "string" } }, "required": [ "item_table", "item_id" ], "title": "MintRowLinkRequest", "type": "object" }, "MobileLinkPreview": { "description": "Preview of a mobile_contact_link that will be affected by merge.\n\nAttributes:\n device_id: Device identifier\n device_contact_id: Contact ID on the device\n source: Which contact this link belongs to\n will_transfer: Whether link will be transferred to primary contact", "properties": { "device_contact_id": { "description": "Device contact ID", "title": "Device Contact Id", "type": "string" }, "device_id": { "description": "Device identifier", "title": "Device Id", "type": "string" }, "source": { "description": "Which contact owns this link", "enum": [ "primary", "secondary" ], "title": "Source", "type": "string" }, "will_transfer": { "default": true, "description": "Whether link will be transferred", "title": "Will Transfer", "type": "boolean" } }, "required": [ "device_id", "device_contact_id", "source" ], "title": "MobileLinkPreview", "type": "object" }, "ModalityCapability": { "description": "One modality an output type may declare, with its authoring facts.", "properties": { "default_required_lanes": { "items": { "type": "string" }, "title": "Default Required Lanes", "type": "array" }, "modality": { "title": "Modality", "type": "string" }, "renderer": { "title": "Renderer", "type": "string" }, "target_primitives": { "items": { "type": "string" }, "title": "Target Primitives", "type": "array" } }, "required": [ "modality", "renderer", "target_primitives", "default_required_lanes" ], "title": "ModalityCapability", "type": "object" }, "ModelBreakdown": { "properties": { "avg_latency_ms": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Avg Latency Ms" }, "cache_hits": { "default": 0, "title": "Cache Hits", "type": "integer" }, "cached_tokens": { "default": 0, "title": "Cached Tokens", "type": "integer" }, "calls": { "default": 0, "title": "Calls", "type": "integer" }, "cost_usd": { "default": 0.0, "title": "Cost Usd", "type": "number" }, "hit_rate_pct": { "default": 0.0, "title": "Hit Rate Pct", "type": "number" }, "model": { "title": "Model", "type": "string" }, "total_tokens": { "default": 0, "title": "Total Tokens", "type": "integer" } }, "required": [ "model" ], "title": "ModelBreakdown", "type": "object" }, "ModelPricingCreate": { "properties": { "batch_input_cost_per_m": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Batch Input Cost Per M" }, "batch_output_cost_per_m": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Batch Output Cost Per M" }, "cache_creation_input_cost_per_m": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Cache Creation Input Cost Per M" }, "cache_read_input_cost_per_m": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Cache Read Input Cost Per M" }, "context_threshold": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Context Threshold" }, "input_cost_above_threshold": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Input Cost Above Threshold" }, "input_cost_per_m": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Input Cost Per M" }, "is_free": { "default": false, "title": "Is Free", "type": "boolean" }, "model_name": { "title": "Model Name", "type": "string" }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Notes" }, "output_cost_above_threshold": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Output Cost Above Threshold" }, "output_cost_per_m": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Output Cost Per M" }, "provider": { "title": "Provider", "type": "string" } }, "required": [ "model_name", "provider" ], "title": "ModelPricingCreate", "type": "object" }, "ModelPricingRow": { "properties": { "batch_input_cost_per_m": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Batch Input Cost Per M" }, "batch_output_cost_per_m": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Batch Output Cost Per M" }, "cache_creation_input_cost_per_m": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Cache Creation Input Cost Per M" }, "cache_read_input_cost_per_m": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Cache Read Input Cost Per M" }, "context_threshold": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Context Threshold" }, "id": { "format": "uuid", "title": "Id", "type": "string" }, "input_cost_above_threshold": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Input Cost Above Threshold" }, "input_cost_per_m": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Input Cost Per M" }, "is_free": { "default": false, "title": "Is Free", "type": "boolean" }, "model_name": { "title": "Model Name", "type": "string" }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Notes" }, "output_cost_above_threshold": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Output Cost Above Threshold" }, "output_cost_per_m": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Output Cost Per M" }, "provider": { "title": "Provider", "type": "string" } }, "required": [ "id", "model_name", "provider" ], "title": "ModelPricingRow", "type": "object" }, "ModelPricingUpdate": { "properties": { "batch_input_cost_per_m": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Batch Input Cost Per M" }, "batch_output_cost_per_m": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Batch Output Cost Per M" }, "cache_creation_input_cost_per_m": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Cache Creation Input Cost Per M" }, "cache_read_input_cost_per_m": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Cache Read Input Cost Per M" }, "context_threshold": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Context Threshold" }, "input_cost_above_threshold": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Input Cost Above Threshold" }, "input_cost_per_m": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Input Cost Per M" }, "is_free": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is Free" }, "model_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Model Name" }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Notes" }, "output_cost_above_threshold": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Output Cost Above Threshold" }, "output_cost_per_m": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Output Cost Per M" }, "provider": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Provider" } }, "title": "ModelPricingUpdate", "type": "object" }, "ModelProvider": { "properties": { "api_flavor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Api Flavor" }, "api_key_env": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Api Key Env" }, "chat_sign_in_runtime": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Chat Sign In Runtime" }, "connect_purposes": { "additionalProperties": { "type": "string" }, "title": "Connect Purposes", "type": "object" }, "default_base_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Default Base Url" }, "display_name": { "title": "Display Name", "type": "string" }, "methods": { "items": { "type": "string" }, "title": "Methods", "type": "array" }, "slug": { "title": "Slug", "type": "string" }, "tos_warning": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Tos Warning" }, "workshop_sign_in_runtime": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Workshop Sign In Runtime" } }, "required": [ "slug", "display_name", "methods" ], "title": "ModelProvider", "type": "object" }, "ModelProviderCatalogResponse": { "properties": { "providers": { "items": { "$ref": "#/components/schemas/ModelProvider" }, "title": "Providers", "type": "array" } }, "title": "ModelProviderCatalogResponse", "type": "object" }, "ModelProviderConnectRequest": { "properties": { "account_label": { "anyOf": [ { "maxLength": 256, "type": "string" }, { "type": "null" } ], "title": "Account Label" }, "allowed_networks": { "items": { "type": "string" }, "maxItems": 32, "title": "Allowed Networks", "type": "array" }, "api_flavor": { "anyOf": [ { "enum": [ "openai-completions", "anthropic-messages" ], "type": "string" }, { "type": "null" } ], "title": "Api Flavor" }, "base_url": { "anyOf": [ { "maxLength": 512, "type": "string" }, { "type": "null" } ], "title": "Base Url" }, "method": { "enum": [ "api_key", "native_box_login" ], "title": "Method", "type": "string" }, "provider": { "maxLength": 64, "minLength": 1, "title": "Provider", "type": "string" }, "runtime": { "anyOf": [ { "maxLength": 64, "type": "string" }, { "type": "null" } ], "title": "Runtime" }, "value": { "anyOf": [ { "maxLength": 65536, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Value" }, "workshop_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Workshop Id" }, "workshop_ids": { "anyOf": [ { "items": { "format": "uuid", "type": "string" }, "maxItems": 32, "type": "array" }, { "type": "null" } ], "title": "Workshop Ids" } }, "required": [ "provider", "method" ], "title": "ModelProviderConnectRequest", "type": "object" }, "ModelProviderConnection": { "properties": { "allowed_networks": { "items": { "type": "string" }, "title": "Allowed Networks", "type": "array" }, "api_flavor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Api Flavor" }, "base_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Base Url" }, "created_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Created At" }, "credential_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Credential Id" }, "endpoint_workshop_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Endpoint Workshop Id" }, "endpoint_workshop_ids": { "items": { "type": "string" }, "title": "Endpoint Workshop Ids", "type": "array" }, "id": { "title": "Id", "type": "string" }, "keyless": { "default": false, "title": "Keyless", "type": "boolean" }, "method": { "enum": [ "api_key", "oauth", "native_box_login" ], "title": "Method", "type": "string" }, "native_box_runtime": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Native Box Runtime" }, "native_box_workshop_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Native Box Workshop Id" }, "native_box_workshop_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Native Box Workshop Name" }, "oauth_account_label": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Oauth Account Label" }, "oauth_expires_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Oauth Expires At" }, "oauth_refresh_state": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Oauth Refresh State" }, "plugin_id": { "title": "Plugin Id", "type": "string" }, "provider_display_name": { "title": "Provider Display Name", "type": "string" }, "provider_slug": { "title": "Provider Slug", "type": "string" }, "remedy": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Remedy" }, "status": { "title": "Status", "type": "string" } }, "required": [ "id", "provider_slug", "provider_display_name", "method", "status", "plugin_id" ], "title": "ModelProviderConnection", "type": "object" }, "ModelProviderConnectionsResponse": { "properties": { "connected_credential_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Connected Credential Id" }, "connections": { "items": { "$ref": "#/components/schemas/ModelProviderConnection" }, "title": "Connections", "type": "array" } }, "title": "ModelProviderConnectionsResponse", "type": "object" }, "ModelProviderEndpointRequest": { "properties": { "allowed_networks": { "anyOf": [ { "items": { "type": "string" }, "maxItems": 32, "type": "array" }, { "type": "null" } ], "title": "Allowed Networks" }, "base_url": { "maxLength": 512, "minLength": 1, "title": "Base Url", "type": "string" }, "workshop_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Workshop Id" }, "workshop_ids": { "anyOf": [ { "items": { "format": "uuid", "type": "string" }, "maxItems": 32, "type": "array" }, { "type": "null" } ], "title": "Workshop Ids" } }, "required": [ "base_url" ], "title": "ModelProviderEndpointRequest", "type": "object" }, "ModelProviderModelsResponse": { "properties": { "models": { "items": { "type": "string" }, "title": "Models", "type": "array" } }, "required": [ "models" ], "title": "ModelProviderModelsResponse", "type": "object" }, "ModelSelectionEntry": { "properties": { "models": { "items": { "type": "string" }, "title": "Models", "type": "array" }, "reasoning_level": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Reasoning Level" }, "runtime": { "title": "Runtime", "type": "string" }, "updated_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Updated At" } }, "required": [ "runtime", "models" ], "title": "ModelSelectionEntry", "type": "object" }, "ModelSelectionResponse": { "properties": { "selections": { "items": { "$ref": "#/components/schemas/ModelSelectionEntry" }, "title": "Selections", "type": "array" } }, "title": "ModelSelectionResponse", "type": "object" }, "ModelSelectionSetRequest": { "properties": { "models": { "items": { "type": "string" }, "maxItems": 8, "minItems": 0, "title": "Models", "type": "array" }, "reasoning_level": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Reasoning Level" } }, "required": [ "models" ], "title": "ModelSelectionSetRequest", "type": "object" }, "ModelSpend": { "properties": { "calls": { "title": "Calls", "type": "integer" }, "cost_usd": { "title": "Cost Usd", "type": "number" }, "model": { "title": "Model", "type": "string" } }, "required": [ "model", "cost_usd", "calls" ], "title": "ModelSpend", "type": "object" }, "MoveEmailFolderRequest": { "properties": { "tidy_folder": { "description": "One of inbox/sent/drafts/outbox/done", "title": "Tidy Folder", "type": "string" } }, "required": [ "tidy_folder" ], "title": "MoveEmailFolderRequest", "type": "object" }, "MoveEmailFolderResponse": { "properties": { "id": { "format": "uuid", "title": "Id", "type": "string" }, "tidy_folder": { "title": "Tidy Folder", "type": "string" } }, "required": [ "id", "tidy_folder" ], "title": "MoveEmailFolderResponse", "type": "object" }, "MoveRequest": { "properties": { "project_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Destination project (typed UUID 'P-...' or shortcode). Pass null to move to personal scope.", "examples": [ "P-...", "KITCHEN" ], "title": "Project Id" } }, "title": "MoveRequest", "type": "object" }, "MoveResponse": { "properties": { "container_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Container Id" }, "container_seq": { "title": "Container Seq", "type": "integer" }, "id": { "title": "Id", "type": "string" }, "moved": { "title": "Moved", "type": "boolean" } }, "required": [ "id", "container_seq", "moved" ], "title": "MoveResponse", "type": "object" }, "MuteSynthesisResponse": { "description": "The proposed narrow mute match + an embedded backtest of it.", "properties": { "conditions": { "items": { "$ref": "#/components/schemas/MatchCondition" }, "title": "Conditions", "type": "array" }, "discriminator_tokens": { "default": [], "items": { "type": "string" }, "title": "Discriminator Tokens", "type": "array" }, "email_id": { "title": "Email Id", "type": "string" }, "preview": { "$ref": "#/components/schemas/PreviewResponse" }, "success": { "default": true, "title": "Success", "type": "boolean" }, "template_confidence": { "title": "Template Confidence", "type": "number" } }, "required": [ "email_id", "conditions", "template_confidence", "preview" ], "title": "MuteSynthesisResponse", "type": "object" }, "MyEntitlementsResponse": { "properties": { "allotments": { "additionalProperties": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "title": "Allotments", "type": "object" }, "billing_exempt": { "title": "Billing Exempt", "type": "boolean" }, "can_manage_billing": { "title": "Can Manage Billing", "type": "boolean" }, "connected_inboxes": { "title": "Connected Inboxes", "type": "integer" }, "features": { "additionalProperties": { "type": "boolean" }, "title": "Features", "type": "object" }, "gated_by": { "additionalProperties": { "$ref": "#/components/schemas/FeatureGate" }, "title": "Gated By", "type": "object" }, "overrides_applied": { "items": { "type": "string" }, "title": "Overrides Applied", "type": "array" }, "subscription_status": { "default": "none", "title": "Subscription Status", "type": "string" }, "tier_id": { "title": "Tier Id", "type": "string" } }, "required": [ "tier_id", "features", "allotments", "overrides_applied", "billing_exempt", "connected_inboxes", "can_manage_billing" ], "title": "MyEntitlementsResponse", "type": "object" }, "MyTeamResponse": { "description": "The caller's line on the workspace's team Org chart (TIDY-19750).", "properties": { "project_id": { "anyOf": [ { "description": "Typed primitive ID for projects (prefix 'P').", "examples": [ "P-550e8400-e29b-41d4-a716-446655440000" ], "pattern": "^P-[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "title": "ProjectId", "type": "string", "x-tidy-typed-id-prefix": "P", "x-tidy-typed-id-table": "projects" }, { "type": "null" } ], "default": null, "description": "The project in_project reads: the one asked about, or a room turn's own", "title": "Project Id" }, "room_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "In a room turn: the room in_room reads", "title": "Room Id" }, "teammates": { "items": { "$ref": "#/components/schemas/TeammateResponse" }, "title": "Teammates", "type": "array" } }, "title": "MyTeamResponse", "type": "object" }, "NativeHarnessConnection": { "properties": { "id": { "title": "Id", "type": "string" }, "label": { "title": "Label", "type": "string" } }, "required": [ "id", "label" ], "title": "NativeHarnessConnection", "type": "object" }, "NeedsAttentionCallout": { "properties": { "count": { "title": "Count", "type": "integer" }, "href": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Href" }, "key": { "title": "Key", "type": "string" }, "label": { "title": "Label", "type": "string" }, "severity": { "default": "info", "title": "Severity", "type": "string" } }, "required": [ "key", "label", "count" ], "title": "NeedsAttentionCallout", "type": "object" }, "NeedsAttentionResponse": { "properties": { "needs_attention": { "items": { "$ref": "#/components/schemas/NeedsAttentionCallout" }, "title": "Needs Attention", "type": "array" }, "quick_stats": { "$ref": "#/components/schemas/QuickStats" } }, "required": [ "needs_attention", "quick_stats" ], "title": "NeedsAttentionResponse", "type": "object" }, "NegotiationCancelResponse": { "properties": { "cancelled": { "description": "Negotiation ids whose waiting continuations were stopped.", "items": { "type": "string" }, "title": "Cancelled", "type": "array" } }, "title": "NegotiationCancelResponse", "type": "object" }, "NegotiationHistoryResponse": { "properties": { "event_id": { "title": "Event Id", "type": "string" }, "hops": { "items": { "$ref": "#/components/schemas/NegotiationHopModel" }, "title": "Hops", "type": "array" } }, "required": [ "event_id" ], "title": "NegotiationHistoryResponse", "type": "object" }, "NegotiationHopModel": { "properties": { "details": { "additionalProperties": true, "title": "Details", "type": "object" }, "hop": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Hop" }, "negotiation_id": { "title": "Negotiation Id", "type": "string" }, "recorded_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Recorded At" } }, "required": [ "negotiation_id" ], "title": "NegotiationHopModel", "type": "object" }, "NegotiationRequest": { "description": "Assistant-managed async negotiation context on a COUNTER send (TIDY-16597).\n\nPresent ONLY on the assistant's send path (the conflict-manager skill's\ntool injects it). When present, the server parks a durable continuation\n(`assistant_continuations`) and registers reply-correlation keys so the\ncounterparty's reply resumes the negotiation instead of landing in plain\ntriage. A manual proposal omits this and registers NOTHING (F4).", "properties": { "conflict_event_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The conflict card's event id the hop trail records against.", "title": "Conflict Event Id" }, "conflict_source_proposal_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The conflict entry this negotiation is resolving.", "title": "Conflict Source Proposal Id" }, "conversation_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The assistant conversation the resumed turn re-engages.", "title": "Conversation Id" }, "expires_days": { "default": 5, "description": "Days to wait for a reply before the reaper surfaces the negotiation loudly back to the member.", "maximum": 30.0, "minimum": 1.0, "title": "Expires Days", "type": "integer" }, "hop_count": { "default": 1, "description": "Which outbound proposal of this negotiation this send is. 1 = the initial proposal; 2 = the one allowed autonomous re-counter.", "maximum": 3.0, "minimum": 1.0, "title": "Hop Count", "type": "integer" }, "negotiation_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Continue an existing negotiation (the skill's one autonomous re-counter). Omitted starts a new one.", "title": "Negotiation Id" }, "recurrence_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "iTIP RECURRENCE-ID when negotiating one occurrence (F5).", "title": "Recurrence Id" } }, "title": "NegotiationRequest", "type": "object" }, "NewsSummariesListResponse": { "description": "List of news summaries with pagination.\n\nUsed in GET /api/v1/news-updates/summaries.\n\nAttributes:\n summaries: Array of NewsSummaryResponse objects\n pagination: Pagination metadata\n\nExample:\n {\n \"summaries\": [{...}, {...}],\n \"pagination\": {\"total\": 12, \"limit\": 10, \"offset\": 0, \"has_more\": true}\n }", "properties": { "pagination": { "$ref": "#/components/schemas/api_service__models__news_updates__PaginationInfo", "description": "Pagination metadata" }, "summaries": { "description": "Array of summaries", "items": { "$ref": "#/components/schemas/NewsSummaryResponse" }, "title": "Summaries", "type": "array" } }, "required": [ "summaries", "pagination" ], "title": "NewsSummariesListResponse", "type": "object" }, "NewsSummary": { "description": "Summary of a related news update.", "properties": { "category": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "News category", "title": "Category" }, "id": { "description": "News ID (UUID)", "title": "Id", "type": "string" }, "link_direction": { "default": "outgoing", "description": "Direction of the edge relative to the primitive you asked about: 'outgoing' (the edge starts there and points at this one) or 'incoming' (this one points AT it). TIDY-15687.", "title": "Link Direction", "type": "string" }, "link_type": { "description": "How this news is related", "title": "Link Type", "type": "string" }, "published_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "description": "When published", "title": "Published At" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "News title", "title": "Title" }, "type": { "const": "news_update", "default": "news_update", "title": "Type", "type": "string" } }, "required": [ "id", "link_type" ], "title": "NewsSummary", "type": "object" }, "NewsSummaryResponse": { "description": "Complete news summary object returned by API endpoints.\n\nUsed in:\n - GET /api/v1/news-updates/summaries (list response items)\n - GET /api/v1/news-updates/summaries/{id} (single summary detail)\n\nAttributes:\n id: Summary UUID\n tenant_id: Tenant UUID\n summary_type: Type (daily, weekly, monthly, custom)\n period_start: Period start timestamp\n period_end: Period end timestamp\n title: Summary title\n summary_markdown: AI-generated summary (markdown)\n key_themes: Array of extracted themes\n source_update_ids: Array of source update UUIDs\n total_updates_count: Number of updates summarized\n generated_by: Generator (n8n-workflow, manual, api)\n llm_model: LLM model used (e.g., claude-sonnet-4)\n generation_metadata: Generation details\n is_read: Whether current user has read this\n metadata: Additional metadata\n created_at: Creation timestamp\n updated_at: Last update timestamp\n\nExample:\n {\n \"id\": \"summary-uuid-here\",\n \"tenant_id\": \"tenant-uuid-here\",\n \"summary_type\": \"weekly\",\n \"period_start\": \"2025-11-13T00:00:00Z\",\n \"period_end\": \"2025-11-19T23:59:59Z\",\n \"title\": \"Weekly Summary: Nov 13-19, 2025\",\n \"summary_markdown\": \"# This Week at School...\",\n \"key_themes\": [\"School play auditions\", \"Field trip\", \"Holiday concert\"],\n \"source_update_ids\": [\"uuid1\", \"uuid2\", \"uuid3\"],\n \"total_updates_count\": 5,\n \"generated_by\": \"n8n-workflow\",\n \"llm_model\": \"claude-sonnet-4\",\n \"generation_metadata\": {\"token_count\": 850, \"duration_ms\": 2100},\n \"is_read\": false,\n \"metadata\": {},\n \"created_at\": \"2025-11-19T18:00:00Z\",\n \"updated_at\": \"2025-11-19T18:00:00Z\"\n }", "properties": { "created_at": { "description": "Creation timestamp", "format": "date-time", "title": "Created At", "type": "string" }, "generated_by": { "description": "Generator (n8n-workflow, manual, api)", "title": "Generated By", "type": "string" }, "generation_metadata": { "additionalProperties": true, "description": "Generation details", "title": "Generation Metadata", "type": "object" }, "id": { "description": "Summary UUID", "format": "uuid", "title": "Id", "type": "string" }, "is_read": { "description": "Whether current user has read this", "title": "Is Read", "type": "boolean" }, "key_themes": { "description": "Array of extracted themes", "items": { "type": "string" }, "title": "Key Themes", "type": "array" }, "llm_model": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "LLM model used", "title": "Llm Model" }, "metadata": { "additionalProperties": true, "description": "Additional metadata", "title": "Metadata", "type": "object" }, "period_end": { "description": "Period end timestamp", "format": "date-time", "title": "Period End", "type": "string" }, "period_start": { "description": "Period start timestamp", "format": "date-time", "title": "Period Start", "type": "string" }, "source_update_ids": { "description": "Array of source update UUIDs", "items": { "format": "uuid", "type": "string" }, "title": "Source Update Ids", "type": "array" }, "summary_markdown": { "description": "AI-generated summary (markdown)", "title": "Summary Markdown", "type": "string" }, "summary_type": { "description": "Summary type (daily, weekly, monthly, custom)", "title": "Summary Type", "type": "string" }, "tenant_id": { "description": "Tenant UUID", "format": "uuid", "title": "Tenant Id", "type": "string" }, "title": { "description": "Summary title", "title": "Title", "type": "string" }, "total_updates_count": { "description": "Number of updates summarized", "title": "Total Updates Count", "type": "integer" }, "updated_at": { "description": "Last update timestamp", "format": "date-time", "title": "Updated At", "type": "string" } }, "required": [ "id", "tenant_id", "summary_type", "period_start", "period_end", "title", "summary_markdown", "source_update_ids", "total_updates_count", "generated_by", "is_read", "created_at", "updated_at" ], "title": "NewsSummaryResponse", "type": "object" }, "NewsSummaryUpdate": { "description": "Input for updating a news summary (mark read/unread).\n\nUsed in PUT /api/v1/news-updates/summaries/{summary_id} (TIDY-7366).\n\nAttributes:\n action: Action to perform (mark_read, mark_unread)", "properties": { "action": { "description": "Action: mark_read, mark_unread", "examples": [ "mark_read" ], "title": "Action", "type": "string" } }, "required": [ "action" ], "title": "NewsSummaryUpdate", "type": "object" }, "NewsSummaryUpdateResponse": { "description": "Response model for summary update endpoint.", "properties": { "is_read": { "description": "Whether current user has read this summary", "title": "Is Read", "type": "boolean" }, "status": { "description": "Outcome status (e.g. 'success')", "title": "Status", "type": "string" }, "summary_id": { "description": "Updated summary UUID", "title": "Summary Id", "type": "string" } }, "required": [ "status", "summary_id", "is_read" ], "title": "NewsSummaryUpdateResponse", "type": "object" }, "NewsUpdateCreate": { "description": "Input for creating a news update (used by LLM extractor).\n\nUsed in POST /api/v1/news-updates/ingest batch ingestion.\n\nAttributes:\n title: Optional brief headline\n content: Markdown content (required)\n summary: Optional AI-generated short summary\n images: Array of image objects (MinIO URLs)\n urls: Array of related URL objects\n source_type: Type of source (email, file_upload, etc.)\n source_id: Optional UUID of source document\n source_metadata: Flexible metadata from extraction\n category: Update category (default: general)\n tags: Array of tags for flexible categorization\n importance_score: AI-generated importance (0.0-1.0, default 0.5)\n published_at: When to show update (default: now)\n expires_at: Optional expiration date\n metadata: Additional extensible metadata\n\nExample:\n {\n \"title\": \"School Play Auditions Next Week\",\n \"content\": \"The annual school play will be **The Wizard of Oz** this year...\",\n \"summary\": \"School play auditions for \\\"The Wizard of Oz\\\" next Tue/Wed 3-5pm.\",\n \"images\": [{\"url\": \"https://minio.../poster.png\", \"alt\": \"Poster\", \"caption\": \"Play poster\"}],\n \"urls\": [{\"url\": \"https://school.edu/play\", \"title\": \"More info\"}],\n \"source_type\": \"email\",\n \"source_id\": \"email-canonical-uuid\",\n \"source_metadata\": {\"email_subject\": \"Drama Club\", \"sender\": \"drama@school.edu\"},\n \"category\": \"arts\",\n \"tags\": [\"drama\", \"auditions\"],\n \"importance_score\": 0.75,\n \"published_at\": \"2025-11-19T10:00:00Z\",\n \"metadata\": {\"child_names\": [\"Alice\"], \"school_name\": \"Lincoln Elementary\"}\n }", "properties": { "category": { "default": "general", "description": "Category: school, academic, sports, arts, clubs, community, fundraiser, health, safety, social, volunteer, schedule, policy, admin, event, advertisement, promotion, shipping, payment, order, subscription, account, automated, general", "title": "Category", "type": "string" }, "content": { "description": "Markdown content (required)", "examples": [ "The annual school play will be **The Wizard of Oz**..." ], "minLength": 1, "title": "Content", "type": "string" }, "expires_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "Optional expiration date", "title": "Expires At" }, "images": { "description": "Array of image objects (MinIO URLs)", "items": { "$ref": "#/components/schemas/ImageObject" }, "title": "Images", "type": "array" }, "importance_score": { "default": 0.5, "description": "Importance score (0.0-1.0)", "maximum": 1.0, "minimum": 0.0, "title": "Importance Score", "type": "number" }, "metadata": { "additionalProperties": true, "description": "Additional extensible metadata", "title": "Metadata", "type": "object" }, "published_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "When to show update (default: now)", "title": "Published At" }, "source_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "description": "Optional UUID of source document", "title": "Source Id" }, "source_metadata": { "additionalProperties": true, "description": "Flexible metadata from extraction", "title": "Source Metadata", "type": "object" }, "source_type": { "description": "Source type: email, file_upload, newsletter, announcement, manual", "examples": [ "email" ], "title": "Source Type", "type": "string" }, "summary": { "anyOf": [ { "maxLength": 1000, "type": "string" }, { "type": "null" } ], "description": "AI-generated short summary", "examples": [ "School play auditions next week" ], "title": "Summary" }, "tags": { "description": "Array of tags", "examples": [ [ "drama", "auditions" ] ], "items": { "type": "string" }, "title": "Tags", "type": "array" }, "title": { "anyOf": [ { "maxLength": 500, "type": "string" }, { "type": "null" } ], "description": "Brief headline", "examples": [ "School Play Auditions Next Week" ], "title": "Title" }, "urls": { "description": "Array of related URL objects", "items": { "$ref": "#/components/schemas/URLObject" }, "title": "Urls", "type": "array" } }, "required": [ "content", "source_type" ], "title": "NewsUpdateCreate", "type": "object" }, "NewsUpdateId": { "description": "Typed primitive ID for news_updates (prefix 'U').", "examples": [ "U-550e8400-e29b-41d4-a716-446655440000" ], "pattern": "^U-[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "title": "NewsUpdateId", "type": "string", "x-tidy-typed-id-prefix": "U", "x-tidy-typed-id-table": "news_updates" }, "NewsUpdateResponse": { "description": "Complete news update object returned by API endpoints.\n\nUsed in:\n - GET /api/v1/news-updates (list response items)\n - GET /api/v1/news-updates/{id} (single update detail)\n - POST /api/v1/news-updates/ingest (created updates response)\n\nAttributes:\n id: Update UUID\n tenant_id: Tenant UUID\n title: Optional brief headline\n content: Markdown content\n summary: Optional AI-generated summary\n images: Array of image objects\n urls: Array of URL objects\n source_type: Source type\n source_id: Optional source document UUID\n source_url: Computed URL to view the original source document\n source_metadata: Source metadata\n category: Update category\n tags: Array of tags\n importance_score: Importance (0.0-1.0)\n is_read: Whether current user has read this\n is_dismissed: Whether current user has dismissed this\n published_at: Publication timestamp\n expires_at: Optional expiration timestamp\n metadata: Additional metadata\n created_at: Creation timestamp\n updated_at: Last update timestamp\n\nExample:\n {\n \"id\": \"a1b2c3d4-e5f6-7890-abcd-ef1234567890\",\n \"tenant_id\": \"tenant-uuid-here\",\n \"title\": \"School Play Auditions Next Week\",\n \"content\": \"The annual school play will be...\",\n \"summary\": \"School play auditions next week\",\n \"images\": [...],\n \"urls\": [...],\n \"source_type\": \"email\",\n \"source_id\": \"email-uuid\",\n \"source_url\": \"/email/view?id=email-uuid\",\n \"source_metadata\": {...},\n \"category\": \"arts\",\n \"tags\": [\"drama\", \"auditions\"],\n \"importance_score\": 0.75,\n \"is_read\": false,\n \"is_dismissed\": false,\n \"published_at\": \"2025-11-19T10:00:00Z\",\n \"expires_at\": null,\n \"metadata\": {...},\n \"created_at\": \"2025-11-19T10:05:00Z\",\n \"updated_at\": \"2025-11-19T10:05:00Z\"\n }", "properties": { "category": { "description": "Update category", "title": "Category", "type": "string" }, "content": { "description": "Markdown content", "title": "Content", "type": "string" }, "created_at": { "description": "Creation timestamp", "format": "date-time", "title": "Created At", "type": "string" }, "expires_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "description": "Optional expiration timestamp", "title": "Expires At" }, "id": { "description": "Update UUID", "format": "uuid", "title": "Id", "type": "string" }, "images": { "description": "Array of image objects", "items": { "$ref": "#/components/schemas/ImageObject" }, "title": "Images", "type": "array" }, "importance_score": { "description": "Importance score (0.0-1.0)", "title": "Importance Score", "type": "number" }, "is_dismissed": { "description": "Whether current user has dismissed this", "title": "Is Dismissed", "type": "boolean" }, "is_read": { "description": "Whether current user has read this", "title": "Is Read", "type": "boolean" }, "metadata": { "additionalProperties": true, "description": "Additional metadata", "title": "Metadata", "type": "object" }, "published_at": { "description": "Publication timestamp", "format": "date-time", "title": "Published At", "type": "string" }, "source_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "default": null, "description": "Source document UUID", "title": "Source Id" }, "source_metadata": { "additionalProperties": true, "description": "Source metadata", "title": "Source Metadata", "type": "object" }, "source_type": { "description": "Source type", "title": "Source Type", "type": "string" }, "source_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "URL to view original source document", "title": "Source Url" }, "summary": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "AI-generated summary", "title": "Summary" }, "tags": { "description": "Array of tags", "items": { "type": "string" }, "title": "Tags", "type": "array" }, "tenant_id": { "description": "Tenant UUID", "format": "uuid", "title": "Tenant Id", "type": "string" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Brief headline", "title": "Title" }, "updated_at": { "description": "Last update timestamp", "format": "date-time", "title": "Updated At", "type": "string" }, "urls": { "description": "Array of URL objects", "items": { "$ref": "#/components/schemas/URLObject" }, "title": "Urls", "type": "array" } }, "required": [ "id", "tenant_id", "content", "source_type", "category", "importance_score", "is_read", "is_dismissed", "published_at", "created_at", "updated_at" ], "title": "NewsUpdateResponse", "type": "object" }, "NewsUpdateUpdate": { "description": "Input for updating a news update (mark read/dismiss).\n\nUsed in PUT /api/v1/news-updates/{id}.\n\nAttributes:\n action: Action to perform (mark_read, mark_unread, dismiss, undismiss)\n\nExample:\n {\"action\": \"mark_read\"}", "properties": { "action": { "description": "Action: mark_read, mark_unread, dismiss, undismiss", "examples": [ "mark_read" ], "title": "Action", "type": "string" } }, "required": [ "action" ], "title": "NewsUpdateUpdate", "type": "object" }, "NewsUpdatesListResponse": { "description": "List of news updates with pagination.\n\nUsed in GET /api/v1/news-updates.\n\nAttributes:\n updates: Array of NewsUpdateResponse objects\n pagination: Pagination metadata\n\nExample:\n {\n \"updates\": [{...}, {...}],\n \"pagination\": {\"total\": 127, \"limit\": 50, \"offset\": 0, \"has_more\": true}\n }", "properties": { "pagination": { "$ref": "#/components/schemas/api_service__models__news_updates__PaginationInfo", "description": "Pagination metadata" }, "updates": { "description": "Array of news updates", "items": { "$ref": "#/components/schemas/NewsUpdateResponse" }, "title": "Updates", "type": "array" } }, "required": [ "updates", "pagination" ], "title": "NewsUpdatesListResponse", "type": "object" }, "NewsletterIssueStats": { "properties": { "blog_url": { "title": "Blog Url", "type": "string" }, "campaign_id": { "title": "Campaign Id", "type": "string" }, "click_rate": { "title": "Click Rate", "type": "number" }, "clicked": { "title": "Clicked", "type": "integer" }, "delivered": { "title": "Delivered", "type": "integer" }, "discord_invite_joins": { "title": "Discord Invite Joins", "type": "integer" }, "discord_invite_url": { "description": "The issue's dedicated invite — its join count IS its attribution.", "title": "Discord Invite Url", "type": "string" }, "issue_slug": { "title": "Issue Slug", "type": "string" }, "name": { "title": "Name", "type": "string" }, "open_rate": { "title": "Open Rate", "type": "number" }, "opened": { "title": "Opened", "type": "integer" }, "quality_note": { "title": "Quality Note", "type": "string" }, "sent": { "title": "Sent", "type": "integer" }, "shipped": { "description": "Reached the list (status sending or sent).", "title": "Shipped", "type": "boolean" }, "status": { "title": "Status", "type": "string" }, "week_start": { "description": "Monday of the ISO week the issue covers.", "title": "Week Start", "type": "string" } }, "required": [ "campaign_id", "issue_slug", "week_start", "name", "status", "shipped", "blog_url", "discord_invite_url", "discord_invite_joins", "quality_note", "sent", "delivered", "opened", "clicked", "open_rate", "click_rate" ], "title": "NewsletterIssueStats", "type": "object" }, "NewsletterRollupResponse": { "properties": { "cadence_ok": { "description": "False when any week in the window shipped nothing.", "title": "Cadence Ok", "type": "boolean" }, "issues": { "items": { "$ref": "#/components/schemas/NewsletterIssueStats" }, "title": "Issues", "type": "array" }, "issues_without_quality_note": { "items": { "type": "string" }, "title": "Issues Without Quality Note", "type": "array" }, "missed_weeks": { "description": "Mondays of weeks with no shipped issue — the CMO flags these to Dave.", "items": { "type": "string" }, "title": "Missed Weeks", "type": "array" }, "totals": { "$ref": "#/components/schemas/NewsletterTotals" }, "weeks": { "title": "Weeks", "type": "integer" }, "window_end": { "title": "Window End", "type": "string" }, "window_start": { "title": "Window Start", "type": "string" } }, "required": [ "weeks", "window_start", "window_end", "cadence_ok", "missed_weeks", "issues_without_quality_note", "issues", "totals" ], "title": "NewsletterRollupResponse", "type": "object" }, "NewsletterTotals": { "properties": { "click_rate": { "title": "Click Rate", "type": "number" }, "clicked": { "title": "Clicked", "type": "integer" }, "delivered": { "title": "Delivered", "type": "integer" }, "discord_joins": { "title": "Discord Joins", "type": "integer" }, "issues_shipped": { "title": "Issues Shipped", "type": "integer" }, "open_rate": { "title": "Open Rate", "type": "number" }, "opened": { "title": "Opened", "type": "integer" }, "sent": { "title": "Sent", "type": "integer" } }, "required": [ "issues_shipped", "sent", "delivered", "opened", "clicked", "discord_joins", "open_rate", "click_rate" ], "title": "NewsletterTotals", "type": "object" }, "NoPlacement": { "additionalProperties": false, "description": "Do not touch the body.\n\nOnly ``POST /api/v1/comments`` accepts this: it is the opt-out from that\nendpoint's default, not a placement. The ``insert_embed`` op has no such\nmode — an op that places nothing would be a no-op with a ledger row.", "properties": { "mode": { "const": "none", "title": "Mode", "type": "string" } }, "required": [ "mode" ], "title": "NoPlacement", "type": "object" }, "NoteAppendMarkdownRequest": { "properties": { "markdown": { "description": "Markdown content to splice into the note body.", "minLength": 1, "title": "Markdown", "type": "string" }, "position": { "default": "append", "description": "Where to insert the new content. Defaults to 'append'.", "pattern": "^(append|prepend)$", "title": "Position", "type": "string" } }, "required": [ "markdown" ], "title": "NoteAppendMarkdownRequest", "type": "object" }, "NoteByImportHashResponse": { "description": "Response shape consumed by doc-service /convert/check-duplicate.", "properties": { "exists": { "title": "Exists", "type": "boolean" }, "noteId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Noteid" }, "noteTitle": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Notetitle" } }, "required": [ "exists" ], "title": "NoteByImportHashResponse", "type": "object" }, "NoteCompactCreate": { "description": "Request for POST /api/v1/notes/{note_id}/compact.", "properties": { "snapshot_blob": { "description": "Base64-encoded compacted Yjs snapshot", "title": "Snapshot Blob", "type": "string" } }, "required": [ "snapshot_blob" ], "title": "NoteCompactCreate", "type": "object" }, "NoteCreate": { "description": "Input model for creating new notes.\n\nUsed in:\n - POST /api/v1/notes\n\nAttributes:\n id: Client-provided UUID for idempotent creates (optional, PowerSync)\n title: Note title/summary (required, 1-500 chars)\n content: Detailed note content (required)\n note_type: Category of note (optional, default: general)\n child_associations: JSON array of child associations (optional)\n location: Where this info applies (optional)\n valid_from: When information becomes valid (optional)\n valid_until: When information expires (optional)\n is_sensitive: Flag for sensitive info (optional, default: false)\n source_type: Where note came from (optional, default: manual)\n source_id: Reference to source document (optional)\n confidence_score: AI confidence score (optional)\n\nRelated: migration 035_notes_schema.sql", "properties": { "banner_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Page banner image URL/ref (TIDY-14049 item 6).", "title": "Banner Url" }, "child_associations": { "anyOf": [ { "items": {}, "type": "array" }, { "type": "null" } ], "description": "JSON array of child associations [{child_name, context}]", "title": "Child Associations" }, "confidence_score": { "anyOf": [ { "maximum": 1.0, "minimum": 0.0, "type": "number" }, { "type": "null" } ], "description": "AI confidence score 0.0-1.0", "title": "Confidence Score" }, "contact_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Anchor: Link to contact (UUID)", "title": "Contact Id" }, "content": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Detailed note content (optional for block notes)", "examples": [ "Gate code: 1234#" ], "title": "Content" }, "drawing_version": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Version counter for drawing notes", "title": "Drawing Version" }, "email_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Anchor: Link to email (UUID)", "title": "Email Id" }, "event_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Anchor: Link to calendar event (UUID)", "title": "Event Id" }, "facets": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "description": "Facet types for block notes (e.g. ['quote', 'bookmark'])", "title": "Facets" }, "feed_date_range_end": { "anyOf": [ { "format": "date", "type": "string" }, { "type": "null" } ], "description": "End of date range for recurring feed appearance", "title": "Feed Date Range End" }, "feed_date_range_start": { "anyOf": [ { "format": "date", "type": "string" }, { "type": "null" } ], "description": "Start of date range for recurring feed appearance", "title": "Feed Date Range Start" }, "feed_target_date": { "anyOf": [ { "format": "date", "type": "string" }, { "type": "null" } ], "description": "Date when note should appear in feed", "title": "Feed Target Date" }, "icon": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Page icon — serialized IconValue (emoji/lucide/image ref) (TIDY-14635).", "title": "Icon" }, "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Client-provided UUID for idempotent creates (PowerSync offline sync)", "title": "Id" }, "import_file_hash": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "SHA-256 hash of the original imported file for dedup", "title": "Import File Hash" }, "import_metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "Provider-specific metadata blob", "title": "Import Metadata" }, "import_source": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Import provider slug ('google_drive', 'dropbox', etc.)", "title": "Import Source" }, "import_source_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Foreign id at the source (Drive file_id, ...)", "title": "Import Source Id" }, "import_source_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Original file format: 'docx', 'xlsx', 'pptx'", "title": "Import Source Type" }, "import_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": "ready", "description": "Async pipeline status: importing|extracting|ready|failed", "title": "Import Status" }, "is_sensitive": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": false, "description": "Flag for sensitive info (passwords, codes)", "title": "Is Sensitive" }, "linked_entities": { "anyOf": [ { "items": { "$ref": "#/components/schemas/LinkedEntity" }, "maxItems": 20, "type": "array" }, { "type": "null" } ], "description": "Entity links to record alongside the note. Each entity must already exist in the tenant; missing IDs are silently skipped (logged at INFO). Each entry inserts one linked_references row with link_type='related_to', link_source='user_created'.", "title": "Linked Entities" }, "location": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Where this info applies", "title": "Location" }, "location_pin": { "anyOf": [ { "$ref": "#/components/schemas/LocationPin" }, { "type": "null" } ], "description": "Geo-location where note was created" }, "note_kind": { "anyOf": [ { "enum": [ "note", "reference" ], "type": "string" }, { "type": "null" } ], "description": "Note kind discriminator: note (default) | reference (excluded from extraction)", "title": "Note Kind" }, "note_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": "reference", "description": "Category (gate_code|wifi|carpool|medical|emergency|reference|policy|contact_info|procedure)", "title": "Note Type" }, "notebook_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Workspace/notebook container UUID", "title": "Notebook Id" }, "original_filename": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Original filename of the imported document", "title": "Original Filename" }, "parent_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Parent note UUID for block notes", "title": "Parent Id" }, "plain_text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Plain-text derivative for local/offline search indexing", "title": "Plain Text" }, "project_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Project association for short-id container scoping", "title": "Project Id" }, "properties": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "Page properties (JSONB)", "title": "Properties" }, "resurrect_if_deleted": { "default": false, "description": "When true and the client-provided id matches a soft-deleted row (same tenant, creator-compatible), the create resurrects it: deleted_at is cleared and the payload applied. Explicit capture/paste flows only — never set by background or import callers.", "title": "Resurrect If Deleted", "type": "boolean" }, "source": { "anyOf": [ { "enum": [ "user", "system", "sms_agent", "logseq", "obsidian" ], "type": "string" }, { "type": "null" } ], "default": "user", "description": "Origin of the note (user|system|sms_agent|logseq|obsidian)", "title": "Source" }, "source_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Reference to source document UUID", "title": "Source Id" }, "source_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": "manual", "description": "Where note came from (extracted|manual|imported)", "title": "Source Type" }, "source_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Supabase Storage path to original imported file", "title": "Source Url" }, "spreadsheet_data": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "Univer IWorkbookData JSON for spreadsheet notes", "title": "Spreadsheet Data" }, "tags": { "anyOf": [ { "items": { "type": "string" }, "maxItems": 50, "type": "array" }, { "type": "null" } ], "description": "Tag slugs to apply to the note. F3 / TIDY-9731: the F3 popup sends user-confirmed slugs here and the create handler inserts tag_assignments rows in the same transaction (migration 293's trigger then recomputes notes.tags). Slugs must match ^[a-z0-9_-]{1,64}$ — invalid entries are skipped with a warning log.", "title": "Tags" }, "title": { "description": "Note title/summary (1-500 characters)", "examples": [ "School Gate Code" ], "maxLength": 500, "minLength": 1, "title": "Title", "type": "string" }, "valid_from": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "When information becomes valid", "title": "Valid From" }, "valid_until": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "When information expires", "title": "Valid Until" }, "visibility": { "anyOf": [ { "enum": [ "private", "shared", "tenant" ], "type": "string" }, { "type": "null" } ], "description": "Per-row visibility: private | shared | tenant. Omitted: private, or shared when created in a shared notebook or project.", "title": "Visibility" }, "yjs_state": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Base64-encoded Yjs CRDT state (bytea)", "title": "Yjs State" } }, "required": [ "title" ], "title": "NoteCreate", "type": "object" }, "NoteId": { "description": "Typed primitive ID for notes (prefix 'N').", "examples": [ "N-550e8400-e29b-41d4-a716-446655440000" ], "pattern": "^N-[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "title": "NoteId", "type": "string", "x-tidy-typed-id-prefix": "N", "x-tidy-typed-id-table": "notes" }, "NoteResponse": { "description": "Complete note object returned by API endpoints.\n\nUsed in:\n - GET /api/v1/notes (list response items)\n - GET /api/v1/notes/{id} (single note detail)\n - POST /api/v1/notes (created note response, 201)\n - PUT/PATCH /api/v1/notes/{id} (updated note response)\n\nAttributes:\n id: Unique note identifier (UUID)\n tenant_id: Associated tenant identifier (UUID)\n title: Note title/summary (required)\n content: Detailed note content (required)\n note_type: Category of note (gate_code|wifi|carpool|medical|emergency|general|other)\n child_associations: JSON array of child associations [{child_name, context}]\n location: Where this info applies (e.g., \"Lincoln Elementary\")\n valid_from: When information becomes valid\n valid_until: When information expires\n is_sensitive: Flag for sensitive info (passwords, codes)\n source_type: Where note came from (extracted|manual|imported)\n source_id: Reference to source document\n confidence_score: AI confidence score 0.0-1.0\n created_at: ISO 8601 timestamp of note creation\n updated_at: ISO 8601 timestamp of last modification\n\nRelated: migration 035_notes_schema.sql", "properties": { "aliases": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "default": null, "description": "Page aliases (resolution keys, not display labels)", "title": "Aliases" }, "banner_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Page banner image URL/ref", "title": "Banner Url" }, "body_markdown": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "GET /notes/{id} only: the body rendered as Markdown — `-` bullets, `1.` ordered items, `- [ ]`/`- [x]` tasks, pipe tables with a header row, fenced code with its language, `>` quotes, `---` rules — in the dialect body_edit and markdown writes parse. Null on other routes, and when the body could not be read.", "title": "Body Markdown" }, "body_markdown_unsupported": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "default": null, "description": "GET /notes/{id} only: node types and marks (`mark:underline`) the Markdown rendering could not express. Their text is still rendered; only the wrapper is lost. Empty when the Markdown is complete.", "title": "Body Markdown Unsupported" }, "child_associations": { "anyOf": [ { "items": {}, "type": "array" }, { "type": "null" } ], "default": null, "description": "JSON array of child associations [{child_name, context}]", "examples": [ [ { "child_name": "Emma", "context": "school" } ] ], "title": "Child Associations" }, "confidence_score": { "anyOf": [ { "maximum": 1.0, "minimum": 0.0, "type": "number" }, { "type": "null" } ], "default": null, "description": "AI confidence score 0.0-1.0", "examples": [ 0.85 ], "title": "Confidence Score" }, "contact_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Anchor: Link to contact this note relates to (UUID)", "examples": [ "a1b2c3d4-..." ], "title": "Contact Id" }, "contact_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Display name of linked contact (joined from contacts table)", "examples": [ "John Smith" ], "title": "Contact Name" }, "container_seq": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Per-container sequence number for short-id composition", "title": "Container Seq" }, "content": { "description": "Legacy body column. Not maintained once the note has a `yjs_state` — it can hold an older draft. Read `plain_text` (search text) or, on GET /notes/{id}, `body_markdown` (structure kept) for the current body.", "examples": [ "Gate code: 1234#" ], "title": "Content", "type": "string" }, "created_at": { "description": "ISO 8601 timestamp of note creation", "format": "date-time", "title": "Created At", "type": "string" }, "drawing_version": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Version counter for drawing notes", "title": "Drawing Version" }, "email_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Anchor: Link to email this note is attached to (UUID)", "title": "Email Id" }, "embeds": { "anyOf": [ { "items": { "$ref": "#/components/schemas/DocumentEmbed" }, "type": "array" }, { "type": "null" } ], "default": null, "description": "GET /notes/{id} only: every embed in the body in document order — saved database views (`database` nodes), charts, dashboards and item cards. Null on other routes, and when the body could not be read.", "title": "Embeds" }, "event_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Anchor: Link to calendar event this note is attached to (UUID)", "title": "Event Id" }, "facets": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "default": null, "description": "Facet types for block notes (e.g. ['drawing', 'journal'])", "title": "Facets" }, "feed_date_range_end": { "anyOf": [ { "format": "date", "type": "string" }, { "type": "null" } ], "default": null, "description": "End of date range for recurring feed appearance", "title": "Feed Date Range End" }, "feed_date_range_start": { "anyOf": [ { "format": "date", "type": "string" }, { "type": "null" } ], "default": null, "description": "Start of date range for recurring feed appearance", "title": "Feed Date Range Start" }, "feed_target_date": { "anyOf": [ { "format": "date", "type": "string" }, { "type": "null" } ], "default": null, "description": "Date when note should appear in feed", "title": "Feed Target Date" }, "icon": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Page icon — serialized IconValue (emoji/lucide/image ref)", "title": "Icon" }, "icon_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Resolved image ref for image-kind icons", "title": "Icon Url" }, "id": { "description": "Unique note identifier (UUID)", "examples": [ "a1b2c3d4-..." ], "title": "Id", "type": "string" }, "import_file_hash": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "SHA-256 hash of the original imported file for dedup", "title": "Import File Hash" }, "import_metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "description": "Provider-specific metadata blob (drive_owner_email, modified_time, ...)", "title": "Import Metadata" }, "import_source": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Import provider slug ('google_drive', 'dropbox', etc.)", "title": "Import Source" }, "import_source_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Foreign id at the source (Drive file_id, Notion page id, ...)", "title": "Import Source Id" }, "import_source_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Original file format: 'docx', 'xlsx', 'pptx'", "title": "Import Source Type" }, "import_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": "ready", "description": "Async import pipeline status: importing|extracting|ready|failed", "title": "Import Status" }, "is_phantom": { "default": false, "description": "Deprecated (TIDY-6078): always false", "title": "Is Phantom", "type": "boolean" }, "is_sensitive": { "default": false, "description": "Flag for sensitive info (passwords, codes)", "title": "Is Sensitive", "type": "boolean" }, "location": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Where this info applies", "examples": [ "Lincoln Elementary" ], "title": "Location" }, "location_pin": { "anyOf": [ { "$ref": "#/components/schemas/LocationPin" }, { "type": "null" } ], "default": null, "description": "Geo-location where note was created" }, "note_type": { "default": "reference", "description": "Category (gate_code|wifi|carpool|medical|emergency|reference|policy|contact_info|procedure)", "examples": [ "gate_code", "wifi", "reference" ], "title": "Note Type", "type": "string" }, "notebook_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Workspace/notebook container UUID", "title": "Notebook Id" }, "original_filename": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Original filename of the imported document", "title": "Original Filename" }, "plain_text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Plain-text derivative for local/offline search indexing", "title": "Plain Text" }, "project_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Project association (TIDY-9010 / F1-S7)", "title": "Project Id" }, "properties": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "description": "Page properties (JSONB)", "title": "Properties" }, "provenance": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "description": "Provenance metadata: who created this note and how (D29).", "title": "Provenance" }, "related_items": { "anyOf": [ { "items": { "$ref": "#/components/schemas/RelatedItem" }, "type": "array" }, { "type": "null" } ], "default": null, "description": "Links to entities extracted from note content", "title": "Related Items" }, "requires_review": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "description": "Whether note requires human review", "title": "Requires Review" }, "review_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Reason the note was flagged for review", "title": "Review Reason" }, "reviewed_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "description": "When the note was reviewed", "title": "Reviewed At" }, "reviewed_by": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Who reviewed the note (user ID)", "title": "Reviewed By" }, "short_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Display short ID (e.g., 'KITCHEN-NOTE-12' or 'NOTE-89')", "title": "Short Id" }, "slug": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "URL-friendly identifier (YYYY-MM-DD for journals, title for pages)", "title": "Slug" }, "source": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": "user", "description": "Note origin: user, system, sms_agent", "title": "Source" }, "source_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Reference to source document (UUID)", "examples": [ "a1b2c3d4-..." ], "title": "Source Id" }, "source_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Where note came from (extracted|manual|imported). TIDY-7540: now projected from linked_references via correlated subquery in NOTE_SELECT_COLUMNS; NULL when no llm_extracted link exists.", "examples": [ "manual", "extracted" ], "title": "Source Type" }, "source_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Supabase Storage URL to the original source document", "examples": [ "tenant-id/raw_emails/2025/12/18/email.eml" ], "title": "Source Url" }, "spreadsheet_data": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "description": "Univer IWorkbookData JSON for spreadsheet notes", "title": "Spreadsheet Data" }, "summary": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "AI-generated summary (filled by pipeline)", "title": "Summary" }, "tags": { "anyOf": [ { "items": {}, "type": "array" }, { "type": "null" } ], "default": null, "description": "Tag metadata", "title": "Tags" }, "tenant_id": { "description": "Associated tenant identifier (UUID)", "examples": [ "a1b2c3d4-..." ], "title": "Tenant Id", "type": "string" }, "title": { "description": "Note title/summary", "examples": [ "School Gate Code" ], "title": "Title", "type": "string" }, "title_plain": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Plain-text projection of the rich title (server-computed).", "title": "Title Plain" }, "updated_at": { "description": "ISO 8601 timestamp of last modification", "format": "date-time", "title": "Updated At", "type": "string" }, "valid_from": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "description": "When information becomes valid", "title": "Valid From" }, "valid_until": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "description": "When information expires", "title": "Valid Until" }, "version": { "default": 1, "description": "Optimistic locking version counter", "title": "Version", "type": "integer" }, "yjs_state": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Base64-encoded Yjs CRDT state (bytea)", "title": "Yjs State" } }, "required": [ "id", "tenant_id", "title", "content", "created_at", "updated_at" ], "title": "NoteResponse", "type": "object" }, "NoteSummary": { "description": "Summary of a related note.", "properties": { "id": { "description": "Note ID (UUID)", "title": "Id", "type": "string" }, "link_direction": { "default": "outgoing", "description": "Direction of the edge relative to the primitive you asked about: 'outgoing' (the edge starts there and points at this one) or 'incoming' (this one points AT it). TIDY-15687.", "title": "Link Direction", "type": "string" }, "link_type": { "description": "How this note is related", "title": "Link Type", "type": "string" }, "note_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Note type", "title": "Note Type" }, "preview": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "First 100 chars of content", "title": "Preview" }, "title": { "description": "Note title", "title": "Title", "type": "string" }, "type": { "const": "note", "default": "note", "title": "Type", "type": "string" } }, "required": [ "id", "title", "link_type" ], "title": "NoteSummary", "type": "object" }, "NoteUpdate": { "description": "Input model for updating existing notes.\n\nUsed in:\n - PUT /api/v1/notes/{id}\n - PATCH /api/v1/notes/{id}\n\nAll fields are optional - only provided fields are updated.\n\nAttributes:\n title: Note title/summary (optional)\n content: Detailed note content (optional)\n note_type: Category of note (optional)\n child_associations: JSON array of child associations (optional)\n location: Where this info applies (optional)\n valid_from: When information becomes valid (optional)\n valid_until: When information expires (optional)\n is_sensitive: Flag for sensitive info (optional)\n\nRelated: migration 035_notes_schema.sql", "properties": { "aliases": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "description": "Page aliases (resolution keys, not display labels)", "title": "Aliases" }, "banner_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Page banner image URL/ref", "title": "Banner Url" }, "child_associations": { "anyOf": [ { "items": {}, "type": "array" }, { "type": "null" } ], "description": "JSON array of child associations [{child_name, context}]", "title": "Child Associations" }, "contact_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Anchor: Link to contact (UUID)", "title": "Contact Id" }, "content": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Detailed note content", "title": "Content" }, "drawing_version": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Version counter for drawing notes", "title": "Drawing Version" }, "email_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Anchor: Link to email (UUID)", "title": "Email Id" }, "event_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Anchor: Link to calendar event (UUID)", "title": "Event Id" }, "facets": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "description": "Facet slugs applied to this note (e.g. ['journal', 'drawing'])", "title": "Facets" }, "feed_date_range_end": { "anyOf": [ { "format": "date", "type": "string" }, { "type": "null" } ], "description": "End of date range for recurring feed appearance", "title": "Feed Date Range End" }, "feed_date_range_start": { "anyOf": [ { "format": "date", "type": "string" }, { "type": "null" } ], "description": "Start of date range for recurring feed appearance", "title": "Feed Date Range Start" }, "feed_target_date": { "anyOf": [ { "format": "date", "type": "string" }, { "type": "null" } ], "description": "Date when note should appear in feed", "title": "Feed Target Date" }, "icon": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Page icon — serialized IconValue (emoji/lucide/image ref)", "title": "Icon" }, "icon_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Resolved image ref for image-kind icons", "title": "Icon Url" }, "inbox_source": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Inbox source metadata. Explicit null clears the source.", "title": "Inbox Source" }, "inbox_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Inbox workflow state. Explicit null clears inbox membership.", "title": "Inbox Status" }, "is_pinned": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Pin flag for insight facets (TIDY-8698/TIDY-11666): a pinned insight is locked from Dreamer regeneration and renders a pinned indicator. Persisted to notes.is_pinned and synced local-first.", "title": "Is Pinned" }, "is_sensitive": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Flag for sensitive info (passwords, codes)", "title": "Is Sensitive" }, "location": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Where this info applies", "title": "Location" }, "note_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Category (gate_code|wifi|carpool|medical|emergency|reference|policy|contact_info|procedure)", "title": "Note Type" }, "notebook_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Parent notebook UUID. Explicit null clears membership.", "title": "Notebook Id" }, "plain_text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Plain-text derivative for local/offline search indexing", "title": "Plain Text" }, "presentation_design_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Active presentation design id (themes a note_type='presentation' deck)", "title": "Presentation Design Id" }, "properties": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "Page properties (JSONB)", "title": "Properties" }, "source": { "anyOf": [ { "enum": [ "user", "system", "sms_agent", "logseq", "obsidian" ], "type": "string" }, { "type": "null" } ], "description": "Origin of the note (user|system|sms_agent|logseq|obsidian)", "title": "Source" }, "source_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "URL to the original source document", "title": "Source Url" }, "spreadsheet_data": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "Univer IWorkbookData JSON for spreadsheet notes", "title": "Spreadsheet Data" }, "summary": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "AI- or user-authored summary of the note", "title": "Summary" }, "tags": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "description": "Tag metadata for categorization", "title": "Tags" }, "title": { "anyOf": [ { "maxLength": 500, "minLength": 1, "type": "string" }, { "type": "null" } ], "description": "Note title/summary (1-500 characters)", "title": "Title" }, "valid_from": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "When information becomes valid", "title": "Valid From" }, "valid_until": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "When information expires", "title": "Valid Until" }, "visibility": { "anyOf": [ { "enum": [ "private", "shared", "tenant" ], "type": "string" }, { "type": "null" } ], "description": "Per-row visibility. Only the row owner may change this.", "title": "Visibility" }, "yaml_frontmatter": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "YAML frontmatter metadata (JSON-serialized)", "title": "Yaml Frontmatter" }, "yjs_state": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Base64-encoded Yjs CRDT state (bytea)", "title": "Yjs State" } }, "title": "NoteUpdate", "type": "object" }, "NoteUpdateCreate": { "description": "Request for POST /api/v1/notes/{note_id}/updates.", "properties": { "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Client-generated UUID for idempotent retry safety", "title": "Id" }, "update_blob": { "description": "Base64-encoded Yjs update chunk", "title": "Update Blob", "type": "string" } }, "required": [ "update_blob" ], "title": "NoteUpdateCreate", "type": "object" }, "NoteUpdateResponse": { "description": "Response for a single note update row.\n\nNote: ``id`` here is the note_updates row id (an internal-ish CRDT update\nUUID), not a primitive id, so it stays bare. ``note_id`` is rewritten to\n``N-``.", "properties": { "account_id": { "title": "Account Id", "type": "string" }, "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "id": { "title": "Id", "type": "string" }, "note_id": { "title": "Note Id", "type": "string" }, "update_blob": { "description": "Base64-encoded Yjs update bytes", "title": "Update Blob", "type": "string" } }, "required": [ "id", "note_id", "account_id", "update_blob", "created_at" ], "title": "NoteUpdateResponse", "type": "object" }, "NoteVersion": { "properties": { "actor_account_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Actor Account Id" }, "actor_display_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Actor Display Name" }, "actor_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Actor Type" }, "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "id": { "title": "Id", "type": "string" }, "metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Metadata" }, "note_id": { "title": "Note Id", "type": "string" }, "preview_text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Preview Text" }, "primitive_type": { "title": "Primitive Type", "type": "string" }, "source_conversation_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Source Conversation Id" }, "trigger": { "title": "Trigger", "type": "string" } }, "required": [ "id", "note_id", "primitive_type", "trigger", "created_at" ], "title": "NoteVersion", "type": "object" }, "NotebookCreate": { "description": "Input for POST /api/v1/notebooks.", "properties": { "color": { "anyOf": [ { "maxLength": 20, "type": "string" }, { "type": "null" } ], "title": "Color" }, "description": { "anyOf": [ { "maxLength": 1000, "type": "string" }, { "type": "null" } ], "title": "Description" }, "icon": { "anyOf": [ { "maxLength": 50, "type": "string" }, { "type": "null" } ], "title": "Icon" }, "id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "description": "Client-provided ID for PowerSync sync", "title": "Id" }, "is_global": { "default": false, "description": "Visible to every member of the workspace. Default false: private.", "title": "Is Global", "type": "boolean" }, "name": { "maxLength": 255, "minLength": 1, "title": "Name", "type": "string" } }, "required": [ "name" ], "title": "NotebookCreate", "type": "object" }, "NotebookId": { "description": "Typed primitive ID for notebooks (prefix 'B').", "examples": [ "B-550e8400-e29b-41d4-a716-446655440000" ], "pattern": "^B-[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "title": "NotebookId", "type": "string", "x-tidy-typed-id-prefix": "B", "x-tidy-typed-id-table": "notebooks" }, "NotebookMemberCreate": { "description": "Input for POST /api/v1/notebooks/{id}/members.", "properties": { "permission": { "default": "can_edit", "description": "Permission level (can_edit|can_view)", "pattern": "^(can_edit|can_view)$", "title": "Permission", "type": "string" }, "user_id": { "description": "Account UUID of user to add", "title": "User Id", "type": "string" } }, "required": [ "user_id" ], "title": "NotebookMemberCreate", "type": "object" }, "NotebookMemberResponse": { "description": "A notebook member in API responses.", "properties": { "created_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Created At" }, "display_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Display Name" }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Email" }, "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Id" }, "is_owner": { "default": false, "title": "Is Owner", "type": "boolean" }, "permission": { "title": "Permission", "type": "string" }, "user_id": { "title": "User Id", "type": "string" } }, "required": [ "user_id", "permission" ], "title": "NotebookMemberResponse", "type": "object" }, "NotebookResponse": { "description": "Response model for notebook endpoints.", "properties": { "color": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Color" }, "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "created_by": { "format": "uuid", "title": "Created By", "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Description" }, "icon": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Icon" }, "id": { "format": "uuid", "title": "Id", "type": "string" }, "is_global": { "title": "Is Global", "type": "boolean" }, "name": { "title": "Name", "type": "string" }, "note_count": { "default": 0, "title": "Note Count", "type": "integer" }, "owner_type": { "title": "Owner Type", "type": "string" }, "sort_order": { "title": "Sort Order", "type": "integer" }, "tenant_id": { "format": "uuid", "title": "Tenant Id", "type": "string" }, "updated_at": { "format": "date-time", "title": "Updated At", "type": "string" }, "user_permission": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "User Permission" } }, "required": [ "id", "tenant_id", "created_by", "owner_type", "name", "is_global", "sort_order", "created_at", "updated_at" ], "title": "NotebookResponse", "type": "object" }, "NotebookUpdate": { "description": "Input for PATCH /api/v1/notebooks/{id}.", "properties": { "color": { "anyOf": [ { "maxLength": 20, "type": "string" }, { "type": "null" } ], "title": "Color" }, "description": { "anyOf": [ { "maxLength": 1000, "type": "string" }, { "type": "null" } ], "title": "Description" }, "icon": { "anyOf": [ { "maxLength": 50, "type": "string" }, { "type": "null" } ], "title": "Icon" }, "is_global": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is Global" }, "name": { "anyOf": [ { "maxLength": 255, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Name" }, "sort_order": { "anyOf": [ { "minimum": 0.0, "type": "integer" }, { "type": "null" } ], "title": "Sort Order" } }, "title": "NotebookUpdate", "type": "object" }, "NotificationCountResponse": { "description": "Response for notification count.", "properties": { "by_service": { "additionalProperties": true, "default": {}, "title": "By Service", "type": "object" }, "by_severity": { "additionalProperties": true, "default": {}, "title": "By Severity", "type": "object" }, "count": { "title": "Count", "type": "integer" } }, "required": [ "count" ], "title": "NotificationCountResponse", "type": "object" }, "NotificationListResponse": { "description": "Response for notification list.", "properties": { "notifications": { "items": { "$ref": "#/components/schemas/NotificationResponse" }, "title": "Notifications", "type": "array" }, "total": { "title": "Total", "type": "integer" }, "unread_count": { "title": "Unread Count", "type": "integer" } }, "required": [ "notifications", "total", "unread_count" ], "title": "NotificationListResponse", "type": "object" }, "NotificationPreferencesResponse": { "description": "Response model for notification preferences.", "example": { "account_id": "550e8400-e29b-41d4-a716-446655440002", "created_at": "2024-01-15T10:30:00Z", "id": "550e8400-e29b-41d4-a716-446655440000", "notify_attendee_responses": true, "notify_cancellations": true, "notify_email": true, "notify_push": true, "notify_sms": false, "notify_time_proposals": true, "quiet_hours_end": "07:00", "quiet_hours_start": "22:00", "quiet_hours_timezone": "America/New_York", "tenant_id": "550e8400-e29b-41d4-a716-446655440001", "updated_at": "2024-01-15T10:30:00Z" }, "properties": { "account_id": { "description": "Account UUID", "title": "Account Id", "type": "string" }, "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "id": { "description": "Preference record UUID", "title": "Id", "type": "string" }, "notify_attendee_responses": { "default": true, "title": "Notify Attendee Responses", "type": "boolean" }, "notify_cancellations": { "default": true, "title": "Notify Cancellations", "type": "boolean" }, "notify_email": { "default": true, "title": "Notify Email", "type": "boolean" }, "notify_push": { "default": true, "title": "Notify Push", "type": "boolean" }, "notify_sms": { "default": false, "title": "Notify Sms", "type": "boolean" }, "notify_time_proposals": { "default": true, "title": "Notify Time Proposals", "type": "boolean" }, "quiet_hours_end": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "e.g., '07:00'", "title": "Quiet Hours End" }, "quiet_hours_start": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "e.g., '22:00'", "title": "Quiet Hours Start" }, "quiet_hours_timezone": { "default": "America/New_York", "title": "Quiet Hours Timezone", "type": "string" }, "tenant_id": { "description": "Tenant UUID", "title": "Tenant Id", "type": "string" }, "updated_at": { "format": "date-time", "title": "Updated At", "type": "string" } }, "required": [ "id", "tenant_id", "account_id", "created_at", "updated_at" ], "title": "NotificationPreferencesResponse", "type": "object" }, "NotificationPreferencesUpdate": { "description": "Request model for updating notification preferences.", "example": { "notify_cancellations": true, "notify_time_proposals": true }, "properties": { "notify_attendee_responses": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Notify Attendee Responses" }, "notify_cancellations": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Notify Cancellations" }, "notify_email": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Notify Email" }, "notify_push": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Notify Push" }, "notify_sms": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Notify Sms" }, "notify_time_proposals": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Notify Time Proposals" }, "quiet_hours_end": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "e.g., '07:00'", "title": "Quiet Hours End" }, "quiet_hours_start": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "e.g., '22:00'", "title": "Quiet Hours Start" }, "quiet_hours_timezone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Quiet Hours Timezone" } }, "title": "NotificationPreferencesUpdate", "type": "object" }, "NotificationResponse": { "description": "Single notification response.", "properties": { "acknowledged_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Acknowledged At" }, "acknowledged_by": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Acknowledged By" }, "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "id": { "title": "Id", "type": "string" }, "message": { "title": "Message", "type": "string" }, "metadata": { "additionalProperties": true, "default": {}, "title": "Metadata", "type": "object" }, "notification_type": { "title": "Notification Type", "type": "string" }, "service": { "title": "Service", "type": "string" }, "severity": { "title": "Severity", "type": "string" }, "title": { "title": "Title", "type": "string" } }, "required": [ "id", "notification_type", "severity", "title", "message", "service", "created_at" ], "title": "NotificationResponse", "type": "object" }, "OAuthAppMutationResponse": { "properties": { "changed": { "title": "Changed", "type": "boolean" }, "ok": { "title": "Ok", "type": "boolean" } }, "required": [ "ok", "changed" ], "title": "OAuthAppMutationResponse", "type": "object" }, "OAuthAppPublic": { "properties": { "allowed_scopes": { "items": { "type": "string" }, "title": "Allowed Scopes", "type": "array" }, "client_id": { "title": "Client Id", "type": "string" }, "client_type": { "title": "Client Type", "type": "string" }, "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "created_by": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Created By" }, "homepage_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Homepage Url" }, "id": { "title": "Id", "type": "string" }, "logo_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Logo Url" }, "name": { "title": "Name", "type": "string" }, "redirect_uris": { "items": { "type": "string" }, "title": "Redirect Uris", "type": "array" }, "review_status": { "title": "Review Status", "type": "string" } }, "required": [ "id", "client_id", "client_type", "name", "redirect_uris", "allowed_scopes", "review_status", "created_at" ], "title": "OAuthAppPublic", "type": "object" }, "OAuthConnectRequest": { "description": "Initiate an OAuth connection.", "properties": { "capabilities": { "description": "What the account is connected for (TIDY-19604 F12), comma-joined as a connect instruction's start_body carries it: any of mail, calendar, contacts, drive for Google; mail,calendar (a mailbox) or calendar (its calendar alone) for Microsoft 365 and Zoho. Consent asks for exactly those scopes. Without mail the connection is not a mailbox and takes no inbox. With plugin_id, they are added to what that plugin is already used for.", "pattern": "^(mail|calendar|contacts|drive)(,(mail|calendar|contacts|drive))*$", "title": "Capabilities", "type": "string" }, "desktop": { "default": false, "description": "Started from the desktop app (TIDY-19315): consent completes in the system browser, so the callback hands back to the app to finish under the member's own session instead of trusting a browser cookie.", "title": "Desktop", "type": "boolean" }, "new_mailbox": { "default": false, "description": "The member is adding a mailbox this workspace has not connected: refused before the provider's consent screen when every inbox the plan allows is in use.", "title": "New Mailbox", "type": "boolean" }, "plugin_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "description": "The account plugin being signed in again, or given one more capability. A mailbox that is not working holds no inbox, so it is refused up front when none is free.", "title": "Plugin Id" }, "provider_type": { "description": "Provider type (e.g. google)", "title": "Provider Type", "type": "string" }, "redirect_uri": { "description": "OAuth redirect URI", "title": "Redirect Uri", "type": "string" }, "return_to": { "default": "/settings/connections", "description": "Page to redirect after OAuth", "title": "Return To", "type": "string" } }, "required": [ "provider_type", "redirect_uri", "capabilities" ], "title": "OAuthConnectRequest", "type": "object" }, "OAuthConnectResponse": { "description": "Response after initiating OAuth.", "properties": { "authorization_url": { "title": "Authorization Url", "type": "string" }, "connection_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Connection Id" }, "state": { "title": "State", "type": "string" } }, "required": [ "authorization_url", "state" ], "title": "OAuthConnectResponse", "type": "object" }, "OAuthLaunchRequest": { "properties": { "state": { "description": "The state a desktop connect minted, from its launch page.", "maxLength": 256, "minLength": 16, "title": "State", "type": "string" } }, "required": [ "state" ], "title": "OAuthLaunchRequest", "type": "object" }, "OAuthLaunchResponse": { "properties": { "authorize_url": { "description": "The provider URL to continue to.", "title": "Authorize Url", "type": "string" }, "binding_cookie_max_age": { "description": "Seconds the cookie lives.", "title": "Binding Cookie Max Age", "type": "integer" }, "binding_cookie_name": { "description": "The per-state nonce cookie to set.", "title": "Binding Cookie Name", "type": "string" }, "binding_cookie_path": { "description": "The path the cookie is scoped to.", "title": "Binding Cookie Path", "type": "string" }, "binding_cookie_value": { "description": "Its value; HttpOnly, never scripted.", "title": "Binding Cookie Value", "type": "string" } }, "required": [ "authorize_url", "binding_cookie_name", "binding_cookie_value", "binding_cookie_path", "binding_cookie_max_age" ], "title": "OAuthLaunchResponse", "type": "object" }, "OAuthResumeRequest": { "properties": { "resume": { "description": "The `oauth_resume` key the desktop deep link carried.", "maxLength": 256, "minLength": 16, "title": "Resume", "type": "string" } }, "required": [ "resume" ], "title": "OAuthResumeRequest", "type": "object" }, "OAuthResumeResponse": { "properties": { "location": { "description": "Where the callback sends the member next: an in-app path, or a provider URL to open in the system browser (GitHub's install step).", "title": "Location", "type": "string" } }, "required": [ "location" ], "title": "OAuthResumeResponse", "type": "object" }, "ObservedPredicate": { "description": "A distinct predicate observed on live linked_references rows.", "properties": { "count": { "description": "Live (non-superseded) rows carrying it", "title": "Count", "type": "integer" }, "predicate": { "description": "Stored predicate label", "title": "Predicate", "type": "string" } }, "required": [ "predicate", "count" ], "title": "ObservedPredicate", "type": "object" }, "OnboardingStatusResponse": { "description": "Onboarding progress + server-computed `current_url` + per-context step list (TIDY-7073).", "properties": { "account_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Stored tenant.account_type (raw).", "title": "Account Type" }, "can_manage_workforce": { "default": false, "title": "Can Manage Workforce", "type": "boolean" }, "canonical_steps_for_context": { "description": "Per-context canonical step list (see STEPS_BY_CONTEXT).", "items": { "type": "string" }, "title": "Canonical Steps For Context", "type": "array" }, "connect_providers": { "additionalProperties": { "enum": [ "offered", "connected", "skipped" ], "type": "string" }, "title": "Connect Providers", "type": "object" }, "current_step": { "description": "Current step: context, profile, connect, plan, team, family, identity, calendar, notifications, complete", "title": "Current Step", "type": "string" }, "current_url": { "default": "", "description": "Server-computed URL the FE should navigate to for current_step.", "title": "Current Url", "type": "string" }, "display_name": { "description": "Tenant display name", "title": "Display Name", "type": "string" }, "effective_account_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "account_type that drives step routing; None if user has not yet picked context.", "title": "Effective Account Type" }, "email_sources_count": { "default": 0, "description": "Number of email sources connected", "title": "Email Sources Count", "type": "integer" }, "family_members_count": { "default": 0, "description": "Number of family members added", "title": "Family Members Count", "type": "integer" }, "onboarding_completed": { "description": "Whether onboarding is complete", "title": "Onboarding Completed", "type": "boolean" }, "onboarding_mode": { "default": "tenant", "description": "Progress owner: 'tenant' for workspace setup or 'member' for invited-user setup.", "title": "Onboarding Mode", "type": "string" }, "returning_customer": { "default": false, "description": "True when this signup's email matches a former-customer suppression record (TIDY-12189) — drives the onboarding 'welcome back' greeting. Boolean recognition only; no retained metadata is exposed.", "title": "Returning Customer", "type": "boolean" }, "selected_plan": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Selected plan tier", "title": "Selected Plan" }, "steps_completed": { "description": "List of completed steps", "items": { "type": "string" }, "title": "Steps Completed", "type": "array" }, "sync_in_progress": { "default": false, "description": "Whether email sync is in progress", "title": "Sync In Progress", "type": "boolean" }, "sync_status": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "Sync progress when active", "title": "Sync Status" }, "tenant_id": { "description": "Tenant UUID", "title": "Tenant Id", "type": "string" }, "workforce_path_policy": { "default": "both", "enum": [ "both", "hosted_only", "workshop_only" ], "title": "Workforce Path Policy", "type": "string" } }, "required": [ "tenant_id", "display_name", "onboarding_completed", "current_step" ], "title": "OnboardingStatusResponse", "type": "object" }, "OooTriggerRequest": { "description": "Trigger OOO auto-reply evaluation for a canonicalized inbound email.", "properties": { "email_id": { "description": "Canonical email UUID.", "title": "Email Id", "type": "string" }, "tenant_id": { "description": "Tenant UUID owning the email.", "title": "Tenant Id", "type": "string" } }, "required": [ "tenant_id", "email_id" ], "title": "OooTriggerRequest", "type": "object" }, "OooTriggerResponse": { "properties": { "message_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Message Id" }, "reason": { "title": "Reason", "type": "string" }, "sent": { "title": "Sent", "type": "boolean" } }, "required": [ "sent", "reason" ], "title": "OooTriggerResponse", "type": "object" }, "OpenBundleForFacetRequest": { "description": "\"Open the bundle for this output type\" — as ONE atomic ask (TIDY-17840).\n\nThe expectation pair is the whole point: it is the active bundle the client\nwas looking at when the user tapped. Sending it lets the server tell \"you\nare up to date\" apart from \"something moved under you\", which is what makes\nreuse safe instead of a race that archives another device's work. Both\nhalves travel together or neither does — an id without its revision cannot\ndetect an intervening add, and a revision without an id names nothing.", "properties": { "confirm_rebind": { "default": false, "description": "The user confirmed changing what the active bundle produces, after a `bundle_rebind_confirmation_required` refusal.", "title": "Confirm Rebind", "type": "boolean" }, "expected_active_bundle_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "description": "The active bundle the client observed, or null for 'none'.", "title": "Expected Active Bundle Id" }, "expected_active_bundle_updated_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "That bundle's observed revision (ISO-8601 UTC).", "title": "Expected Active Bundle Updated At" }, "facet_slug": { "description": "Output type to open the active bundle for.", "minLength": 1, "title": "Facet Slug", "type": "string" }, "surface": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Where the request came from (e.g. 'web:podcast-detail').", "title": "Surface" } }, "required": [ "facet_slug" ], "title": "OpenBundleForFacetRequest", "type": "object" }, "OpenBundleForFacetResponse": { "description": "Which of the four things the server did, and the bundle it did it to.\n\nThe bundle is the canonical active row the existing hosts already render\n(D11) — the web Bundle tab and the Android capture tray focus it through\nPowerSync. No new surface, no new state channel.", "properties": { "bundle": { "$ref": "#/components/schemas/ActiveBundleSummary" }, "outcome": { "enum": [ "focused", "bound", "created", "rebound" ], "title": "Outcome", "type": "string" } }, "required": [ "outcome", "bundle" ], "title": "OpenBundleForFacetResponse", "type": "object" }, "OpenConversationChannelRequest": { "properties": { "invitee_account_ids": { "items": { "type": "string" }, "maxItems": 20, "minItems": 1, "title": "Invitee Account Ids", "type": "array" }, "message": { "$ref": "#/components/schemas/SendMatrixRoomMessageRequest" } }, "required": [ "invitee_account_ids", "message" ], "title": "OpenConversationChannelRequest", "type": "object" }, "OpenIDConfigurationResponse": { "properties": { "authorization_endpoint": { "title": "Authorization Endpoint", "type": "string" }, "authorization_response_iss_parameter_supported": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Authorization Response Iss Parameter Supported" }, "code_challenge_methods_supported": { "items": { "type": "string" }, "title": "Code Challenge Methods Supported", "type": "array" }, "device_authorization_endpoint": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Device Authorization Endpoint" }, "grant_types_supported": { "items": { "type": "string" }, "title": "Grant Types Supported", "type": "array" }, "introspection_endpoint": { "title": "Introspection Endpoint", "type": "string" }, "issuer": { "title": "Issuer", "type": "string" }, "jwks_uri": { "title": "Jwks Uri", "type": "string" }, "op_logo_uri": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Op Logo Uri" }, "op_policy_uri": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Op Policy Uri" }, "op_tos_uri": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Op Tos Uri" }, "registration_endpoint": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Registration Endpoint" }, "response_modes_supported": { "items": { "type": "string" }, "title": "Response Modes Supported", "type": "array" }, "response_types_supported": { "items": { "type": "string" }, "title": "Response Types Supported", "type": "array" }, "revocation_endpoint": { "title": "Revocation Endpoint", "type": "string" }, "scopes_supported": { "items": { "type": "string" }, "title": "Scopes Supported", "type": "array" }, "service_documentation": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Service Documentation" }, "token_endpoint": { "title": "Token Endpoint", "type": "string" }, "token_endpoint_auth_methods_supported": { "items": { "type": "string" }, "title": "Token Endpoint Auth Methods Supported", "type": "array" }, "ui_locales_supported": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Ui Locales Supported" } }, "required": [ "issuer", "authorization_endpoint", "token_endpoint", "revocation_endpoint", "introspection_endpoint", "jwks_uri", "scopes_supported", "response_types_supported", "response_modes_supported", "grant_types_supported", "code_challenge_methods_supported", "token_endpoint_auth_methods_supported" ], "title": "OpenIDConfigurationResponse", "type": "object" }, "OperationConflict": { "properties": { "code": { "const": "idempotency_key_reused", "title": "Code", "type": "string" }, "op_id": { "title": "Op Id", "type": "string" } }, "required": [ "code", "op_id" ], "title": "OperationConflict", "type": "object" }, "OperationResponse": { "properties": { "connection_id": { "format": "uuid", "title": "Connection Id", "type": "string" }, "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "enrollment_command": { "anyOf": [ { "$ref": "#/components/schemas/EnrollmentCommand" }, { "type": "null" } ], "default": null }, "error_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Error Code" }, "operation_id": { "format": "uuid", "title": "Operation Id", "type": "string" }, "provider_resource_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Provider Resource Id" }, "record_id": { "format": "uuid", "title": "Record Id", "type": "string" }, "residue": { "items": { "type": "string" }, "title": "Residue", "type": "array" }, "stage": { "title": "Stage", "type": "string" }, "state": { "title": "State", "type": "string" }, "updated_at": { "format": "date-time", "title": "Updated At", "type": "string" }, "workshop_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Workshop Id" } }, "required": [ "operation_id", "record_id", "workshop_id", "connection_id", "state", "stage", "created_at", "updated_at" ], "title": "OperationResponse", "type": "object" }, "OperationStatusResponse": { "properties": { "receipt_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "default": null, "title": "Receipt Id" }, "status": { "title": "Status", "type": "string" } }, "required": [ "status" ], "title": "OperationStatusResponse", "type": "object" }, "OperationalNoticeDismissResponse": { "description": "Result of ``POST /api/v1/journal/operational-notices/{id}/dismiss``.", "properties": { "dismissed": { "default": true, "description": "Always true — a miss is a 404", "title": "Dismissed", "type": "boolean" }, "id": { "description": "The dismissed notice id", "format": "uuid", "title": "Id", "type": "string" } }, "required": [ "id" ], "title": "OperationalNoticeDismissResponse", "type": "object" }, "OperatorEntry": { "properties": { "account_id": { "title": "Account Id", "type": "string" }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Email" }, "granted_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Granted At" }, "is_platform_operator": { "title": "Is Platform Operator", "type": "boolean" }, "source": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Source" } }, "required": [ "account_id", "is_platform_operator" ], "title": "OperatorEntry", "type": "object" }, "OperatorGrantRequest": { "description": "The email of the account to grant platform-operator on.", "properties": { "email": { "description": "Account email (case-insensitive)", "format": "email", "title": "Email", "type": "string" } }, "required": [ "email" ], "title": "OperatorGrantRequest", "type": "object" }, "OperatorListResponse": { "properties": { "operators": { "items": { "$ref": "#/components/schemas/OperatorEntry" }, "title": "Operators", "type": "array" } }, "required": [ "operators" ], "title": "OperatorListResponse", "type": "object" }, "OperatorMutationResponse": { "properties": { "account_id": { "title": "Account Id", "type": "string" }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Email" }, "is_platform_operator": { "title": "Is Platform Operator", "type": "boolean" } }, "required": [ "account_id", "is_platform_operator" ], "title": "OperatorMutationResponse", "type": "object" }, "OpportunityDecideRequest": { "properties": { "action": { "enum": [ "approve", "reject" ], "title": "Action", "type": "string" }, "rationale": { "minLength": 1, "title": "Rationale", "type": "string" } }, "required": [ "action", "rationale" ], "title": "OpportunityDecideRequest", "type": "object" }, "OpportunityDecideResponse": { "properties": { "executed": { "additionalProperties": true, "title": "Executed", "type": "object" }, "opportunity": { "$ref": "#/components/schemas/OpportunityModel" } }, "required": [ "opportunity", "executed" ], "title": "OpportunityDecideResponse", "type": "object" }, "OpportunityListResponse": { "properties": { "opportunities": { "items": { "$ref": "#/components/schemas/OpportunityModel" }, "title": "Opportunities", "type": "array" } }, "required": [ "opportunities" ], "title": "OpportunityListResponse", "type": "object" }, "OpportunityModel": { "properties": { "blocked_reasons": { "items": { "additionalProperties": true, "type": "object" }, "title": "Blocked Reasons", "type": "array" }, "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "decided_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Decided At" }, "decided_by": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Decided By" }, "definition_id": { "format": "uuid", "title": "Definition Id", "type": "string" }, "delegation_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Delegation Id" }, "gates": { "items": { "additionalProperties": true, "type": "object" }, "title": "Gates", "type": "array" }, "id": { "format": "uuid", "title": "Id", "type": "string" }, "kind": { "title": "Kind", "type": "string" }, "rationale": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Rationale" }, "status": { "title": "Status", "type": "string" }, "suggested_action": { "additionalProperties": true, "title": "Suggested Action", "type": "object" }, "updated_at": { "format": "date-time", "title": "Updated At", "type": "string" }, "version_id": { "format": "uuid", "title": "Version Id", "type": "string" } }, "required": [ "id", "definition_id", "version_id", "kind", "status", "gates", "suggested_action", "blocked_reasons", "decided_by", "delegation_id", "decided_at", "rationale", "created_at", "updated_at" ], "title": "OpportunityModel", "type": "object" }, "OptInRequest": { "properties": { "opted_in": { "title": "Opted In", "type": "boolean" } }, "required": [ "opted_in" ], "title": "OptInRequest", "type": "object" }, "OrgEmailEntry": { "description": "One org email channel entry (generic-role-only by convention, D6/R12).", "properties": { "address": { "description": "Email address", "maxLength": 255, "title": "Address", "type": "string" }, "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Display label (e.g. main, billing)", "title": "Label" }, "primary": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Primary flag (canonical key)", "title": "Primary" }, "type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Address type (e.g. work)", "title": "Type" } }, "required": [ "address" ], "title": "OrgEmailEntry", "type": "object" }, "OrgFieldResolution": { "description": "How one organizations column resolved for a survivor/loser pair.", "properties": { "chosen_value": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Chosen Value" }, "field": { "title": "Field", "type": "string" }, "loser_value": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Loser Value" }, "source": { "title": "Source", "type": "string" }, "survivor_value": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Survivor Value" } }, "required": [ "field", "source" ], "title": "OrgFieldResolution", "type": "object" }, "OrgLocationEntry": { "description": "One org location entry — REUSES the contact address entry shape (D19).", "properties": { "address": { "description": "Location address", "maxLength": 500, "title": "Address", "type": "string" }, "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Display label (e.g. Main, Warehouse)", "title": "Label" }, "primary": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Primary flag (canonical key)", "title": "Primary" } }, "required": [ "address" ], "title": "OrgLocationEntry", "type": "object" }, "OrgLogoDecision": { "description": "Outcome of the logo precedence rule for one survivor/loser pair.", "properties": { "discarded": { "items": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "title": "Discarded", "type": "array" }, "loser_source": { "title": "Loser Source", "type": "string" }, "survivor_source": { "title": "Survivor Source", "type": "string" }, "winner": { "title": "Winner", "type": "string" }, "winner_source": { "title": "Winner Source", "type": "string" } }, "required": [ "winner", "winner_source", "survivor_source", "loser_source" ], "title": "OrgLogoDecision", "type": "object" }, "OrgMergeLoserPlan": { "description": "Per-loser plan: field resolutions, residual entries and the logo call.", "properties": { "field_resolutions": { "items": { "$ref": "#/components/schemas/OrgFieldResolution" }, "title": "Field Resolutions", "type": "array" }, "logo_decision": { "$ref": "#/components/schemas/OrgLogoDecision" }, "loser": { "$ref": "#/components/schemas/api_service__models__organization_merge__OrganizationSummary" }, "residual_entries": { "items": { "$ref": "#/components/schemas/OrgResidualEntry" }, "title": "Residual Entries", "type": "array" } }, "required": [ "loser", "logo_decision" ], "title": "OrgMergeLoserPlan", "type": "object" }, "OrgPhoneEntry": { "description": "One org phone channel entry.", "properties": { "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Display label (e.g. main, fax)", "title": "Label" }, "number": { "description": "Phone number", "maxLength": 50, "title": "Number", "type": "string" }, "primary": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Primary flag (canonical key)", "title": "Primary" } }, "required": [ "number" ], "title": "OrgPhoneEntry", "type": "object" }, "OrgResidualEntry": { "description": "A value that could not be carried and lands in the residual log.", "properties": { "field": { "title": "Field", "type": "string" }, "loser_id": { "title": "Loser Id", "type": "string" }, "loser_name": { "default": "", "title": "Loser Name", "type": "string" }, "reason": { "title": "Reason", "type": "string" }, "value": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Value" } }, "required": [ "field", "reason", "loser_id" ], "title": "OrgResidualEntry", "type": "object" }, "OrgSocialProfileEntry": { "description": "One org social profile entry.\n\n``platform`` is a free string; documented picklist: linkedin, x, facebook,\ninstagram, youtube, tiktok, github — anything else is accepted as freeform.", "properties": { "platform": { "description": "Platform slug (picklist + freeform)", "maxLength": 50, "title": "Platform", "type": "string" }, "url": { "description": "Profile URL", "maxLength": 500, "title": "Url", "type": "string" } }, "required": [ "platform", "url" ], "title": "OrgSocialProfileEntry", "type": "object" }, "OrgWebsiteEntry": { "description": "One org website entry.", "properties": { "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Display label (e.g. main, careers)", "title": "Label" }, "url": { "description": "Website URL", "maxLength": 500, "title": "Url", "type": "string" } }, "required": [ "url" ], "title": "OrgWebsiteEntry", "type": "object" }, "OrganizationBatchMergeItem": { "description": "Per-item outcome — one refusal never aborts the other merges.", "properties": { "error_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error Code" }, "loser_ids": { "items": { "type": "string" }, "title": "Loser Ids", "type": "array" }, "message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Message" }, "result": { "anyOf": [ { "$ref": "#/components/schemas/OrganizationMergeResult" }, { "type": "null" } ] }, "success": { "title": "Success", "type": "boolean" }, "survivor_id": { "title": "Survivor Id", "type": "string" } }, "required": [ "survivor_id", "success" ], "title": "OrganizationBatchMergeItem", "type": "object" }, "OrganizationBatchMergeRequest": { "description": "Several independent merges; each runs in its own transaction.", "properties": { "merges": { "items": { "$ref": "#/components/schemas/OrganizationMergeRequest" }, "minItems": 1, "title": "Merges", "type": "array" } }, "required": [ "merges" ], "title": "OrganizationBatchMergeRequest", "type": "object" }, "OrganizationBatchMergeResponse": { "description": "Batch outcome with per-item results.", "properties": { "failed": { "default": 0, "title": "Failed", "type": "integer" }, "results": { "items": { "$ref": "#/components/schemas/OrganizationBatchMergeItem" }, "title": "Results", "type": "array" }, "succeeded": { "default": 0, "title": "Succeeded", "type": "integer" } }, "title": "OrganizationBatchMergeResponse", "type": "object" }, "OrganizationClusterRequest": { "description": "Cluster-detection knobs. Scope is always the caller's visible set (D3).", "properties": { "min_confidence": { "anyOf": [ { "maximum": 1.0, "minimum": 0.0, "type": "number" }, { "type": "null" } ], "title": "Min Confidence" } }, "title": "OrganizationClusterRequest", "type": "object" }, "OrganizationClustersResponse": { "description": "Transitive duplicate clusters, each with a suggested survivor.", "properties": { "clusters": { "items": { "$ref": "#/components/schemas/OrganizationDuplicateCluster" }, "title": "Clusters", "type": "array" }, "total": { "default": 0, "title": "Total", "type": "integer" } }, "title": "OrganizationClustersResponse", "type": "object" }, "OrganizationConflictTarget": { "description": "Existing organization blocking publication of a same-name draft.", "properties": { "approval_status": { "title": "Approval Status", "type": "string" }, "id": { "format": "uuid", "title": "Id", "type": "string" }, "name": { "title": "Name", "type": "string" } }, "required": [ "id", "name", "approval_status" ], "title": "OrganizationConflictTarget", "type": "object" }, "OrganizationCreate": { "description": "Input model for creating new organizations.\n\nUsed in:\n - POST /api/v1/organizations\n\nAttributes:\n name: Organization name (required)\n type: Organization type (optional, default: other)\n website: Organization website URL (optional)\n email: Organization contact email (optional)\n phone: Organization contact phone (optional)\n address: Organization physical address (optional)\n description: Organization description (optional)\n\nRelated: migration 156_enhanced_crawl_rules.sql", "properties": { "address": { "anyOf": [ { "maxLength": 500, "type": "string" }, { "type": "null" } ], "description": "Organization physical address", "title": "Address" }, "aliases": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "description": "Alternate names", "title": "Aliases" }, "description": { "anyOf": [ { "maxLength": 2000, "type": "string" }, { "type": "null" } ], "description": "Organization description", "title": "Description" }, "email": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "description": "Organization contact email", "title": "Email" }, "emails": { "anyOf": [ { "items": { "$ref": "#/components/schemas/OrgEmailEntry" }, "type": "array" }, { "type": "null" } ], "description": "Email channels", "title": "Emails" }, "legal_name": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "description": "Registered legal name", "title": "Legal Name" }, "locations": { "anyOf": [ { "items": { "$ref": "#/components/schemas/OrgLocationEntry" }, "type": "array" }, { "type": "null" } ], "description": "Locations", "title": "Locations" }, "name": { "description": "Organization name (1-255 characters)", "examples": [ "Lincoln Elementary" ], "maxLength": 255, "minLength": 1, "title": "Name", "type": "string" }, "parent_organization_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Parent organization UUID (cycles rejected with 422)", "title": "Parent Organization Id" }, "phone": { "anyOf": [ { "maxLength": 50, "type": "string" }, { "type": "null" } ], "description": "Organization contact phone", "title": "Phone" }, "phones": { "anyOf": [ { "items": { "$ref": "#/components/schemas/OrgPhoneEntry" }, "type": "array" }, { "type": "null" } ], "description": "Phone channels", "title": "Phones" }, "social_profiles": { "anyOf": [ { "items": { "$ref": "#/components/schemas/OrgSocialProfileEntry" }, "type": "array" }, { "type": "null" } ], "description": "Social profiles", "title": "Social Profiles" }, "type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": "other", "description": "Organization type", "examples": [ "school", "team", "club" ], "title": "Type" }, "visibility": { "anyOf": [ { "enum": [ "private", "shared" ], "type": "string" }, { "type": "null" } ], "description": "Omitted: private to you (TIDY-20007); shared by choice.", "title": "Visibility" }, "website": { "anyOf": [ { "maxLength": 500, "type": "string" }, { "type": "null" } ], "description": "Organization website URL", "title": "Website" }, "websites": { "anyOf": [ { "items": { "$ref": "#/components/schemas/OrgWebsiteEntry" }, "type": "array" }, { "type": "null" } ], "description": "Websites", "title": "Websites" } }, "required": [ "name" ], "title": "OrganizationCreate", "type": "object" }, "OrganizationDismissRequest": { "description": "Mark a pair as 'not duplicates'.", "properties": { "organization_a_id": { "title": "Organization A Id", "type": "string" }, "organization_b_id": { "title": "Organization B Id", "type": "string" }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Reason" } }, "required": [ "organization_a_id", "organization_b_id" ], "title": "OrganizationDismissRequest", "type": "object" }, "OrganizationDismissedListResponse": { "description": "Pairs this tenant dismissed, newest first.", "properties": { "pairs": { "items": { "$ref": "#/components/schemas/DismissedOrganizationPair" }, "title": "Pairs", "type": "array" }, "total": { "default": 0, "title": "Total", "type": "integer" } }, "title": "OrganizationDismissedListResponse", "type": "object" }, "OrganizationDraftMatchCandidate": { "description": "One existing organization the draft may already be.", "properties": { "best_tier": { "default": 0, "title": "Best Tier", "type": "integer" }, "confidence": { "title": "Confidence", "type": "number" }, "organization": { "$ref": "#/components/schemas/api_service__models__organization_merge__OrganizationSummary" }, "reasons": { "items": { "type": "string" }, "title": "Reasons", "type": "array" } }, "required": [ "organization", "confidence" ], "title": "OrganizationDraftMatchCandidate", "type": "object" }, "OrganizationDraftMatchRequest": { "description": "An unsaved organization draft to score against the caller's visible orgs.\n\nCreate-time near-duplicate warning (TIDY-15513). No row is written; the\nclient sends what the user has typed so far.", "properties": { "address": { "anyOf": [ { "maxLength": 500, "type": "string" }, { "type": "null" } ], "title": "Address" }, "emails": { "items": { "type": "string" }, "maxItems": 10, "title": "Emails", "type": "array" }, "exclude_ids": { "description": "Organization ids to skip (e.g. the draft row itself)", "items": { "type": "string" }, "title": "Exclude Ids", "type": "array" }, "legal_name": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "title": "Legal Name" }, "limit": { "default": 5, "maximum": 20.0, "minimum": 1.0, "title": "Limit", "type": "integer" }, "name": { "maxLength": 255, "title": "Name", "type": "string" }, "phone": { "anyOf": [ { "maxLength": 50, "type": "string" }, { "type": "null" } ], "title": "Phone" }, "website": { "anyOf": [ { "maxLength": 500, "type": "string" }, { "type": "null" } ], "title": "Website" } }, "required": [ "name" ], "title": "OrganizationDraftMatchRequest", "type": "object" }, "OrganizationDraftMatchResponse": { "description": "Ranked create-time candidates. Advisory only — creation is never blocked.", "properties": { "candidates": { "items": { "$ref": "#/components/schemas/OrganizationDraftMatchCandidate" }, "title": "Candidates", "type": "array" } }, "title": "OrganizationDraftMatchResponse", "type": "object" }, "OrganizationDuplicateCluster": { "description": "Transitive cluster of duplicate organizations.", "properties": { "confidence": { "title": "Confidence", "type": "number" }, "contains_parent_child": { "default": false, "title": "Contains Parent Child", "type": "boolean" }, "organizations": { "items": { "$ref": "#/components/schemas/api_service__models__organization_merge__OrganizationSummary" }, "title": "Organizations", "type": "array" }, "reasons": { "items": { "type": "string" }, "title": "Reasons", "type": "array" }, "suggested_survivor_id": { "title": "Suggested Survivor Id", "type": "string" } }, "required": [ "organizations", "confidence", "suggested_survivor_id" ], "title": "OrganizationDuplicateCluster", "type": "object" }, "OrganizationDuplicatePair": { "description": "A scored candidate duplicate pair. Detection proposes; a human confirms.", "properties": { "confidence": { "title": "Confidence", "type": "number" }, "organization_a": { "$ref": "#/components/schemas/api_service__models__organization_merge__OrganizationSummary" }, "organization_b": { "$ref": "#/components/schemas/api_service__models__organization_merge__OrganizationSummary" }, "parent_child": { "default": false, "title": "Parent Child", "type": "boolean" }, "reasons": { "items": { "type": "string" }, "title": "Reasons", "type": "array" } }, "required": [ "organization_a", "organization_b", "confidence" ], "title": "OrganizationDuplicatePair", "type": "object" }, "OrganizationDuplicatesResponse": { "description": "Scored duplicate pairs for the caller's tenant.", "properties": { "pairs": { "items": { "$ref": "#/components/schemas/OrganizationDuplicatePair" }, "title": "Pairs", "type": "array" }, "total": { "default": 0, "title": "Total", "type": "integer" } }, "title": "OrganizationDuplicatesResponse", "type": "object" }, "OrganizationEditHistoryEntry": { "description": "Single organization field edit record.", "properties": { "change_set_id": { "description": "Edit batch UUID", "title": "Change Set Id", "type": "string" }, "changed_at": { "description": "ISO 8601 timestamp of the change", "format": "date-time", "title": "Changed At", "type": "string" }, "changed_by": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Account UUID that made the change", "title": "Changed By" }, "edit_source": { "description": "Source of the change (user, assistant, restore)", "title": "Edit Source", "type": "string" }, "field_name": { "description": "Changed field name", "title": "Field Name", "type": "string" }, "id": { "description": "Edit history UUID", "title": "Id", "type": "string" }, "new_value": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "New stored value", "title": "New Value" }, "old_value": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Previous stored value", "title": "Old Value" }, "organization_id": { "description": "Organization UUID", "title": "Organization Id", "type": "string" }, "source_context": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "description": "Captured source attribution for the change", "title": "Source Context" } }, "required": [ "id", "change_set_id", "organization_id", "field_name", "edit_source", "changed_at" ], "title": "OrganizationEditHistoryEntry", "type": "object" }, "OrganizationEditHistoryResponse": { "description": "Response payload for organization edit history queries.", "properties": { "entries": { "description": "Most recent edit history entries for the organization", "items": { "$ref": "#/components/schemas/OrganizationEditHistoryEntry" }, "title": "Entries", "type": "array" } }, "title": "OrganizationEditHistoryResponse", "type": "object" }, "OrganizationId": { "description": "Typed primitive ID for organizations (prefix 'O').", "examples": [ "O-550e8400-e29b-41d4-a716-446655440000" ], "pattern": "^O-[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "title": "OrganizationId", "type": "string", "x-tidy-typed-id-prefix": "O", "x-tidy-typed-id-table": "organizations" }, "OrganizationMappingCreate": { "description": "Input for POST /api/v1/organizations/{id}/mappings.", "properties": { "kind": { "description": "Mapping kind — a whole domain or one specific sender address", "enum": [ "domain", "sender" ], "title": "Kind", "type": "string" }, "reassign": { "default": false, "description": "When the value is already mapped to another organization by this member, move the mapping instead of returning 409", "title": "Reassign", "type": "boolean" }, "value": { "description": "Domain (e.g. parentsquare.com) or sender addr-spec (e.g. tom@gmail.com)", "maxLength": 320, "minLength": 1, "title": "Value", "type": "string" } }, "required": [ "kind", "value" ], "title": "OrganizationMappingCreate", "type": "object" }, "OrganizationMappingListResponse": { "description": "List of the caller's own mappings for one organization.", "properties": { "mappings": { "items": { "$ref": "#/components/schemas/OrganizationMappingResponse" }, "title": "Mappings", "type": "array" } }, "title": "OrganizationMappingListResponse", "type": "object" }, "OrganizationMappingResponse": { "description": "One sender/domain mapping row (member-owned).", "properties": { "created_at": { "description": "Creation timestamp", "format": "date-time", "title": "Created At", "type": "string" }, "id": { "description": "Mapping row id (UUID)", "title": "Id", "type": "string" }, "kind": { "description": "Mapping kind", "enum": [ "domain", "sender" ], "title": "Kind", "type": "string" }, "organization_id": { "description": "Organization this domain/sender maps to", "examples": [ "O-550e8400-e29b-41d4-a716-446655440000" ], "pattern": "^O-[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "title": "OrganizationId", "type": "string", "x-tidy-typed-id-prefix": "O", "x-tidy-typed-id-table": "organizations" }, "updated_at": { "description": "Last modification timestamp", "format": "date-time", "title": "Updated At", "type": "string" }, "value": { "description": "Normalized domain or sender addr-spec", "title": "Value", "type": "string" } }, "required": [ "id", "organization_id", "kind", "value", "created_at", "updated_at" ], "title": "OrganizationMappingResponse", "type": "object" }, "OrganizationMemberCreate": { "description": "Input for POST /api/v1/organizations/{id}/members.", "properties": { "contact_id": { "description": "Contact to add as a member (typed C-id or UUID)", "title": "Contact Id", "type": "string" }, "relationship_type": { "anyOf": [ { "maxLength": 100, "type": "string" }, { "type": "null" } ], "description": "Affiliation nuance (e.g. works_at, member_of). Defaults to affiliated_with.", "title": "Relationship Type" }, "role": { "anyOf": [ { "maxLength": 200, "type": "string" }, { "type": "null" } ], "description": "Title/role at the organization (e.g. 'Teacher')", "title": "Role" } }, "required": [ "contact_id" ], "title": "OrganizationMemberCreate", "type": "object" }, "OrganizationMemberListResponse": { "description": "Members of one organization visible to the caller.", "properties": { "members": { "items": { "$ref": "#/components/schemas/OrganizationMemberResponse" }, "title": "Members", "type": "array" } }, "title": "OrganizationMemberListResponse", "type": "object" }, "OrganizationMemberResponse": { "description": "One membership row, joined to its contact's display name.", "properties": { "contact_id": { "description": "Member contact", "examples": [ "C-550e8400-e29b-41d4-a716-446655440000" ], "pattern": "^C-[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "title": "ContactId", "type": "string", "x-tidy-typed-id-prefix": "C", "x-tidy-typed-id-table": "contacts" }, "contact_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Contact display name", "title": "Contact Name" }, "created_at": { "description": "Creation timestamp", "format": "date-time", "title": "Created At", "type": "string" }, "is_org_primary_contact": { "description": "This member is the organization's primary contact", "title": "Is Org Primary Contact", "type": "boolean" }, "is_primary": { "description": "This org is the contact's primary organization", "title": "Is Primary", "type": "boolean" }, "membership_id": { "description": "Membership row id (UUID)", "title": "Membership Id", "type": "string" }, "organization_id": { "description": "Organization", "examples": [ "O-550e8400-e29b-41d4-a716-446655440000" ], "pattern": "^O-[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "title": "OrganizationId", "type": "string", "x-tidy-typed-id-prefix": "O", "x-tidy-typed-id-table": "organizations" }, "parent_membership_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Manager membership id within the same org (UUID), or null (root)", "title": "Parent Membership Id" }, "relationship_type": { "description": "Affiliation type", "title": "Relationship Type", "type": "string" }, "role": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Title/role at the organization", "title": "Role" }, "updated_at": { "description": "Last modification timestamp", "format": "date-time", "title": "Updated At", "type": "string" } }, "required": [ "membership_id", "organization_id", "contact_id", "relationship_type", "is_primary", "is_org_primary_contact", "created_at", "updated_at" ], "title": "OrganizationMemberResponse", "type": "object" }, "OrganizationMemberUpdate": { "description": "Input for PATCH /api/v1/organizations/{id}/members/{membership_id}.\n\nEvery field is optional; only fields actually present in the request body\nare applied (``model_fields_set``). ``parent_membership_id`` accepts ``null``\nto detach (become a root), distinct from omission which leaves it unchanged.", "properties": { "is_org_primary_contact": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Designate (true) / clear (false) this member as the org's primary contact", "title": "Is Org Primary Contact" }, "is_primary": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Make (true) / unmake (false) this organization the contact's primary organization; setting it clears the contact's previous primary (TIDY-19489 — the contact's organizations relation edits it here)", "title": "Is Primary" }, "parent_membership_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Membership id of this member's manager within the SAME org (bare UUID), or null to detach to root", "title": "Parent Membership Id" }, "relationship_type": { "anyOf": [ { "maxLength": 100, "type": "string" }, { "type": "null" } ], "title": "Relationship Type" }, "role": { "anyOf": [ { "maxLength": 200, "type": "string" }, { "type": "null" } ], "title": "Role" } }, "title": "OrganizationMemberUpdate", "type": "object" }, "OrganizationMergeHistoryResponse": { "description": "Merge provenance for one survivor.", "properties": { "merged_from": { "items": { "$ref": "#/components/schemas/OrganizationMergedFromEntry" }, "title": "Merged From", "type": "array" }, "organization_id": { "title": "Organization Id", "type": "string" } }, "required": [ "organization_id" ], "title": "OrganizationMergeHistoryResponse", "type": "object" }, "OrganizationMergePreview": { "description": "Read-only projection of what a merge would do (R3).", "properties": { "losers": { "items": { "$ref": "#/components/schemas/OrgMergeLoserPlan" }, "title": "Losers", "type": "array" }, "residual_entries": { "items": { "$ref": "#/components/schemas/OrgResidualEntry" }, "title": "Residual Entries", "type": "array" }, "survivor": { "$ref": "#/components/schemas/api_service__models__organization_merge__OrganizationSummary" }, "transfer_counts": { "additionalProperties": { "type": "integer" }, "title": "Transfer Counts", "type": "object" } }, "required": [ "survivor" ], "title": "OrganizationMergePreview", "type": "object" }, "OrganizationMergePreviewRequest": { "description": "Explicit survivor + explicit losers (D2) — there is no auto-merge.", "properties": { "loser_ids": { "items": { "type": "string" }, "minItems": 1, "title": "Loser Ids", "type": "array" }, "survivor_id": { "title": "Survivor Id", "type": "string" } }, "required": [ "survivor_id", "loser_ids" ], "title": "OrganizationMergePreviewRequest", "type": "object" }, "OrganizationMergeRequest": { "description": "Execute one merge. Same shape as the preview request.", "properties": { "loser_ids": { "items": { "type": "string" }, "minItems": 1, "title": "Loser Ids", "type": "array" }, "survivor_id": { "title": "Survivor Id", "type": "string" } }, "required": [ "survivor_id", "loser_ids" ], "title": "OrganizationMergeRequest", "type": "object" }, "OrganizationMergeResult": { "description": "Outcome of an executed merge.", "properties": { "approval_status": { "title": "Approval Status", "type": "string" }, "loser_ids": { "items": { "type": "string" }, "title": "Loser Ids", "type": "array" }, "merge_id": { "default": "", "description": "Merge history id — pass to the undo endpoint (TIDY-15507)", "title": "Merge Id", "type": "string" }, "residual_entries": { "items": { "$ref": "#/components/schemas/OrgResidualEntry" }, "title": "Residual Entries", "type": "array" }, "restore_hints": { "additionalProperties": true, "title": "Restore Hints", "type": "object" }, "survivor_id": { "title": "Survivor Id", "type": "string" }, "transferred": { "additionalProperties": { "type": "integer" }, "title": "Transferred", "type": "object" } }, "required": [ "survivor_id", "approval_status" ], "title": "OrganizationMergeResult", "type": "object" }, "OrganizationMergeUndoResponse": { "description": "Outcome of undoing a merge (TIDY-15507).", "properties": { "merge_id": { "title": "Merge Id", "type": "string" }, "restored_ids": { "items": { "type": "string" }, "title": "Restored Ids", "type": "array" }, "rows_restored": { "additionalProperties": { "additionalProperties": { "type": "integer" }, "type": "object" }, "title": "Rows Restored", "type": "object" }, "survivor_id": { "title": "Survivor Id", "type": "string" } }, "required": [ "merge_id", "survivor_id" ], "title": "OrganizationMergeUndoResponse", "type": "object" }, "OrganizationMergedFromEntry": { "description": "One organization that was merged away into this survivor (F1).\n\nServed from ``organization_merge_history`` rows — never parsed out of the\nresidual-log prose or the survivor's aliases.", "properties": { "id": { "title": "Id", "type": "string" }, "merge_id": { "title": "Merge Id", "type": "string" }, "merged_at": { "format": "date-time", "title": "Merged At", "type": "string" }, "name": { "title": "Name", "type": "string" } }, "required": [ "id", "name", "merged_at", "merge_id" ], "title": "OrganizationMergedFromEntry", "type": "object" }, "OrganizationResponse": { "description": "Complete organization object returned by API endpoints.\n\nUsed in:\n - GET /api/v1/organizations (list response items)\n - GET /api/v1/organizations/{id} (single organization detail)\n - POST /api/v1/organizations (created organization response, 201)\n - PUT /api/v1/organizations/{id} (updated organization response)\n\nAttributes:\n id: Unique organization identifier (UUID)\n tenant_id: Associated tenant identifier (UUID)\n name: Organization name (required)\n type: Organization type (school, team, club, etc.)\n website: Organization website URL\n email: Organization contact email\n phone: Organization contact phone\n address: Organization physical address\n description: Organization description\n logo_url: URL to organization logo\n source_type: Where organization came from (extraction|manual|sync)\n source_id: Reference to source object (UUID)\n confidence: AI confidence score 0.0-1.0\n requires_review: Whether organization needs human review\n review_reason: Reason for review requirement\n reviewed_at: When organization was reviewed\n reviewed_by: Who reviewed the organization\n contact_count: Number of contacts linked to this organization\n created_at: ISO 8601 timestamp of organization creation\n updated_at: ISO 8601 timestamp of last modification\n\nRelated: migration 156_enhanced_crawl_rules.sql, 171_organizations_enhancements.sql", "properties": { "address": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Organization physical address", "examples": [ "123 Main St, Springfield, IL 62701" ], "title": "Address" }, "aliases": { "description": "Alternate names (feed search, recipient typeahead, extraction dedup)", "items": { "type": "string" }, "title": "Aliases", "type": "array" }, "avatar_schema": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "description": "Custom avatar schema (mirrors contacts.avatar_schema)", "title": "Avatar Schema" }, "confidence": { "anyOf": [ { "maximum": 1.0, "minimum": 0.0, "type": "number" }, { "type": "null" } ], "default": null, "description": "AI confidence score 0.0-1.0", "examples": [ 0.85 ], "title": "Confidence" }, "contact_count": { "default": 0, "description": "Number of contacts linked to this organization", "title": "Contact Count", "type": "integer" }, "created_at": { "description": "ISO 8601 timestamp of organization creation", "format": "date-time", "title": "Created At", "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Organization description", "examples": [ "Local elementary school serving grades K-5" ], "title": "Description" }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Organization contact email", "examples": [ "info@lincoln.edu" ], "title": "Email" }, "emails": { "description": "Email channels", "items": { "$ref": "#/components/schemas/OrgEmailEntry" }, "title": "Emails", "type": "array" }, "icon": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Polymorphic icon value (D12) — serialized F3 IconValue ({kind,value}); a bare Lucide name round-trips as a plain string (TIDY-10503 / F8).", "title": "Icon" }, "id": { "description": "Unique organization identifier (UUID)", "examples": [ "a1b2c3d4-..." ], "title": "Id", "type": "string" }, "identity_source": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Selected-identity discriminator: 'custom_avatar' | 'photo' | NULL (NULL = automatic: logo → icon → default building)", "title": "Identity Source" }, "legal_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Registered legal name", "title": "Legal Name" }, "locations": { "description": "Locations (contact address entry shape)", "items": { "$ref": "#/components/schemas/OrgLocationEntry" }, "title": "Locations", "type": "array" }, "logo_domain": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Resolved logo domain", "title": "Logo Domain" }, "logo_thumbnail": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Inline resolved-logo thumbnail (base64)", "title": "Logo Thumbnail" }, "logo_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "URL to organization logo", "title": "Logo Url" }, "name": { "description": "Organization name", "examples": [ "Lincoln Elementary" ], "title": "Name", "type": "string" }, "parent_organization_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Parent organization UUID (district→schools; cycles rejected)", "title": "Parent Organization Id" }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Organization contact phone", "examples": [ "+15551234567" ], "title": "Phone" }, "phones": { "description": "Phone channels", "items": { "$ref": "#/components/schemas/OrgPhoneEntry" }, "title": "Phones", "type": "array" }, "photo_thumbnail": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Inline uploaded-photo thumbnail (base64, square, <8KB)", "title": "Photo Thumbnail" }, "photo_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Uploaded photo storage path (never a presigned URL)", "title": "Photo Url" }, "requires_review": { "default": false, "description": "Whether organization needs human review", "title": "Requires Review", "type": "boolean" }, "review_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Reason for review requirement", "title": "Review Reason" }, "reviewed_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "description": "When organization was reviewed", "title": "Reviewed At" }, "reviewed_by": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Who reviewed the organization (user UUID)", "title": "Reviewed By" }, "social_profiles": { "description": "Social profiles", "items": { "$ref": "#/components/schemas/OrgSocialProfileEntry" }, "title": "Social Profiles", "type": "array" }, "source_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Reference to source object (UUID)", "examples": [ "a1b2c3d4-..." ], "title": "Source Id" }, "source_type": { "default": "manual", "description": "Where organization came from (extraction|manual|sync)", "examples": [ "manual", "extraction" ], "title": "Source Type", "type": "string" }, "tenant_id": { "description": "Associated tenant identifier (UUID)", "examples": [ "a1b2c3d4-..." ], "title": "Tenant Id", "type": "string" }, "type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": "other", "description": "Organization type (school, team, club, etc.)", "examples": [ "school", "team", "club" ], "title": "Type" }, "updated_at": { "description": "ISO 8601 timestamp of last modification", "format": "date-time", "title": "Updated At", "type": "string" }, "website": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Organization website URL", "examples": [ "https://lincoln.edu" ], "title": "Website" }, "websites": { "description": "Websites", "items": { "$ref": "#/components/schemas/OrgWebsiteEntry" }, "title": "Websites", "type": "array" } }, "required": [ "id", "tenant_id", "name", "created_at", "updated_at" ], "title": "OrganizationResponse", "type": "object" }, "OrganizationSummary": { "description": "Summary of an organization for embedding in contact responses.", "properties": { "id": { "description": "Organization UUID", "title": "Id", "type": "string" }, "is_primary": { "default": false, "description": "Whether this is the contact's primary organization", "title": "Is Primary", "type": "boolean" }, "name": { "description": "Organization name", "examples": [ "Lincoln Elementary" ], "title": "Name", "type": "string" }, "role": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Contact's role at this organization", "examples": [ "Teacher", "Coach", "Parent" ], "title": "Role" }, "type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Organization type (school, team, club, activity, etc.)", "examples": [ "school", "team", "club" ], "title": "Type" } }, "required": [ "id", "name" ], "title": "OrganizationSummary", "type": "object" }, "OrganizationUpdate": { "description": "Input model for updating existing organizations.\n\nUsed in:\n - PUT /api/v1/organizations/{id}\n - PATCH /api/v1/organizations/{id}\n\nAll fields are optional - only provided fields are updated.\n\nAttributes:\n name: Organization name (optional)\n type: Organization type (optional)\n website: Organization website URL (optional)\n email: Organization contact email (optional)\n phone: Organization contact phone (optional)\n address: Organization physical address (optional)\n description: Organization description (optional)\n\nRelated: migration 156_enhanced_crawl_rules.sql", "properties": { "address": { "anyOf": [ { "maxLength": 500, "type": "string" }, { "type": "null" } ], "description": "Organization physical address", "title": "Address" }, "aliases": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "description": "Alternate names", "title": "Aliases" }, "avatar_schema": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "Custom avatar schema (mirrors contacts.avatar_schema)", "title": "Avatar Schema" }, "description": { "anyOf": [ { "maxLength": 2000, "type": "string" }, { "type": "null" } ], "description": "Organization description", "title": "Description" }, "email": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "description": "Organization contact email", "title": "Email" }, "emails": { "anyOf": [ { "items": { "$ref": "#/components/schemas/OrgEmailEntry" }, "type": "array" }, { "type": "null" } ], "description": "Email channels", "title": "Emails" }, "icon": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Polymorphic icon value (D12) — serialized F3 IconValue ({kind,value}); a bare Lucide name round-trips as a plain string (TIDY-10503 / F8).", "title": "Icon" }, "identity_source": { "anyOf": [ { "pattern": "^(custom_avatar|photo)$", "type": "string" }, { "type": "null" } ], "description": "Selected-identity discriminator: 'custom_avatar' | 'photo' | null", "title": "Identity Source" }, "is_starred": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Star flag (member-owned pin)", "title": "Is Starred" }, "legal_name": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "description": "Registered legal name", "title": "Legal Name" }, "locations": { "anyOf": [ { "items": { "$ref": "#/components/schemas/OrgLocationEntry" }, "type": "array" }, { "type": "null" } ], "description": "Locations", "title": "Locations" }, "name": { "anyOf": [ { "maxLength": 255, "minLength": 1, "type": "string" }, { "type": "null" } ], "description": "Organization name (1-255 characters)", "title": "Name" }, "parent_organization_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Parent organization UUID; null clears (cycles rejected with 422)", "title": "Parent Organization Id" }, "phone": { "anyOf": [ { "maxLength": 50, "type": "string" }, { "type": "null" } ], "description": "Organization contact phone", "title": "Phone" }, "phones": { "anyOf": [ { "items": { "$ref": "#/components/schemas/OrgPhoneEntry" }, "type": "array" }, { "type": "null" } ], "description": "Phone channels", "title": "Phones" }, "social_profiles": { "anyOf": [ { "items": { "$ref": "#/components/schemas/OrgSocialProfileEntry" }, "type": "array" }, { "type": "null" } ], "description": "Social profiles", "title": "Social Profiles" }, "type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Organization type", "title": "Type" }, "visibility": { "anyOf": [ { "enum": [ "private", "shared" ], "type": "string" }, { "type": "null" } ], "description": "Who sees it. Only its owner can change this.", "title": "Visibility" }, "website": { "anyOf": [ { "maxLength": 500, "type": "string" }, { "type": "null" } ], "description": "Organization website URL", "title": "Website" }, "websites": { "anyOf": [ { "items": { "$ref": "#/components/schemas/OrgWebsiteEntry" }, "type": "array" }, { "type": "null" } ], "description": "Websites", "title": "Websites" } }, "title": "OrganizationUpdate", "type": "object" }, "OrganizationWithContacts": { "description": "Organization response with linked contacts.\n\nExtended response model that includes contact relationships.\n\nAttributes:\n (all from OrganizationResponse)\n contacts: List of contacts linked to this organization", "properties": { "address": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Organization physical address", "examples": [ "123 Main St, Springfield, IL 62701" ], "title": "Address" }, "aliases": { "description": "Alternate names (feed search, recipient typeahead, extraction dedup)", "items": { "type": "string" }, "title": "Aliases", "type": "array" }, "avatar_schema": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "description": "Custom avatar schema (mirrors contacts.avatar_schema)", "title": "Avatar Schema" }, "confidence": { "anyOf": [ { "maximum": 1.0, "minimum": 0.0, "type": "number" }, { "type": "null" } ], "default": null, "description": "AI confidence score 0.0-1.0", "examples": [ 0.85 ], "title": "Confidence" }, "contact_count": { "default": 0, "description": "Number of contacts linked to this organization", "title": "Contact Count", "type": "integer" }, "contacts": { "default": [], "description": "Contacts linked to this organization", "items": { "$ref": "#/components/schemas/ContactOrganizationLink" }, "title": "Contacts", "type": "array" }, "created_at": { "description": "ISO 8601 timestamp of organization creation", "format": "date-time", "title": "Created At", "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Organization description", "examples": [ "Local elementary school serving grades K-5" ], "title": "Description" }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Organization contact email", "examples": [ "info@lincoln.edu" ], "title": "Email" }, "emails": { "description": "Email channels", "items": { "$ref": "#/components/schemas/OrgEmailEntry" }, "title": "Emails", "type": "array" }, "icon": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Polymorphic icon value (D12) — serialized F3 IconValue ({kind,value}); a bare Lucide name round-trips as a plain string (TIDY-10503 / F8).", "title": "Icon" }, "id": { "description": "Unique organization identifier (UUID)", "examples": [ "a1b2c3d4-..." ], "title": "Id", "type": "string" }, "identity_source": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Selected-identity discriminator: 'custom_avatar' | 'photo' | NULL (NULL = automatic: logo → icon → default building)", "title": "Identity Source" }, "legal_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Registered legal name", "title": "Legal Name" }, "locations": { "description": "Locations (contact address entry shape)", "items": { "$ref": "#/components/schemas/OrgLocationEntry" }, "title": "Locations", "type": "array" }, "logo_domain": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Resolved logo domain", "title": "Logo Domain" }, "logo_thumbnail": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Inline resolved-logo thumbnail (base64)", "title": "Logo Thumbnail" }, "logo_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "URL to organization logo", "title": "Logo Url" }, "merge_forwarded": { "default": false, "description": "True when `requested_id` was a merged organization forwarded to `id`.", "title": "Merge Forwarded", "type": "boolean" }, "name": { "description": "Organization name", "examples": [ "Lincoln Elementary" ], "title": "Name", "type": "string" }, "parent_organization_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Parent organization UUID (district→schools; cycles rejected)", "title": "Parent Organization Id" }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Organization contact phone", "examples": [ "+15551234567" ], "title": "Phone" }, "phones": { "description": "Phone channels", "items": { "$ref": "#/components/schemas/OrgPhoneEntry" }, "title": "Phones", "type": "array" }, "photo_thumbnail": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Inline uploaded-photo thumbnail (base64, square, <8KB)", "title": "Photo Thumbnail" }, "photo_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Uploaded photo storage path (never a presigned URL)", "title": "Photo Url" }, "requested_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "The organization id the caller asked for. Differs from `id` when the requested organization was merged away and forwarded to its survivor (TIDY-15507).", "title": "Requested Id" }, "requires_review": { "default": false, "description": "Whether organization needs human review", "title": "Requires Review", "type": "boolean" }, "review_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Reason for review requirement", "title": "Review Reason" }, "reviewed_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "description": "When organization was reviewed", "title": "Reviewed At" }, "reviewed_by": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Who reviewed the organization (user UUID)", "title": "Reviewed By" }, "social_profiles": { "description": "Social profiles", "items": { "$ref": "#/components/schemas/OrgSocialProfileEntry" }, "title": "Social Profiles", "type": "array" }, "source_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Reference to source object (UUID)", "examples": [ "a1b2c3d4-..." ], "title": "Source Id" }, "source_type": { "default": "manual", "description": "Where organization came from (extraction|manual|sync)", "examples": [ "manual", "extraction" ], "title": "Source Type", "type": "string" }, "tenant_id": { "description": "Associated tenant identifier (UUID)", "examples": [ "a1b2c3d4-..." ], "title": "Tenant Id", "type": "string" }, "type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": "other", "description": "Organization type (school, team, club, etc.)", "examples": [ "school", "team", "club" ], "title": "Type" }, "updated_at": { "description": "ISO 8601 timestamp of last modification", "format": "date-time", "title": "Updated At", "type": "string" }, "website": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Organization website URL", "examples": [ "https://lincoln.edu" ], "title": "Website" }, "websites": { "description": "Websites", "items": { "$ref": "#/components/schemas/OrgWebsiteEntry" }, "title": "Websites", "type": "array" } }, "required": [ "id", "tenant_id", "name", "created_at", "updated_at" ], "title": "OrganizationWithContacts", "type": "object" }, "OrphanedFacetCard": { "description": "One orphan group: all of the user's facets on one unreadable target.", "properties": { "demoted_by_actor_display_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Demoted By Actor Display Name" }, "facet_count": { "title": "Facet Count", "type": "integer" }, "facet_preview": { "default": [], "items": { "type": "string" }, "title": "Facet Preview", "type": "array" }, "last_observation_at": { "format": "date-time", "title": "Last Observation At", "type": "string" }, "target_display_name": { "title": "Target Display Name", "type": "string" }, "target_entity_id": { "title": "Target Entity Id", "type": "string" }, "target_entity_type": { "enum": [ "contact", "organization" ], "title": "Target Entity Type", "type": "string" } }, "required": [ "target_entity_id", "target_entity_type", "target_display_name", "facet_count", "last_observation_at" ], "title": "OrphanedFacetCard", "type": "object" }, "OrphanedFacetListResponse": { "description": "The user's pending orphaned-facet lint cards.", "properties": { "count": { "title": "Count", "type": "integer" }, "orphans": { "items": { "$ref": "#/components/schemas/OrphanedFacetCard" }, "title": "Orphans", "type": "array" } }, "required": [ "orphans", "count" ], "title": "OrphanedFacetListResponse", "type": "object" }, "OutboundTriggerRequest": { "properties": { "signature_org_name": { "anyOf": [ { "maxLength": 120, "type": "string" }, { "type": "null" } ], "title": "Signature Org Name" }, "source_sent_email_id": { "title": "Source Sent Email Id", "type": "string" }, "tenant_id": { "title": "Tenant Id", "type": "string" } }, "required": [ "tenant_id", "source_sent_email_id" ], "title": "OutboundTriggerRequest", "type": "object" }, "OutgoingResponseTimes": { "properties": { "avg_seconds": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Avg Seconds" }, "by_hour": { "items": { "$ref": "#/components/schemas/ResponseTimeByHour" }, "title": "By Hour", "type": "array" }, "by_period": { "items": { "$ref": "#/components/schemas/ResponseTimeByPeriod" }, "title": "By Period", "type": "array" }, "median_seconds": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Median Seconds" }, "p90_seconds": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "P90 Seconds" } }, "required": [ "avg_seconds", "median_seconds", "p90_seconds", "by_period", "by_hour" ], "title": "OutgoingResponseTimes", "type": "object" }, "OutputCatalogEnablementBody": { "description": "Facet slug -> enabled. A slug absent from the map keeps its shipped default.\n\n``tier3_enabled`` is the SECOND gate of D25 (TIDY-15716): whether this\ntenant may run tier-3 (sandboxed code) generations at all, independently of\nany output type's own toggle. ``None`` leaves it unchanged, so a client\nthat only manages the type map cannot silently flip the tier gate.", "properties": { "enabled": { "additionalProperties": { "type": "boolean" }, "title": "Enabled", "type": "object" }, "tier3_enabled": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Enable/disable tier-3 (sandboxed code) generation for this tenant. Omit to leave unchanged. Off by default (D25).", "title": "Tier3 Enabled" } }, "title": "OutputCatalogEnablementBody", "type": "object" }, "OutputCatalogEnablementResponse": { "properties": { "enabled": { "additionalProperties": { "type": "boolean" }, "title": "Enabled", "type": "object" }, "tier3_enabled": { "default": false, "title": "Tier3 Enabled", "type": "boolean" } }, "required": [ "enabled" ], "title": "OutputCatalogEnablementResponse", "type": "object" }, "OvernightBatchRow": { "properties": { "audio_hours": { "title": "Audio Hours", "type": "number" }, "batch_count": { "title": "Batch Count", "type": "integer" }, "batch_date": { "format": "date", "title": "Batch Date", "type": "string" }, "completed_count": { "title": "Completed Count", "type": "integer" }, "estimated_cost_usd": { "title": "Estimated Cost Usd", "type": "number" }, "failed_count": { "title": "Failed Count", "type": "integer" }, "requested_count": { "title": "Requested Count", "type": "integer" } }, "required": [ "batch_date", "batch_count", "requested_count", "completed_count", "failed_count", "audio_hours", "estimated_cost_usd" ], "title": "OvernightBatchRow", "type": "object" }, "OverrideCreate": { "properties": { "burst_duration_seconds": { "default": 60, "maximum": 3600.0, "minimum": 1.0, "title": "Burst Duration Seconds", "type": "integer" }, "burst_multiplier": { "default": 2.0, "maximum": 100.0, "minimum": 1.0, "title": "Burst Multiplier", "type": "number" }, "limit_per_minute": { "minimum": 1.0, "title": "Limit Per Minute", "type": "integer" }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Reason" }, "scope_key": { "minLength": 1, "title": "Scope Key", "type": "string" }, "scope_type": { "enum": [ "tenant", "token", "service_endpoint" ], "title": "Scope Type", "type": "string" } }, "required": [ "scope_type", "scope_key", "limit_per_minute" ], "title": "OverrideCreate", "type": "object" }, "OverrideCreditsRequest": { "properties": { "credits_allocated": { "title": "Credits Allocated", "type": "integer" } }, "required": [ "credits_allocated" ], "title": "OverrideCreditsRequest", "type": "object" }, "OverrideResponse": { "properties": { "burst_duration_seconds": { "title": "Burst Duration Seconds", "type": "integer" }, "burst_multiplier": { "title": "Burst Multiplier", "type": "number" }, "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "created_by": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Created By" }, "id": { "format": "uuid", "title": "Id", "type": "string" }, "limit_per_minute": { "title": "Limit Per Minute", "type": "integer" }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Reason" }, "scope_key": { "title": "Scope Key", "type": "string" }, "scope_type": { "title": "Scope Type", "type": "string" }, "updated_at": { "format": "date-time", "title": "Updated At", "type": "string" } }, "required": [ "id", "scope_type", "scope_key", "limit_per_minute", "burst_multiplier", "burst_duration_seconds", "reason", "created_by", "created_at", "updated_at" ], "title": "OverrideResponse", "type": "object" }, "OverrideScope": { "description": "Allowed actions for support access.", "enum": [ "view_data", "modify_settings", "manage_connections", "reset_password", "export_data" ], "title": "OverrideScope", "type": "string" }, "OverrideStatus": { "description": "Support override status.", "enum": [ "active", "expired", "revoked" ], "title": "OverrideStatus", "type": "string" }, "OvhCredentials": { "additionalProperties": false, "properties": { "application_key": { "format": "password", "maxLength": 256, "minLength": 1, "title": "Application Key", "type": "string", "writeOnly": true }, "application_secret": { "format": "password", "maxLength": 256, "minLength": 1, "title": "Application Secret", "type": "string", "writeOnly": true }, "consumer_key": { "format": "password", "maxLength": 256, "minLength": 1, "title": "Consumer Key", "type": "string", "writeOnly": true }, "endpoint": { "default": "eu", "enum": [ "eu", "us" ], "title": "Endpoint", "type": "string" }, "project_id": { "anyOf": [ { "pattern": "^[A-Za-z0-9-]{1,128}$", "type": "string" }, { "type": "null" } ], "title": "Project Id" } }, "required": [ "application_key", "application_secret", "consumer_key" ], "title": "OvhCredentials", "type": "object" }, "OwnerConsentRequest": { "properties": { "feature": { "title": "Feature", "type": "string" }, "user_id": { "title": "User Id", "type": "string" } }, "required": [ "user_id", "feature" ], "title": "OwnerConsentRequest", "type": "object" }, "OwnerConsentResponse": { "properties": { "consent_token": { "title": "Consent Token", "type": "string" } }, "required": [ "consent_token" ], "title": "OwnerConsentResponse", "type": "object" }, "OwnerControlsRequest": { "properties": { "checkpoint_pct": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Checkpoint Pct" }, "owner_approval_required": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Owner Approval Required" }, "topup_owner_restricted": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Topup Owner Restricted" } }, "title": "OwnerControlsRequest", "type": "object" }, "OwnerControlsResponse": { "properties": { "checkpoint_pct": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "title": "Checkpoint Pct" }, "owner_approval_required": { "title": "Owner Approval Required", "type": "boolean" }, "topup_owner_restricted": { "title": "Topup Owner Restricted", "type": "boolean" } }, "required": [ "owner_approval_required", "topup_owner_restricted" ], "title": "OwnerControlsResponse", "type": "object" }, "PATPublic": { "properties": { "account_email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Account Email" }, "account_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Account Id" }, "agent_label": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Agent Label" }, "client_kind": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Client Kind" }, "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "expires_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Expires At" }, "id": { "title": "Id", "type": "string" }, "last_used_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Last Used At" }, "name": { "title": "Name", "type": "string" }, "prefix": { "title": "Prefix", "type": "string" }, "scopes": { "items": { "type": "string" }, "title": "Scopes", "type": "array" }, "tenant_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Tenant Id" } }, "required": [ "id", "name", "prefix", "scopes", "created_at" ], "title": "PATPublic", "type": "object" }, "PackCatalogEntry": { "properties": { "cost_class": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cost Class" }, "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "dependent_recipe_count": { "title": "Dependent Recipe Count", "type": "integer" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "display_name": { "title": "Display Name", "type": "string" }, "family": { "title": "Family", "type": "string" }, "freshness_class": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Freshness Class" }, "health_24h_invocations": { "title": "Health 24H Invocations", "type": "integer" }, "health_24h_success_pct": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Health 24H Success Pct" }, "id": { "format": "uuid", "title": "Id", "type": "string" }, "latest_version_number": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Latest Version Number" }, "latest_version_state": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Latest Version State" }, "owner": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Owner" }, "pin_drift_count": { "title": "Pin Drift Count", "type": "integer" }, "slug": { "title": "Slug", "type": "string" }, "updated_at": { "format": "date-time", "title": "Updated At", "type": "string" }, "version_count": { "title": "Version Count", "type": "integer" } }, "required": [ "id", "slug", "family", "display_name", "description", "owner", "latest_version_number", "latest_version_state", "version_count", "dependent_recipe_count", "pin_drift_count", "freshness_class", "cost_class", "health_24h_invocations", "health_24h_success_pct", "created_at", "updated_at" ], "title": "PackCatalogEntry", "type": "object" }, "PackCatalogResponse": { "properties": { "packs": { "items": { "$ref": "#/components/schemas/PackCatalogEntry" }, "title": "Packs", "type": "array" }, "total_pin_drift": { "title": "Total Pin Drift", "type": "integer" } }, "required": [ "packs", "total_pin_drift" ], "title": "PackCatalogResponse", "type": "object" }, "PackDependentModel": { "properties": { "pack_version_id": { "format": "uuid", "title": "Pack Version Id", "type": "string" }, "pack_version_number": { "title": "Pack Version Number", "type": "integer" }, "recipe_slug": { "title": "Recipe Slug", "type": "string" }, "recipe_state": { "title": "Recipe State", "type": "string" }, "recipe_version_id": { "format": "uuid", "title": "Recipe Version Id", "type": "string" }, "recipe_version_number": { "title": "Recipe Version Number", "type": "integer" } }, "required": [ "recipe_version_id", "recipe_slug", "recipe_version_number", "recipe_state", "pack_version_id", "pack_version_number" ], "title": "PackDependentModel", "type": "object" }, "PackDetailResponse": { "properties": { "blocked_by_archive": { "items": { "type": "string" }, "title": "Blocked By Archive", "type": "array" }, "dependents": { "items": { "$ref": "#/components/schemas/PackDependentModel" }, "title": "Dependents", "type": "array" }, "pack": { "$ref": "#/components/schemas/PackCatalogEntry" }, "pin_drift": { "items": { "$ref": "#/components/schemas/PackDependentModel" }, "title": "Pin Drift", "type": "array" }, "versions": { "items": { "$ref": "#/components/schemas/PackVersionModel" }, "title": "Versions", "type": "array" } }, "required": [ "pack", "versions", "dependents", "blocked_by_archive", "pin_drift" ], "title": "PackDetailResponse", "type": "object" }, "PackInvokeRequest": { "properties": { "inputs": { "additionalProperties": true, "title": "Inputs", "type": "object" } }, "title": "PackInvokeRequest", "type": "object" }, "PackInvokeResponse": { "properties": { "data": { "title": "Data" }, "freshness": { "additionalProperties": true, "title": "Freshness", "type": "object" }, "meta": { "additionalProperties": true, "title": "Meta", "type": "object" }, "source_refs": { "items": { "type": "string" }, "title": "Source Refs", "type": "array" } }, "required": [ "data", "source_refs", "freshness", "meta" ], "title": "PackInvokeResponse", "type": "object" }, "PackPreviewRequest": { "properties": { "bypass_cache": { "default": false, "title": "Bypass Cache", "type": "boolean" }, "inputs": { "additionalProperties": true, "title": "Inputs", "type": "object" }, "tenant_id": { "format": "uuid", "title": "Tenant Id", "type": "string" }, "version_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Version Id" } }, "required": [ "tenant_id" ], "title": "PackPreviewRequest", "type": "object" }, "PackPreviewResponse": { "properties": { "counts": { "additionalProperties": { "type": "integer" }, "title": "Counts", "type": "object" }, "data": { "title": "Data" }, "freshness": { "additionalProperties": true, "title": "Freshness", "type": "object" }, "meta": { "additionalProperties": true, "title": "Meta", "type": "object" }, "preview_principal_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Preview Principal Id" }, "source_refs": { "items": { "type": "string" }, "title": "Source Refs", "type": "array" } }, "required": [ "data", "source_refs", "freshness", "meta", "counts", "preview_principal_id" ], "title": "PackPreviewResponse", "type": "object" }, "PackToolSchema": { "properties": { "bounds": { "additionalProperties": true, "title": "Bounds", "type": "object" }, "cost_class": { "title": "Cost Class", "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "display_name": { "title": "Display Name", "type": "string" }, "family": { "title": "Family", "type": "string" }, "freshness_class": { "title": "Freshness Class", "type": "string" }, "inputs_schema": { "additionalProperties": true, "title": "Inputs Schema", "type": "object" }, "latency_class": { "title": "Latency Class", "type": "string" }, "principal_required": { "title": "Principal Required", "type": "boolean" }, "slug": { "title": "Slug", "type": "string" }, "version_number": { "title": "Version Number", "type": "integer" } }, "required": [ "slug", "display_name", "description", "family", "version_number", "inputs_schema", "principal_required", "bounds", "freshness_class", "cost_class", "latency_class" ], "title": "PackToolSchema", "type": "object" }, "PackToolsResponse": { "properties": { "tools": { "items": { "$ref": "#/components/schemas/PackToolSchema" }, "title": "Tools", "type": "array" } }, "required": [ "tools" ], "title": "PackToolsResponse", "type": "object" }, "PackTransitionRequest": { "properties": { "action": { "enum": [ "retire", "quarantine" ], "title": "Action", "type": "string" }, "reason": { "minLength": 1, "title": "Reason", "type": "string" } }, "required": [ "action", "reason" ], "title": "PackTransitionRequest", "type": "object" }, "PackTransitionResponse": { "properties": { "affected": { "additionalProperties": true, "title": "Affected", "type": "object" }, "pack_version_id": { "format": "uuid", "title": "Pack Version Id", "type": "string" }, "previous_state": { "title": "Previous State", "type": "string" }, "state": { "title": "State", "type": "string" } }, "required": [ "pack_version_id", "previous_state", "state", "affected" ], "title": "PackTransitionResponse", "type": "object" }, "PackVersionModel": { "properties": { "code_commit": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Code Commit" }, "code_ref": { "title": "Code Ref", "type": "string" }, "contract_diff": { "items": { "additionalProperties": true, "type": "object" }, "title": "Contract Diff", "type": "array" }, "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "id": { "format": "uuid", "title": "Id", "type": "string" }, "parent_version_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Parent Version Id" }, "registration": { "additionalProperties": true, "title": "Registration", "type": "object" }, "registration_hash": { "title": "Registration Hash", "type": "string" }, "state": { "title": "State", "type": "string" }, "version_number": { "title": "Version Number", "type": "integer" } }, "required": [ "id", "version_number", "parent_version_id", "state", "registration", "registration_hash", "code_ref", "code_commit", "contract_diff", "created_at" ], "title": "PackVersionModel", "type": "object" }, "PackageExpertiseRequest": { "description": "Findings from the research harness → a packaged, verified skill.", "properties": { "brief": { "maxLength": 2000, "minLength": 1, "title": "Brief", "type": "string" }, "claims": { "items": { "$ref": "#/components/schemas/ResearchClaimIn" }, "minItems": 1, "title": "Claims", "type": "array" }, "sources": { "items": { "$ref": "#/components/schemas/ResearchSourceIn" }, "title": "Sources", "type": "array" }, "visibility": { "default": "private", "enum": [ "private", "shared", "tenant", "global" ], "title": "Visibility", "type": "string" } }, "required": [ "brief", "claims" ], "title": "PackageExpertiseRequest", "type": "object" }, "PackageExpertiseResponse": { "properties": { "skill": { "additionalProperties": true, "title": "Skill", "type": "object" }, "unverified_count": { "title": "Unverified Count", "type": "integer" }, "verified_count": { "title": "Verified Count", "type": "integer" } }, "required": [ "skill", "verified_count", "unverified_count" ], "title": "PackageExpertiseResponse", "type": "object" }, "PageCreateRequest": { "description": "Request for POST /api/v1/notes/pages (create page).", "properties": { "content": { "default": "", "title": "Content", "type": "string" }, "email_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Anchor: source email this page was extracted from", "title": "Email Id" }, "note_type": { "default": "standalone_page", "title": "Note Type", "type": "string" }, "notebook_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Workspace/notebook container UUID", "title": "Notebook Id" }, "slug": { "anyOf": [ { "maxLength": 255, "minLength": 1, "type": "string" }, { "type": "null" } ], "description": "Optional stable slug for idempotent page creation", "title": "Slug" }, "tags": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "description": "Tag metadata for categorization", "title": "Tags" }, "title": { "maxLength": 500, "minLength": 1, "title": "Title", "type": "string" } }, "required": [ "title" ], "title": "PageCreateRequest", "type": "object" }, "PageListItem": { "description": "Summary item for standalone page listing.", "properties": { "id": { "title": "Id", "type": "string" }, "is_phantom": { "default": false, "description": "Deprecated (TIDY-6078): always false", "title": "Is Phantom", "type": "boolean" }, "note_type": { "default": "standalone_page", "title": "Note Type", "type": "string" }, "title": { "title": "Title", "type": "string" } }, "required": [ "id", "title" ], "title": "PageListItem", "type": "object" }, "PagesListResponse": { "description": "Response for GET /api/v1/notes/pages.", "properties": { "journals": { "items": { "$ref": "#/components/schemas/JournalListItem" }, "title": "Journals", "type": "array" }, "pages": { "items": { "$ref": "#/components/schemas/PageListItem" }, "title": "Pages", "type": "array" } }, "required": [ "journals", "pages" ], "title": "PagesListResponse", "type": "object" }, "ParentalConsentGrant": { "description": "Input model for granting parental consent.\n\nUsed in:\n - POST /api/v1/consents/{id}/grant", "example": { "consent_scope": { "data_collection": true, "email_processing": true, "event_extraction": true, "third_party_sharing": false } }, "properties": { "consent_scope": { "$ref": "#/components/schemas/ConsentScope", "description": "What is being consented to" } }, "title": "ParentalConsentGrant", "type": "object" }, "ParentalConsentResponse": { "description": "Complete parental consent object returned by API endpoints.\n\nUsed in:\n - GET /api/v1/consents (list)\n - GET /api/v1/consents/{id} (detail)\n - POST /api/v1/consents (created response, 201)", "properties": { "child_contact_id": { "description": "Child's contact ID in contacts table (UUID)", "title": "Child Contact Id", "type": "string" }, "child_date_of_birth": { "description": "Child's date of birth", "format": "date", "title": "Child Date Of Birth", "type": "string" }, "consent_ip_address": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "IP address when consent given", "title": "Consent Ip Address" }, "consent_scope": { "$ref": "#/components/schemas/ConsentScope", "description": "What was consented to" }, "consent_timestamp": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "description": "When consent was given", "title": "Consent Timestamp" }, "consent_user_agent": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "User agent when consent given", "title": "Consent User Agent" }, "consent_version": { "default": "1.0", "description": "Consent form version", "title": "Consent Version", "type": "string" }, "consenting_account_id": { "description": "Parent's account ID (UUID)", "title": "Consenting Account Id", "type": "string" }, "consenting_contact_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Parent's contact ID if exists (UUID)", "title": "Consenting Contact Id" }, "created_at": { "description": "ISO 8601 creation timestamp", "format": "date-time", "title": "Created At", "type": "string" }, "expires_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "description": "When consent expires (annual renewal)", "title": "Expires At" }, "id": { "description": "Unique consent identifier (UUID)", "title": "Id", "type": "string" }, "renewal_reminder_sent_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "description": "When renewal reminder was sent", "title": "Renewal Reminder Sent At" }, "revocation_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Why consent was revoked", "title": "Revocation Reason" }, "revoked_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "description": "When consent was revoked", "title": "Revoked At" }, "status": { "$ref": "#/components/schemas/ConsentStatus", "default": "pending", "description": "Consent status" }, "tenant_id": { "description": "Associated tenant identifier (UUID)", "title": "Tenant Id", "type": "string" }, "updated_at": { "description": "ISO 8601 last modification timestamp", "format": "date-time", "title": "Updated At", "type": "string" } }, "required": [ "id", "tenant_id", "child_contact_id", "child_date_of_birth", "consenting_account_id", "created_at", "updated_at" ], "title": "ParentalConsentResponse", "type": "object" }, "ParentalConsentRevoke": { "description": "Input model for revoking parental consent.\n\nUsed in:\n - POST /api/v1/consents/{id}/revoke", "example": { "reason": "Child has turned 13 years old" }, "properties": { "reason": { "description": "Reason for revoking consent", "maxLength": 500, "minLength": 5, "title": "Reason", "type": "string" } }, "required": [ "reason" ], "title": "ParentalConsentRevoke", "type": "object" }, "ParsedEmail": { "description": "Parsed email content for viewing (legacy format).", "properties": { "attachments": { "items": { "$ref": "#/components/schemas/AttachmentLegacy" }, "title": "Attachments", "type": "array" }, "cc": { "items": { "$ref": "#/components/schemas/EmailAddressLegacy" }, "title": "Cc", "type": "array" }, "date": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Date" }, "from": { "anyOf": [ { "$ref": "#/components/schemas/EmailAddressLegacy" }, { "type": "null" } ], "default": null }, "headers": { "additionalProperties": true, "title": "Headers", "type": "object" }, "html": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Html" }, "html_sanitized": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Html Sanitized" }, "subject": { "title": "Subject", "type": "string" }, "text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Text" }, "to": { "items": { "$ref": "#/components/schemas/EmailAddressLegacy" }, "title": "To", "type": "array" } }, "required": [ "subject" ], "title": "ParsedEmail", "type": "object" }, "PatchInstanceRequest": { "properties": { "config": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Config" }, "screen_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Screen Type" } }, "title": "PatchInstanceRequest", "type": "object" }, "PatchKeywordAlertRequest": { "description": "Request body for ``PATCH /api/v1/chat/keyword-alerts/{alert_id}``.\n\nBoth fields optional — a partial update. At least one must be present\n(enforced in the handler) so an empty PATCH is rejected.", "properties": { "enabled": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Enabled" }, "keyword": { "anyOf": [ { "maxLength": 100, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Keyword" } }, "title": "PatchKeywordAlertRequest", "type": "object" }, "PatchUserRequest": { "properties": { "is_admin": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is Admin" }, "suspended": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Suspended" } }, "title": "PatchUserRequest", "type": "object" }, "PayloadMappingCreate": { "properties": { "enabled": { "default": true, "title": "Enabled", "type": "boolean" }, "facet_slug": { "maxLength": 80, "minLength": 1, "title": "Facet Slug", "type": "string" }, "mapping": { "items": { "$ref": "#/components/schemas/MappingRule" }, "minItems": 1, "title": "Mapping", "type": "array" }, "match_field": { "maxLength": 120, "minLength": 1, "title": "Match Field", "type": "string" }, "name": { "maxLength": 120, "minLength": 1, "title": "Name", "type": "string" }, "target_table": { "default": "contacts", "enum": [ "contacts", "records" ], "title": "Target Table", "type": "string" } }, "required": [ "name", "facet_slug", "match_field", "mapping" ], "title": "PayloadMappingCreate", "type": "object" }, "PayloadMappingResponse": { "properties": { "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "enabled": { "title": "Enabled", "type": "boolean" }, "event_type_id": { "title": "Event Type Id", "type": "string" }, "facet_slug": { "title": "Facet Slug", "type": "string" }, "id": { "title": "Id", "type": "string" }, "mapping": { "items": { "$ref": "#/components/schemas/MappingRule" }, "title": "Mapping", "type": "array" }, "match_field": { "title": "Match Field", "type": "string" }, "name": { "title": "Name", "type": "string" }, "target_table": { "enum": [ "contacts", "records" ], "title": "Target Table", "type": "string" }, "updated_at": { "format": "date-time", "title": "Updated At", "type": "string" } }, "required": [ "id", "event_type_id", "name", "target_table", "facet_slug", "match_field", "mapping", "enabled", "created_at", "updated_at" ], "title": "PayloadMappingResponse", "type": "object" }, "PayloadMappingRunResponse": { "description": "One row of the event's capture run ledger (story D4).", "properties": { "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Error" }, "event_type_id": { "title": "Event Type Id", "type": "string" }, "id": { "title": "Id", "type": "string" }, "mapping_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Mapping Id" }, "payload_excerpt": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "title": "Payload Excerpt" }, "status": { "enum": [ "ok", "failed" ], "title": "Status", "type": "string" } }, "required": [ "id", "event_type_id", "status", "created_at" ], "title": "PayloadMappingRunResponse", "type": "object" }, "PayloadMappingUpdate": { "properties": { "enabled": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Enabled" }, "facet_slug": { "anyOf": [ { "maxLength": 80, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Facet Slug" }, "mapping": { "anyOf": [ { "items": { "$ref": "#/components/schemas/MappingRule" }, "type": "array" }, { "type": "null" } ], "title": "Mapping" }, "match_field": { "anyOf": [ { "maxLength": 120, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Match Field" }, "name": { "anyOf": [ { "maxLength": 120, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Name" }, "target_table": { "anyOf": [ { "enum": [ "contacts", "records" ], "type": "string" }, { "type": "null" } ], "title": "Target Table" } }, "title": "PayloadMappingUpdate", "type": "object" }, "PaymentMethod": { "properties": { "brand": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Brand" }, "exp_month": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Exp Month" }, "exp_year": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Exp Year" }, "last4": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last4" } }, "title": "PaymentMethod", "type": "object" }, "PdfMargins": { "properties": { "bottom": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Bottom" }, "left": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Left" }, "right": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Right" }, "top": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Top" } }, "title": "PdfMargins", "type": "object" }, "PdfOptions": { "properties": { "customFooterLeft": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Customfooterleft" }, "customFooterRight": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Customfooterright" }, "customHeaderLeft": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Customheaderleft" }, "customHeaderRight": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Customheaderright" }, "includeHeaderFooter": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Includeheaderfooter" }, "margins": { "anyOf": [ { "$ref": "#/components/schemas/PdfMargins" }, { "type": "null" } ] }, "orientation": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Orientation" }, "pageSize": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Pagesize" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Title" } }, "title": "PdfOptions", "type": "object" }, "PendingCreateApplyRequest": { "description": "Create the blocked event, at one of its own resolution proposals.", "properties": { "expected_version": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Expected Version" }, "proposal_id": { "description": "A proposal_id from this card's resolution_proposals. The times come from the persisted proposal, never from the caller.", "title": "Proposal Id", "type": "string" } }, "required": [ "proposal_id" ], "title": "PendingCreateApplyRequest", "type": "object" }, "PendingCreateApplyResponse": { "properties": { "already_resolved": { "default": false, "title": "Already Resolved", "type": "boolean" }, "applied": { "title": "Applied", "type": "boolean" }, "end_time": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "End Time" }, "event_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Event Id" }, "pending_create_id": { "title": "Pending Create Id", "type": "string" }, "start_time": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Start Time" }, "version": { "title": "Version", "type": "integer" }, "warnings": { "items": { "type": "string" }, "title": "Warnings", "type": "array" } }, "required": [ "pending_create_id", "applied", "version" ], "title": "PendingCreateApplyResponse", "type": "object" }, "PendingEvent": { "description": "Complete pending event object (response).", "properties": { "all_day": { "title": "All Day", "type": "boolean" }, "approved_event_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Approved Event Id" }, "confidence": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Confidence" }, "conflict_with": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Conflict With" }, "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "end_time": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "End Time" }, "extraction_metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Extraction Metadata" }, "id": { "title": "Id", "type": "string" }, "location": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Location" }, "review_notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Review Notes" }, "review_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Review Reason" }, "review_status": { "description": "Review status", "examples": [ "pending", "approved", "rejected", "merged" ], "title": "Review Status", "type": "string" }, "reviewed_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Reviewed At" }, "reviewed_by": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Reviewed By" }, "source_email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Source Email" }, "source_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Source Id" }, "source_type": { "title": "Source Type", "type": "string" }, "start_time": { "format": "date-time", "title": "Start Time", "type": "string" }, "tenant_id": { "title": "Tenant Id", "type": "string" }, "timezone": { "title": "Timezone", "type": "string" }, "title": { "title": "Title", "type": "string" }, "type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Type" } }, "required": [ "id", "tenant_id", "title", "description", "start_time", "end_time", "all_day", "timezone", "location", "type", "source_type", "source_id", "source_email", "confidence", "review_status", "review_reason", "conflict_with", "reviewed_by", "reviewed_at", "review_notes", "approved_event_id", "extraction_metadata", "created_at" ], "title": "PendingEvent", "type": "object" }, "PendingEventCreate": { "description": "Input model for creating pending events.", "example": { "confidence": 0.58, "description": "Possible school play event", "end_time": "2024-11-25T20:00:00-05:00", "extraction_metadata": { "ambiguities": [ "date_unclear", "location_unclear" ], "extraction_method": "vision_llm", "llm_model": "claude-sonnet-4" }, "location": "School Auditorium?", "review_reason": "Low confidence: 0.58 - Ambiguous date and location", "source_email": "school@district.edu", "source_type": "email", "start_time": "2024-11-25T18:00:00-05:00", "title": "School Play?", "type": "school" }, "properties": { "all_day": { "default": false, "title": "All Day", "type": "boolean" }, "confidence": { "anyOf": [ { "maximum": 1.0, "minimum": 0.0, "type": "number" }, { "type": "null" } ], "title": "Confidence" }, "conflict_with": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Conflicting event UUID", "title": "Conflict With" }, "description": { "anyOf": [ { "maxLength": 5000, "type": "string" }, { "type": "null" } ], "title": "Description" }, "end_time": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "End Time" }, "extraction_metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "LLM extraction details", "title": "Extraction Metadata" }, "location": { "anyOf": [ { "maxLength": 500, "type": "string" }, { "type": "null" } ], "title": "Location" }, "review_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Why this event needs review", "examples": [ "Low confidence: 0.58", "Conflict detected" ], "title": "Review Reason" }, "source_email": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "title": "Source Email" }, "source_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Source record UUID (email_canonical.id, etc.)", "title": "Source Id" }, "source_type": { "description": "Source type", "examples": [ "email", "file_upload", "manual" ], "title": "Source Type", "type": "string" }, "start_time": { "format": "date-time", "title": "Start Time", "type": "string" }, "timezone": { "default": "UTC", "title": "Timezone", "type": "string" }, "title": { "maxLength": 500, "minLength": 1, "title": "Title", "type": "string" }, "type": { "anyOf": [ { "maxLength": 50, "type": "string" }, { "type": "null" } ], "title": "Type" } }, "required": [ "title", "start_time", "source_type" ], "title": "PendingEventCreate", "type": "object" }, "PendingEventUpdate": { "description": "Input model for updating pending events before approval.", "properties": { "all_day": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "All Day" }, "description": { "anyOf": [ { "maxLength": 5000, "type": "string" }, { "type": "null" } ], "title": "Description" }, "end_time": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "End Time" }, "location": { "anyOf": [ { "maxLength": 500, "type": "string" }, { "type": "null" } ], "title": "Location" }, "start_time": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Start Time" }, "timezone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Timezone" }, "title": { "anyOf": [ { "maxLength": 500, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Title" }, "type": { "anyOf": [ { "maxLength": 50, "type": "string" }, { "type": "null" } ], "title": "Type" } }, "title": "PendingEventUpdate", "type": "object" }, "PendingInvite": { "description": "A calendar invite awaiting response.", "properties": { "created_at": { "description": "When the invite was received", "format": "date-time", "title": "Created At", "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Description" }, "dtend": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "description": "Event end time", "title": "Dtend" }, "dtstart": { "description": "Event start time", "format": "date-time", "title": "Dtstart", "type": "string" }, "event_id": { "description": "Calendar event UUID", "title": "Event Id", "type": "string" }, "ics_method": { "description": "ICS METHOD: REQUEST, CANCEL, etc.", "title": "Ics Method", "type": "string" }, "location": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Location" }, "organizer_email": { "description": "Who sent the invite", "title": "Organizer Email", "type": "string" }, "organizer_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Organizer Name" }, "our_partstat": { "default": "NEEDS-ACTION", "description": "Our current participation status", "enum": [ "NEEDS-ACTION", "ACCEPTED", "DECLINED", "TENTATIVE" ], "title": "Our Partstat", "type": "string" }, "response_sent_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "description": "When we last responded (if any)", "title": "Response Sent At" }, "summary": { "description": "Event title", "title": "Summary", "type": "string" }, "tenant_id": { "description": "Tenant UUID", "title": "Tenant Id", "type": "string" }, "uid": { "description": "ICS UID", "title": "Uid", "type": "string" } }, "required": [ "event_id", "tenant_id", "uid", "summary", "dtstart", "organizer_email", "ics_method", "created_at" ], "title": "PendingInvite", "type": "object" }, "PendingSynthesisCard": { "description": "A card pending synthesis.", "properties": { "cardId": { "description": "Card ID", "title": "Cardid", "type": "string" }, "cardType": { "description": "Card type (note or journal)", "title": "Cardtype", "type": "string" }, "createdAt": { "description": "Card creation timestamp", "title": "Createdat", "type": "string" }, "pendingSectionCount": { "description": "Number of sections pending synthesis", "title": "Pendingsectioncount", "type": "integer" }, "title": { "description": "Card title", "title": "Title", "type": "string" } }, "required": [ "cardId", "cardType", "title", "pendingSectionCount", "createdAt" ], "title": "PendingSynthesisCard", "type": "object" }, "PendingSynthesisResponse": { "description": "Response for pending synthesis query.", "properties": { "cards": { "description": "Cards pending synthesis", "items": { "$ref": "#/components/schemas/PendingSynthesisCard" }, "title": "Cards", "type": "array" }, "totalCount": { "description": "Total number of cards pending synthesis", "title": "Totalcount", "type": "integer" } }, "required": [ "cards", "totalCount" ], "title": "PendingSynthesisResponse", "type": "object" }, "PeriodComparison": { "properties": { "prev_received": { "title": "Prev Received", "type": "integer" }, "prev_sent": { "title": "Prev Sent", "type": "integer" }, "received_change_pct": { "title": "Received Change Pct", "type": "number" }, "sent_change_pct": { "title": "Sent Change Pct", "type": "number" } }, "required": [ "prev_received", "prev_sent", "received_change_pct", "sent_change_pct" ], "title": "PeriodComparison", "type": "object" }, "PermissionCreateRequest": { "properties": { "expires_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Expires At" }, "scope": { "default": [ "search" ], "items": { "type": "string" }, "title": "Scope", "type": "array" }, "target_account_id": { "format": "uuid", "title": "Target Account Id", "type": "string" } }, "required": [ "target_account_id" ], "title": "PermissionCreateRequest", "type": "object" }, "PermissionResponse": { "properties": { "approved_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Approved At" }, "approved_by": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "default": null, "title": "Approved By" }, "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "expires_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Expires At" }, "id": { "format": "uuid", "title": "Id", "type": "string" }, "person_id": { "format": "uuid", "title": "Person Id", "type": "string" }, "requested_at": { "format": "date-time", "title": "Requested At", "type": "string" }, "revoked_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Revoked At" }, "revoked_by": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "default": null, "title": "Revoked By" }, "scope": { "items": { "type": "string" }, "title": "Scope", "type": "array" }, "source_account_id": { "format": "uuid", "title": "Source Account Id", "type": "string" }, "source_account_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Source Account Name" }, "status": { "title": "Status", "type": "string" }, "target_account_id": { "format": "uuid", "title": "Target Account Id", "type": "string" }, "target_account_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Target Account Name" }, "updated_at": { "format": "date-time", "title": "Updated At", "type": "string" } }, "required": [ "id", "person_id", "source_account_id", "target_account_id", "status", "scope", "requested_at", "created_at", "updated_at" ], "title": "PermissionResponse", "type": "object" }, "PersonResult": { "properties": { "account_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Account Id" }, "display_name": { "title": "Display Name", "type": "string" }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Email" }, "matrix_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Matrix Id" }, "score": { "title": "Score", "type": "number" } }, "required": [ "account_id", "matrix_id", "display_name", "email", "score" ], "title": "PersonResult", "type": "object" }, "PhantomCreateRequest": { "description": "Request for POST /api/v1/notes/phantom.", "properties": { "title": { "maxLength": 500, "minLength": 1, "title": "Title", "type": "string" } }, "required": [ "title" ], "title": "PhantomCreateRequest", "type": "object" }, "PhoneNumberCreate": { "description": "Request model for creating a phone number.", "properties": { "is_primary": { "default": false, "description": "Set as primary phone number", "title": "Is Primary", "type": "boolean" }, "label": { "default": "personal", "description": "Phone label (personal/work/other)", "title": "Label", "type": "string" }, "phone_number": { "description": "Phone number in E.164 format", "title": "Phone Number", "type": "string" } }, "required": [ "phone_number" ], "title": "PhoneNumberCreate", "type": "object" }, "PhoneNumberListResponse": { "description": "Response model for listing account phone numbers.", "properties": { "phone_numbers": { "items": { "$ref": "#/components/schemas/PhoneNumberResponse" }, "title": "Phone Numbers", "type": "array" } }, "title": "PhoneNumberListResponse", "type": "object" }, "PhoneNumberResponse": { "description": "Response model for a single phone number.", "properties": { "account_id": { "description": "Owner account ID", "format": "uuid", "title": "Account Id", "type": "string" }, "created_at": { "description": "Creation timestamp", "format": "date-time", "title": "Created At", "type": "string" }, "id": { "description": "Phone number ID", "format": "uuid", "title": "Id", "type": "string" }, "is_primary": { "description": "Whether this is the primary phone", "title": "Is Primary", "type": "boolean" }, "is_verified": { "description": "Whether phone is verified", "title": "Is Verified", "type": "boolean" }, "label": { "description": "Phone label", "title": "Label", "type": "string" }, "phone_number": { "description": "Phone number in E.164 format", "title": "Phone Number", "type": "string" }, "updated_at": { "description": "Last update timestamp", "format": "date-time", "title": "Updated At", "type": "string" }, "verified_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "description": "Verification timestamp", "title": "Verified At" } }, "required": [ "id", "account_id", "phone_number", "label", "is_primary", "is_verified", "created_at", "updated_at" ], "title": "PhoneNumberResponse", "type": "object" }, "PhoneNumberUpdate": { "description": "Request model for updating a phone number.", "properties": { "is_primary": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Set or unset primary status", "title": "Is Primary" }, "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Phone label (personal/work/other)", "title": "Label" } }, "title": "PhoneNumberUpdate", "type": "object" }, "PhotoCaptionResponse": { "description": "Response for a caption edit.", "properties": { "caption": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Caption" }, "id": { "format": "uuid", "title": "Id", "type": "string" }, "updated_at": { "format": "date-time", "title": "Updated At", "type": "string" } }, "required": [ "id", "updated_at" ], "title": "PhotoCaptionResponse", "type": "object" }, "PhotoCaptionUpdateRequest": { "description": "Request body for a caption edit (``null`` clears the caption).", "properties": { "caption": { "anyOf": [ { "maxLength": 2000, "type": "string" }, { "type": "null" } ], "description": "New caption text; null clears the caption.", "title": "Caption" } }, "required": [ "caption" ], "title": "PhotoCaptionUpdateRequest", "type": "object" }, "PhotoDeleteResponse": { "description": "Response for a soft-deleted photo.", "properties": { "deleted_at": { "format": "date-time", "title": "Deleted At", "type": "string" }, "faces_soft_deleted": { "title": "Faces Soft Deleted", "type": "integer" }, "id": { "format": "uuid", "title": "Id", "type": "string" } }, "required": [ "id", "deleted_at", "faces_soft_deleted" ], "title": "PhotoDeleteResponse", "type": "object" }, "PhotoFromFaceRequest": { "properties": { "face_id": { "format": "uuid", "title": "Face Id", "type": "string" } }, "required": [ "face_id" ], "title": "PhotoFromFaceRequest", "type": "object" }, "PhotoFromFaceResponse": { "properties": { "contact_id": { "format": "uuid", "title": "Contact Id", "type": "string" }, "contact_photo_id": { "format": "uuid", "title": "Contact Photo Id", "type": "string" }, "created_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Created At" }, "photo_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Photo Url" } }, "required": [ "contact_id", "contact_photo_id" ], "title": "PhotoFromFaceResponse", "type": "object" }, "PhotoIngestResponse": { "description": "Response for a successful photo ingest.", "properties": { "height": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Height" }, "id": { "format": "uuid", "title": "Id", "type": "string" }, "location_lat": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "title": "Location Lat" }, "location_lng": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "title": "Location Lng" }, "processing_status": { "title": "Processing Status", "type": "string" }, "storage_path": { "title": "Storage Path", "type": "string" }, "taken_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Taken At" }, "thumbnail_path": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Thumbnail Path" }, "width": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Width" } }, "required": [ "id", "storage_path", "processing_status" ], "title": "PhotoIngestResponse", "type": "object" }, "PinRequest": { "properties": { "event_id": { "minLength": 1, "title": "Event Id", "type": "string" }, "message_preview": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Message Preview" }, "note": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Note" }, "sender_matrix_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Sender Matrix Id" } }, "required": [ "event_id" ], "title": "PinRequest", "type": "object" }, "PinResponse": { "properties": { "event_id": { "title": "Event Id", "type": "string" }, "id": { "format": "uuid", "title": "Id", "type": "string" }, "message_preview": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Message Preview" }, "note": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Note" }, "pinned_at": { "format": "date-time", "title": "Pinned At", "type": "string" }, "pinned_by_account_id": { "format": "uuid", "title": "Pinned By Account Id", "type": "string" }, "room_id": { "title": "Room Id", "type": "string" }, "sender_matrix_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Sender Matrix Id" }, "sort_order": { "title": "Sort Order", "type": "integer" }, "tenant_id": { "format": "uuid", "title": "Tenant Id", "type": "string" } }, "required": [ "id", "tenant_id", "room_id", "event_id", "message_preview", "sender_matrix_id", "pinned_by_account_id", "pinned_at", "sort_order", "note" ], "title": "PinResponse", "type": "object" }, "PinScmObjectRequest": { "description": "Body for pinning a provider URL into the index (D9).", "properties": { "url": { "maxLength": 2000, "minLength": 1, "title": "Url", "type": "string" } }, "required": [ "url" ], "title": "PinScmObjectRequest", "type": "object" }, "PipelineAnalysisResponse": { "description": "Response model for pipeline analysis.", "properties": { "current_stage": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Current Stage" }, "debug_links": { "anyOf": [ { "$ref": "#/components/schemas/DebugLinksResponse" }, { "type": "null" } ] }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error" }, "error_categories": { "default": [], "items": { "$ref": "#/components/schemas/ErrorCategoryResponse" }, "title": "Error Categories", "type": "array" }, "errors_found": { "default": [], "items": { "additionalProperties": true, "type": "object" }, "title": "Errors Found", "type": "array" }, "failure_states": { "default": [], "items": { "additionalProperties": true, "type": "object" }, "title": "Failure States", "type": "array" }, "fix_actions": { "default": [], "items": { "$ref": "#/components/schemas/FixActionResponse" }, "title": "Fix Actions", "type": "array" }, "ingestion_job_status": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Ingestion Job Status" }, "overall_status": { "title": "Overall Status", "type": "string" }, "plan_analysis": { "additionalProperties": true, "default": {}, "title": "Plan Analysis", "type": "object" }, "queue_health": { "additionalProperties": true, "default": {}, "title": "Queue Health", "type": "object" }, "recommended_actions": { "default": [], "items": { "type": "string" }, "title": "Recommended Actions", "type": "array" }, "root_cause": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Root Cause" }, "root_cause_details": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Root Cause Details" }, "service_health": { "additionalProperties": true, "default": {}, "title": "Service Health", "type": "object" }, "source_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Source Type" }, "stage_analysis": { "additionalProperties": true, "default": {}, "title": "Stage Analysis", "type": "object" }, "stuck_duration_minutes": { "title": "Stuck Duration Minutes", "type": "integer" }, "success": { "title": "Success", "type": "boolean" }, "summary": { "title": "Summary", "type": "string" }, "trace_id": { "title": "Trace Id", "type": "string" } }, "required": [ "success", "trace_id", "summary", "overall_status", "stuck_duration_minutes" ], "title": "PipelineAnalysisResponse", "type": "object" }, "PipelineCanonicalTextResponse": { "properties": { "id": { "title": "Id", "type": "string" }, "markdown": { "title": "Markdown", "type": "string" }, "metadata": { "additionalProperties": true, "title": "Metadata", "type": "object" } }, "required": [ "id", "markdown", "metadata" ], "title": "PipelineCanonicalTextResponse", "type": "object" }, "PipelineCostResponse": { "properties": { "month": { "format": "date", "title": "Month", "type": "string" }, "tenants": { "items": { "$ref": "#/components/schemas/PipelineCostRow" }, "title": "Tenants", "type": "array" } }, "required": [ "month", "tenants" ], "title": "PipelineCostResponse", "type": "object" }, "PipelineCostRow": { "properties": { "batched_calls": { "default": 0, "title": "Batched Calls", "type": "integer" }, "batched_cost_usd": { "default": 0.0, "title": "Batched Cost Usd", "type": "number" }, "cached_token_share": { "default": 0.0, "title": "Cached Token Share", "type": "number" }, "cost_per_email_usd": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "title": "Cost Per Email Usd" }, "emails_processed": { "default": 0, "title": "Emails Processed", "type": "integer" }, "llm_calls": { "default": 0, "title": "Llm Calls", "type": "integer" }, "margin_consumption_pct": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "title": "Margin Consumption Pct" }, "margin_status": { "default": "green", "title": "Margin Status", "type": "string" }, "month": { "format": "date", "title": "Month", "type": "string" }, "pipeline_cost_usd": { "default": 0.0, "title": "Pipeline Cost Usd", "type": "number" }, "seats": { "default": 0, "title": "Seats", "type": "integer" }, "sync_calls": { "default": 0, "title": "Sync Calls", "type": "integer" }, "sync_cost_usd": { "default": 0.0, "title": "Sync Cost Usd", "type": "number" }, "tenant_id": { "title": "Tenant Id", "type": "string" }, "tier_revenue_usd": { "default": 0.0, "title": "Tier Revenue Usd", "type": "number" } }, "required": [ "tenant_id", "month" ], "title": "PipelineCostRow", "type": "object" }, "PipelineEntitlementResponse": { "properties": { "cycle_start": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Cycle Start" }, "emails_allotted": { "default": 0, "title": "Emails Allotted", "type": "integer" }, "emails_processed": { "default": 0, "title": "Emails Processed", "type": "integer" }, "reset_date": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Reset Date" }, "stage": { "default": "normal", "title": "Stage", "type": "string" }, "stage_changed_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Stage Changed At" }, "tenant_id": { "title": "Tenant Id", "type": "string" }, "utilization": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "title": "Utilization" } }, "required": [ "tenant_id" ], "title": "PipelineEntitlementResponse", "type": "object" }, "PipelineInFlight": { "properties": { "consumer": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Consumer" }, "episode": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "title": "Episode" }, "job_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Job Id" }, "lane": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Lane" }, "stage": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Stage" }, "started_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Started At" } }, "title": "PipelineInFlight", "type": "object" }, "PipelineLaneDepths": { "properties": { "background": { "default": 0, "title": "Background", "type": "integer" }, "dead": { "default": 0, "title": "Dead", "type": "integer" }, "priority": { "default": 0, "title": "Priority", "type": "integer" } }, "title": "PipelineLaneDepths", "type": "object" }, "PipelinePriorityDetail": { "properties": { "in_flight_ref": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "In Flight Ref" }, "last_results": { "default": [], "items": { "$ref": "#/components/schemas/PipelinePriorityResult" }, "title": "Last Results", "type": "array" }, "queued": { "default": 0, "title": "Queued", "type": "integer" } }, "title": "PipelinePriorityDetail", "type": "object" }, "PipelinePriorityResult": { "properties": { "episode": { "title": "Episode", "type": "string" }, "latency_s": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "title": "Latency S" }, "status": { "title": "Status", "type": "string" } }, "required": [ "status", "episode" ], "title": "PipelinePriorityResult", "type": "object" }, "PipelineQueued": { "description": "Stage 1 — episodes ingested into the pipeline but not yet transcribed.\n\nCurrent backlog gauges (Redis lane depths), NOT lifetime counts: the\npipeline keeps no cumulative enqueue ledger.", "properties": { "background": { "default": 0, "title": "Background", "type": "integer" }, "dead": { "default": 0, "title": "Dead", "type": "integer" }, "in_flight_stage": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "In Flight Stage" }, "priority": { "default": 0, "title": "Priority", "type": "integer" } }, "title": "PipelineQueued", "type": "object" }, "PipelineReferenceContentResponse": { "properties": { "markdown": { "title": "Markdown", "type": "string" }, "metadata": { "additionalProperties": true, "title": "Metadata", "type": "object" } }, "required": [ "markdown", "metadata" ], "title": "PipelineReferenceContentResponse", "type": "object" }, "PipelineRunDetailResponse": { "properties": { "run": { "additionalProperties": true, "title": "Run", "type": "object" } }, "required": [ "run" ], "title": "PipelineRunDetailResponse", "type": "object" }, "PipelineRunInfo": { "properties": { "completed_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Completed At" }, "doc_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Doc Name" }, "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Id" }, "overall_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Overall Status" }, "source_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Source Url" }, "stages": { "anyOf": [ {}, { "type": "null" } ], "default": null, "title": "Stages" }, "started_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Started At" }, "tenant_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Tenant Id" }, "trace_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Trace Id" } }, "title": "PipelineRunInfo", "type": "object" }, "PipelineRunsListResponse": { "properties": { "runs": { "items": { "additionalProperties": true, "type": "object" }, "title": "Runs", "type": "array" } }, "required": [ "runs" ], "title": "PipelineRunsListResponse", "type": "object" }, "PipelineSnapshot": { "properties": { "current_stage": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Current Stage" }, "overall_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Overall Status" }, "triage_result": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Triage Result" } }, "title": "PipelineSnapshot", "type": "object" }, "PipelineStatusResponse": { "description": "Typed passthrough of the pipeline's ``/status``, plus the surfacing flag.\n\nOn an outage ONLY ``pipeline_reachable`` (False) and ``error`` are set; the\nrest stay at their empty defaults so the panel renders an outage banner.", "properties": { "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Error" }, "in_flight": { "anyOf": [ { "$ref": "#/components/schemas/PipelineInFlight" }, { "type": "null" } ], "default": null }, "lanes": { "$ref": "#/components/schemas/PipelineLaneDepths", "default": { "background": 0, "dead": 0, "priority": 0 } }, "last_completions": { "default": [], "items": { "additionalProperties": true, "type": "object" }, "title": "Last Completions", "type": "array" }, "paused": { "default": false, "title": "Paused", "type": "boolean" }, "pipeline_reachable": { "title": "Pipeline Reachable", "type": "boolean" }, "priority": { "$ref": "#/components/schemas/PipelinePriorityDetail", "default": { "in_flight_ref": null, "last_results": [], "queued": 0 } }, "today": { "additionalProperties": true, "default": {}, "title": "Today", "type": "object" }, "workers": { "default": [], "items": { "$ref": "#/components/schemas/PipelineWorker" }, "title": "Workers", "type": "array" }, "writeback": { "additionalProperties": true, "default": {}, "title": "Writeback", "type": "object" } }, "required": [ "pipeline_reachable" ], "title": "PipelineStatusResponse", "type": "object" }, "PipelineTranscribed": { "description": "Stage 2 — transcription completions in the DAG corpus manifest.", "properties": { "last_completed_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Last Completed At" }, "today": { "default": 0, "title": "Today", "type": "integer" }, "total": { "default": 0, "title": "Total", "type": "integer" } }, "title": "PipelineTranscribed", "type": "object" }, "PipelineWorker": { "description": "One pipeline machine's liveness + current work (heartbeat-derived).\n\n``last_beat=\"\"`` means a crashed machine still holding PEL entries — listed\nso stuck in-flight work is never invisible.", "properties": { "consumer": { "title": "Consumer", "type": "string" }, "in_flight": { "anyOf": [ { "$ref": "#/components/schemas/PipelineInFlight" }, { "type": "null" } ], "default": null }, "last_beat": { "default": "", "title": "Last Beat", "type": "string" }, "pending": { "additionalProperties": { "type": "integer" }, "default": {}, "title": "Pending", "type": "object" }, "started_at": { "default": "", "title": "Started At", "type": "string" } }, "required": [ "consumer" ], "title": "PipelineWorker", "type": "object" }, "PipelineWorkersHealth": { "description": "Worker-fleet liveness from the pipeline's heartbeat keys. A crashed\nmachine still holding PEL entries counts in ``total`` but not ``beating``\n(its ``last_beat`` is empty) so stuck work stays visible.", "properties": { "beating": { "default": 0, "title": "Beating", "type": "integer" }, "total": { "default": 0, "title": "Total", "type": "integer" } }, "title": "PipelineWorkersHealth", "type": "object" }, "PlanDimensionResponse": { "description": "One registry row, for the operator surfaces that render every dimension.", "properties": { "column": { "description": "plan_tiers column and override dimension", "title": "Column", "type": "string" }, "enforces": { "title": "Enforces", "type": "string" }, "key": { "description": "effective_entitlements() features/allotments key", "title": "Key", "type": "string" }, "kind": { "enum": [ "feature", "limit" ], "title": "Kind", "type": "string" }, "label": { "title": "Label", "type": "string" }, "minimum": { "title": "Minimum", "type": "integer" }, "nullable": { "title": "Nullable", "type": "boolean" }, "unit": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Unit" }, "unlimited": { "enum": [ "none", "null", "negative_one" ], "title": "Unlimited", "type": "string" } }, "required": [ "column", "key", "kind", "label", "unlimited", "enforces", "nullable", "minimum" ], "title": "PlanDimensionResponse", "type": "object" }, "PlanResponse": { "properties": { "id": { "title": "Id", "type": "string" }, "status": { "title": "Status", "type": "string" }, "tasks": { "items": { "$ref": "#/components/schemas/AgentTaskResponse" }, "title": "Tasks", "type": "array" }, "title": { "title": "Title", "type": "string" } }, "required": [ "id", "title", "status", "tasks" ], "title": "PlanResponse", "type": "object" }, "PlanSeatItem": { "description": "The workspace's own seat: always there, at the plan's tier.", "properties": { "holder_account_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Holder Account Id" }, "tier": { "title": "Tier", "type": "string" } }, "required": [ "tier" ], "title": "PlanSeatItem", "type": "object" }, "PlanSelectionRequest": { "description": "Request model for plan selection. Verified against Stripe Checkout session (TIDY-7079).", "properties": { "plan": { "description": "Plan tier id: 'core', 'plus', 'max'", "pattern": "^(core|plus|max)$", "title": "Plan", "type": "string" }, "stripe_session_id": { "description": "Stripe Checkout Session ID to verify (cs_test_... or cs_live_...)", "minLength": 1, "title": "Stripe Session Id", "type": "string" } }, "required": [ "plan", "stripe_session_id" ], "title": "PlanSelectionRequest", "type": "object" }, "PlanSelectionResponse": { "description": "Response model for plan selection after Stripe verification (TIDY-7079).", "properties": { "next_step": { "description": "Next step after plan (team or family)", "title": "Next Step", "type": "string" }, "next_url": { "description": "URL FE should navigate to", "title": "Next Url", "type": "string" }, "plan_tier": { "description": "Persisted plan_tier", "title": "Plan Tier", "type": "string" }, "success": { "description": "Always true on success", "title": "Success", "type": "boolean" }, "trial_days": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Starter no-card trial length in days when the Starter path is used", "title": "Trial Days" } }, "required": [ "success", "plan_tier", "next_step", "next_url" ], "title": "PlanSelectionResponse", "type": "object" }, "PlanTaskInput": { "properties": { "agent_assignee": { "anyOf": [ { "maxLength": 200, "type": "string" }, { "type": "null" } ], "title": "Agent Assignee" }, "detail": { "anyOf": [ { "maxLength": 4000, "type": "string" }, { "type": "null" } ], "title": "Detail" }, "execution": { "anyOf": [ { "$ref": "#/components/schemas/TaskExecution" }, { "type": "null" } ] }, "title": { "maxLength": 500, "minLength": 1, "title": "Title", "type": "string" } }, "required": [ "title" ], "title": "PlanTaskInput", "type": "object" }, "PlanTier": { "properties": { "allotment_hosted_employees": { "anyOf": [ { "minimum": 0.0, "type": "integer" }, { "type": "null" } ], "description": "Hosted employees: Virtual employees on Tidy-hosted placement (blank = unlimited)", "title": "Allotment Hosted Employees" }, "annual_price_cents": { "title": "Annual Price Cents", "type": "integer" }, "automation_runs_per_month": { "anyOf": [ { "minimum": 0.0, "type": "integer" }, { "type": "null" } ], "description": "Automation runs: Automation runs per month (blank = unlimited)", "title": "Automation Runs Per Month" }, "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "credits_per_seat_month": { "description": "Credits: Monthly credit grant per seat", "minimum": 0.0, "title": "Credits Per Seat Month", "type": "integer" }, "display_name": { "title": "Display Name", "type": "string" }, "escalation_sms_monthly_cap": { "anyOf": [ { "minimum": 0.0, "type": "integer" }, { "type": "null" } ], "description": "Escalation SMS: Escalation texts per month (blank = unlimited)", "title": "Escalation Sms Monthly Cap" }, "feature_automations": { "description": "Automations: Arming and running automations", "title": "Feature Automations", "type": "boolean" }, "feature_byo_inference": { "description": "Bring your own model: Settings → AI Models own-model endpoints", "title": "Feature Byo Inference", "type": "boolean" }, "feature_mcp": { "description": "MCP: MCP tool access", "title": "Feature Mcp", "type": "boolean" }, "feature_photos": { "description": "Photos: Photo upload and galleries", "title": "Feature Photos", "type": "boolean" }, "feature_podcasts": { "description": "Podcasts: Podcast transcription and episodes", "title": "Feature Podcasts", "type": "boolean" }, "feature_sms": { "description": "SMS: SMS send and receive, escalation texts included", "title": "Feature Sms", "type": "boolean" }, "feature_virtual_employees": { "description": "Virtual employees: Virtual-employee agents", "title": "Feature Virtual Employees", "type": "boolean" }, "feature_webhooks_api": { "description": "Webhooks / API: Webhooks, personal access tokens and the API", "title": "Feature Webhooks Api", "type": "boolean" }, "import_email_max": { "description": "Email import: Largest email history import (-1 = unlimited)", "minimum": -1.0, "title": "Import Email Max", "type": "integer" }, "import_note_sources": { "description": "Note import sources: Distinct note-source imports (-1 = unlimited)", "minimum": -1.0, "title": "Import Note Sources", "type": "integer" }, "inboxes": { "description": "Inboxes: Connected mailboxes per paid seat, at that seat's own tier (Core 1, Plus 2, Max 3); paid add-ons are extra. An override sets the workspace total, add-ons included.", "minimum": 0.0, "title": "Inboxes", "type": "integer" }, "max_users": { "anyOf": [ { "minimum": 0.0, "type": "integer" }, { "type": "null" } ], "description": "Members: Workspace members (blank = unlimited)", "title": "Max Users" }, "monthly_price_cents": { "title": "Monthly Price Cents", "type": "integer" }, "onboarding_backfill_days": { "description": "History backfill: Mail history backfilled at onboarding", "minimum": 0.0, "title": "Onboarding Backfill Days", "type": "integer" }, "pipeline_emails_per_day_per_inbox": { "description": "Emails processed: Email-pipeline processing per inbox per day", "minimum": 0.0, "title": "Pipeline Emails Per Day Per Inbox", "type": "integer" }, "recipes_max": { "anyOf": [ { "minimum": 0.0, "type": "integer" }, { "type": "null" } ], "description": "Recipes: Enabled recipes (blank = unlimited)", "title": "Recipes Max" }, "storage_gb_per_seat": { "description": "Storage: File storage pool per seat", "minimum": 0.0, "title": "Storage Gb Per Seat", "type": "integer" }, "tier_id": { "title": "Tier Id", "type": "string" }, "updated_at": { "format": "date-time", "title": "Updated At", "type": "string" }, "workflow_executions_per_month": { "anyOf": [ { "minimum": 0.0, "type": "integer" }, { "type": "null" } ], "description": "Workflow runs: Workflow executions per month (blank = unlimited)", "title": "Workflow Executions Per Month" }, "workshop_relay_mib_per_day": { "description": "Relayed transfers: File bytes a workspace's workshops send each other through Tidy's relay per UTC day, when they have no direct path; past it a transfer pauses. Never charged in credits.", "minimum": 0.0, "title": "Workshop Relay Mib Per Day", "type": "integer" } }, "required": [ "tier_id", "display_name", "monthly_price_cents", "annual_price_cents", "feature_photos", "feature_podcasts", "feature_sms", "feature_automations", "feature_virtual_employees", "feature_mcp", "feature_webhooks_api", "feature_byo_inference", "inboxes", "credits_per_seat_month", "storage_gb_per_seat", "pipeline_emails_per_day_per_inbox", "onboarding_backfill_days", "import_email_max", "import_note_sources", "workshop_relay_mib_per_day", "created_at", "updated_at" ], "title": "PlanTier", "type": "object" }, "PlanTierAllotments": { "description": "Per-tier limits. ``null`` means unlimited; ``-1`` is unlimited for the import limits. ``inboxes`` is per active member.", "properties": { "automation_runs_per_month": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Automation runs: Automation runs per month (blank = unlimited)", "title": "Automation Runs Per Month" }, "credits_per_seat_month": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Credits: Monthly credit grant per seat", "title": "Credits Per Seat Month" }, "escalation_sms_monthly": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Escalation SMS: Escalation texts per month (blank = unlimited)", "title": "Escalation Sms Monthly" }, "hosted_employees": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Hosted employees: Virtual employees on Tidy-hosted placement (blank = unlimited)", "title": "Hosted Employees" }, "import_email_max": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Email import: Largest email history import (-1 = unlimited)", "title": "Import Email Max" }, "import_note_sources": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Note import sources: Distinct note-source imports (-1 = unlimited)", "title": "Import Note Sources" }, "inboxes": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Inboxes: Connected mailboxes per paid seat, at that seat's own tier (Core 1, Plus 2, Max 3); paid add-ons are extra. An override sets the workspace total, add-ons included.", "title": "Inboxes" }, "max_users": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Members: Workspace members (blank = unlimited)", "title": "Max Users" }, "onboarding_backfill_days": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "History backfill: Mail history backfilled at onboarding", "title": "Onboarding Backfill Days" }, "pipeline_emails_per_day_per_inbox": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Emails processed: Email-pipeline processing per inbox per day", "title": "Pipeline Emails Per Day Per Inbox" }, "recipes_max": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Recipes: Enabled recipes (blank = unlimited)", "title": "Recipes Max" }, "storage_gb_per_seat": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Storage: File storage pool per seat", "title": "Storage Gb Per Seat" }, "workflow_executions_per_month": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Workflow runs: Workflow executions per month (blank = unlimited)", "title": "Workflow Executions Per Month" }, "workshop_relay_mib_per_day": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Relayed transfers: File bytes a workspace's workshops send each other through Tidy's relay per UTC day, when they have no direct path; past it a transfer pauses. Never charged in credits.", "title": "Workshop Relay Mib Per Day" } }, "title": "PlanTierAllotments", "type": "object" }, "PlanTierFeatures": { "description": "Per-tier premium feature flags (mirrors the entitlement resolver keys).", "properties": { "automations": { "description": "Automations", "title": "Automations", "type": "boolean" }, "byo_inference": { "description": "Bring your own model", "title": "Byo Inference", "type": "boolean" }, "mcp": { "description": "MCP", "title": "Mcp", "type": "boolean" }, "photos": { "description": "Photos", "title": "Photos", "type": "boolean" }, "podcasts": { "description": "Podcasts", "title": "Podcasts", "type": "boolean" }, "sms": { "description": "SMS", "title": "Sms", "type": "boolean" }, "virtual_employees": { "description": "Virtual employees", "title": "Virtual Employees", "type": "boolean" }, "webhooks_api": { "description": "Webhooks / API", "title": "Webhooks Api", "type": "boolean" } }, "required": [ "photos", "podcasts", "sms", "automations", "virtual_employees", "mcp", "webhooks_api", "byo_inference" ], "title": "PlanTierFeatures", "type": "object" }, "PlanTierPublic": { "description": "One tier of the ladder, priced and described for the billing UI.", "properties": { "allotments": { "$ref": "#/components/schemas/PlanTierAllotments" }, "annual_price_cents": { "title": "Annual Price Cents", "type": "integer" }, "display_name": { "title": "Display Name", "type": "string" }, "features": { "$ref": "#/components/schemas/PlanTierFeatures" }, "monthly_price_cents": { "title": "Monthly Price Cents", "type": "integer" }, "tier_id": { "title": "Tier Id", "type": "string" } }, "required": [ "tier_id", "display_name", "monthly_price_cents", "annual_price_cents", "features", "allotments" ], "title": "PlanTierPublic", "type": "object" }, "PlanTierUpdate": { "description": "Partial update of a plan_tiers row. Only known editable columns accepted; an explicit null clears a nullable limit (unlimited, or one per member for inboxes). Prices are set in Stripe, not here.", "properties": { "allotment_hosted_employees": { "anyOf": [ { "minimum": 0.0, "type": "integer" }, { "type": "null" } ], "description": "Hosted employees: Virtual employees on Tidy-hosted placement (blank = unlimited)", "title": "Allotment Hosted Employees" }, "automation_runs_per_month": { "anyOf": [ { "minimum": 0.0, "type": "integer" }, { "type": "null" } ], "description": "Automation runs: Automation runs per month (blank = unlimited)", "title": "Automation Runs Per Month" }, "credits_per_seat_month": { "anyOf": [ { "minimum": 0.0, "type": "integer" }, { "type": "null" } ], "description": "Credits: Monthly credit grant per seat", "title": "Credits Per Seat Month" }, "display_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Display Name" }, "escalation_sms_monthly_cap": { "anyOf": [ { "minimum": 0.0, "type": "integer" }, { "type": "null" } ], "description": "Escalation SMS: Escalation texts per month (blank = unlimited)", "title": "Escalation Sms Monthly Cap" }, "feature_automations": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Automations: Arming and running automations", "title": "Feature Automations" }, "feature_byo_inference": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Bring your own model: Settings → AI Models own-model endpoints", "title": "Feature Byo Inference" }, "feature_mcp": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "MCP: MCP tool access", "title": "Feature Mcp" }, "feature_photos": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Photos: Photo upload and galleries", "title": "Feature Photos" }, "feature_podcasts": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Podcasts: Podcast transcription and episodes", "title": "Feature Podcasts" }, "feature_sms": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "SMS: SMS send and receive, escalation texts included", "title": "Feature Sms" }, "feature_virtual_employees": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Virtual employees: Virtual-employee agents", "title": "Feature Virtual Employees" }, "feature_webhooks_api": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Webhooks / API: Webhooks, personal access tokens and the API", "title": "Feature Webhooks Api" }, "import_email_max": { "anyOf": [ { "minimum": -1.0, "type": "integer" }, { "type": "null" } ], "description": "Email import: Largest email history import (-1 = unlimited)", "title": "Import Email Max" }, "import_note_sources": { "anyOf": [ { "minimum": -1.0, "type": "integer" }, { "type": "null" } ], "description": "Note import sources: Distinct note-source imports (-1 = unlimited)", "title": "Import Note Sources" }, "inboxes": { "anyOf": [ { "minimum": 0.0, "type": "integer" }, { "type": "null" } ], "description": "Inboxes: Connected mailboxes per paid seat, at that seat's own tier (Core 1, Plus 2, Max 3); paid add-ons are extra. An override sets the workspace total, add-ons included.", "title": "Inboxes" }, "max_users": { "anyOf": [ { "minimum": 0.0, "type": "integer" }, { "type": "null" } ], "description": "Members: Workspace members (blank = unlimited)", "title": "Max Users" }, "onboarding_backfill_days": { "anyOf": [ { "minimum": 0.0, "type": "integer" }, { "type": "null" } ], "description": "History backfill: Mail history backfilled at onboarding", "title": "Onboarding Backfill Days" }, "pipeline_emails_per_day_per_inbox": { "anyOf": [ { "minimum": 0.0, "type": "integer" }, { "type": "null" } ], "description": "Emails processed: Email-pipeline processing per inbox per day", "title": "Pipeline Emails Per Day Per Inbox" }, "recipes_max": { "anyOf": [ { "minimum": 0.0, "type": "integer" }, { "type": "null" } ], "description": "Recipes: Enabled recipes (blank = unlimited)", "title": "Recipes Max" }, "storage_gb_per_seat": { "anyOf": [ { "minimum": 0.0, "type": "integer" }, { "type": "null" } ], "description": "Storage: File storage pool per seat", "title": "Storage Gb Per Seat" }, "workflow_executions_per_month": { "anyOf": [ { "minimum": 0.0, "type": "integer" }, { "type": "null" } ], "description": "Workflow runs: Workflow executions per month (blank = unlimited)", "title": "Workflow Executions Per Month" }, "workshop_relay_mib_per_day": { "anyOf": [ { "minimum": 0.0, "type": "integer" }, { "type": "null" } ], "description": "Relayed transfers: File bytes a workspace's workshops send each other through Tidy's relay per UTC day, when they have no direct path; past it a transfer pauses. Never charged in credits.", "title": "Workshop Relay Mib Per Day" } }, "title": "PlanTierUpdate", "type": "object" }, "PlanTiersResponse": { "properties": { "tiers": { "items": { "$ref": "#/components/schemas/PlanTierPublic" }, "title": "Tiers", "type": "array" } }, "required": [ "tiers" ], "title": "PlanTiersResponse", "type": "object" }, "PlantStarterRequest": { "properties": { "agent_account_id": { "description": "The employee that was just hired.", "title": "Agent Account Id", "type": "string" } }, "required": [ "agent_account_id" ], "title": "PlantStarterRequest", "type": "object" }, "PlantStarterResponse": { "properties": { "objectives_created": { "items": { "type": "string" }, "title": "Objectives Created", "type": "array" }, "skipped": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Skipped" }, "standing_instructions_written": { "title": "Standing Instructions Written", "type": "boolean" } }, "required": [ "objectives_created", "standing_instructions_written" ], "title": "PlantStarterResponse", "type": "object" }, "PlatformPodcastPipelineStatus": { "description": "The composed three-stage view. On a DAG outage ONLY\n``pipeline_reachable`` (False), ``error`` and ``received_here`` are real;\nthe stage blocks sit at their empty defaults so the tile renders the\noutage banner next to the env's last-known receive state.", "properties": { "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Error" }, "paused": { "default": false, "title": "Paused", "type": "boolean" }, "pipeline_reachable": { "title": "Pipeline Reachable", "type": "boolean" }, "queued": { "$ref": "#/components/schemas/PipelineQueued", "default": { "background": 0, "dead": 0, "in_flight_stage": null, "priority": 0 } }, "received_here": { "$ref": "#/components/schemas/ReceivedHere", "default": { "episodes_ingested": 0, "last_writeback_at": null, "writebacks_last_24h": 0, "writebacks_last_7d": 0 } }, "targets": { "additionalProperties": { "$ref": "#/components/schemas/TargetShipping" }, "default": {}, "title": "Targets", "type": "object" }, "transcribed": { "$ref": "#/components/schemas/PipelineTranscribed", "default": { "last_completed_at": null, "today": 0, "total": 0 } }, "workers": { "$ref": "#/components/schemas/PipelineWorkersHealth", "default": { "beating": 0, "total": 0 } } }, "required": [ "pipeline_reachable" ], "title": "PlatformPodcastPipelineStatus", "type": "object" }, "Plugin": { "properties": { "account_identifier": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Account Identifier" }, "connection_method": { "enum": [ "oauth", "api_key", "mcp", "app_install", "native_box_login", "webhook", "outgoing_webhook" ], "title": "Connection Method", "type": "string" }, "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "credential_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Credential Id" }, "failure_count": { "default": 0, "title": "Failure Count", "type": "integer" }, "id": { "title": "Id", "type": "string" }, "kind": { "title": "Kind", "type": "string" }, "label": { "title": "Label", "type": "string" }, "last_error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Last Error" }, "last_verified_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Last Verified At" }, "owner_account_id": { "title": "Owner Account Id", "type": "string" }, "scopes": { "items": { "type": "string" }, "title": "Scopes", "type": "array" }, "status": { "enum": [ "working", "needs_reauth", "disconnected", "pending" ], "title": "Status", "type": "string" }, "tenant_id": { "title": "Tenant Id", "type": "string" }, "updated_at": { "format": "date-time", "title": "Updated At", "type": "string" }, "used_by": { "items": { "type": "string" }, "title": "Used By", "type": "array" }, "visibility": { "enum": [ "private", "shared" ], "title": "Visibility", "type": "string" } }, "required": [ "id", "tenant_id", "owner_account_id", "kind", "connection_method", "label", "status", "visibility", "created_at", "updated_at" ], "title": "Plugin", "type": "object" }, "PluginAccessCandidate": { "description": "One of the person's own connections of the kind.", "properties": { "grant_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Grant Id" }, "plugin_id": { "title": "Plugin Id", "type": "string" }, "usable": { "title": "Usable", "type": "boolean" } }, "required": [ "plugin_id", "usable" ], "title": "PluginAccessCandidate", "type": "object" }, "PluginAccessChoice": { "additionalProperties": false, "description": "Meet one requirement with one of the person's own connections.", "properties": { "plugin_id": { "format": "uuid", "title": "Plugin Id", "type": "string" }, "plugin_kind": { "maxLength": 64, "minLength": 1, "title": "Plugin Kind", "type": "string" }, "replace_shipment_ids": { "items": { "format": "uuid", "type": "string" }, "maxItems": 16, "title": "Replace Shipment Ids", "type": "array" }, "workshop_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Workshop Id" } }, "required": [ "plugin_kind", "plugin_id" ], "title": "PluginAccessChoice", "type": "object" }, "PluginAccessEnv": { "properties": { "base_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Base Url" }, "token": { "title": "Token", "type": "string" } }, "required": [ "token" ], "title": "PluginAccessEnv", "type": "object" }, "PluginAccessFileOffer": { "description": "One of the person's own saved dotenv secret files, not lent to the\nemployee, that alone answers every name the requirement needs on every\nharness that carries it (TIDY-20019 F9). Ids and names the skill declares\nonly: the file's title is the client's own synced record.", "properties": { "credential_id": { "title": "Credential Id", "type": "string" }, "env_keys": { "items": { "type": "string" }, "title": "Env Keys", "type": "array" }, "record_id": { "title": "Record Id", "type": "string" } }, "required": [ "record_id", "credential_id", "env_keys" ], "title": "PluginAccessFileOffer", "type": "object" }, "PluginAccessFileSource": { "description": "One of the person's own secret files lent to the employee that answers\nsome of the requirement's names (TIDY-19802 D1) — never another member's.", "properties": { "credential_id": { "title": "Credential Id", "type": "string" }, "env_keys": { "items": { "type": "string" }, "title": "Env Keys", "type": "array" }, "record_id": { "title": "Record Id", "type": "string" }, "runtime": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Runtime" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Title" } }, "required": [ "credential_id", "record_id", "env_keys" ], "title": "PluginAccessFileSource", "type": "object" }, "PluginAccessRequirement": { "properties": { "candidates": { "items": { "$ref": "#/components/schemas/PluginAccessCandidate" }, "title": "Candidates", "type": "array" }, "delivery_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Delivery Reason" }, "delivery_state": { "enum": [ "not_shipped", "other_workshop", "failed", "refused", "held", "pending_ack", "ready" ], "title": "Delivery State", "type": "string" }, "env": { "$ref": "#/components/schemas/PluginAccessEnv" }, "file_offers": { "items": { "$ref": "#/components/schemas/PluginAccessFileOffer" }, "title": "File Offers", "type": "array" }, "file_sources": { "items": { "$ref": "#/components/schemas/PluginAccessFileSource" }, "title": "File Sources", "type": "array" }, "grant_hint": { "title": "Grant Hint", "type": "string" }, "in_place": { "items": { "$ref": "#/components/schemas/PluginAccessShipment" }, "title": "In Place", "type": "array" }, "inputs": { "items": { "type": "string" }, "title": "Inputs", "type": "array" }, "met_by": { "anyOf": [ { "enum": [ "plugin", "secret_file" ], "type": "string" }, { "type": "null" } ], "default": null, "title": "Met By" }, "plugin_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Plugin Id" }, "plugin_kind": { "title": "Plugin Kind", "type": "string" }, "required": { "title": "Required", "type": "boolean" }, "required_env": { "items": { "type": "string" }, "title": "Required Env", "type": "array" }, "runtimes": { "items": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "title": "Runtimes", "type": "array" }, "skill_versions": { "items": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" }, { "type": "null" } ] }, "type": "array" }, "title": "Skill Versions", "type": "array" }, "skills": { "items": { "type": "string" }, "title": "Skills", "type": "array" }, "status": { "enum": [ "met", "ambiguous", "needs_access" ], "title": "Status", "type": "string" } }, "required": [ "plugin_kind", "env", "required", "skills", "status", "delivery_state", "grant_hint", "candidates", "in_place" ], "title": "PluginAccessRequirement", "type": "object" }, "PluginAccessShipment": { "properties": { "plugin_id": { "title": "Plugin Id", "type": "string" }, "shipment_id": { "title": "Shipment Id", "type": "string" }, "stays_for_harness": { "default": false, "title": "Stays For Harness", "type": "boolean" }, "workshop_id": { "title": "Workshop Id", "type": "string" } }, "required": [ "plugin_id", "shipment_id", "workshop_id" ], "title": "PluginAccessShipment", "type": "object" }, "PluginAccessSkillRef": { "properties": { "skill_id": { "title": "Skill Id", "type": "string" }, "version": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Version" } }, "required": [ "skill_id" ], "title": "PluginAccessSkillRef", "type": "object" }, "PluginAccessWorkshop": { "properties": { "approval": { "enum": [ "automatic", "yours", "held" ], "title": "Approval", "type": "string" }, "env_binding_receipt": { "anyOf": [ { "enum": [ "supported", "connector_update_required", "unknown" ], "type": "string" }, { "type": "null" } ], "default": null, "title": "Env Binding Receipt" }, "workshop_id": { "title": "Workshop Id", "type": "string" } }, "required": [ "workshop_id", "approval" ], "title": "PluginAccessWorkshop", "type": "object" }, "PluginApiKeyConnect": { "additionalProperties": false, "description": "Connect a built-in API with the key its provider issued the member, or\nreplace the key of one already connected (TIDY-19604 F8).", "properties": { "access_client_id": { "anyOf": [ { "maxLength": 256, "type": "string" }, { "type": "null" } ], "title": "Access Client Id" }, "access_client_secret": { "anyOf": [ { "maxLength": 256, "type": "string" }, { "type": "null" } ], "title": "Access Client Secret" }, "base_url": { "anyOf": [ { "maxLength": 2048, "type": "string" }, { "type": "null" } ], "title": "Base Url" }, "kind": { "maxLength": 64, "minLength": 1, "title": "Kind", "type": "string" }, "label": { "anyOf": [ { "maxLength": 200, "type": "string" }, { "type": "null" } ], "title": "Label" }, "plugin_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Plugin Id" }, "remove_access": { "default": false, "title": "Remove Access", "type": "boolean" }, "username": { "anyOf": [ { "maxLength": 256, "type": "string" }, { "type": "null" } ], "title": "Username" }, "value": { "anyOf": [ { "maxLength": 4096, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Value" } }, "required": [ "kind" ], "title": "PluginApiKeyConnect", "type": "object" }, "PluginAppEventReceipt": { "description": "The answer Tidy's own provider app gets for one delivery (TIDY-19604\nF8T). ``delivered`` is how many plugins it set off; ``dropped`` is a\ndelivery for an account no plugin here receives events for, or an event\nTidy does not offer — handled, so the provider does not retry it.", "properties": { "delivered": { "title": "Delivered", "type": "integer" }, "status": { "enum": [ "accepted", "duplicate", "rejected", "dropped" ], "title": "Status", "type": "string" } }, "required": [ "status", "delivered" ], "title": "PluginAppEventReceipt", "type": "object" }, "PluginBindingNamesResponse": { "description": "Every env name a catalogue connection binding can deliver (TIDY-19802).\n\nPublic catalogue metadata, the same for every caller: no connection,\nskill, grant or tenant fact. A connector removes all of them from a turn it\nmaterializes nothing for (a room, the first turn after boot), so an\ninherited value can never stand in for a pair the turn was refused.\n``revision`` is the SHA-256 of the canonical names list.", "properties": { "names": { "items": { "type": "string" }, "title": "Names", "type": "array" }, "revision": { "title": "Revision", "type": "string" } }, "required": [ "names", "revision" ], "title": "PluginBindingNamesResponse", "type": "object" }, "PluginCatalogEntry": { "properties": { "available": { "title": "Available", "type": "boolean" }, "category": { "enum": [ "mail", "source_control", "tools", "model_provider", "cloud_host", "custom", "webhook" ], "title": "Category", "type": "string" }, "connect_help": { "anyOf": [ { "$ref": "#/components/schemas/PluginConnectHelp" }, { "type": "null" } ], "default": null }, "connect_options": { "default": [], "items": { "$ref": "#/components/schemas/PluginConnectOption" }, "title": "Connect Options", "type": "array" }, "display_name": { "title": "Display Name", "type": "string" }, "icon": { "title": "Icon", "type": "string" }, "kind": { "title": "Kind", "type": "string" }, "lendable": { "title": "Lendable", "type": "boolean" }, "methods": { "items": { "enum": [ "oauth", "api_key", "mcp", "app_install", "native_box_login", "webhook", "outgoing_webhook" ], "type": "string" }, "title": "Methods", "type": "array" }, "script_env": { "default": [], "items": { "$ref": "#/components/schemas/PluginScriptEnvName" }, "title": "Script Env", "type": "array" }, "used_by": { "items": { "type": "string" }, "title": "Used By", "type": "array" } }, "required": [ "kind", "display_name", "icon", "category", "methods", "used_by", "available", "lendable" ], "title": "PluginCatalogEntry", "type": "object" }, "PluginCatalogResponse": { "properties": { "entries": { "items": { "$ref": "#/components/schemas/PluginCatalogEntry" }, "title": "Entries", "type": "array" } }, "required": [ "entries" ], "title": "PluginCatalogResponse", "type": "object" }, "PluginConnectHelp": { "description": "Where the member gets the key on the provider's own site (TIDY-18730 / PD4).\n\nCarried by the catalogue manifest so every client renders the same\ninstructions beside the same key field; a Svelte string table would reach\none client and drift from the card.", "properties": { "console_url": { "title": "Console Url", "type": "string" }, "scope_note": { "title": "Scope Note", "type": "string" }, "steps": { "items": { "type": "string" }, "title": "Steps", "type": "array" } }, "required": [ "console_url", "steps", "scope_note" ], "title": "PluginConnectHelp", "type": "object" }, "PluginConnectLinkResponse": { "properties": { "display_name": { "title": "Display Name", "type": "string" }, "kind": { "title": "Kind", "type": "string" }, "link": { "title": "Link", "type": "string" }, "user_step": { "title": "User Step", "type": "string" } }, "required": [ "kind", "display_name", "link", "user_step" ], "title": "PluginConnectLinkResponse", "type": "object" }, "PluginConnectOption": { "description": "One purpose a multi-purpose card connects for (TIDY-19277 F3).\n\nGoogle is both a mailbox and a model provider, so its Connect asks which;\n``purpose`` is what the ``plugin_connect`` verb is invoked with.", "properties": { "label": { "title": "Label", "type": "string" }, "method": { "enum": [ "oauth", "api_key", "mcp", "app_install", "native_box_login", "webhook", "outgoing_webhook" ], "title": "Method", "type": "string" }, "purpose": { "title": "Purpose", "type": "string" } }, "required": [ "purpose", "method", "label" ], "title": "PluginConnectOption", "type": "object" }, "PluginEventDeliveryResponse": { "properties": { "event_key": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Event Key" }, "event_type_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Event Type Id" }, "id": { "title": "Id", "type": "string" }, "outcome": { "$ref": "#/components/schemas/DeliveryOutcome" }, "payload": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "title": "Payload" }, "plugin_id": { "title": "Plugin Id", "type": "string" }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Reason" }, "received_at": { "format": "date-time", "title": "Received At", "type": "string" }, "size_bytes": { "title": "Size Bytes", "type": "integer" }, "status": { "enum": [ "accepted", "rejected", "captured" ], "title": "Status", "type": "string" } }, "required": [ "id", "plugin_id", "status", "size_bytes", "outcome", "received_at" ], "title": "PluginEventDeliveryResponse", "type": "object" }, "PluginEventReceipt": { "description": "The answer a sender gets. Deliberately small: the delivery log on the\nplugin is where a member reads the detail. ``duplicate`` is a provider's\nretry of a delivery already accepted — nothing is set off again and\nnothing is logged, so there is no delivery id.", "properties": { "delivery_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Delivery Id" }, "event": { "title": "Event", "type": "string" }, "status": { "enum": [ "accepted", "captured", "duplicate" ], "title": "Status", "type": "string" } }, "required": [ "status", "event" ], "title": "PluginEventReceipt", "type": "object" }, "PluginEventSample": { "additionalProperties": false, "properties": { "sample": { "additionalProperties": true, "title": "Sample", "type": "object" } }, "required": [ "sample" ], "title": "PluginEventSample", "type": "object" }, "PluginEventTrigger": { "additionalProperties": false, "description": "Fires when a plugin's Events door accepts a delivery of ``event``\n(TIDY-19604 F9; the webhook rule of TIDY-17345 / S6, re-homed).\n\nA delivery is not a facet item, so a plugin-event rule is system-lane\nexactly like ``system_event`` and ``email``: ``facet_id`` must be null and\nthe trigger subject is the delivery's VALIDATED fields, addressed as\n``{{event.}}`` and, in a clause, ``event.``.\n\nD13: this trigger IS the folder-event answer — a user who wants\nfolder-change automation points their own tooling at a Custom webhook\nplugin. Tidy ships no folder watcher.", "properties": { "event": { "description": "The event's key on that plugin (``delivery``, ``issue_opened``).", "pattern": "^[a-z0-9][a-z0-9_]{0,62}$", "title": "Event", "type": "string" }, "kind": { "const": "plugin_event", "title": "Kind", "type": "string" }, "plugin_id": { "description": "The plugin whose Events door fires this rule. Checked at SAVE time against the plugins the author can see — an unknown or removed plugin is a 422, never a rule that silently never fires.", "minLength": 1, "title": "Plugin Id", "type": "string" } }, "required": [ "kind", "plugin_id", "event" ], "title": "PluginEventTrigger", "type": "object" }, "PluginEventTypeCreate": { "additionalProperties": false, "properties": { "key": { "anyOf": [ { "pattern": "^[a-z0-9][a-z0-9_]{0,62}$", "type": "string" }, { "type": "null" } ], "title": "Key" }, "label": { "maxLength": 120, "minLength": 1, "title": "Label", "type": "string" }, "listen": { "default": false, "title": "Listen", "type": "boolean" }, "match": { "anyOf": [ { "$ref": "#/components/schemas/EventMatch" }, { "type": "null" } ] }, "sample": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Sample" } }, "required": [ "label" ], "title": "PluginEventTypeCreate", "type": "object" }, "PluginEventTypeResponse": { "properties": { "assign_ve_action": { "anyOf": [ { "$ref": "#/components/schemas/AssignVeActionConfig" }, { "type": "null" } ], "default": null }, "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "fields": { "items": { "$ref": "#/components/schemas/EventFieldModel" }, "title": "Fields", "type": "array" }, "id": { "title": "Id", "type": "string" }, "key": { "title": "Key", "type": "string" }, "label": { "title": "Label", "type": "string" }, "listening": { "default": false, "title": "Listening", "type": "boolean" }, "match": { "anyOf": [ { "$ref": "#/components/schemas/EventMatch" }, { "type": "null" } ], "default": null }, "plugin_id": { "title": "Plugin Id", "type": "string" }, "sample": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "title": "Sample" }, "sample_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Sample At" }, "scoped_workflow_ids": { "items": { "type": "string" }, "title": "Scoped Workflow Ids", "type": "array" }, "skipped_keys": { "items": { "type": "string" }, "title": "Skipped Keys", "type": "array" }, "updated_at": { "format": "date-time", "title": "Updated At", "type": "string" } }, "required": [ "id", "plugin_id", "key", "label", "fields", "created_at", "updated_at" ], "title": "PluginEventTypeResponse", "type": "object" }, "PluginEventTypeUpdate": { "additionalProperties": false, "description": "Every key optional. ``match`` / ``assign_ve_action`` sent as ``null``\nclear them; omitted, they are left as they are.", "properties": { "assign_ve_action": { "anyOf": [ { "$ref": "#/components/schemas/AssignVeActionConfig" }, { "type": "null" } ] }, "fields": { "anyOf": [ { "items": { "$ref": "#/components/schemas/EventFieldModel" }, "type": "array" }, { "type": "null" } ], "title": "Fields" }, "label": { "anyOf": [ { "maxLength": 120, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Label" }, "listen": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Listen" }, "match": { "anyOf": [ { "$ref": "#/components/schemas/EventMatch" }, { "type": "null" } ] }, "scoped_workflow_ids": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Scoped Workflow Ids" } }, "title": "PluginEventTypeUpdate", "type": "object" }, "PluginEventsDoorOpen": { "additionalProperties": false, "description": "Turn a built-in plugin's events on (TIDY-19604 F10). ``secret`` is the\none the PROVIDER issued (Todoist's client secret, or a Notion token the\nmember already holds); without one a Notion door waits for Notion's\none-time verification token.", "properties": { "secret": { "anyOf": [ { "maxLength": 512, "minLength": 8, "type": "string" }, { "type": "null" } ], "title": "Secret" } }, "title": "PluginEventsDoorOpen", "type": "object" }, "PluginEventsResponse": { "properties": { "arrival": { "default": "door", "enum": [ "door", "github_app", "google_sheets", "app" ], "title": "Arrival", "type": "string" }, "can_edit": { "title": "Can Edit", "type": "boolean" }, "capture_count": { "default": 0, "title": "Capture Count", "type": "integer" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Description" }, "enabled": { "title": "Enabled", "type": "boolean" }, "event_types": { "items": { "$ref": "#/components/schemas/PluginEventTypeResponse" }, "title": "Event Types", "type": "array" }, "has_door": { "default": true, "title": "Has Door", "type": "boolean" }, "last_capture_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Last Capture At" }, "last_delivery_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Last Delivery At" }, "member_defined": { "title": "Member Defined", "type": "boolean" }, "plugin_id": { "title": "Plugin Id", "type": "string" }, "rate_limit_per_minute": { "title": "Rate Limit Per Minute", "type": "integer" }, "setup": { "anyOf": [ { "$ref": "#/components/schemas/PluginEventsSetup" }, { "type": "null" } ], "default": null }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Url" }, "verification": { "anyOf": [ { "$ref": "#/components/schemas/VerificationResponse" }, { "type": "null" } ], "default": null }, "verification_token": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Verification Token", "writeOnly": true } }, "required": [ "plugin_id", "enabled", "rate_limit_per_minute", "can_edit", "member_defined", "event_types" ], "title": "PluginEventsResponse", "type": "object" }, "PluginEventsSecretResponse": { "properties": { "arrival": { "default": "door", "enum": [ "door", "github_app", "google_sheets", "app" ], "title": "Arrival", "type": "string" }, "can_edit": { "title": "Can Edit", "type": "boolean" }, "capture_count": { "default": 0, "title": "Capture Count", "type": "integer" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Description" }, "enabled": { "title": "Enabled", "type": "boolean" }, "event_types": { "items": { "$ref": "#/components/schemas/PluginEventTypeResponse" }, "title": "Event Types", "type": "array" }, "has_door": { "default": true, "title": "Has Door", "type": "boolean" }, "last_capture_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Last Capture At" }, "last_delivery_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Last Delivery At" }, "member_defined": { "title": "Member Defined", "type": "boolean" }, "plugin_id": { "title": "Plugin Id", "type": "string" }, "rate_limit_per_minute": { "title": "Rate Limit Per Minute", "type": "integer" }, "secret": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Secret", "writeOnly": true }, "setup": { "anyOf": [ { "$ref": "#/components/schemas/PluginEventsSetup" }, { "type": "null" } ], "default": null }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Url" }, "verification": { "anyOf": [ { "$ref": "#/components/schemas/VerificationResponse" }, { "type": "null" } ], "default": null }, "verification_token": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Verification Token", "writeOnly": true } }, "required": [ "plugin_id", "enabled", "rate_limit_per_minute", "can_edit", "member_defined", "event_types" ], "title": "PluginEventsSecretResponse", "type": "object" }, "PluginEventsSetup": { "description": "How a built-in plugin's events are connected on the provider's side —\nthe catalogue's words (TIDY-19604 F10).", "properties": { "handshake": { "default": false, "title": "Handshake", "type": "boolean" }, "provider": { "title": "Provider", "type": "string" }, "requires": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Requires" }, "secret_label": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Secret Label" }, "steps": { "items": { "type": "string" }, "title": "Steps", "type": "array" } }, "required": [ "provider" ], "title": "PluginEventsSetup", "type": "object" }, "PluginEventsUpdate": { "additionalProperties": false, "description": "Change how deliveries prove themselves, or turn the door off. A new\nscheme (or a new HMAC secret) answers with the one-time secret.", "properties": { "description": { "anyOf": [ { "maxLength": 8000, "type": "string" }, { "type": "null" } ], "title": "Description" }, "enabled": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Enabled" }, "rate_limit_per_minute": { "anyOf": [ { "maximum": 6000.0, "minimum": 1.0, "type": "integer" }, { "type": "null" } ], "title": "Rate Limit Per Minute" }, "rotate_secret": { "default": false, "title": "Rotate Secret", "type": "boolean" }, "verification": { "anyOf": [ { "$ref": "#/components/schemas/VerificationSettings" }, { "type": "null" } ] } }, "title": "PluginEventsUpdate", "type": "object" }, "PluginLend": { "properties": { "capability_scope": { "items": { "type": "string" }, "title": "Capability Scope", "type": "array" }, "conversation_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Conversation Id" }, "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "employee_account_id": { "title": "Employee Account Id", "type": "string" }, "expires_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Expires At" }, "id": { "title": "Id", "type": "string" }, "owner_account_id": { "title": "Owner Account Id", "type": "string" }, "plugin_id": { "title": "Plugin Id", "type": "string" }, "purpose": { "title": "Purpose", "type": "string" }, "revoked_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Revoked At" }, "scope": { "enum": [ "once", "session", "standing" ], "title": "Scope", "type": "string" }, "tenant_id": { "title": "Tenant Id", "type": "string" }, "used_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Used At" } }, "required": [ "id", "tenant_id", "plugin_id", "employee_account_id", "owner_account_id", "scope", "capability_scope", "purpose", "created_at" ], "title": "PluginLend", "type": "object" }, "PluginReauthInstruction": { "description": "Where the client goes to re-run the plugin's sign-in.\n\n``oauth_redirect`` / ``app_install``: POST ``start_path`` with\n``start_body`` and follow the authorize URL it returns. ``catalog_form``:\nopen the catalogue entry's configured form; it submits to ``start_path``.", "properties": { "mode": { "enum": [ "oauth_redirect", "app_install", "catalog_form" ], "title": "Mode", "type": "string" }, "start_body": { "additionalProperties": { "type": "string" }, "title": "Start Body", "type": "object" }, "start_path": { "title": "Start Path", "type": "string" } }, "required": [ "mode", "start_path" ], "title": "PluginReauthInstruction", "type": "object" }, "PluginReauthResponse": { "properties": { "plugin": { "$ref": "#/components/schemas/Plugin" }, "reauth": { "$ref": "#/components/schemas/PluginReauthInstruction" } }, "required": [ "plugin", "reauth" ], "title": "PluginReauthResponse", "type": "object" }, "PluginReauthRow": { "description": "Connections a tenant must re-authorize before work can resume.", "properties": { "count": { "title": "Count", "type": "integer" }, "kind": { "title": "Kind", "type": "string" }, "tenant": { "title": "Tenant", "type": "string" }, "tenant_id": { "title": "Tenant Id", "type": "string" } }, "required": [ "tenant_id", "tenant", "kind", "count" ], "title": "PluginReauthRow", "type": "object" }, "PluginRemovedResponse": { "properties": { "id": { "title": "Id", "type": "string" }, "removed": { "title": "Removed", "type": "boolean" } }, "required": [ "id", "removed" ], "title": "PluginRemovedResponse", "type": "object" }, "PluginScriptEnvName": { "description": "One env name a workshop script reads a connection of this kind under\n(TIDY-19802 F3): its token is ``secret``, its address ``public``. Names\nonly — what a skill declares in frontmatter ``credentials``. Declaring one\ngrants nothing: a turn receives the pair only through a lent, shipped\nconnection.", "properties": { "connection_method": { "anyOf": [ { "enum": [ "oauth", "api_key", "mcp", "app_install", "native_box_login", "webhook", "outgoing_webhook" ], "type": "string" }, { "type": "null" } ], "default": null, "title": "Connection Method" }, "name": { "title": "Name", "type": "string" }, "role": { "enum": [ "secret", "public" ], "title": "Role", "type": "string" } }, "required": [ "name", "role" ], "title": "PluginScriptEnvName", "type": "object" }, "PluginSetupCreate": { "additionalProperties": false, "properties": { "algorithm": { "anyOf": [ { "enum": [ "sha256", "sha1", "sha512" ], "type": "string" }, { "type": "null" } ], "title": "Algorithm" }, "auth_scheme": { "anyOf": [ { "maxLength": 40, "type": "string" }, { "type": "null" } ], "title": "Auth Scheme" }, "base_url": { "anyOf": [ { "maxLength": 2048, "type": "string" }, { "type": "null" } ], "title": "Base Url" }, "description": { "anyOf": [ { "maxLength": 2000, "type": "string" }, { "type": "null" } ], "title": "Description" }, "encoding": { "anyOf": [ { "enum": [ "hex", "base64" ], "type": "string" }, { "type": "null" } ], "title": "Encoding" }, "events": { "items": { "$ref": "#/components/schemas/PluginSetupEvent" }, "maxItems": 20, "title": "Events", "type": "array" }, "header_name": { "anyOf": [ { "maxLength": 120, "type": "string" }, { "type": "null" } ], "title": "Header Name" }, "kind": { "enum": [ "custom_api", "webhook_destination", "custom_webhook", "mcp" ], "title": "Kind", "type": "string" }, "label": { "maxLength": 200, "minLength": 1, "title": "Label", "type": "string" }, "region": { "anyOf": [ { "maxLength": 64, "type": "string" }, { "type": "null" } ], "title": "Region" }, "service": { "anyOf": [ { "maxLength": 64, "type": "string" }, { "type": "null" } ], "title": "Service" }, "signature_prefix": { "anyOf": [ { "maxLength": 40, "type": "string" }, { "type": "null" } ], "title": "Signature Prefix" }, "timestamp_header": { "anyOf": [ { "maxLength": 120, "type": "string" }, { "type": "null" } ], "title": "Timestamp Header" }, "url": { "anyOf": [ { "maxLength": 2048, "type": "string" }, { "type": "null" } ], "title": "Url" } }, "required": [ "kind", "label" ], "title": "PluginSetupCreate", "type": "object" }, "PluginSetupEvent": { "additionalProperties": false, "description": "An event a Custom webhook receives, its fields inferred from a sample.", "properties": { "label": { "maxLength": 120, "minLength": 1, "title": "Label", "type": "string" }, "sample": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Sample" } }, "required": [ "label" ], "title": "PluginSetupEvent", "type": "object" }, "PluginSetupResponse": { "properties": { "plugin": { "$ref": "#/components/schemas/UsablePlugin" } }, "required": [ "plugin" ], "title": "PluginSetupResponse", "type": "object" }, "PluginSetupUpdate": { "additionalProperties": false, "properties": { "algorithm": { "anyOf": [ { "enum": [ "sha256", "sha1", "sha512" ], "type": "string" }, { "type": "null" } ], "title": "Algorithm" }, "auth_scheme": { "anyOf": [ { "maxLength": 40, "type": "string" }, { "type": "null" } ], "title": "Auth Scheme" }, "base_url": { "anyOf": [ { "maxLength": 2048, "type": "string" }, { "type": "null" } ], "title": "Base Url" }, "description": { "anyOf": [ { "maxLength": 2000, "type": "string" }, { "type": "null" } ], "title": "Description" }, "encoding": { "anyOf": [ { "enum": [ "hex", "base64" ], "type": "string" }, { "type": "null" } ], "title": "Encoding" }, "events": { "items": { "$ref": "#/components/schemas/PluginSetupEvent" }, "maxItems": 20, "title": "Events", "type": "array" }, "header_name": { "anyOf": [ { "maxLength": 120, "type": "string" }, { "type": "null" } ], "title": "Header Name" }, "label": { "anyOf": [ { "maxLength": 200, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Label" }, "region": { "anyOf": [ { "maxLength": 64, "type": "string" }, { "type": "null" } ], "title": "Region" }, "service": { "anyOf": [ { "maxLength": 64, "type": "string" }, { "type": "null" } ], "title": "Service" }, "signature_prefix": { "anyOf": [ { "maxLength": 40, "type": "string" }, { "type": "null" } ], "title": "Signature Prefix" }, "timestamp_header": { "anyOf": [ { "maxLength": 120, "type": "string" }, { "type": "null" } ], "title": "Timestamp Header" }, "url": { "anyOf": [ { "maxLength": 2048, "type": "string" }, { "type": "null" } ], "title": "Url" } }, "title": "PluginSetupUpdate", "type": "object" }, "PluginSheet": { "properties": { "columns": { "items": { "$ref": "#/components/schemas/PluginSheetColumn" }, "title": "Columns", "type": "array" }, "events": { "$ref": "#/components/schemas/PluginSheetEventKeys" }, "header_row": { "title": "Header Row", "type": "integer" }, "id": { "title": "Id", "type": "string" }, "key_column": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Key Column" }, "label": { "title": "Label", "type": "string" }, "last_read_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Last Read At" }, "last_read_error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Last Read Error" }, "max_rows": { "title": "Max Rows", "type": "integer" }, "row_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Row Count" }, "sheet_gid": { "title": "Sheet Gid", "type": "integer" }, "sheet_title": { "title": "Sheet Title", "type": "string" }, "spreadsheet_id": { "title": "Spreadsheet Id", "type": "string" }, "spreadsheet_row_id": { "title": "Spreadsheet Row Id", "type": "string" }, "spreadsheet_title": { "title": "Spreadsheet Title", "type": "string" }, "url": { "title": "Url", "type": "string" }, "watch": { "$ref": "#/components/schemas/PluginSheetWatch" } }, "required": [ "id", "spreadsheet_row_id", "spreadsheet_id", "spreadsheet_title", "sheet_gid", "sheet_title", "label", "url", "header_row", "columns", "max_rows", "watch", "events" ], "title": "PluginSheet", "type": "object" }, "PluginSheetColumn": { "properties": { "label": { "title": "Label", "type": "string" }, "name": { "title": "Name", "type": "string" }, "type": { "enum": [ "text", "number", "boolean" ], "title": "Type", "type": "string" } }, "required": [ "name", "label", "type" ], "title": "PluginSheetColumn", "type": "object" }, "PluginSheetEventKeys": { "description": "The keys a rule's plugin-event trigger names for this sheet.", "properties": { "row_added": { "title": "Row Added", "type": "string" }, "row_changed": { "title": "Row Changed", "type": "string" } }, "required": [ "row_added", "row_changed" ], "title": "PluginSheetEventKeys", "type": "object" }, "PluginSheetTab": { "properties": { "sheet_gid": { "title": "Sheet Gid", "type": "integer" }, "title": { "title": "Title", "type": "string" } }, "required": [ "sheet_gid", "title" ], "title": "PluginSheetTab", "type": "object" }, "PluginSheetTabAdd": { "additionalProperties": false, "properties": { "sheet_gid": { "minimum": 0.0, "title": "Sheet Gid", "type": "integer" } }, "required": [ "sheet_gid" ], "title": "PluginSheetTabAdd", "type": "object" }, "PluginSheetUpdate": { "additionalProperties": false, "description": "Which tab, header row and key column a picked sheet uses. A change\nstarts a new baseline: the next read sends no row events.", "properties": { "clear_key_column": { "default": false, "title": "Clear Key Column", "type": "boolean" }, "header_row": { "anyOf": [ { "maximum": 1000.0, "minimum": 1.0, "type": "integer" }, { "type": "null" } ], "title": "Header Row" }, "key_column": { "anyOf": [ { "pattern": "^\\w{1,100}$", "type": "string" }, { "type": "null" } ], "title": "Key Column" }, "sheet_gid": { "anyOf": [ { "minimum": 0.0, "type": "integer" }, { "type": "null" } ], "title": "Sheet Gid" } }, "title": "PluginSheetUpdate", "type": "object" }, "PluginSheetWatch": { "description": "Whether Google tells Tidy when the spreadsheet changes. ``failed``\ncarries Google's reason; the hourly renewal and Read now try again.", "properties": { "checked_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Checked At" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Error" }, "expires_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Expires At" }, "status": { "enum": [ "pending", "watching", "failed" ], "title": "Status", "type": "string" } }, "required": [ "status" ], "title": "PluginSheetWatch", "type": "object" }, "PluginSheetsPickRequest": { "additionalProperties": false, "properties": { "desktop": { "default": false, "title": "Desktop", "type": "boolean" }, "return_to": { "maxLength": 2000, "minLength": 1, "title": "Return To", "type": "string" } }, "required": [ "return_to" ], "title": "PluginSheetsPickRequest", "type": "object" }, "PluginSheetsPickResponse": { "properties": { "authorization_url": { "title": "Authorization Url", "type": "string" }, "state": { "title": "State", "type": "string" } }, "required": [ "authorization_url", "state" ], "title": "PluginSheetsPickResponse", "type": "object" }, "PluginSheetsResponse": { "properties": { "can_edit": { "title": "Can Edit", "type": "boolean" }, "drive_connected": { "title": "Drive Connected", "type": "boolean" }, "plugin_id": { "title": "Plugin Id", "type": "string" }, "sheets": { "items": { "$ref": "#/components/schemas/PluginSheet" }, "title": "Sheets", "type": "array" } }, "required": [ "plugin_id", "can_edit", "drive_connected", "sheets" ], "title": "PluginSheetsResponse", "type": "object" }, "PluginShipment": { "properties": { "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "delivered_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Delivered At" }, "delivery_kind": { "enum": [ "scoped_token", "env_key", "stdio_config", "env_binding" ], "title": "Delivery Kind", "type": "string" }, "employee_account_id": { "title": "Employee Account Id", "type": "string" }, "expires_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Expires At" }, "grant_id": { "title": "Grant Id", "type": "string" }, "harness_activated": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Harness Activated" }, "id": { "title": "Id", "type": "string" }, "plugin_id": { "title": "Plugin Id", "type": "string" }, "push_job_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Push Job Id" }, "revoked_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Revoked At" }, "tenant_id": { "title": "Tenant Id", "type": "string" }, "workshop_id": { "title": "Workshop Id", "type": "string" } }, "required": [ "id", "tenant_id", "plugin_id", "grant_id", "employee_account_id", "workshop_id", "delivery_kind", "created_at" ], "title": "PluginShipment", "type": "object" }, "PluginSignInStart": { "description": "Sign a built-in API in with its provider (TIDY-19604 F8T): a new\nconnection, or ``plugin_id`` signed in again as the same account.", "properties": { "desktop": { "default": false, "title": "Desktop", "type": "boolean" }, "kind": { "maxLength": 64, "minLength": 1, "title": "Kind", "type": "string" }, "plugin_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Plugin Id" }, "return_to": { "anyOf": [ { "maxLength": 2000, "type": "string" }, { "type": "null" } ], "title": "Return To" } }, "required": [ "kind" ], "title": "PluginSignInStart", "type": "object" }, "PluginSignInStartResponse": { "description": "The provider's authorize URL (on desktop, the launch page) and its\none-shot state.", "properties": { "authorization_url": { "title": "Authorization Url", "type": "string" }, "state": { "title": "State", "type": "string" } }, "required": [ "authorization_url", "state" ], "title": "PluginSignInStartResponse", "type": "object" }, "PluginsResponse": { "properties": { "plugins": { "items": { "$ref": "#/components/schemas/Plugin" }, "title": "Plugins", "type": "array" } }, "required": [ "plugins" ], "title": "PluginsResponse", "type": "object" }, "PodcastAutoDownloadRequest": { "properties": { "network_type": { "default": "wifi", "pattern": "^(wifi|cellular|unknown)$", "title": "Network Type", "type": "string" } }, "title": "PodcastAutoDownloadRequest", "type": "object" }, "PodcastAutoDownloadResponse": { "properties": { "attempted": { "default": 0, "title": "Attempted", "type": "integer" }, "downloaded": { "default": 0, "title": "Downloaded", "type": "integer" }, "errors": { "items": { "additionalProperties": { "type": "string" }, "type": "object" }, "title": "Errors", "type": "array" }, "failed": { "default": 0, "title": "Failed", "type": "integer" }, "skipped": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Skipped" } }, "title": "PodcastAutoDownloadResponse", "type": "object" }, "PodcastCutCreateRequest": { "description": "Capture request — minimal shape per the S5 AC.\n\nNote that ``trailing_window_seconds``, ``tags``, and ``personal_dictation``\nhave been REMOVED from the create body: window is computed at\nmaterialization using the user's preferences; tags are extracted by the AI;\nDeep Cut dictation is submitted via ``/cuts/{id}/finalize-deep-cut``.\n\nEpisode reference is polymorphic (TIDY-10932 / R24): a cut targets EITHER a\nglobal episode (``subscription_id`` + ``episode_id``) OR a personal episode\n(``personal_episode_id``), never both. The DB one-of CHECK is the hard\nguard; the service validates the request shape before the insert.", "properties": { "capture_mode": { "enum": [ "quick", "deep" ], "title": "Capture Mode", "type": "string" }, "captured_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Captured At" }, "client_cut_id": { "anyOf": [ { "maxLength": 36, "minLength": 36, "type": "string" }, { "type": "null" } ], "title": "Client Cut Id" }, "episode_id": { "anyOf": [ { "maxLength": 36, "minLength": 36, "type": "string" }, { "type": "null" } ], "title": "Episode Id" }, "fingerprint_match_confidence": { "anyOf": [ { "maximum": 1.0, "minimum": 0.0, "type": "number" }, { "type": "null" } ], "title": "Fingerprint Match Confidence" }, "fingerprint_offset_seconds": { "anyOf": [ { "maximum": 7200.0, "minimum": -7200.0, "type": "number" }, { "type": "null" } ], "title": "Fingerprint Offset Seconds" }, "fingerprint_query": { "anyOf": [ { "maxLength": 262144, "type": "string" }, { "type": "null" } ], "title": "Fingerprint Query" }, "fingerprint_query_start_seconds": { "anyOf": [ { "minimum": 0.0, "type": "number" }, { "type": "null" } ], "title": "Fingerprint Query Start Seconds" }, "location": { "anyOf": [ { "maxLength": 500, "type": "string" }, { "type": "null" } ], "title": "Location" }, "personal_episode_id": { "anyOf": [ { "maxLength": 36, "minLength": 36, "type": "string" }, { "type": "null" } ], "title": "Personal Episode Id" }, "queue_item_id": { "anyOf": [ { "maxLength": 36, "minLength": 36, "type": "string" }, { "type": "null" } ], "title": "Queue Item Id" }, "subscription_id": { "anyOf": [ { "maxLength": 36, "minLength": 36, "type": "string" }, { "type": "null" } ], "title": "Subscription Id" }, "timestamp_seconds": { "minimum": 0.0, "title": "Timestamp Seconds", "type": "integer" } }, "required": [ "capture_mode", "timestamp_seconds" ], "title": "PodcastCutCreateRequest", "type": "object" }, "PodcastCutDeleteResponse": { "properties": { "deleted": { "title": "Deleted", "type": "boolean" }, "id": { "title": "Id", "type": "string" } }, "required": [ "deleted", "id" ], "title": "PodcastCutDeleteResponse", "type": "object" }, "PodcastCutListResponse": { "properties": { "count": { "title": "Count", "type": "integer" }, "cuts": { "items": { "$ref": "#/components/schemas/PodcastCutResponse" }, "title": "Cuts", "type": "array" } }, "required": [ "count" ], "title": "PodcastCutListResponse", "type": "object" }, "PodcastCutResponse": { "properties": { "account_id": { "title": "Account Id", "type": "string" }, "canonical_window_end_seconds": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Canonical Window End Seconds" }, "canonical_window_start_seconds": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Canonical Window Start Seconds" }, "capture_mode": { "enum": [ "quick", "deep" ], "title": "Capture Mode", "type": "string" }, "captured_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Captured At" }, "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "deleted_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Deleted At" }, "dictation_unavailable": { "default": false, "title": "Dictation Unavailable", "type": "boolean" }, "episode_title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Episode Title" }, "external_episode_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "External Episode Id" }, "failure_message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Failure Message" }, "failure_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Failure Reason" }, "fingerprint_match_confidence": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "title": "Fingerprint Match Confidence" }, "id": { "title": "Id", "type": "string" }, "location": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Location" }, "materialized_note_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Materialized Note Id" }, "personal_episode_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Personal Episode Id" }, "queue_item_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Queue Item Id" }, "status": { "enum": [ "captured", "awaiting_transcript", "extracting", "extraction_failed", "materialized", "materialization_failed" ], "title": "Status", "type": "string" }, "subscription_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Subscription Id" }, "subscription_title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Subscription Title" }, "tenant_id": { "title": "Tenant Id", "type": "string" }, "timestamp_seconds": { "title": "Timestamp Seconds", "type": "integer" }, "transcript_version_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Transcript Version Id" }, "trigger_count": { "default": 1, "title": "Trigger Count", "type": "integer" }, "updated_at": { "format": "date-time", "title": "Updated At", "type": "string" }, "user_window_end_seconds": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "User Window End Seconds" }, "user_window_start_seconds": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "User Window Start Seconds" }, "window_end_seconds": { "title": "Window End Seconds", "type": "integer" }, "window_start_seconds": { "title": "Window Start Seconds", "type": "integer" } }, "required": [ "id", "tenant_id", "account_id", "capture_mode", "timestamp_seconds", "window_start_seconds", "window_end_seconds", "status", "created_at", "updated_at" ], "title": "PodcastCutResponse", "type": "object" }, "PodcastDiscoveryCategoriesResponse": { "description": "Podcast discovery categories response payload.", "properties": { "categories": { "items": { "$ref": "#/components/schemas/PodcastDiscoveryCategoryResponse" }, "title": "Categories", "type": "array" } }, "title": "PodcastDiscoveryCategoriesResponse", "type": "object" }, "PodcastDiscoveryCategoryResponse": { "description": "Podcast discovery category payload.", "properties": { "id": { "title": "Id", "type": "integer" }, "name": { "title": "Name", "type": "string" } }, "required": [ "id", "name" ], "title": "PodcastDiscoveryCategoryResponse", "type": "object" }, "PodcastDiscoveryTrendingListResponse": { "description": "Podcast discovery trending response payload.", "properties": { "trending": { "items": { "$ref": "#/components/schemas/PodcastDiscoveryTrendingResponse" }, "title": "Trending", "type": "array" } }, "title": "PodcastDiscoveryTrendingListResponse", "type": "object" }, "PodcastDiscoveryTrendingResponse": { "description": "Podcast discovery trending payload.", "properties": { "artwork_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Artwork Url" }, "author": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Author" }, "category_id": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Category Id" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "feed_id": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Feed Id" }, "id": { "title": "Id", "type": "integer" }, "rss_feed_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Rss Feed Url" }, "title": { "title": "Title", "type": "string" }, "trend_score": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Trend Score" } }, "required": [ "id", "title" ], "title": "PodcastDiscoveryTrendingResponse", "type": "object" }, "PodcastDraftCreateRequest": { "properties": { "content_json": { "additionalProperties": true, "title": "Content Json", "type": "object" }, "generation_options": { "$ref": "#/components/schemas/PodcastDraftGenerationOptions" }, "plain_text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Plain Text" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Title" } }, "title": "PodcastDraftCreateRequest", "type": "object" }, "PodcastDraftGenerationOptions": { "properties": { "additional_research": { "default": false, "title": "Additional Research", "type": "boolean" }, "custom_instructions": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Custom Instructions" }, "fidelity": { "default": "summarized", "enum": [ "verbatim", "summarized" ], "title": "Fidelity", "type": "string" }, "voice_mode": { "default": "dual", "enum": [ "single", "dual" ], "title": "Voice Mode", "type": "string" }, "voice_settings": { "additionalProperties": true, "title": "Voice Settings", "type": "object" } }, "title": "PodcastDraftGenerationOptions", "type": "object" }, "PodcastDraftListResponse": { "properties": { "drafts": { "items": { "$ref": "#/components/schemas/PodcastDraftResponse" }, "title": "Drafts", "type": "array" } }, "required": [ "drafts" ], "title": "PodcastDraftListResponse", "type": "object" }, "PodcastDraftPatchRequest": { "properties": { "content_json": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Content Json" }, "generation_options": { "anyOf": [ { "$ref": "#/components/schemas/PodcastDraftGenerationOptions" }, { "type": "null" } ] }, "plain_text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Plain Text" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Title" } }, "title": "PodcastDraftPatchRequest", "type": "object" }, "PodcastDraftResponse": { "properties": { "content_json": { "additionalProperties": true, "title": "Content Json", "type": "object" }, "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "error_message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error Message" }, "generation_job_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Generation Job Id" }, "generation_options": { "$ref": "#/components/schemas/PodcastDraftGenerationOptions" }, "id": { "title": "Id", "type": "string" }, "plain_text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Plain Text" }, "status": { "title": "Status", "type": "string" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Title" }, "updated_at": { "format": "date-time", "title": "Updated At", "type": "string" } }, "required": [ "id", "generation_options", "status", "created_at", "updated_at" ], "title": "PodcastDraftResponse", "type": "object" }, "PodcastDraftSubmitResponse": { "properties": { "draft": { "$ref": "#/components/schemas/PodcastDraftResponse" }, "estimated_duration_seconds": { "title": "Estimated Duration Seconds", "type": "integer" }, "job_id": { "title": "Job Id", "type": "string" }, "status": { "title": "Status", "type": "string" } }, "required": [ "draft", "job_id", "status", "estimated_duration_seconds" ], "title": "PodcastDraftSubmitResponse", "type": "object" }, "PodcastEphemeralSyncRequest": { "properties": { "episode_guid": { "maxLength": 2000, "minLength": 1, "title": "Episode Guid", "type": "string" }, "rss_feed_url": { "maxLength": 2000, "minLength": 1, "title": "Rss Feed Url", "type": "string" } }, "required": [ "rss_feed_url", "episode_guid" ], "title": "PodcastEphemeralSyncRequest", "type": "object" }, "PodcastEphemeralSyncResponse": { "properties": { "episode_id": { "title": "Episode Id", "type": "string" }, "subscription_id": { "title": "Subscription Id", "type": "string" } }, "required": [ "subscription_id", "episode_id" ], "title": "PodcastEphemeralSyncResponse", "type": "object" }, "PodcastEpisodeDownloadRequest": { "properties": { "force": { "default": false, "title": "Force", "type": "boolean" }, "network_type": { "default": "wifi", "pattern": "^(wifi|cellular|unknown)$", "title": "Network Type", "type": "string" } }, "title": "PodcastEpisodeDownloadRequest", "type": "object" }, "PodcastEpisodeDownloadResponse": { "properties": { "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Reason" }, "size_bytes": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Size Bytes" }, "status": { "title": "Status", "type": "string" }, "storage_path": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Storage Path" } }, "required": [ "status" ], "title": "PodcastEpisodeDownloadResponse", "type": "object" }, "PodcastEpisodeId": { "description": "Typed primitive ID for podcast_episodes (prefix 'D').", "examples": [ "D-550e8400-e29b-41d4-a716-446655440000" ], "pattern": "^D-[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "title": "PodcastEpisodeId", "type": "string", "x-tidy-typed-id-prefix": "D", "x-tidy-typed-id-table": "podcast_episodes" }, "PodcastEpisodeItem": { "description": "Episode summary returned by list endpoint.", "properties": { "audio_size_bytes": { "title": "Audio Size Bytes", "type": "integer" }, "audio_url": { "title": "Audio Url", "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Description" }, "duration_seconds": { "title": "Duration Seconds", "type": "integer" }, "fidelity": { "title": "Fidelity", "type": "string" }, "generation_job_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Generation Job Id" }, "id": { "title": "Id", "type": "string" }, "mode": { "title": "Mode", "type": "string" }, "note_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Note Id" }, "published_at": { "format": "date-time", "title": "Published At", "type": "string" }, "source_type": { "title": "Source Type", "type": "string" }, "title": { "title": "Title", "type": "string" } }, "required": [ "id", "title", "source_type", "mode", "fidelity", "duration_seconds", "audio_size_bytes", "published_at", "audio_url" ], "title": "PodcastEpisodeItem", "type": "object" }, "PodcastEpisodeListResponse": { "description": "Episode list response.", "properties": { "episodes": { "items": { "$ref": "#/components/schemas/PodcastEpisodeItem" }, "title": "Episodes", "type": "array" } }, "required": [ "episodes" ], "title": "PodcastEpisodeListResponse", "type": "object" }, "PodcastEpisodePlaybackUpdateRequest": { "properties": { "is_completed": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is Completed" }, "playback_position_seconds": { "anyOf": [ { "minimum": 0.0, "type": "integer" }, { "type": "null" } ], "title": "Playback Position Seconds" } }, "title": "PodcastEpisodePlaybackUpdateRequest", "type": "object" }, "PodcastEpisodeRef": { "properties": { "episode_id": { "description": "The episode id from a subscription's episode list (not a corpus episode id).", "format": "uuid", "title": "Episode Id", "type": "string" }, "subscription_id": { "format": "uuid", "title": "Subscription Id", "type": "string" } }, "required": [ "subscription_id", "episode_id" ], "title": "PodcastEpisodeRef", "type": "object" }, "PodcastEpisodeSummary": { "description": "Summary of a related podcast episode.", "properties": { "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Episode description", "title": "Description" }, "duration_seconds": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Duration in seconds", "title": "Duration Seconds" }, "id": { "description": "Podcast episode ID (UUID)", "title": "Id", "type": "string" }, "link_direction": { "default": "outgoing", "description": "Direction of the edge relative to the primitive you asked about: 'outgoing' (the edge starts there and points at this one) or 'incoming' (this one points AT it). TIDY-15687.", "title": "Link Direction", "type": "string" }, "link_type": { "description": "How this episode is related", "title": "Link Type", "type": "string" }, "published_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "description": "When published", "title": "Published At" }, "title": { "description": "Episode title", "title": "Title", "type": "string" }, "type": { "const": "podcast_episode", "default": "podcast_episode", "title": "Type", "type": "string" } }, "required": [ "id", "title", "link_type" ], "title": "PodcastEpisodeSummary", "type": "object" }, "PodcastExternalEpisodeListResponse": { "properties": { "episodes": { "items": { "$ref": "#/components/schemas/PodcastExternalEpisodeResponse" }, "title": "Episodes", "type": "array" } }, "required": [ "episodes" ], "title": "PodcastExternalEpisodeListResponse", "type": "object" }, "PodcastExternalEpisodeResponse": { "properties": { "artwork_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Artwork Url" }, "audio_length_bytes": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Audio Length Bytes" }, "audio_url": { "title": "Audio Url", "type": "string" }, "author": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Author" }, "created_at": { "title": "Created At", "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "download_error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Download Error" }, "download_progress_pct": { "default": 0, "title": "Download Progress Pct", "type": "integer" }, "download_status": { "title": "Download Status", "type": "string" }, "downloaded_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Downloaded At" }, "downloaded_storage_path": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Downloaded Storage Path" }, "duration_seconds": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Duration Seconds" }, "explicit": { "title": "Explicit", "type": "boolean" }, "generated_episode_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Generated Episode Id" }, "guid": { "title": "Guid", "type": "string" }, "id": { "title": "Id", "type": "string" }, "is_completed": { "title": "Is Completed", "type": "boolean" }, "match_preview": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Match Preview" }, "match_sources": { "items": { "type": "string" }, "title": "Match Sources", "type": "array" }, "offline_audio_url": { "title": "Offline Audio Url", "type": "string" }, "playback_position_seconds": { "title": "Playback Position Seconds", "type": "integer" }, "published_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Published At" }, "related_cut_count": { "default": 0, "title": "Related Cut Count", "type": "integer" }, "subscription_id": { "title": "Subscription Id", "type": "string" }, "title": { "title": "Title", "type": "string" }, "transcript_note_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Transcript Note Id" }, "updated_at": { "title": "Updated At", "type": "string" }, "webpage_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Webpage Url" } }, "required": [ "id", "subscription_id", "guid", "title", "audio_url", "explicit", "playback_position_seconds", "is_completed", "download_status", "offline_audio_url", "created_at", "updated_at" ], "title": "PodcastExternalEpisodeResponse", "type": "object" }, "PodcastFeedArtworkRequest": { "description": "Set the show's cover art from a file, or from the caller's profile photo.\n\nA file id or a named source rather than a URL: the artwork must be bytes\nTidy already holds for this caller, so pointing the feed at an arbitrary URL\n— including one that later 404s or serves something else — is not\nrepresentable (TIDY-15712).\n\nTIDY-17834 widened this additively: `source` defaults to `\"file\"`, so the\npre-existing `{\"file_id\": \"...\"}` body from the settings UI keeps validating\nunchanged while the four-mode clients (S6/S7) send the discriminated form.", "properties": { "file_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "File Id" }, "source": { "default": "file", "enum": [ "file", "profile_avatar" ], "title": "Source", "type": "string" } }, "title": "PodcastFeedArtworkRequest", "type": "object" }, "PodcastFeedRegenerateResponse": { "description": "Token regeneration response.", "properties": { "feed_url": { "title": "Feed Url", "type": "string" }, "token": { "title": "Token", "type": "string" } }, "required": [ "feed_url", "token" ], "title": "PodcastFeedRegenerateResponse", "type": "object" }, "PodcastFeedSettingsResponse": { "description": "Authenticated podcast feed settings response.", "properties": { "artwork_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Artwork Url" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "feed_url": { "title": "Feed Url", "type": "string" }, "is_active": { "default": true, "title": "Is Active", "type": "boolean" }, "title": { "title": "Title", "type": "string" }, "token": { "title": "Token", "type": "string" } }, "required": [ "feed_url", "token", "title" ], "title": "PodcastFeedSettingsResponse", "type": "object" }, "PodcastGenerateRequest": { "description": "Payload for enqueueing podcast generation.\n\n``bundle`` (TIDY-15702 / D15) WIDENS the source model of the existing\npipeline — it is not a second audio path. A bundle's material is assembled\nby the shared context assembler (F3 S3) and handed to the same two-pass\nscript generation, host mode, fidelity, voice lane and audio assembly every\nother source uses.", "properties": { "custom_instructions": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Custom Instructions" }, "fidelity": { "default": "summarized", "enum": [ "verbatim", "summarized" ], "title": "Fidelity", "type": "string" }, "include_documents": { "default": false, "title": "Include Documents", "type": "boolean" }, "include_research": { "default": false, "title": "Include Research", "type": "boolean" }, "include_urls": { "default": false, "title": "Include Urls", "type": "boolean" }, "mode": { "default": "dual", "enum": [ "single", "dual", "research" ], "title": "Mode", "type": "string" }, "research_prompt": { "anyOf": [ { "maxLength": 2000, "type": "string" }, { "type": "null" } ], "description": "What the RESEARCH phase should look for (TIDY-17831 / D1). It steers question planning only; `custom_instructions` remains the sole script/global steering field. Sending it — even blank — puts this request on the dedicated contract, so general instructions never leak into web-search questions. Setting it while `include_research` is false is refused, not dropped.", "title": "Research Prompt" }, "research_prompt_mode": { "anyOf": [ { "enum": [ "dedicated", "legacy_custom" ], "type": "string" }, { "type": "null" } ], "description": "Server-owned classification of `research_prompt`. Callers leave it unset: a request that names `research_prompt` is `dedicated`, one that provably omits it (an older client) is `legacy_custom` and keeps the pre-TIDY-17831 behavior of steering research from `custom_instructions`. Set explicitly only when replaying a persisted job.", "title": "Research Prompt Mode" }, "source_id": { "title": "Source Id", "type": "string" }, "source_ids": { "items": { "type": "string" }, "title": "Source Ids", "type": "array" }, "source_type": { "enum": [ "email", "note", "bundle" ], "title": "Source Type", "type": "string" }, "voice_settings": { "additionalProperties": true, "title": "Voice Settings", "type": "object" } }, "required": [ "source_type", "source_id" ], "title": "PodcastGenerateRequest", "type": "object" }, "PodcastGenerateResponse": { "description": "Accepted response for generation request.", "properties": { "estimated_duration_seconds": { "title": "Estimated Duration Seconds", "type": "integer" }, "job_id": { "title": "Job Id", "type": "string" }, "status": { "title": "Status", "type": "string" } }, "required": [ "job_id", "status", "estimated_duration_seconds" ], "title": "PodcastGenerateResponse", "type": "object" }, "PodcastJobStatusResponse": { "description": "Current status for a generation job.\n\n``job_id`` is an internal job identifier (not a public primitive)\nso it stays bare. ``episode_id`` is the public podcast_episode id\n(D-).", "properties": { "completed_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Completed At" }, "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "episode_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Episode Id" }, "error_message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Error Message" }, "job_id": { "title": "Job Id", "type": "string" }, "progress_pct": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": 0, "title": "Progress Pct" }, "started_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Started At" }, "status": { "title": "Status", "type": "string" } }, "required": [ "job_id", "status", "created_at" ], "title": "PodcastJobStatusResponse", "type": "object" }, "PodcastOpmlImportFailure": { "properties": { "fallback_attempted": { "default": false, "title": "Fallback Attempted", "type": "boolean" }, "fallback_succeeded": { "default": false, "title": "Fallback Succeeded", "type": "boolean" }, "reason": { "title": "Reason", "type": "string" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Title" }, "url": { "title": "Url", "type": "string" } }, "required": [ "url", "reason" ], "title": "PodcastOpmlImportFailure", "type": "object" }, "PodcastOpmlImportJobResponse": { "description": "Returned by POST /import (202) and GET /import/{job_id}.\n\nContract consumed by web (TIDY-12258) and mobile (TIDY-12260):\nPOST returns this with status='pending' and a job_id immediately; clients\npoll the GET endpoint until status is 'completed' or 'failed'.", "properties": { "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error" }, "existing": { "title": "Existing", "type": "integer" }, "failed": { "title": "Failed", "type": "integer" }, "failures": { "items": { "$ref": "#/components/schemas/PodcastOpmlImportFailure" }, "title": "Failures", "type": "array" }, "imported": { "title": "Imported", "type": "integer" }, "job_id": { "title": "Job Id", "type": "string" }, "processed": { "title": "Processed", "type": "integer" }, "status": { "title": "Status", "type": "string" }, "total": { "title": "Total", "type": "integer" } }, "required": [ "job_id", "status", "total", "processed", "imported", "existing", "failed", "failures" ], "title": "PodcastOpmlImportJobResponse", "type": "object" }, "PodcastPlaylistApplyRequest": { "properties": { "mode": { "description": "top = play next (right after what is playing), bottom = play last (after everything queued), replace = the playlist becomes the queue.", "enum": [ "top", "bottom", "replace" ], "title": "Mode", "type": "string" } }, "required": [ "mode" ], "title": "PodcastPlaylistApplyRequest", "type": "object" }, "PodcastPlaylistApplyResponse": { "properties": { "added_count": { "title": "Added Count", "type": "integer" }, "count": { "title": "Count", "type": "integer" }, "current_item_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Current Item Id" }, "items": { "items": { "$ref": "#/components/schemas/PodcastQueueItemResponse" }, "title": "Items", "type": "array" }, "mode": { "title": "Mode", "type": "string" }, "playlist_id": { "title": "Playlist Id", "type": "string" }, "skipped_count": { "title": "Skipped Count", "type": "integer" } }, "required": [ "playlist_id", "mode", "added_count", "skipped_count", "items", "count" ], "title": "PodcastPlaylistApplyResponse", "type": "object" }, "PodcastPlaylistCreateRequest": { "properties": { "description": { "anyOf": [ { "maxLength": 2000, "type": "string" }, { "type": "null" } ], "title": "Description" }, "episodes": { "items": { "$ref": "#/components/schemas/PodcastEpisodeRef" }, "maxItems": 200, "title": "Episodes", "type": "array" }, "name": { "maxLength": 200, "minLength": 1, "title": "Name", "type": "string" } }, "required": [ "name" ], "title": "PodcastPlaylistCreateRequest", "type": "object" }, "PodcastPlaylistDeleteResponse": { "properties": { "deleted": { "title": "Deleted", "type": "boolean" } }, "required": [ "deleted" ], "title": "PodcastPlaylistDeleteResponse", "type": "object" }, "PodcastPlaylistItemResponse": { "properties": { "artwork_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Artwork Url" }, "author": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Author" }, "created_at": { "title": "Created At", "type": "string" }, "duration_seconds": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Duration Seconds" }, "episode_id": { "title": "Episode Id", "type": "string" }, "id": { "title": "Id", "type": "string" }, "playlist_id": { "title": "Playlist Id", "type": "string" }, "position": { "title": "Position", "type": "integer" }, "published_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Published At" }, "subscription_id": { "title": "Subscription Id", "type": "string" }, "title": { "title": "Title", "type": "string" } }, "required": [ "id", "playlist_id", "subscription_id", "episode_id", "title", "position", "created_at" ], "title": "PodcastPlaylistItemResponse", "type": "object" }, "PodcastPlaylistItemsAddRequest": { "properties": { "episodes": { "items": { "$ref": "#/components/schemas/PodcastEpisodeRef" }, "maxItems": 200, "minItems": 1, "title": "Episodes", "type": "array" } }, "required": [ "episodes" ], "title": "PodcastPlaylistItemsAddRequest", "type": "object" }, "PodcastPlaylistListResponse": { "properties": { "count": { "title": "Count", "type": "integer" }, "playlists": { "items": { "$ref": "#/components/schemas/PodcastPlaylistResponse" }, "title": "Playlists", "type": "array" } }, "required": [ "playlists", "count" ], "title": "PodcastPlaylistListResponse", "type": "object" }, "PodcastPlaylistResponse": { "properties": { "created_at": { "title": "Created At", "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "id": { "title": "Id", "type": "string" }, "item_count": { "title": "Item Count", "type": "integer" }, "items": { "items": { "$ref": "#/components/schemas/PodcastPlaylistItemResponse" }, "title": "Items", "type": "array" }, "name": { "title": "Name", "type": "string" }, "total_duration_seconds": { "title": "Total Duration Seconds", "type": "integer" }, "updated_at": { "title": "Updated At", "type": "string" } }, "required": [ "id", "name", "item_count", "total_duration_seconds", "created_at", "updated_at" ], "title": "PodcastPlaylistResponse", "type": "object" }, "PodcastPreferencesPatchRequest": { "properties": { "auto_download_default": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Auto Download Default" }, "auto_download_keep_newest_default": { "anyOf": [ { "maximum": 100.0, "minimum": 1.0, "type": "integer" }, { "type": "null" } ], "title": "Auto Download Keep Newest Default" }, "custom_ai_instructions": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Custom Ai Instructions" }, "cut_length_seconds": { "anyOf": [ { "maximum": 120.0, "minimum": 5.0, "type": "integer" }, { "type": "null" } ], "title": "Cut Length Seconds" }, "cut_max_total_seconds": { "anyOf": [ { "maximum": 900.0, "minimum": 5.0, "type": "integer" }, { "type": "null" } ], "title": "Cut Max Total Seconds" }, "cut_post_buffer_seconds": { "anyOf": [ { "maximum": 600.0, "minimum": 5.0, "type": "integer" }, { "type": "null" } ], "title": "Cut Post Buffer Seconds" }, "cut_pre_buffer_seconds": { "anyOf": [ { "maximum": 300.0, "minimum": 0.0, "type": "integer" }, { "type": "null" } ], "title": "Cut Pre Buffer Seconds" }, "cut_successive_append_threshold_seconds": { "anyOf": [ { "maximum": 900.0, "minimum": 0.0, "type": "integer" }, { "type": "null" } ], "title": "Cut Successive Append Threshold Seconds" }, "default_template_id": { "anyOf": [ { "maxLength": 36, "minLength": 36, "type": "string" }, { "type": "null" } ], "title": "Default Template Id" }, "extraction_mode": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Extraction Mode" }, "lead_buffer_seconds": { "anyOf": [ { "maximum": 120.0, "minimum": 5.0, "type": "integer" }, { "type": "null" } ], "title": "Lead Buffer Seconds" }, "resume_on_submit": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Resume On Submit" }, "tap_delay_compensation_seconds": { "anyOf": [ { "maximum": 30.0, "minimum": 0.0, "type": "integer" }, { "type": "null" } ], "title": "Tap Delay Compensation Seconds" }, "trail_buffer_seconds": { "anyOf": [ { "maximum": 120.0, "minimum": 5.0, "type": "integer" }, { "type": "null" } ], "title": "Trail Buffer Seconds" } }, "title": "PodcastPreferencesPatchRequest", "type": "object" }, "PodcastPreferencesResponse": { "properties": { "auto_download_default": { "title": "Auto Download Default", "type": "boolean" }, "auto_download_keep_newest_default": { "title": "Auto Download Keep Newest Default", "type": "integer" }, "created_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Created At" }, "custom_ai_instructions": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Custom Ai Instructions" }, "cut_length_seconds": { "title": "Cut Length Seconds", "type": "integer" }, "cut_max_total_seconds": { "title": "Cut Max Total Seconds", "type": "integer" }, "cut_post_buffer_seconds": { "title": "Cut Post Buffer Seconds", "type": "integer" }, "cut_pre_buffer_seconds": { "title": "Cut Pre Buffer Seconds", "type": "integer" }, "cut_successive_append_threshold_seconds": { "title": "Cut Successive Append Threshold Seconds", "type": "integer" }, "default_template_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Default Template Id" }, "extraction_mode": { "title": "Extraction Mode", "type": "string" }, "lead_buffer_seconds": { "title": "Lead Buffer Seconds", "type": "integer" }, "resume_on_submit": { "title": "Resume On Submit", "type": "boolean" }, "tap_delay_compensation_seconds": { "title": "Tap Delay Compensation Seconds", "type": "integer" }, "trail_buffer_seconds": { "title": "Trail Buffer Seconds", "type": "integer" }, "updated_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Updated At" } }, "required": [ "tap_delay_compensation_seconds", "cut_length_seconds", "lead_buffer_seconds", "trail_buffer_seconds", "resume_on_submit", "cut_pre_buffer_seconds", "cut_post_buffer_seconds", "cut_max_total_seconds", "cut_successive_append_threshold_seconds", "extraction_mode", "auto_download_default", "auto_download_keep_newest_default" ], "title": "PodcastPreferencesResponse", "type": "object" }, "PodcastPurgeResponse": { "properties": { "purged": { "default": 0, "title": "Purged", "type": "integer" }, "skipped": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Skipped" } }, "title": "PodcastPurgeResponse", "type": "object" }, "PodcastQueueCompleteRequest": { "properties": { "retain_position_seconds": { "anyOf": [ { "minimum": 0.0, "type": "integer" }, { "type": "null" } ], "title": "Retain Position Seconds" } }, "title": "PodcastQueueCompleteRequest", "type": "object" }, "PodcastQueueCompleteResponse": { "properties": { "already_completed": { "default": false, "title": "Already Completed", "type": "boolean" }, "completed_episode_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Completed Episode Id" }, "count": { "title": "Count", "type": "integer" }, "current_item_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Current Item Id" }, "items": { "items": { "$ref": "#/components/schemas/PodcastQueueItemResponse" }, "title": "Items", "type": "array" } }, "required": [ "items", "count" ], "title": "PodcastQueueCompleteResponse", "type": "object" }, "PodcastQueueCurrentRequest": { "properties": { "queue_item_id": { "maxLength": 36, "minLength": 36, "title": "Queue Item Id", "type": "string" } }, "required": [ "queue_item_id" ], "title": "PodcastQueueCurrentRequest", "type": "object" }, "PodcastQueueInsertRequest": { "properties": { "episode_id": { "maxLength": 36, "minLength": 36, "title": "Episode Id", "type": "string" }, "insert_mode": { "default": "add_queue", "pattern": "^(play_now|play_first|play_next|play_last|add_queue|add_top|add_bottom)$", "title": "Insert Mode", "type": "string" }, "subscription_id": { "maxLength": 36, "minLength": 36, "title": "Subscription Id", "type": "string" } }, "required": [ "subscription_id", "episode_id" ], "title": "PodcastQueueInsertRequest", "type": "object" }, "PodcastQueueItemResponse": { "properties": { "account_id": { "title": "Account Id", "type": "string" }, "artwork_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Artwork Url" }, "audio_url": { "title": "Audio Url", "type": "string" }, "author": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Author" }, "created_at": { "title": "Created At", "type": "string" }, "duration_seconds": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Duration Seconds" }, "episode_id": { "title": "Episode Id", "type": "string" }, "id": { "title": "Id", "type": "string" }, "is_completed": { "default": false, "title": "Is Completed", "type": "boolean" }, "is_current": { "title": "Is Current", "type": "boolean" }, "is_tidy_generated": { "default": false, "title": "Is Tidy Generated", "type": "boolean" }, "offline_audio_url": { "title": "Offline Audio Url", "type": "string" }, "playback_position_seconds": { "title": "Playback Position Seconds", "type": "integer" }, "playback_speed": { "title": "Playback Speed", "type": "number" }, "position": { "title": "Position", "type": "integer" }, "subscription_id": { "title": "Subscription Id", "type": "string" }, "tenant_id": { "title": "Tenant Id", "type": "string" }, "title": { "title": "Title", "type": "string" }, "updated_at": { "title": "Updated At", "type": "string" } }, "required": [ "id", "tenant_id", "account_id", "subscription_id", "episode_id", "title", "audio_url", "offline_audio_url", "playback_position_seconds", "playback_speed", "position", "is_current", "created_at", "updated_at" ], "title": "PodcastQueueItemResponse", "type": "object" }, "PodcastQueueListResponse": { "properties": { "count": { "title": "Count", "type": "integer" }, "current_item_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Current Item Id" }, "items": { "items": { "$ref": "#/components/schemas/PodcastQueueItemResponse" }, "title": "Items", "type": "array" } }, "required": [ "items", "count" ], "title": "PodcastQueueListResponse", "type": "object" }, "PodcastQueueReorderRequest": { "properties": { "item_ids": { "items": { "type": "string" }, "maxItems": 500, "title": "Item Ids", "type": "array" } }, "title": "PodcastQueueReorderRequest", "type": "object" }, "PodcastQueueTranscriptionBatchCreateRequest": { "properties": { "queue_item_ids": { "items": { "type": "string" }, "maxItems": 100, "minItems": 1, "title": "Queue Item Ids", "type": "array" }, "service_name": { "default": "podcast-worker", "maxLength": 100, "minLength": 1, "title": "Service Name", "type": "string" }, "source_type": { "default": "podcast_transcription_batch", "maxLength": 100, "minLength": 1, "title": "Source Type", "type": "string" } }, "title": "PodcastQueueTranscriptionBatchCreateRequest", "type": "object" }, "PodcastQueueTranscriptionBatchItemResponse": { "properties": { "audio_url": { "title": "Audio Url", "type": "string" }, "batch_id": { "title": "Batch Id", "type": "string" }, "completed_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Completed At" }, "created_at": { "title": "Created At", "type": "string" }, "duration_seconds": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Duration Seconds" }, "error_message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error Message" }, "estimated_cost_usd": { "title": "Estimated Cost Usd", "type": "number" }, "external_episode_id": { "title": "External Episode Id", "type": "string" }, "id": { "title": "Id", "type": "string" }, "provider_artifacts": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Provider Artifacts" }, "provider_error_kind": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Provider Error Kind" }, "provider_request_id": { "title": "Provider Request Id", "type": "string" }, "queue_item_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Queue Item Id" }, "status": { "title": "Status", "type": "string" }, "subscription_id": { "title": "Subscription Id", "type": "string" }, "title": { "title": "Title", "type": "string" }, "transcript_json": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Transcript Json" }, "transcript_text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Transcript Text" }, "updated_at": { "title": "Updated At", "type": "string" } }, "required": [ "id", "batch_id", "subscription_id", "external_episode_id", "title", "audio_url", "provider_request_id", "status", "estimated_cost_usd", "created_at", "updated_at" ], "title": "PodcastQueueTranscriptionBatchItemResponse", "type": "object" }, "PodcastQueueTranscriptionBatchListResponse": { "properties": { "batches": { "items": { "$ref": "#/components/schemas/PodcastQueueTranscriptionBatchResponse" }, "title": "Batches", "type": "array" }, "count": { "title": "Count", "type": "integer" } }, "required": [ "batches", "count" ], "title": "PodcastQueueTranscriptionBatchListResponse", "type": "object" }, "PodcastQueueTranscriptionBatchResponse": { "properties": { "account_id": { "title": "Account Id", "type": "string" }, "completed_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Completed At" }, "completed_count": { "title": "Completed Count", "type": "integer" }, "created_at": { "title": "Created At", "type": "string" }, "error_message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error Message" }, "failed_count": { "title": "Failed Count", "type": "integer" }, "id": { "title": "Id", "type": "string" }, "items": { "items": { "$ref": "#/components/schemas/PodcastQueueTranscriptionBatchItemResponse" }, "title": "Items", "type": "array" }, "provider": { "title": "Provider", "type": "string" }, "provider_batch_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Provider Batch Id" }, "provider_error_file_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Provider Error File Id" }, "provider_error_kind": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Provider Error Kind" }, "provider_input_file_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Provider Input File Id" }, "provider_metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Provider Metadata" }, "provider_model": { "title": "Provider Model", "type": "string" }, "provider_output_file_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Provider Output File Id" }, "provider_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Provider Status" }, "requested_count": { "title": "Requested Count", "type": "integer" }, "status": { "title": "Status", "type": "string" }, "submitted_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Submitted At" }, "tenant_id": { "title": "Tenant Id", "type": "string" }, "trace_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Trace Id" }, "updated_at": { "title": "Updated At", "type": "string" } }, "required": [ "id", "tenant_id", "account_id", "provider", "provider_model", "status", "requested_count", "completed_count", "failed_count", "created_at", "updated_at" ], "title": "PodcastQueueTranscriptionBatchResponse", "type": "object" }, "PodcastQueueUpdateRequest": { "properties": { "playback_position_seconds": { "anyOf": [ { "minimum": 0.0, "type": "integer" }, { "type": "null" } ], "title": "Playback Position Seconds" }, "playback_speed": { "anyOf": [ { "maximum": 3.0, "minimum": 0.5, "type": "number" }, { "type": "null" } ], "title": "Playback Speed" } }, "title": "PodcastQueueUpdateRequest", "type": "object" }, "PodcastSearchResponse": { "description": "Podcast discovery response payload.", "properties": { "query": { "title": "Query", "type": "string" }, "resolved_apple_link": { "default": false, "title": "Resolved Apple Link", "type": "boolean" }, "results": { "items": { "$ref": "#/components/schemas/PodcastSearchResultResponse" }, "title": "Results", "type": "array" } }, "required": [ "query" ], "title": "PodcastSearchResponse", "type": "object" }, "PodcastSearchResultResponse": { "description": "Single podcast discovery result.", "properties": { "apple_podcast_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Apple Podcast Url" }, "artwork_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Artwork Url" }, "author": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Author" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "itunes_id": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Itunes Id" }, "podcast_index_id": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Podcast Index Id" }, "rss_feed_url": { "title": "Rss Feed Url", "type": "string" }, "source": { "enum": [ "podcast_index", "podcast_index_public", "itunes_lookup" ], "title": "Source", "type": "string" }, "title": { "title": "Title", "type": "string" } }, "required": [ "title", "rss_feed_url", "source" ], "title": "PodcastSearchResultResponse", "type": "object" }, "PodcastSourceMetadataResponse": { "description": "Metadata used by the generation modal to show source context toggles.", "properties": { "canonical_url_count": { "default": 0, "title": "Canonical Url Count", "type": "integer" }, "canonical_urls": { "items": { "type": "string" }, "title": "Canonical Urls", "type": "array" }, "processed_document_count": { "default": 0, "title": "Processed Document Count", "type": "integer" }, "processed_documents": { "items": { "type": "string" }, "title": "Processed Documents", "type": "array" }, "source_id": { "title": "Source Id", "type": "string" }, "source_type": { "enum": [ "email", "note" ], "title": "Source Type", "type": "string" } }, "required": [ "source_type", "source_id" ], "title": "PodcastSourceMetadataResponse", "type": "object" }, "PodcastSubscriptionCreateRequest": { "properties": { "auto_download": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Auto Download" }, "auto_download_max_newest": { "anyOf": [ { "maximum": 100.0, "minimum": 1.0, "type": "integer" }, { "type": "null" } ], "title": "Auto Download Max Newest" }, "keep_episode_count": { "default": 50, "maximum": 500.0, "minimum": 1.0, "title": "Keep Episode Count", "type": "integer" }, "poll_interval_minutes": { "anyOf": [ { "maximum": 10080.0, "minimum": 5.0, "type": "integer" }, { "type": "null" } ], "title": "Poll Interval Minutes" }, "purge_listened_after_days": { "default": 30, "maximum": 3650.0, "minimum": 0.0, "title": "Purge Listened After Days", "type": "integer" }, "rss_feed_url": { "maxLength": 2000, "minLength": 1, "title": "Rss Feed Url", "type": "string" }, "wifi_only_download": { "default": false, "title": "Wifi Only Download", "type": "boolean" } }, "required": [ "rss_feed_url" ], "title": "PodcastSubscriptionCreateRequest", "type": "object" }, "PodcastSubscriptionDeleteResponse": { "properties": { "deleted": { "title": "Deleted", "type": "boolean" } }, "required": [ "deleted" ], "title": "PodcastSubscriptionDeleteResponse", "type": "object" }, "PodcastSubscriptionListResponse": { "properties": { "subscriptions": { "items": { "$ref": "#/components/schemas/PodcastSubscriptionResponse" }, "title": "Subscriptions", "type": "array" } }, "required": [ "subscriptions" ], "title": "PodcastSubscriptionListResponse", "type": "object" }, "PodcastSubscriptionPollResponse": { "properties": { "auto_download": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Auto Download" }, "auto_purge": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Auto Purge" }, "inserted": { "default": 0, "title": "Inserted", "type": "integer" }, "skipped": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Skipped" }, "total_in_feed": { "default": 0, "title": "Total In Feed", "type": "integer" }, "updated": { "default": 0, "title": "Updated", "type": "integer" } }, "title": "PodcastSubscriptionPollResponse", "type": "object" }, "PodcastSubscriptionPreferencesPutRequest": { "properties": { "custom_ai_instructions": { "anyOf": [ { "maxLength": 4000, "type": "string" }, { "type": "null" } ], "title": "Custom Ai Instructions" }, "default_playback_speed": { "anyOf": [ { "maximum": 3.0, "minimum": 0.5, "type": "number" }, { "type": "null" } ], "title": "Default Playback Speed" }, "lead_buffer_seconds": { "anyOf": [ { "maximum": 120.0, "minimum": 5.0, "type": "integer" }, { "type": "null" } ], "title": "Lead Buffer Seconds" }, "total_capture_seconds": { "anyOf": [ { "maximum": 900.0, "minimum": 5.0, "type": "integer" }, { "type": "null" } ], "title": "Total Capture Seconds" }, "trail_buffer_seconds": { "anyOf": [ { "maximum": 120.0, "minimum": 5.0, "type": "integer" }, { "type": "null" } ], "title": "Trail Buffer Seconds" } }, "title": "PodcastSubscriptionPreferencesPutRequest", "type": "object" }, "PodcastSubscriptionPreferencesResponse": { "properties": { "custom_ai_instructions": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Custom Ai Instructions" }, "default_playback_speed": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "title": "Default Playback Speed" }, "lead_buffer_seconds": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Lead Buffer Seconds" }, "subscription_id": { "title": "Subscription Id", "type": "string" }, "total_capture_seconds": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Total Capture Seconds" }, "trail_buffer_seconds": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Trail Buffer Seconds" }, "updated_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Updated At" } }, "required": [ "subscription_id" ], "title": "PodcastSubscriptionPreferencesResponse", "type": "object" }, "PodcastSubscriptionResponse": { "properties": { "artwork_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Artwork Url" }, "author": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Author" }, "auto_download": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Auto Download" }, "auto_download_max_newest": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Auto Download Max Newest" }, "created": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Created" }, "created_at": { "title": "Created At", "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "episode_count": { "default": 0, "title": "Episode Count", "type": "integer" }, "id": { "title": "Id", "type": "string" }, "is_active": { "title": "Is Active", "type": "boolean" }, "is_default": { "title": "Is Default", "type": "boolean" }, "keep_episode_count": { "title": "Keep Episode Count", "type": "integer" }, "last_error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Error" }, "last_polled_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Polled At" }, "latest_episode_published_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Latest Episode Published At" }, "next_poll_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Poll At" }, "played_episode_count": { "default": 0, "title": "Played Episode Count", "type": "integer" }, "poll_interval_minutes": { "title": "Poll Interval Minutes", "type": "integer" }, "purge_listened_after_days": { "title": "Purge Listened After Days", "type": "integer" }, "rss_feed_url": { "title": "Rss Feed Url", "type": "string" }, "source": { "title": "Source", "type": "string" }, "sync_inserted": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Sync Inserted" }, "sync_total_in_feed": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Sync Total In Feed" }, "sync_updated": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Sync Updated" }, "tenant_id": { "title": "Tenant Id", "type": "string" }, "title": { "title": "Title", "type": "string" }, "updated_at": { "title": "Updated At", "type": "string" }, "website_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Website Url" }, "wifi_only_download": { "title": "Wifi Only Download", "type": "boolean" } }, "required": [ "id", "tenant_id", "title", "rss_feed_url", "source", "is_default", "keep_episode_count", "purge_listened_after_days", "poll_interval_minutes", "wifi_only_download", "is_active", "created_at", "updated_at" ], "title": "PodcastSubscriptionResponse", "type": "object" }, "PodcastSubscriptionUpdateRequest": { "properties": { "auto_download": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Auto Download" }, "auto_download_max_newest": { "anyOf": [ { "maximum": 100.0, "minimum": 1.0, "type": "integer" }, { "type": "null" } ], "title": "Auto Download Max Newest" }, "keep_episode_count": { "anyOf": [ { "maximum": 500.0, "minimum": 1.0, "type": "integer" }, { "type": "null" } ], "title": "Keep Episode Count" }, "poll_interval_minutes": { "anyOf": [ { "maximum": 10080.0, "minimum": 5.0, "type": "integer" }, { "type": "null" } ], "title": "Poll Interval Minutes" }, "purge_listened_after_days": { "anyOf": [ { "maximum": 3650.0, "minimum": 0.0, "type": "integer" }, { "type": "null" } ], "title": "Purge Listened After Days" }, "wifi_only_download": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Wifi Only Download" } }, "title": "PodcastSubscriptionUpdateRequest", "type": "object" }, "PodcastVoiceCatalogResponse": { "description": "Catalog of available voice options by TTS tier.", "properties": { "defaults": { "$ref": "#/components/schemas/PodcastVoiceDefaults" }, "premium": { "items": { "$ref": "#/components/schemas/PodcastVoiceOption" }, "title": "Premium", "type": "array" }, "premium_openai": { "items": { "$ref": "#/components/schemas/PodcastVoiceOption" }, "title": "Premium Openai", "type": "array" }, "standard": { "items": { "$ref": "#/components/schemas/PodcastVoiceOption" }, "title": "Standard", "type": "array" } }, "required": [ "defaults" ], "title": "PodcastVoiceCatalogResponse", "type": "object" }, "PodcastVoiceDefaults": { "description": "Default voice selections used by podcast generation UI.", "properties": { "premium_host_a": { "default": "kore", "title": "Premium Host A", "type": "string" }, "premium_host_b": { "default": "charon", "title": "Premium Host B", "type": "string" }, "premium_openai_host_a": { "default": "nova", "title": "Premium Openai Host A", "type": "string" }, "premium_openai_host_b": { "default": "onyx", "title": "Premium Openai Host B", "type": "string" }, "premium_openai_voice": { "default": "nova", "title": "Premium Openai Voice", "type": "string" }, "premium_provider": { "default": "gemini", "title": "Premium Provider", "type": "string" }, "premium_voice": { "title": "Premium Voice", "type": "string" }, "standard_host_a": { "title": "Standard Host A", "type": "string" }, "standard_host_b": { "title": "Standard Host B", "type": "string" }, "standard_narrator": { "title": "Standard Narrator", "type": "string" } }, "required": [ "standard_host_a", "standard_host_b", "standard_narrator", "premium_voice" ], "title": "PodcastVoiceDefaults", "type": "object" }, "PodcastVoiceOption": { "description": "Voice option for podcast generation UI.", "properties": { "id": { "title": "Id", "type": "string" }, "label": { "title": "Label", "type": "string" } }, "required": [ "id", "label" ], "title": "PodcastVoiceOption", "type": "object" }, "PodchaserCategoryResponse": { "description": "Podchaser category.", "properties": { "podcast_count": { "default": 0, "title": "Podcast Count", "type": "integer" }, "slug": { "title": "Slug", "type": "string" }, "title": { "title": "Title", "type": "string" } }, "required": [ "slug", "title" ], "title": "PodchaserCategoryResponse", "type": "object" }, "PodchaserDiscoveryResponse": { "description": "Full Podchaser discovery payload.", "properties": { "categories": { "items": { "$ref": "#/components/schemas/PodchaserCategoryResponse" }, "title": "Categories", "type": "array" }, "podcasts": { "items": { "$ref": "#/components/schemas/PodchaserPodcastResponse" }, "title": "Podcasts", "type": "array" } }, "title": "PodchaserDiscoveryResponse", "type": "object" }, "PodchaserPodcastResponse": { "description": "Podchaser podcast entry.", "properties": { "apple_podcasts_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Apple Podcasts Id" }, "author_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Author Name" }, "category_slug": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Category Slug" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "episode_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Episode Count" }, "image_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Image Url" }, "podchaser_id": { "title": "Podchaser Id", "type": "string" }, "rating_average": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Rating Average" }, "rating_count": { "default": 0, "title": "Rating Count", "type": "integer" }, "sort_rank": { "default": 0, "title": "Sort Rank", "type": "integer" }, "sort_type": { "default": "rating", "title": "Sort Type", "type": "string" }, "spotify_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Spotify Id" }, "title": { "title": "Title", "type": "string" } }, "required": [ "podchaser_id", "title" ], "title": "PodchaserPodcastResponse", "type": "object" }, "PodchaserRatingResponse": { "properties": { "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Id" }, "rating_average": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Rating Average" }, "rating_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Rating Count" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Title" } }, "title": "PodchaserRatingResponse", "type": "object" }, "PolicyHitRequest": { "properties": { "conversation_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Conversation Id" }, "effect": { "description": "deny | require_approval", "title": "Effect", "type": "string" }, "member_account_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Member Account Id" }, "normalized_command": { "anyOf": [ { "maxLength": 4096, "type": "string" }, { "type": "null" } ], "title": "Normalized Command" }, "outcome": { "description": "What the connector did: refused | prompted | approved", "title": "Outcome", "type": "string" }, "request_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Request Id" }, "rule_id": { "maxLength": 128, "title": "Rule Id", "type": "string" } }, "required": [ "rule_id", "effect", "outcome" ], "title": "PolicyHitRequest", "type": "object" }, "PolicyHitResponse": { "properties": { "recorded": { "title": "Recorded", "type": "boolean" }, "rule_id": { "title": "Rule Id", "type": "string" } }, "required": [ "recorded", "rule_id" ], "title": "PolicyHitResponse", "type": "object" }, "PollOption": { "properties": { "emoji": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Emoji" }, "label": { "maxLength": 160, "minLength": 1, "title": "Label", "type": "string" } }, "required": [ "label" ], "title": "PollOption", "type": "object" }, "PollResponse": { "properties": { "allows_multiple": { "title": "Allows Multiple", "type": "boolean" }, "close_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Close At" }, "closed_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Closed At" }, "event_id": { "title": "Event Id", "type": "string" }, "hide_results_until_close": { "title": "Hide Results Until Close", "type": "boolean" }, "id": { "format": "uuid", "title": "Id", "type": "string" }, "is_anonymous": { "title": "Is Anonymous", "type": "boolean" }, "options": { "items": { "additionalProperties": true, "type": "object" }, "title": "Options", "type": "array" }, "poll_kind": { "title": "Poll Kind", "type": "string" }, "question": { "title": "Question", "type": "string" }, "room_id": { "title": "Room Id", "type": "string" }, "totals": { "items": { "$ref": "#/components/schemas/PollTotals" }, "title": "Totals", "type": "array" } }, "required": [ "id", "room_id", "event_id", "poll_kind", "question", "options", "is_anonymous", "allows_multiple", "hide_results_until_close", "close_at", "closed_at", "totals" ], "title": "PollResponse", "type": "object" }, "PollTotals": { "properties": { "count": { "title": "Count", "type": "integer" }, "emoji": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Emoji" }, "label": { "title": "Label", "type": "string" }, "option_idx": { "title": "Option Idx", "type": "integer" }, "voted_by_me": { "default": false, "title": "Voted By Me", "type": "boolean" } }, "required": [ "option_idx", "label", "count" ], "title": "PollTotals", "type": "object" }, "PollVoteRequest": { "properties": { "option_idx": { "anyOf": [ { "type": "integer" }, { "items": { "type": "integer" }, "type": "array" } ], "title": "Option Idx" } }, "required": [ "option_idx" ], "title": "PollVoteRequest", "type": "object" }, "PortalCatalogResponse": { "properties": { "portals": { "items": { "$ref": "#/components/schemas/PortalEntry" }, "title": "Portals", "type": "array" } }, "required": [ "portals" ], "title": "PortalCatalogResponse", "type": "object" }, "PortalEntry": { "description": "One backend admin portal as the fleet actually runs it.", "properties": { "description": { "title": "Description", "type": "string" }, "gate_mode": { "enum": [ "nginx-auth-request", "native-lan", "not-deployed" ], "title": "Gate Mode", "type": "string" }, "id": { "description": "Stable portal key used in audit rows", "title": "Id", "type": "string" }, "label": { "title": "Label", "type": "string" }, "path_suffix": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Path appended to a url_kind=subdomain host (e.g. '/ui' for Docling). Absent means the service root.", "title": "Path Suffix" }, "service": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Subdomain service key for url_kind=subdomain", "title": "Service" }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Url" }, "url_kind": { "enum": [ "path", "subdomain", "none" ], "title": "Url Kind", "type": "string" } }, "required": [ "id", "label", "description", "gate_mode", "url_kind" ], "title": "PortalEntry", "type": "object" }, "PortalSessionResponse": { "properties": { "url": { "title": "Url", "type": "string" } }, "required": [ "url" ], "title": "PortalSessionResponse", "type": "object" }, "PortraitHistoryResponse": { "properties": { "portraits": { "items": { "$ref": "#/components/schemas/PortraitModel" }, "title": "Portraits", "type": "array" }, "undecided": { "description": "The CALLER's own in-flight and undecided generations for this entity, newest first — the reachability half of the honest-quota rule. A preview here has spent quota and awaits accept/reject; a pending row is still generating. Account-scoped, unlike the accepted history.", "items": { "$ref": "#/components/schemas/PortraitModel" }, "title": "Undecided", "type": "array" } }, "required": [ "portraits" ], "title": "PortraitHistoryResponse", "type": "object" }, "PortraitModel": { "description": "One generation, as the client sees it.", "properties": { "accepted_at": { "title": "Accepted At" }, "attached_path": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Storage path of the accepted portrait on the entity.", "title": "Attached Path" }, "avatar_hash": { "title": "Avatar Hash", "type": "string" }, "created_at": { "title": "Created At" }, "entity_id": { "title": "Entity Id", "type": "string" }, "entity_type": { "title": "Entity Type", "type": "string" }, "failure_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Why a refused/failed generation ended there ('content_policy', 'interrupted', ...). Null while pending and on success.", "title": "Failure Reason" }, "id": { "title": "Id", "type": "string" }, "instructions": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Instructions" }, "outcome": { "description": "pending | succeeded | refused | failed. The generation runs asynchronously — poll GET /api/v1/avatars/portraits/{id} until the outcome is terminal. Only 'succeeded' consumes quota.", "title": "Outcome", "type": "string" }, "preview_path": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Storage path of the preview; null once promoted or collected.", "title": "Preview Path" }, "rejected_at": { "title": "Rejected At" }, "style_preset": { "title": "Style Preset", "type": "string" }, "thumbnail_base64": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Inline 96x96 JPEG derivative, present on the accept response.", "title": "Thumbnail Base64" } }, "required": [ "id", "entity_type", "entity_id", "style_preset", "instructions", "avatar_hash", "outcome", "created_at", "accepted_at", "rejected_at", "preview_path", "attached_path" ], "title": "PortraitModel", "type": "object" }, "PortraitOptionsResponse": { "description": "Everything the generate panel needs on open.", "properties": { "default_preset": { "title": "Default Preset", "type": "string" }, "max_instruction_chars": { "title": "Max Instruction Chars", "type": "integer" }, "presets": { "items": { "$ref": "#/components/schemas/StylePresetModel" }, "title": "Presets", "type": "array" }, "quota": { "$ref": "#/components/schemas/QuotaStatusModel" } }, "required": [ "presets", "default_preset", "max_instruction_chars", "quota" ], "title": "PortraitOptionsResponse", "type": "object" }, "PortraitStatusResponse": { "description": "One poll of an in-flight (or finished) generation.\n\nCarries the quota so the panel's count reconciles from the LEDGER the\nmoment the outcome lands, instead of asserting anything the transport\ncannot know (the bounce's false \"this did not use one of today's\nportraits\").", "properties": { "portrait": { "$ref": "#/components/schemas/PortraitModel" }, "quota": { "$ref": "#/components/schemas/QuotaStatusModel" } }, "required": [ "portrait", "quota" ], "title": "PortraitStatusResponse", "type": "object" }, "PostureBucket": { "properties": { "count": { "title": "Count", "type": "integer" }, "label": { "title": "Label", "type": "string" } }, "required": [ "label", "count" ], "title": "PostureBucket", "type": "object" }, "PotentialMatch": { "description": "An existing contact the matcher proposes as a merge target.", "properties": { "confidence": { "maximum": 1.0, "minimum": 0.0, "title": "Confidence", "type": "number" }, "contact_id": { "title": "Contact Id", "type": "string" }, "name": { "title": "Name", "type": "string" }, "reasons": { "items": { "$ref": "#/components/schemas/PotentialMatchReason" }, "title": "Reasons", "type": "array" } }, "required": [ "contact_id", "name", "confidence" ], "title": "PotentialMatch", "type": "object" }, "PotentialMatchReason": { "description": "Single signal supporting a Potential Match recommendation.", "properties": { "detail": { "description": "Human-readable explanation rendered in UI.", "title": "Detail", "type": "string" }, "type": { "description": "Signal classification.", "enum": [ "alias_match", "email_overlap", "kg_linkage", "org_overlap", "name_similarity" ], "title": "Type", "type": "string" } }, "required": [ "type", "detail" ], "title": "PotentialMatchReason", "type": "object" }, "PreflightCounts": { "properties": { "excluded_missing_merge_field": { "title": "Excluded Missing Merge Field", "type": "integer" }, "excluded_no_email": { "title": "Excluded No Email", "type": "integer" }, "excluded_suppressed": { "title": "Excluded Suppressed", "type": "integer" }, "included": { "title": "Included", "type": "integer" } }, "required": [ "included", "excluded_suppressed", "excluded_no_email", "excluded_missing_merge_field" ], "title": "PreflightCounts", "type": "object" }, "PreflightRequest": { "description": "Optional properties override for the write-behind race (TIDY-14685).\n\nCampaign field authoring is local-first: the client writes a property\n(audience_view, template_note, from_identity...) to its local SQLite and\nthe PowerSync upload reaches Postgres a moment later. A preflight fired\nimmediately after a field write would read the STALE stored properties\nand report e.g. no_audience_view for a view the user just picked. The\nclient passes its known-local properties here; the server preflights\nexactly what the user sees.", "properties": { "properties": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Properties" } }, "title": "PreflightRequest", "type": "object" }, "PreflightResponse": { "properties": { "blocked": { "title": "Blocked", "type": "boolean" }, "blocked_reason": { "default": "", "title": "Blocked Reason", "type": "string" }, "campaign_id": { "title": "Campaign Id", "type": "string" }, "counts": { "$ref": "#/components/schemas/PreflightCounts" } }, "required": [ "campaign_id", "counts", "blocked" ], "title": "PreflightResponse", "type": "object" }, "PrependPlacement": { "additionalProperties": false, "description": "At the start of the body.", "properties": { "mode": { "const": "prepend", "title": "Mode", "type": "string" } }, "required": [ "mode" ], "title": "PrependPlacement", "type": "object" }, "PresentationDesignListResponse": { "description": "Envelope for GET /api/v1/presentation-designs.", "properties": { "items": { "items": { "$ref": "#/components/schemas/PresentationDesignResponse" }, "title": "Items", "type": "array" } }, "required": [ "items" ], "title": "PresentationDesignListResponse", "type": "object" }, "PresentationDesignResponse": { "description": "A presentation design row as returned by the API.", "properties": { "created_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Created At" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "design": { "additionalProperties": true, "title": "Design", "type": "object" }, "forked_from_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Forked From Id" }, "id": { "title": "Id", "type": "string" }, "is_system": { "title": "Is System", "type": "boolean" }, "name": { "title": "Name", "type": "string" }, "owner_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Owner Id" }, "tenant_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Tenant Id" }, "updated_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Updated At" }, "visibility": { "title": "Visibility", "type": "string" } }, "required": [ "id", "tenant_id", "owner_id", "name", "description", "design", "is_system", "visibility", "forked_from_id", "created_at", "updated_at" ], "title": "PresentationDesignResponse", "type": "object" }, "PresentationManifest": { "description": "`GET /api/v1/presentations/{note_id}` response + `POST render` result.", "properties": { "note_id": { "title": "Note Id", "type": "string" }, "rendered_at": { "format": "date-time", "title": "Rendered At", "type": "string" }, "slide_count": { "title": "Slide Count", "type": "integer" }, "slides": { "items": { "$ref": "#/components/schemas/SlideImage" }, "title": "Slides", "type": "array" }, "stale": { "description": "True when the deck has changed since this manifest was rendered (cached deck_hash ≠ current notes.yjs_content_hash). The LAST manifest is still served — never blank, never partial (R20).", "title": "Stale", "type": "boolean" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Title" } }, "required": [ "note_id", "slide_count", "rendered_at", "stale", "slides" ], "title": "PresentationManifest", "type": "object" }, "PresentationPublication": { "description": "A single immutable published version of a deck.\n\nReturned by the publish endpoint and the assets endpoint. The list/read of\npublications otherwise arrives on the client via PowerSync (this same row\nshape minus the signed URLs, which are minted per request).", "properties": { "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "id": { "title": "Id", "type": "string" }, "note_id": { "title": "Note Id", "type": "string" }, "pptx_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Short-lived signed URL for the frozen PPTX.", "title": "Pptx Url" }, "published_by": { "title": "Published By", "type": "string" }, "published_by_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Best-effort display name of the publisher.", "title": "Published By Name" }, "slide_count": { "title": "Slide Count", "type": "integer" }, "slides": { "description": "Frozen slides with signed PNG URLs (empty on the bare row).", "items": { "$ref": "#/components/schemas/PublicationSlide" }, "title": "Slides", "type": "array" }, "tenant_id": { "title": "Tenant Id", "type": "string" }, "title": { "title": "Title", "type": "string" } }, "required": [ "id", "tenant_id", "note_id", "published_by", "title", "slide_count", "created_at" ], "title": "PresentationPublication", "type": "object" }, "PreviewApplyItem": { "properties": { "action": { "title": "Action", "type": "string" }, "conflict": { "title": "Conflict", "type": "boolean" }, "kind": { "title": "Kind", "type": "string" }, "ref": { "title": "Ref", "type": "string" } }, "required": [ "kind", "ref", "action", "conflict" ], "title": "PreviewApplyItem", "type": "object" }, "PreviewApplyResponse": { "properties": { "create_count": { "title": "Create Count", "type": "integer" }, "items": { "items": { "$ref": "#/components/schemas/PreviewApplyItem" }, "title": "Items", "type": "array" }, "requires": { "items": { "type": "string" }, "title": "Requires", "type": "array" }, "skip_count": { "title": "Skip Count", "type": "integer" }, "template_slug": { "title": "Template Slug", "type": "string" }, "template_version": { "title": "Template Version", "type": "integer" } }, "required": [ "template_slug", "template_version", "create_count", "skip_count", "items" ], "title": "PreviewApplyResponse", "type": "object" }, "PreviewEvidenceModel": { "properties": { "contact_linked_senders_swept": { "items": { "type": "string" }, "title": "Contact Linked Senders Swept", "type": "array" }, "distinct_senders": { "title": "Distinct Senders", "type": "integer" }, "distinct_subject_templates": { "title": "Distinct Subject Templates", "type": "integer" }, "important_teaches": { "items": { "$ref": "#/components/schemas/ImportantTeach" }, "title": "Important Teaches", "type": "array" }, "opened_count": { "title": "Opened Count", "type": "integer" }, "replied_count": { "title": "Replied Count", "type": "integer" }, "teach_important_conflicts": { "title": "Teach Important Conflicts", "type": "integer" }, "vip_senders_swept": { "items": { "type": "string" }, "title": "Vip Senders Swept", "type": "array" } }, "required": [ "opened_count", "replied_count", "teach_important_conflicts", "vip_senders_swept", "contact_linked_senders_swept", "distinct_senders", "distinct_subject_templates" ], "title": "PreviewEvidenceModel", "type": "object" }, "PreviewRequest": { "description": "Body for POST /api/v1/defense/rules/preview.", "properties": { "action_family": { "default": "suppress", "enum": [ "block", "screen", "route", "classify", "defer", "harvest", "suppress", "calendar_shield", "workflow" ], "title": "Action Family", "type": "string" }, "match": { "$ref": "#/components/schemas/RuleMatch" }, "window_days": { "default": 365, "maximum": 730.0, "minimum": 1.0, "title": "Window Days", "type": "integer" } }, "required": [ "match" ], "title": "PreviewRequest", "type": "object" }, "PreviewResponse": { "properties": { "body_unavailable_count": { "default": 0, "title": "Body Unavailable Count", "type": "integer" }, "coverage_days": { "title": "Coverage Days", "type": "integer" }, "evidence": { "$ref": "#/components/schemas/PreviewEvidenceModel" }, "matched_count": { "title": "Matched Count", "type": "integer" }, "samples": { "items": { "$ref": "#/components/schemas/PreviewSample" }, "title": "Samples", "type": "array" }, "verdict": { "enum": [ "high_confidence", "needs_review", "unsafe" ], "title": "Verdict", "type": "string" }, "window_days": { "title": "Window Days", "type": "integer" } }, "required": [ "matched_count", "window_days", "coverage_days", "samples", "evidence", "verdict" ], "title": "PreviewResponse", "type": "object" }, "PreviewSample": { "properties": { "email_id": { "title": "Email Id", "type": "string" }, "from_address": { "title": "From Address", "type": "string" }, "inbox_split": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Inbox Split" }, "is_done": { "title": "Is Done", "type": "boolean" }, "sent_at": { "format": "date-time", "title": "Sent At", "type": "string" }, "subject": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Subject" } }, "required": [ "email_id", "from_address", "sent_at", "is_done" ], "title": "PreviewSample", "type": "object" }, "PrimitiveContentEditBatch": { "description": "One recorded edit batch, as version history needs to see it.\n\nContent-free by construction: identity, attribution, and whether the batch\ncan still be reverted. Operations, inverses, and replaced/deleted text are\nserver-only and never appear here.", "properties": { "actor_display_name": { "title": "Actor Display Name", "type": "string" }, "actor_principal_type": { "title": "Actor Principal Type", "type": "string" }, "batch_id": { "title": "Batch Id", "type": "string" }, "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "engine": { "title": "Engine", "type": "string" }, "not_revertible_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Not Revertible Reason" }, "op_count": { "title": "Op Count", "type": "integer" }, "revert_of_batch_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Revert Of Batch Id" }, "reverted_by_batch_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Reverted By Batch Id" }, "revertible": { "title": "Revertible", "type": "boolean" }, "version_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Version Id" } }, "required": [ "batch_id", "engine", "op_count", "actor_principal_type", "actor_display_name", "created_at", "revertible" ], "title": "PrimitiveContentEditBatch", "type": "object" }, "PrimitiveContentEditBatchList": { "properties": { "batches": { "items": { "$ref": "#/components/schemas/PrimitiveContentEditBatch" }, "title": "Batches", "type": "array" } }, "title": "PrimitiveContentEditBatchList", "type": "object" }, "PrimitiveContentEditRevertRequest": { "additionalProperties": false, "description": "Body of a surgical revert. Carries NO operations — the ops are the\nrecorded batch's own inverses, which is what makes a revert impossible to\nforge into an arbitrary edit.", "properties": { "request_id": { "format": "uuid", "title": "Request Id", "type": "string" } }, "required": [ "request_id" ], "title": "PrimitiveContentEditRevertRequest", "type": "object" }, "PrimitiveContentEditRevertResponse": { "description": "The revert's own applied batch, plus the batch it undid.", "properties": { "actor_display_name": { "title": "Actor Display Name", "type": "string" }, "actor_type": { "title": "Actor Type", "type": "string" }, "checklist": { "items": { "$ref": "#/components/schemas/ChecklistItemState" }, "title": "Checklist", "type": "array" }, "duplicate": { "default": false, "title": "Duplicate", "type": "boolean" }, "id": { "title": "Id", "type": "string" }, "live_broadcast": { "title": "Live Broadcast", "type": "boolean" }, "results": { "items": { "additionalProperties": true, "type": "object" }, "title": "Results", "type": "array" }, "reverted_batch_id": { "title": "Reverted Batch Id", "type": "string" }, "version_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Version Id" } }, "required": [ "id", "results", "actor_type", "actor_display_name", "live_broadcast", "reverted_batch_id" ], "title": "PrimitiveContentEditRevertResponse", "type": "object" }, "PrimitiveContentEditsRequest": { "additionalProperties": false, "description": "Canonical body. No full content, actor, engine, inverse, or Yjs field.", "properties": { "field": { "anyOf": [ { "maxLength": 128, "minLength": 1, "type": "string" }, { "type": "null" } ], "description": "For a FIELD-KEYED primitive (see x-tidy-content-edit-field-keyed-prefixes), the rich-text property this batch edits — required for those and rejected for every other prefix. Must be declared as a `rich_text` field on the row's facet definition; no other property is touched.", "title": "Field" }, "handle": { "anyOf": [ { "maxLength": 8192, "type": "string" }, { "type": "null" } ], "title": "Handle" }, "operations": { "items": { "discriminator": { "mapping": { "add_element": "#/components/schemas/AddElementOp", "append_section": "#/components/schemas/AppendSectionOp", "delete_element": "#/components/schemas/DeleteElementOp", "delete_span": "#/components/schemas/DeleteSpanOp", "insert_column": "#/components/schemas/InsertColumnOp", "insert_embed": "#/components/schemas/InsertEmbedOp", "insert_row": "#/components/schemas/InsertRowOp", "insert_slide": "#/components/schemas/InsertSlideOp", "remove_block": "#/components/schemas/RemoveBlockOp", "remove_slide": "#/components/schemas/RemoveSlideOp", "reorder_slide": "#/components/schemas/ReorderSlideOp", "replace_blocks": "#/components/schemas/ReplaceBlocksOp", "replace_section": "#/components/schemas/ReplaceSectionOp", "replace_span": "#/components/schemas/ReplaceSpanOp", "set_cell": "#/components/schemas/SetCellOp", "set_layout": "#/components/schemas/SetSlideLayoutOp", "set_range": "#/components/schemas/SetRangeOp", "toggle_checklist_item": "#/components/schemas/ToggleChecklistItemOp", "update_element": "#/components/schemas/UpdateElementOp" }, "propertyName": "op" }, "oneOf": [ { "$ref": "#/components/schemas/ToggleChecklistItemOp" }, { "$ref": "#/components/schemas/ReplaceSpanOp" }, { "$ref": "#/components/schemas/DeleteSpanOp" }, { "$ref": "#/components/schemas/RemoveBlockOp" }, { "$ref": "#/components/schemas/AppendSectionOp" }, { "$ref": "#/components/schemas/ReplaceSectionOp" }, { "$ref": "#/components/schemas/ReplaceBlocksOp" }, { "$ref": "#/components/schemas/InsertEmbedOp" }, { "$ref": "#/components/schemas/InsertColumnOp" }, { "$ref": "#/components/schemas/InsertRowOp" }, { "$ref": "#/components/schemas/SetCellOp" }, { "$ref": "#/components/schemas/SetRangeOp" }, { "$ref": "#/components/schemas/UpdateElementOp" }, { "$ref": "#/components/schemas/DeleteElementOp" }, { "$ref": "#/components/schemas/AddElementOp" }, { "$ref": "#/components/schemas/InsertSlideOp" }, { "$ref": "#/components/schemas/RemoveSlideOp" }, { "$ref": "#/components/schemas/ReorderSlideOp" }, { "$ref": "#/components/schemas/SetSlideLayoutOp" } ] }, "maxItems": 20, "minItems": 1, "title": "Operations", "type": "array" }, "request_id": { "format": "uuid", "title": "Request Id", "type": "string" } }, "required": [ "request_id", "operations" ], "title": "PrimitiveContentEditsRequest", "type": "object" }, "PrimitiveContentEditsResponse": { "properties": { "actor_display_name": { "title": "Actor Display Name", "type": "string" }, "actor_type": { "title": "Actor Type", "type": "string" }, "checklist": { "items": { "$ref": "#/components/schemas/ChecklistItemState" }, "title": "Checklist", "type": "array" }, "duplicate": { "default": false, "title": "Duplicate", "type": "boolean" }, "id": { "title": "Id", "type": "string" }, "live_broadcast": { "title": "Live Broadcast", "type": "boolean" }, "results": { "items": { "additionalProperties": true, "type": "object" }, "title": "Results", "type": "array" }, "version_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Version Id" } }, "required": [ "id", "results", "actor_type", "actor_display_name", "live_broadcast" ], "title": "PrimitiveContentEditsResponse", "type": "object" }, "PrimitiveHistoryRevertRequest": { "additionalProperties": false, "properties": { "field": { "description": "The recorded field path to put back, e.g. `title` or `facet_data.task.status`.", "maxLength": 200, "minLength": 1, "title": "Field", "type": "string" } }, "required": [ "field" ], "title": "PrimitiveHistoryRevertRequest", "type": "object" }, "PrimitiveHistoryRevertResponse": { "properties": { "entity_id": { "title": "Entity Id", "type": "string" }, "entity_type": { "title": "Entity Type", "type": "string" }, "entry_id": { "title": "Entry Id", "type": "string" }, "field": { "title": "Field", "type": "string" }, "value": { "anyOf": [ {}, { "type": "null" } ], "default": null, "title": "Value" } }, "required": [ "entry_id", "entity_type", "entity_id", "field" ], "title": "PrimitiveHistoryRevertResponse", "type": "object" }, "PrimitiveInstanceCreateRequest": { "properties": { "facet_slug": { "description": "Slug of the facet to instantiate — ANY facet, any target_table.", "minLength": 1, "title": "Facet Slug", "type": "string" }, "project_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional project (`P-`) — honored for activities and notes. Rejected (422) for targets with no project association.", "title": "Project Id" }, "properties": { "additionalProperties": true, "description": "Facet field values keyed by field key. Values that map to real columns on the target primitive (e.g. contact name, event start_time) are routed to those columns automatically.", "title": "PrimitiveInstanceCreateProperties", "type": "object" }, "tags": { "description": "Tags to apply — honored for records, activities, notes, and contacts. Rejected (422) for calendar_events.", "items": { "type": "string" }, "title": "Tags", "type": "array" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Display title for the created primitive. Falls back to a title-like property (title/name/display_name/summary).", "title": "Title" } }, "required": [ "facet_slug" ], "title": "PrimitiveInstanceCreateRequest", "type": "object" }, "PrimitiveInstanceCreateResponse": { "properties": { "facet_slug": { "title": "Facet Slug", "type": "string" }, "id": { "description": "Typed id of the created instance (e.g. A-)", "title": "Id", "type": "string" }, "target_table": { "title": "Target Table", "type": "string" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Title" } }, "required": [ "id", "target_table", "facet_slug" ], "title": "PrimitiveInstanceCreateResponse", "type": "object" }, "PrimitiveInstanceItem": { "properties": { "created_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Created At" }, "created_by": { "anyOf": [ { "$ref": "#/components/schemas/RecordAuthor" }, { "type": "null" } ], "default": null, "description": "Who created the instance (member or virtual employee). Records carry it; null for other targets and for records that predate creator tracking." }, "facet_slug": { "title": "Facet Slug", "type": "string" }, "id": { "description": "Typed id (prefix routes the primitive table)", "title": "Id", "type": "string" }, "properties": { "additionalProperties": true, "description": "The facet-scoped value view, normalized across storage shapes.", "title": "PrimitiveInstanceItemProperties", "type": "object" }, "target_table": { "title": "Target Table", "type": "string" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Title" }, "updated_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Updated At" } }, "required": [ "id", "target_table", "facet_slug" ], "title": "PrimitiveInstanceItem", "type": "object" }, "PrimitiveInstanceListResponse": { "properties": { "items": { "items": { "$ref": "#/components/schemas/PrimitiveInstanceItem" }, "title": "Items", "type": "array" }, "total": { "title": "Total", "type": "integer" } }, "required": [ "items", "total" ], "title": "PrimitiveInstanceListResponse", "type": "object" }, "PrimitiveInstanceUpdateRequest": { "properties": { "facet_slug": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Facet whose value view the update targets. Required only when the row carries zero or multiple facet associations.", "title": "Facet Slug" }, "properties": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "Per-key merge into the facet's value store: a provided key overwrites, an explicit null clears the key, unprovided keys survive.", "title": "PrimitiveInstanceUpdateProperties" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "New display title for the instance.", "title": "Title" } }, "title": "PrimitiveInstanceUpdateRequest", "type": "object" }, "PrimitiveProvenanceResponse": { "properties": { "records": { "description": "Generation records for this artifact, newest first", "items": { "$ref": "#/components/schemas/ProvenanceRecord" }, "title": "Records", "type": "array" }, "total": { "title": "Total", "type": "integer" } }, "required": [ "records", "total" ], "title": "PrimitiveProvenanceResponse", "type": "object" }, "PriorityFailureError": { "additionalProperties": false, "properties": { "message": { "title": "Message", "type": "string" }, "stage": { "title": "Stage", "type": "string" } }, "required": [ "stage", "message" ], "title": "PriorityFailureError", "type": "object" }, "PriorityFailureRequest": { "additionalProperties": false, "description": "Pipeline → app priority-failure notice (P3 S1 R-P3.3 / S2 R-P3.6).\n\nThe pipeline pushes this when a PRIORITY-lane job dead-letters so the user's\npending ledger item surfaces the error instead of hanging forever.", "properties": { "error": { "$ref": "#/components/schemas/PriorityFailureError" }, "guid": { "title": "Guid", "type": "string" }, "request_ref": { "title": "Request Ref", "type": "string" }, "rss_feed_url": { "title": "Rss Feed Url", "type": "string" } }, "required": [ "request_ref", "rss_feed_url", "guid", "error" ], "title": "PriorityFailureRequest", "type": "object" }, "PriorityFailureResponse": { "properties": { "items_failed": { "title": "Items Failed", "type": "integer" }, "status": { "title": "Status", "type": "string" } }, "required": [ "status", "items_failed" ], "title": "PriorityFailureResponse", "type": "object" }, "PriorityLedgerMetrics": { "description": "P4 S1 (R-P4.2): ledger-derived priority-request metrics, replacing the\nremoved D14 tier-queue payload (per_tier + dead-queue fields are GONE).\n\nSourced from the repurposed podcast_transcription_batches/_batch_items\n(P3 ledger, provider='pipeline_priority'). Item statuses: 'queued'=pending,\n'completed', 'failed' (D9 — no paused). The oldest still-pending request and\nits wait time replace the old FIFO-head batch concept.", "properties": { "completed_today": { "title": "Completed Today", "type": "integer" }, "failed": { "title": "Failed", "type": "integer" }, "in_flight": { "title": "In Flight", "type": "integer" }, "oldest_pending_request_ref": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Oldest Pending Request Ref" }, "oldest_pending_waiting_seconds": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Oldest Pending Waiting Seconds" }, "pending": { "title": "Pending", "type": "integer" } }, "required": [ "pending", "in_flight", "completed_today", "failed", "oldest_pending_request_ref", "oldest_pending_waiting_seconds" ], "title": "PriorityLedgerMetrics", "type": "object" }, "ProblemDetail": { "additionalProperties": true, "description": "An RFC 9457 problem+json error envelope.\n\nEmitted by the api-service problem middleware for a coded failure. Every\nfield below is always present; ``retry_after_seconds`` is null unless the\ncode is retryable AND the server has a timing hint.", "properties": { "code": { "description": "Canonical machine-readable error code. This is the field a client branches on; e.g. `links_unavailable` means a linked-reference read failed, which is NOT the same as a primitive having no links.", "title": "Code", "type": "string" }, "detail": { "description": "Human-readable description of THIS occurrence.", "title": "Detail", "type": "string" }, "docs_url": { "description": "Documentation for this error code.", "title": "Docs Url", "type": "string" }, "error_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The SPECIFIC service refusal code when it differs from the status-mapped `code` (RFC 9457 extension member). E.g. a Tidy inference model refusal carries `error_code: tidy_inference_model_not_published` with the refused alias named in `detail`; absent when the failure is only described by the canonical `code`.", "title": "Error Code" }, "instance": { "description": "Request path the failure occurred on.", "title": "Instance", "type": "string" }, "request_id": { "description": "Correlation id — always present.", "title": "Request Id", "type": "string" }, "retry_after_seconds": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Retry-timing hint when the server has one.", "title": "Retry After Seconds" }, "retryable": { "description": "Whether retrying the identical request can succeed.", "title": "Retryable", "type": "boolean" }, "status": { "description": "HTTP status, repeated in the body per RFC 9457.", "title": "Status", "type": "integer" }, "title": { "description": "Short, stable, human-readable summary of the code.", "title": "Title", "type": "string" }, "type": { "description": "URI identifying the problem type (the docs URL).", "title": "Type", "type": "string" } }, "required": [ "type", "title", "status", "detail", "instance", "request_id", "code", "retryable", "docs_url" ], "title": "ProblemDetail", "type": "object" }, "ProcessAttachmentResponse": { "description": "202 response — the attachment was queued for pipeline processing.", "properties": { "already_pending": { "default": false, "title": "Already Pending", "type": "boolean" }, "status": { "title": "Status", "type": "string" }, "trace_id": { "title": "Trace Id", "type": "string" } }, "required": [ "status", "trace_id" ], "title": "ProcessAttachmentResponse", "type": "object" }, "ProcessDocumentRequest": { "description": "Request to process an existing document in storage.", "properties": { "metadata": { "additionalProperties": true, "default": {}, "description": "Optional metadata to attach to chunks", "title": "Metadata", "type": "object" }, "module": { "description": "Coaching module (wellness, productivity, relationships, parenting)", "examples": [ "wellness" ], "title": "Module", "type": "string" }, "storage_path": { "description": "Path to file in coaching-knowledge bucket", "examples": [ "wellness/breathing-techniques.pdf" ], "title": "Storage Path", "type": "string" } }, "required": [ "storage_path", "module" ], "title": "ProcessDocumentRequest", "type": "object" }, "ProcessDocumentResponse": { "description": "Response from document processing.", "properties": { "chunks_created": { "title": "Chunks Created", "type": "integer" }, "document_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Document Id" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error" }, "module": { "title": "Module", "type": "string" }, "source_document": { "title": "Source Document", "type": "string" }, "success": { "title": "Success", "type": "boolean" } }, "required": [ "success", "chunks_created", "source_document", "module" ], "title": "ProcessDocumentResponse", "type": "object" }, "ProcessReferenceRequest": { "description": "Body for POST /emails/{email_id}/references/process.", "properties": { "link_text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional anchor text for the link (improves filename derivation).", "title": "Link Text" }, "url": { "description": "The href to process (link URL or attachment content URL).", "title": "Url", "type": "string" } }, "required": [ "url" ], "title": "ProcessReferenceRequest", "type": "object" }, "ProcessReferenceResponse": { "description": "202 response — the reference was queued for pipeline processing.", "properties": { "job_id": { "description": "Deterministic pipeline_run id for this (email, reference).", "title": "Job Id", "type": "string" }, "status": { "description": "Always 'queued'.", "title": "Status", "type": "string" } }, "required": [ "status", "job_id" ], "title": "ProcessReferenceResponse", "type": "object" }, "ProcessedAttachmentResponse": { "description": "Processed attachment metadata for working-panel attachment previews.", "properties": { "confidence_raw": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Raw extraction confidence", "title": "Confidence Raw" }, "content_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "MIME type", "title": "Content Type" }, "created_at": { "description": "When the attachment row was created", "format": "date-time", "title": "Created At", "type": "string" }, "decision_action": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pipeline decision for the attachment", "title": "Decision Action" }, "email_canonical_id": { "description": "Source email UUID", "format": "uuid", "title": "Email Canonical Id", "type": "string" }, "filename": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Original attachment filename", "title": "Filename" }, "id": { "description": "processed_attachments UUID", "format": "uuid", "title": "Id", "type": "string" }, "locator": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "AttachmentLocator dict (storage/provider/unavailable)", "title": "Locator" }, "locator_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Reason string when locator.type == 'unavailable'", "title": "Locator Reason" }, "markdown": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Extracted markdown/text preview", "title": "Markdown" }, "processed_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "When attachment processing completed", "title": "Processed At" }, "processing_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Attachment processing status", "title": "Processing Status" }, "processor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Processor that handled the attachment", "title": "Processor" }, "storage_path": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Storage path for signed URL generation", "title": "Storage Path" }, "tenant_id": { "description": "Tenant UUID that owns the attachment", "format": "uuid", "title": "Tenant Id", "type": "string" } }, "required": [ "id", "tenant_id", "email_canonical_id", "created_at" ], "title": "ProcessedAttachmentResponse", "type": "object" }, "ProducerPayload": { "properties": { "content_kind": { "title": "Content Kind", "type": "string" }, "payload": { "additionalProperties": true, "title": "ContentProducerPayloadData", "type": "object" }, "producer": { "title": "Producer", "type": "string" } }, "required": [ "producer", "content_kind", "payload" ], "title": "ProducerPayload", "type": "object" }, "ProfileAvatarConvertResponse": { "properties": { "cached": { "title": "Cached", "type": "boolean" }, "schema": { "additionalProperties": true, "title": "Schema", "type": "object" } }, "required": [ "schema", "cached" ], "title": "ProfileAvatarConvertResponse", "type": "object" }, "ProfileLink": { "description": "A social/web profile link for a contact.", "properties": { "confidence": { "anyOf": [ { "maximum": 1.0, "minimum": 0.0, "type": "number" }, { "type": "null" } ], "description": "Confidence score", "title": "Confidence" }, "last_verified_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "When last verified", "title": "Last Verified At" }, "network": { "description": "Network name (linkedin, twitter, etc.)", "examples": [ "linkedin" ], "title": "Network", "type": "string" }, "source": { "default": "manual", "description": "How the link was discovered (manual, google, enrichment)", "title": "Source", "type": "string" }, "url": { "description": "Full URL to the profile", "examples": [ "https://linkedin.com/in/jsmith" ], "title": "Url", "type": "string" }, "verified_by_user": { "default": false, "description": "Whether user verified this link", "title": "Verified By User", "type": "boolean" } }, "required": [ "network", "url" ], "title": "ProfileLink", "type": "object" }, "ProfileLinkCreate": { "description": "Input for adding a profile link.", "properties": { "confidence": { "anyOf": [ { "maximum": 1.0, "minimum": 0.0, "type": "number" }, { "type": "null" } ], "title": "Confidence" }, "network": { "description": "Network name", "examples": [ "linkedin" ], "title": "Network", "type": "string" }, "source": { "default": "manual", "description": "Link source", "title": "Source", "type": "string" }, "url": { "description": "Full URL", "examples": [ "https://linkedin.com/in/jsmith" ], "title": "Url", "type": "string" }, "verified_by_user": { "default": false, "title": "Verified By User", "type": "boolean" } }, "required": [ "network", "url" ], "title": "ProfileLinkCreate", "type": "object" }, "ProfileLinksResponse": { "description": "Response for profile links queries.", "properties": { "contact_id": { "title": "Contact Id", "type": "string" }, "profile_links": { "items": { "$ref": "#/components/schemas/ProfileLink" }, "title": "Profile Links", "type": "array" } }, "required": [ "contact_id" ], "title": "ProfileLinksResponse", "type": "object" }, "ProfilePhoneNumberResponse": { "description": "Response model for account phone numbers in profile payload.", "properties": { "id": { "description": "Phone number UUID", "format": "uuid", "title": "Id", "type": "string" }, "is_primary": { "description": "Whether this phone is primary", "title": "Is Primary", "type": "boolean" }, "is_verified": { "description": "Whether this phone is verified", "title": "Is Verified", "type": "boolean" }, "label": { "description": "Phone label", "title": "Label", "type": "string" }, "phone_number": { "description": "Phone number in E.164 format", "title": "Phone Number", "type": "string" }, "verified_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "Verification timestamp", "title": "Verified At" } }, "required": [ "id", "phone_number", "label", "is_primary", "is_verified" ], "title": "ProfilePhoneNumberResponse", "type": "object" }, "ProfileResponse": { "properties": { "avg_email_length": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Avg Email Length" }, "avg_sentence_length": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "title": "Avg Sentence Length" }, "closing_style": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Closing Style" }, "directness_score": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "title": "Directness Score" }, "extraction_model": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Extraction Model" }, "formality_score": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "title": "Formality Score" }, "greeting_patterns": { "default": [], "items": { "type": "string" }, "title": "Greeting Patterns", "type": "array" }, "greeting_style": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Greeting Style" }, "id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "default": null, "title": "Id" }, "last_analyzed_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Last Analyzed At" }, "profile_version": { "default": 0, "title": "Profile Version", "type": "integer" }, "sample_email_ids": { "default": [], "items": { "format": "uuid", "type": "string" }, "title": "Sample Email Ids", "type": "array" }, "samples_analyzed": { "default": 0, "title": "Samples Analyzed", "type": "integer" }, "signoff_patterns": { "default": [], "items": { "type": "string" }, "title": "Signoff Patterns", "type": "array" }, "style_guide": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Style Guide" }, "tone_formal": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "title": "Tone Formal" }, "tone_length": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Tone Length" }, "uses_contractions": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "title": "Uses Contractions" }, "uses_emoji": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "title": "Uses Emoji" }, "vocabulary_notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Vocabulary Notes" } }, "title": "ProfileResponse", "type": "object" }, "ProgressResponse": { "properties": { "bounce_rate": { "default": 0.0, "description": "bounced / sent (0 when nothing sent).", "title": "Bounce Rate", "type": "number" }, "bounce_rate_flag": { "default": false, "description": "True when bounce_rate reached the 2% best-practice ceiling (R13).", "title": "Bounce Rate Flag", "type": "boolean" }, "bounced": { "default": 0, "description": "Coalesced bounced engagement events for this campaign (R13).", "title": "Bounced", "type": "integer" }, "campaign_id": { "title": "Campaign Id", "type": "string" }, "cancelled": { "default": 0, "title": "Cancelled", "type": "integer" }, "complained": { "default": 0, "description": "Coalesced complained engagement events for this campaign (R13).", "title": "Complained", "type": "integer" }, "complaint_rate": { "default": 0.0, "description": "complained / sent (0 when nothing sent).", "title": "Complaint Rate", "type": "number" }, "complaint_rate_flag": { "default": false, "description": "True when complaint_rate reached Gmail's 0.3% never-exceed bulk-sender threshold (R13).", "title": "Complaint Rate Flag", "type": "boolean" }, "failed": { "default": 0, "title": "Failed", "type": "integer" }, "pause_reason": { "default": "", "title": "Pause Reason", "type": "string" }, "queued": { "default": 0, "title": "Queued", "type": "integer" }, "rendering": { "default": 0, "title": "Rendering", "type": "integer" }, "retrying": { "default": 0, "title": "Retrying", "type": "integer" }, "sending": { "default": 0, "title": "Sending", "type": "integer" }, "sent": { "default": 0, "title": "Sent", "type": "integer" }, "status": { "title": "Status", "type": "string" }, "uncertain": { "default": 0, "title": "Uncertain", "type": "integer" }, "uncertain_actionable": { "default": 0, "description": "Uncertain rows past the self-heal timeout — awaiting an explicit operator retry/skip decision.", "title": "Uncertain Actionable", "type": "integer" } }, "required": [ "campaign_id", "status" ], "title": "ProgressResponse", "type": "object" }, "ProjectCreate": { "description": "Input model for creating new projects.\n\nUsed in:\n - POST /api/v1/projects\n\nAttributes:\n name: Project name (required, 1-255 chars)\n description: Project description (optional)\n project_type: Type (optional)\n status: Initial status (optional, default: active)\n start_date: Start date (optional)\n end_date: End date (optional)\n auto_archive: Auto-archive setting (optional, default: true)\n primary_family_member_id: Primary family member UUID (optional)\n goals: List of goals (optional)\n milestones: Milestone objects (optional)\n budget: Budget amount (optional)\n keywords: Matching keywords (optional)\n sender_patterns: Sender domain patterns (optional)\n organization_matches: Organization names (optional)\n color: UI color (optional)\n icon: UI icon (optional)\n\nRelated: migration 237_projects.sql", "properties": { "auto_archive": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": true, "description": "Auto-archive when end_date passes", "title": "Auto Archive" }, "budget": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Budget amount", "title": "Budget" }, "classification_rules": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "description": "Classification rules JSON", "title": "Classification Rules" }, "color": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "UI color (hex)", "title": "Color" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Project description", "title": "Description" }, "enable_chat": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": true, "description": "Ensure the project's chat channel on create (opt-out — default true)", "title": "Enable Chat" }, "end_date": { "anyOf": [ { "format": "date", "type": "string" }, { "type": "null" } ], "description": "Project end date", "title": "End Date" }, "goals": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "description": "List of goals", "title": "Goals" }, "icon": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "UI icon name", "title": "Icon" }, "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Client-provided UUID for idempotent creates (PowerSync offline sync)", "title": "Id" }, "is_global": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": false, "description": "Visible to entire tenant", "title": "Is Global" }, "keywords": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "description": "Matching keywords", "title": "Keywords" }, "milestones": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "description": "Milestone objects", "title": "Milestones" }, "name": { "description": "Project name (1-255 characters)", "examples": [ "Soccer Fall 2026" ], "maxLength": 255, "minLength": 1, "title": "Name", "type": "string" }, "organization_matches": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "description": "Organization names", "title": "Organization Matches" }, "owner_type": { "anyOf": [ { "pattern": "^(user|account)$", "type": "string" }, { "type": "null" } ], "default": "user", "description": "Owner type (user|account)", "title": "Owner Type" }, "primary_family_member_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Primary family member UUID", "title": "Primary Family Member Id" }, "project_type": { "anyOf": [ { "pattern": "^(activity|goal|recurring|event|household|vacation|school|administrative|creative|community|work)?$", "type": "string" }, { "type": "null" } ], "description": "Project type (activity|goal|recurring|event|household|vacation|school|administrative|creative|community|work)", "title": "Project Type" }, "sender_patterns": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "description": "Sender domain patterns", "title": "Sender Patterns" }, "start_date": { "anyOf": [ { "format": "date", "type": "string" }, { "type": "null" } ], "description": "Project start date", "title": "Start Date" }, "status": { "anyOf": [ { "pattern": "^(active|archived|completed)?$", "type": "string" }, { "type": "null" } ], "default": "active", "description": "Lifecycle status (active|archived|completed)", "title": "Status" }, "visibility": { "anyOf": [ { "pattern": "^(private|shared)$", "type": "string" }, { "type": "null" } ], "default": "private", "description": "Visibility (private|shared); omitted creates are private (TIDY-20007)", "title": "Visibility" } }, "required": [ "name" ], "title": "ProjectCreate", "type": "object" }, "ProjectFileAssociateRequest": { "description": "Associate an existing canonical file into the project.", "properties": { "file_id": { "description": "Canonical file id (F- or bare UUID)", "title": "File Id", "type": "string" } }, "required": [ "file_id" ], "title": "ProjectFileAssociateRequest", "type": "object" }, "ProjectFileListResponse": { "properties": { "count": { "title": "Count", "type": "integer" }, "files": { "items": { "$ref": "#/components/schemas/ProjectFileMembershipResponse" }, "title": "Files", "type": "array" } }, "required": [ "files", "count" ], "title": "ProjectFileListResponse", "type": "object" }, "ProjectFileMembershipResponse": { "description": "Membership row + the canonical file payload.", "properties": { "added_at": { "format": "date-time", "title": "Added At", "type": "string" }, "added_by": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Added By" }, "created": { "default": true, "description": "False when the association already existed (idempotent hit)", "title": "Created", "type": "boolean" }, "file": { "anyOf": [ { "$ref": "#/components/schemas/FileResponse" }, { "type": "null" } ], "default": null }, "file_id": { "title": "File Id", "type": "string" }, "membership_id": { "title": "Membership Id", "type": "string" }, "project_id": { "title": "Project Id", "type": "string" }, "sort_order": { "default": 0, "title": "Sort Order", "type": "integer" } }, "required": [ "membership_id", "project_id", "file_id", "added_at" ], "title": "ProjectFileMembershipResponse", "type": "object" }, "ProjectHealth": { "properties": { "completed": { "title": "Completed", "type": "integer" }, "completion_pct": { "title": "Completion Pct", "type": "number" }, "overdue": { "title": "Overdue", "type": "integer" }, "project_id": { "title": "Project Id", "type": "string" }, "project_name": { "title": "Project Name", "type": "string" }, "total": { "title": "Total", "type": "integer" } }, "required": [ "project_id", "project_name", "total", "completed", "overdue", "completion_pct" ], "title": "ProjectHealth", "type": "object" }, "ProjectHighlightGenerateResponse": { "properties": { "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "id": { "title": "Id", "type": "string" }, "llm_usage": { "$ref": "#/components/schemas/ProjectHighlightLlmUsageResponse" }, "note_id": { "title": "Note Id", "type": "string" }, "since_ts": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Since Ts" }, "stats": { "$ref": "#/components/schemas/ProjectHighlightStatsResponse" }, "summary_text": { "title": "Summary Text", "type": "string" }, "title": { "title": "Title", "type": "string" }, "until_ts": { "format": "date-time", "title": "Until Ts", "type": "string" } }, "required": [ "id", "note_id", "title", "summary_text", "stats", "created_at", "since_ts", "until_ts", "llm_usage" ], "title": "ProjectHighlightGenerateResponse", "type": "object" }, "ProjectHighlightLlmUsageResponse": { "properties": { "completion_tokens": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Completion Tokens" }, "model": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Model" }, "prompt_tokens": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Prompt Tokens" }, "request_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Request Id" }, "total_tokens": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Total Tokens" } }, "title": "ProjectHighlightLlmUsageResponse", "type": "object" }, "ProjectHighlightStatsResponse": { "properties": { "activity_by_type": { "additionalProperties": { "additionalProperties": { "type": "integer" }, "type": "object" }, "title": "Activity By Type", "type": "object" }, "contacts_touched": { "default": 0, "title": "Contacts Touched", "type": "integer" }, "emails_count": { "default": 0, "title": "Emails Count", "type": "integer" }, "messages_count": { "default": 0, "title": "Messages Count", "type": "integer" }, "notes_written": { "default": 0, "title": "Notes Written", "type": "integer" }, "tasks_closed": { "default": 0, "title": "Tasks Closed", "type": "integer" }, "tasks_new": { "default": 0, "title": "Tasks New", "type": "integer" }, "tasks_total": { "default": 0, "title": "Tasks Total", "type": "integer" } }, "title": "ProjectHighlightStatsResponse", "type": "object" }, "ProjectId": { "description": "Typed primitive ID for projects (prefix 'P').", "examples": [ "P-550e8400-e29b-41d4-a716-446655440000" ], "pattern": "^P-[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "title": "ProjectId", "type": "string", "x-tidy-typed-id-prefix": "P", "x-tidy-typed-id-table": "projects" }, "ProjectLinkCreate": { "description": "Input model for linking an item to a project.\n\nUsed in:\n - POST /api/v1/projects/{id}/items\n\nAttributes:\n primitive_type: Type of item to link (required)\n primitive_id: UUID of the item (required)\n link_source: How the link is being created (optional, default: user_assigned)\n confidence: Confidence score for auto-detected links (optional)\n\nRelated: migration 237_projects.sql", "properties": { "confidence": { "anyOf": [ { "maximum": 1.0, "minimum": 0.0, "type": "number" }, { "type": "null" } ], "default": 1.0, "description": "Confidence score 0.0-1.0", "title": "Confidence" }, "link_source": { "anyOf": [ { "pattern": "^(auto_detected|user_assigned|admin|llm_suggested)?$", "type": "string" }, { "type": "null" } ], "default": "user_assigned", "description": "Link creation source", "title": "Link Source" }, "primitive_id": { "description": "UUID of the item to link", "examples": [ "a1b2c3d4-..." ], "title": "Primitive Id", "type": "string" }, "primitive_type": { "description": "Type of item (email|task|event|calendar_event|contact|note|news_update|reminder|organization)", "examples": [ "task" ], "pattern": "^(email|task|event|calendar_event|contact|note|news_update|reminder|organization)$", "title": "Primitive Type", "type": "string" } }, "required": [ "primitive_type", "primitive_id" ], "title": "ProjectLinkCreate", "type": "object" }, "ProjectLinkResponse": { "description": "A linked item in a project.\n\nRepresents the junction between a project and a primitive.\n\nAttributes:\n id: Link UUID\n primitive_type: Type of linked item (email, task, event, etc.)\n primitive_id: UUID of the linked item\n link_source: How the link was created\n confidence: Confidence score for auto-detected links (0.0-1.0)\n created_at: When the link was created\n\nRelated: linked_references table (source_container_type='project')", "properties": { "confidence": { "anyOf": [ { "maximum": 1.0, "minimum": 0.0, "type": "number" }, { "type": "null" } ], "default": 1.0, "description": "Confidence score for auto-detected links (0.0-1.0)", "title": "Confidence" }, "created_at": { "description": "When the link was created", "format": "date-time", "title": "Created At", "type": "string" }, "id": { "description": "Link UUID", "title": "Id", "type": "string" }, "link_source": { "default": "user_assigned", "description": "How the link was created (auto_detected|user_assigned|admin|llm_suggested)", "examples": [ "user_assigned" ], "title": "Link Source", "type": "string" }, "primitive_id": { "description": "UUID of the linked item", "title": "Primitive Id", "type": "string" }, "primitive_type": { "description": "Type of linked item (email|task|event|calendar_event|contact|note|news_update|reminder|organization)", "examples": [ "email", "task" ], "title": "Primitive Type", "type": "string" } }, "required": [ "id", "primitive_type", "primitive_id", "created_at" ], "title": "ProjectLinkResponse", "type": "object" }, "ProjectRepoLinkRequest": { "description": "Link (or re-link) a project to a repository.", "properties": { "clone_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Clone Url" }, "default_branch": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Default Branch" }, "provider": { "description": "Source-control provider id, e.g. 'github'", "title": "Provider", "type": "string" }, "repo_full_name": { "description": "owner/name", "minLength": 1, "title": "Repo Full Name", "type": "string" }, "web_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Web Url" } }, "required": [ "provider", "repo_full_name" ], "title": "ProjectRepoLinkRequest", "type": "object" }, "ProjectRepoLinkResponse": { "description": "A project's linked repository. Absent (404) when the project has none.", "properties": { "clone_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Clone Url" }, "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "default_branch": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Default Branch" }, "linked_by": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Linked By" }, "project_id": { "title": "Project Id", "type": "string" }, "provider": { "title": "Provider", "type": "string" }, "repo_full_name": { "title": "Repo Full Name", "type": "string" }, "updated_at": { "format": "date-time", "title": "Updated At", "type": "string" }, "web_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Web Url" } }, "required": [ "project_id", "provider", "repo_full_name", "created_at", "updated_at" ], "title": "ProjectRepoLinkResponse", "type": "object" }, "ProjectRequirementsCoverage": { "description": "Batch coverage + gap queries for a project.", "properties": { "project_id": { "title": "Project Id", "type": "string" }, "requirements": { "default": [], "items": { "$ref": "#/components/schemas/RequirementCoverage" }, "title": "Requirements", "type": "array" }, "unplanned_requirements": { "default": [], "items": { "type": "string" }, "title": "Unplanned Requirements", "type": "array" }, "work_without_requirements": { "default": [], "items": { "$ref": "#/components/schemas/UnlinkedWorkItem" }, "title": "Work Without Requirements", "type": "array" } }, "required": [ "project_id" ], "title": "ProjectRequirementsCoverage", "type": "object" }, "ProjectResponse": { "description": "Complete project object returned by API endpoints.\n\nRelated: migration 237_projects.sql, 019_project_multi_user_columns.sql", "properties": { "auto_archive": { "default": true, "description": "Auto-archive when end_date passes", "title": "Auto Archive", "type": "boolean" }, "budget": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "description": "Project budget amount", "examples": [ 500.0 ], "title": "Budget" }, "classification_rules": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "default": null, "description": "Classification rules JSON", "title": "Classification Rules" }, "color": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "UI display color (hex)", "examples": [ "#22c55e" ], "title": "Color" }, "completion_percentage": { "default": 0, "description": "Progress 0-100%", "maximum": 100, "minimum": 0, "title": "Completion Percentage", "type": "integer" }, "created_at": { "description": "Creation timestamp", "format": "date-time", "title": "Created At", "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Project description", "examples": [ "Harrison's soccer season" ], "title": "Description" }, "end_date": { "anyOf": [ { "format": "date", "type": "string" }, { "type": "null" } ], "default": null, "description": "Project end date", "examples": [ "2026-11-15" ], "title": "End Date" }, "goals": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "default": null, "description": "List of project goals", "examples": [ [ "Win 5 games", "Improve fitness" ] ], "title": "Goals" }, "icon": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "UI icon name", "examples": [ "trophy" ], "title": "Icon" }, "id": { "description": "Unique project identifier (UUID)", "title": "Id", "type": "string" }, "is_global": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": false, "description": "Visible to entire tenant", "title": "Is Global" }, "keywords": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "default": null, "description": "Keywords for email matching", "examples": [ [ "soccer", "practice", "game" ] ], "title": "Keywords" }, "members": { "anyOf": [ { "items": {}, "type": "array" }, { "type": "null" } ], "default": null, "description": "Project members (in detail view)", "title": "Members" }, "milestones": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "default": null, "description": "Milestone objects [{name, due_date, completed}]", "examples": [ [ { "completed": false, "due_date": "2026-08-20", "name": "First game" } ] ], "title": "Milestones" }, "name": { "description": "Project name", "examples": [ "Soccer Fall 2026" ], "title": "Name", "type": "string" }, "organization_matches": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "default": null, "description": "Organization names to match", "examples": [ [ "Youth Soccer League" ] ], "title": "Organization Matches" }, "owner_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Owner account UUID", "title": "Owner Id" }, "owner_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": "user", "description": "Owner type (user|account)", "title": "Owner Type" }, "primary_family_member_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Primary associated family member UUID", "title": "Primary Family Member Id" }, "project_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Project type (activity|goal|recurring|event|household|vacation|school|administrative|creative|community|work)", "examples": [ "activity" ], "title": "Project Type" }, "sender_patterns": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "default": null, "description": "Domain patterns for matching senders", "examples": [ [ "@soccerclub.org" ] ], "title": "Sender Patterns" }, "shortcode": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Project shortcode (auto-generated; e.g., 'KITCHEN')", "examples": [ "KITCHEN" ], "title": "Shortcode" }, "sort_order": { "default": 0, "description": "Display order", "title": "Sort Order", "type": "integer" }, "start_date": { "anyOf": [ { "format": "date", "type": "string" }, { "type": "null" } ], "default": null, "description": "Project start date", "examples": [ "2026-08-15" ], "title": "Start Date" }, "stats": { "anyOf": [ { "$ref": "#/components/schemas/ProjectStats" }, { "type": "null" } ], "default": null, "description": "Aggregate item counts (in detail view)" }, "status": { "default": "active", "description": "Lifecycle status (active|archived|completed)", "examples": [ "active" ], "title": "Status", "type": "string" }, "tenant_id": { "description": "Associated tenant identifier (UUID)", "title": "Tenant Id", "type": "string" }, "updated_at": { "description": "Last modification timestamp", "format": "date-time", "title": "Updated At", "type": "string" }, "visibility": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": "private", "description": "Visibility (private|shared)", "title": "Visibility" }, "work_config": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "description": "Per-project work configuration (facet/type/icons/time fields)", "title": "Work Config" } }, "required": [ "id", "tenant_id", "name", "created_at", "updated_at" ], "title": "ProjectResponse", "type": "object" }, "ProjectRootCloneAccessResponse": { "description": "Whether a workshop can clone the project's linked repository for the\ncaller. `repository` is null when the project links no GitHub repository.", "properties": { "code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Code" }, "message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Message" }, "ready": { "title": "Ready", "type": "boolean" }, "repository": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Repository" } }, "required": [ "repository", "ready" ], "title": "ProjectRootCloneAccessResponse", "type": "object" }, "ProjectRootCommandResponse": { "properties": { "push_job_id": { "format": "uuid", "title": "Push Job Id", "type": "string" }, "root_id": { "format": "uuid", "title": "Root Id", "type": "string" }, "root_path": { "title": "Root Path", "type": "string" }, "status": { "enum": [ "pending", "ready", "error", "detached" ], "title": "Status", "type": "string" } }, "required": [ "root_id", "root_path", "status", "push_job_id" ], "title": "ProjectRootCommandResponse", "type": "object" }, "ProjectRootExposeRequest": { "description": "The owner's confirmation, and the two things it is bound to.\n\n`confirmed_path` and `confirmed_question` are not decoration: the server\nchecks both against the inspection that produced the question, so a client\ncannot confirm one directory and expose another, and a directory that\nchanged since it was inspected is inspected again rather than exposed.", "properties": { "confirmed_path": { "maxLength": 4096, "minLength": 2, "title": "Confirmed Path", "type": "string" }, "confirmed_question": { "enum": [ "work_here", "confirm_link", "link_other_repo", "create_and_clone", "create_empty" ], "title": "Confirmed Question", "type": "string" }, "mode": { "default": "read_write", "enum": [ "read_write", "read_only" ], "title": "Mode", "type": "string" } }, "required": [ "confirmed_path", "confirmed_question" ], "title": "ProjectRootExposeRequest", "type": "object" }, "ProjectRootInspectRequest": { "description": "The candidate directory. Absolute; the shape is checked here and the\nmachine contract — symlinks, the OS's own trees, ownership — is checked by\nroot on the box, which is the only place it can be checked honestly.", "properties": { "root_path": { "maxLength": 4096, "minLength": 2, "title": "Root Path", "type": "string" } }, "required": [ "root_path" ], "title": "ProjectRootInspectRequest", "type": "object" }, "ProjectStats": { "description": "Aggregate statistics for a project.\n\nProvides counts of linked items by type for dashboard display.\n\nAttributes:\n email_count: Number of linked emails\n task_count: Number of linked tasks\n event_count: Number of linked events (internal + external)\n contact_count: Number of linked contacts\n note_count: Number of linked notes\n total_links: Total number of linked items\n\nRelated: project_stats view in migration 237_projects.sql", "properties": { "contact_count": { "default": 0, "description": "Number of linked contacts", "title": "Contact Count", "type": "integer" }, "email_count": { "default": 0, "description": "Number of linked emails", "title": "Email Count", "type": "integer" }, "event_count": { "default": 0, "description": "Number of linked calendar events", "title": "Event Count", "type": "integer" }, "note_count": { "default": 0, "description": "Number of linked notes", "title": "Note Count", "type": "integer" }, "task_count": { "default": 0, "description": "Number of linked tasks", "title": "Task Count", "type": "integer" }, "total_links": { "default": 0, "description": "Total number of linked items", "title": "Total Links", "type": "integer" } }, "title": "ProjectStats", "type": "object" }, "ProjectSuggestionItem": { "description": "A single project suggestion.", "properties": { "confidence": { "default": 0.0, "description": "Confidence score (0-1)", "title": "Confidence", "type": "number" }, "created_at": { "description": "When the suggestion was created", "format": "date-time", "title": "Created At", "type": "string" }, "id": { "description": "UUID of the suggestion", "title": "Id", "type": "string" }, "source_excerpt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Source email excerpt", "title": "Source Excerpt" }, "suggested_keywords": { "description": "Keywords", "items": { "type": "string" }, "title": "Suggested Keywords", "type": "array" }, "suggested_name": { "description": "Suggested project name", "title": "Suggested Name", "type": "string" }, "suggested_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Suggested project type", "title": "Suggested Type" } }, "required": [ "id", "suggested_name", "created_at" ], "title": "ProjectSuggestionItem", "type": "object" }, "ProjectSummaryResponse": { "properties": { "final_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Final Reason" }, "generation_mode": { "description": "deterministic_extractive | local_model | cloud_model", "title": "Generation Mode", "type": "string" }, "input_watermark": { "title": "Input Watermark", "type": "string" }, "project_id": { "title": "Project Id", "type": "string" }, "provisional": { "title": "Provisional", "type": "boolean" }, "quality": { "additionalProperties": true, "title": "Quality", "type": "object" }, "state": { "description": "provisional | upgrading | final", "title": "State", "type": "string" }, "summary": { "additionalProperties": true, "title": "Summary", "type": "object" } }, "required": [ "project_id", "state", "generation_mode", "provisional", "input_watermark" ], "title": "ProjectSummaryResponse", "type": "object" }, "ProjectUpdate": { "description": "Input model for updating existing projects.\n\nUsed in:\n - PUT /api/v1/projects/{id}\n - PATCH /api/v1/projects/{id}\n\nAll fields are optional - only provided fields are updated.\n\nRelated: migration 237_projects.sql", "properties": { "auto_archive": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Auto-archive setting", "title": "Auto Archive" }, "base_values": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Base Values" }, "budget": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Budget", "title": "Budget" }, "classification_rules": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "description": "Classification rules JSON", "title": "Classification Rules" }, "color": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "UI color", "title": "Color" }, "completion_percentage": { "anyOf": [ { "maximum": 100.0, "minimum": 0.0, "type": "integer" }, { "type": "null" } ], "description": "Completion 0-100%", "title": "Completion Percentage" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Project description", "title": "Description" }, "end_date": { "anyOf": [ { "format": "date", "type": "string" }, { "type": "null" } ], "description": "End date", "title": "End Date" }, "goals": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "description": "Goals list", "title": "Goals" }, "icon": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "UI icon", "title": "Icon" }, "is_global": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Visible to entire tenant", "title": "Is Global" }, "keywords": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "description": "Keywords", "title": "Keywords" }, "milestones": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "description": "Milestones", "title": "Milestones" }, "name": { "anyOf": [ { "maxLength": 255, "minLength": 1, "type": "string" }, { "type": "null" } ], "description": "Project name (1-255 characters)", "title": "Name" }, "organization_matches": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "description": "Organization matches", "title": "Organization Matches" }, "primary_family_member_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Primary family member UUID", "title": "Primary Family Member Id" }, "project_type": { "anyOf": [ { "pattern": "^(activity|goal|recurring|event|household|vacation|school|administrative|creative|community|work)?$", "type": "string" }, { "type": "null" } ], "description": "Project type (activity|goal|recurring|event|household|vacation|school|administrative|creative|community|work)", "title": "Project Type" }, "sender_patterns": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "description": "Sender patterns", "title": "Sender Patterns" }, "shortcode": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Project shortcode (2-8 chars, [A-Z][A-Z0-9]+, not reserved)", "examples": [ "WORK" ], "title": "Shortcode" }, "sort_order": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Display order", "title": "Sort Order" }, "source_context": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Source Context" }, "start_date": { "anyOf": [ { "format": "date", "type": "string" }, { "type": "null" } ], "description": "Start date", "title": "Start Date" }, "status": { "anyOf": [ { "pattern": "^(active|archived|completed)?$", "type": "string" }, { "type": "null" } ], "description": "Lifecycle status", "title": "Status" }, "visibility": { "anyOf": [ { "pattern": "^(private|shared)$", "type": "string" }, { "type": "null" } ], "description": "Visibility (private|shared)", "title": "Visibility" }, "work_config": { "anyOf": [ { "$ref": "#/components/schemas/WorkConfigUpdate" }, { "type": "null" } ], "description": "Per-project work configuration (facet/type/icons/time fields)" } }, "title": "ProjectUpdate", "type": "object" }, "ProjectionRetryResult": { "properties": { "conversation_id": { "format": "uuid", "title": "Conversation Id", "type": "string" } }, "required": [ "conversation_id" ], "title": "ProjectionRetryResult", "type": "object" }, "PromoteGroupResponse": { "properties": { "members_linked": { "title": "Members Linked", "type": "integer" }, "organization_id": { "format": "uuid", "title": "Organization Id", "type": "string" }, "orgs_parented": { "title": "Orgs Parented", "type": "integer" }, "orgs_skipped": { "default": [], "items": { "$ref": "#/components/schemas/PromoteSkippedOrg" }, "title": "Orgs Skipped", "type": "array" } }, "required": [ "organization_id", "members_linked", "orgs_parented" ], "title": "PromoteGroupResponse", "type": "object" }, "PromoteResponse": { "properties": { "from_visibility": { "title": "From Visibility", "type": "string" }, "merged": { "default": false, "title": "Merged", "type": "boolean" }, "ok": { "default": true, "title": "Ok", "type": "boolean" }, "redirected_facets": { "default": 0, "title": "Redirected Facets", "type": "integer" }, "redirected_references": { "default": 0, "title": "Redirected References", "type": "integer" }, "redirected_tags": { "default": 0, "title": "Redirected Tags", "type": "integer" }, "surviving_id": { "title": "Surviving Id", "type": "string" }, "to_visibility": { "title": "To Visibility", "type": "string" } }, "required": [ "surviving_id", "from_visibility", "to_visibility" ], "title": "PromoteResponse", "type": "object" }, "PromoteSkippedOrg": { "description": "An organization member skipped during promotion (already parented).", "properties": { "id": { "format": "uuid", "title": "Id", "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name" }, "reason": { "title": "Reason", "type": "string" } }, "required": [ "id", "reason" ], "title": "PromoteSkippedOrg", "type": "object" }, "PromotionRequest": { "properties": { "activate_descriptor": { "default": false, "title": "Activate Descriptor", "type": "boolean" }, "candidate_path": { "title": "Candidate Path", "type": "string" }, "release_path": { "title": "Release Path", "type": "string" }, "sha256": { "title": "Sha256", "type": "string" } }, "required": [ "candidate_path", "release_path", "sha256" ], "title": "PromotionRequest", "type": "object" }, "PromptGenerateRequest": { "description": "Start one generation from a prompt alone (TIDY-19705 F10).\n\nThe prompt is the run's ONLY source: the producer grounds the output in what\nit says, so a prompt that names a topic without its material gets a thin\nresult. To generate from notes, files or mail, build a bundle instead.", "properties": { "facet_slug": { "description": "Output type to generate, e.g. `slide_deck`", "minLength": 1, "title": "Facet Slug", "type": "string" }, "prompt": { "description": "What to make, and the material to make it from", "minLength": 1, "title": "Prompt", "type": "string" }, "surface": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Client surface that started the generation (observability)", "title": "Surface" } }, "required": [ "facet_slug", "prompt" ], "title": "PromptGenerateRequest", "type": "object" }, "PromptNeededInput": { "description": "A required handler/workflow input that the client must collect (D6).\n\nEmitted when a REQUIRED input on the resolved handler (or bound workflow)\nhas neither a mapped ``ActionParamSpec`` nor a supplied ``prompt_values``\nentry — i.e. the action author did not map it and the user did not type it.\nThe client renders a prompt from this shape and re-invokes with the value\nin ``prompt_values``. Server-only inputs are NOT reported here — they stay a\nhard 422 (genuinely un-promptable).", "properties": { "default": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pre-selected choice / default value", "title": "Default" }, "key": { "description": "Handler/workflow input name", "title": "Key", "type": "string" }, "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Human label for the prompt field", "title": "Label" }, "multiline": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Render a textarea for this string", "title": "Multiline" }, "option_labels": { "anyOf": [ { "additionalProperties": { "type": "string" }, "type": "object" }, { "type": "null" } ], "description": "Member-facing label per option value", "title": "Option Labels" }, "options": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "description": "Choices for a select input", "title": "Options" }, "required": { "default": true, "description": "Always true for prompt-needed", "title": "Required", "type": "boolean" }, "type": { "default": "string", "description": "Declared input type for the prompt field", "title": "Type", "type": "string" } }, "required": [ "key" ], "title": "PromptNeededInput", "type": "object" }, "PropertyChangedTrigger": { "additionalProperties": false, "description": "Fires when ``field`` changes on an item of the bound facet.\n\n``scope`` semantics reuse the data_change trigger schema\n(``services/trigger_registry.py``): ``any`` = changed to any new value;\n``to`` = new value equals ``value`` and the old value differed;\n``from_to`` = old value equals ``from_value`` and new value equals\n``to_value``.", "properties": { "field": { "minLength": 1, "title": "Field", "type": "string" }, "from_value": { "anyOf": [ {}, { "type": "null" } ], "title": "From Value" }, "kind": { "const": "property_changed", "title": "Kind", "type": "string" }, "scope": { "default": "any", "enum": [ "any", "to", "from_to" ], "title": "Scope", "type": "string" }, "tags_any": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Tags Any" }, "to_value": { "anyOf": [ {}, { "type": "null" } ], "title": "To Value" }, "value": { "anyOf": [ {}, { "type": "null" } ], "title": "Value" } }, "required": [ "kind", "field" ], "title": "PropertyChangedTrigger", "type": "object" }, "ProposalApprove": { "properties": { "review_digest": { "anyOf": [ { "maxLength": 128, "type": "string" }, { "type": "null" } ], "description": "TIDY-19882: the `review_digest` of the hire the reviewer was shown. Required to approve a hire that sets up a workshop employee; a stale digest is refused.", "title": "Review Digest" } }, "title": "ProposalApprove", "type": "object" }, "ProposalApproveRequest": { "description": "The member's approval decision.\n\nEither an existing ``organization_id`` (moved to approved) or an\n``organization_name`` for a new organization. The contact is an existing\n``contact_id`` or, by default, a new contact for the proposal's address.", "properties": { "contact_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Existing contact to link. Must be visible to the caller.", "title": "Contact Id" }, "contact_name": { "anyOf": [ { "maxLength": 200, "type": "string" }, { "type": "null" } ], "description": "Name for the NEW contact; defaults to the address.", "title": "Contact Name" }, "organization_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Existing organization to link. Must be visible to the caller.", "title": "Organization Id" }, "organization_name": { "anyOf": [ { "maxLength": 200, "type": "string" }, { "type": "null" } ], "description": "Name for a NEW organization.", "title": "Organization Name" } }, "title": "ProposalApproveRequest", "type": "object" }, "ProposalApproveResponse": { "properties": { "contact_created": { "title": "Contact Created", "type": "boolean" }, "contact_id": { "title": "Contact Id", "type": "string" }, "enrichment_hook_emitted": { "title": "Enrichment Hook Emitted", "type": "boolean" }, "mapping_created": { "title": "Mapping Created", "type": "boolean" }, "mapping_id": { "title": "Mapping Id", "type": "string" }, "normalized_domain": { "title": "Normalized Domain", "type": "string" }, "organization_created": { "title": "Organization Created", "type": "boolean" }, "organization_id": { "title": "Organization Id", "type": "string" }, "proposal_id": { "title": "Proposal Id", "type": "string" } }, "required": [ "proposal_id", "contact_id", "organization_id", "contact_created", "organization_created", "mapping_id", "mapping_created", "normalized_domain", "enrichment_hook_emitted" ], "title": "ProposalApproveResponse", "type": "object" }, "ProposalCreate": { "properties": { "assignee_agent_account_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "TIDY-16480: draft this task FOR another employee. The manager's approval performs the assignment — a VE can never route work at a colleague directly. Task proposals only.", "title": "Assignee Agent Account Id" }, "change": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "TIDY-20067: required for a change to an existing employee, filed from your owner's DM with you (yourself, or an employee that reports to you). placement: {employee_account_id, target_kind: 'workshop'|'hosted' (Tidy compute), to_workshop_id}. runtime: {employee_account_id, harness, model?: {source: 'tidy_inference'|'plugin'|'own_sign_in', plugin_id?, models?}, make_default?}. manager: {employee_account_id, reports_to_account_id (a member or employee; null = nobody)}. Approval applies it as the person who approves, through their own settings. TIDY-20067 F6: kind='job' with a `change` is scheduled work ANOTHER employee runs: {employee_account_id, name, prompt, cron or the recurrence_* fields, starts_at?, ends_at?, repeats?, max_runs?, command?, command_timeout_sec?} (POST /scheduled-jobs' own fields). Approval declares it as the approver. TIDY-20067 F5: plugin_lend: {employee_account_id, plugin_id, capabilities, days?} (shipped to its workshop); secret_file_lend: {employee_account_id, file_id or file_title}; data_access: {employee_account_id, data: 'email'|'calendar'|'notes'|'contacts'|'tasks'|'projects'|'files'|'photos', access: 'read'|'read_write', days?}; skill_give: {employee_account_id, skill_id, version, runtime?}. TIDY-20203 F6: repo_skill: {employee_account_id, url, commit (the 40-hex commit you reviewed), ref?, include?, exclude?, credentials?: [{env_key, purpose?, required?}], env_file?, requires?: [{name: node|python|chrome, min_version?, required?, purpose?}], review (your review of the code at that commit)} — approval adds it as the approver's skill and gives it to that employee.", "title": "Change" }, "cron": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Required for a reflection's kind='job' (your own duty): five-field cron. A job for another employee carries its schedule in `change`.", "title": "Cron" }, "description": { "maxLength": 20000, "minLength": 1, "title": "Description", "type": "string" }, "goal_edit": { "anyOf": [ { "$ref": "#/components/schemas/ProposalGoalEdit" }, { "type": "null" } ], "description": "Required for kind='goal': the goal change proposed." }, "goal_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "TIDY-16479: the active goal this work serves. REQUIRED once the proposing employee has at least one active assigned goal.", "title": "Goal Id" }, "hire": { "anyOf": [ { "$ref": "#/components/schemas/ProposedHire" }, { "type": "null" } ], "description": "TIDY-19500 F5: required for kind='hire' — the employees to hire. Approval defines them, owned by the person who approves. TIDY-19882: one employee may name an existing workshop to land on, with its model access and the plugins and secret files lent to it on day one. TIDY-20125: model_access.method 'own_sign_in' runs a workshop harness that signs itself in (Claude Code) on that sign-in, done by the approver right after approving; omitted, it is Tidy inference where the harness runs it, else its own sign-in. A method the harness cannot run is refused at filing." }, "kind": { "description": "'task', 'job', 'goal' or 'hire'; TIDY-20067: 'placement', 'runtime', 'manager', 'plugin_lend', 'secret_file_lend', 'data_access' or 'skill_give' for a change to an existing employee; TIDY-20203 F6: 'repo_skill' to add a GitHub repository as a skill that employee carries", "title": "Kind", "type": "string" }, "priority": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Priority" }, "rationale": { "anyOf": [ { "maxLength": 4000, "type": "string" }, { "type": "null" } ], "title": "Rationale" }, "timezone": { "anyOf": [ { "maxLength": 64, "type": "string" }, { "type": "null" } ], "title": "Timezone" }, "title": { "maxLength": 200, "minLength": 1, "title": "Title", "type": "string" }, "vetting": { "anyOf": [ { "$ref": "#/components/schemas/ProposalVetting" }, { "type": "null" } ], "description": "Required from a reflection or an employee's own turn (TIDY-20216). TIDY-19882: a hire your owner asked for in their own DM with you needs none." }, "work_summary": { "anyOf": [ { "maxLength": 400, "type": "string" }, { "type": "null" } ], "title": "Work Summary" } }, "required": [ "kind", "title", "description" ], "title": "ProposalCreate", "type": "object" }, "ProposalCreated": { "properties": { "created_by_wake_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Created By Wake Id" }, "expires_at": { "title": "Expires At", "type": "string" }, "id": { "title": "Id", "type": "string" }, "kind": { "title": "Kind", "type": "string" }, "status": { "title": "Status", "type": "string" }, "title": { "title": "Title", "type": "string" } }, "required": [ "id", "kind", "title", "status", "expires_at" ], "title": "ProposalCreated", "type": "object" }, "ProposalDisposition": { "properties": { "applied": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "description": "TIDY-20067: what an approved change to an employee did — `ok`, the `summary` lines the approver is shown, a `link` to where it shows, and a `next_step` {label, link} when one step stays the person's own (a harness sign-in).", "title": "Applied" }, "deployment": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "description": "TIDY-19882: an approved workshop hire's deployment — `deploy_queued` with its push job, or `assigned_not_deployed` with the refusal shown on the employee's card, where Retry is.", "title": "Deployment" }, "disposition": { "title": "Disposition", "type": "string" }, "employee_account_ids": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "default": null, "description": "TIDY-19500 F5: the employees an approved hire proposal defined.", "title": "Employee Account Ids" }, "goal_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "TIDY-16479: the goal an approved goal proposal landed.", "title": "Goal Id" }, "id": { "title": "Id", "type": "string" }, "kind": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Kind" }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Reason" }, "sign_in": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "description": "TIDY-20125: the harness sign-in this approval left to the person who approved it — a workshop hire, or a runtime change, on the harness's own sign-in: {kind: 'harness_sign_in', label, link, employee_account_id, runtime, workshop_id}. Also recorded on the request as `proposal.sign_in`; clients present the harness's sign-in where the person approved.", "title": "Sign In" } }, "required": [ "id", "disposition" ], "title": "ProposalDisposition", "type": "object" }, "ProposalGoalEdit": { "description": "TIDY-16479 (A15): the goal change a `kind='goal'` proposal asks for.", "properties": { "description": { "anyOf": [ { "maxLength": 20000, "type": "string" }, { "type": "null" } ], "title": "Description" }, "goal_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Change this existing goal. Omit to propose a new one.", "title": "Goal Id" }, "horizon": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "quarter | year | ongoing", "title": "Horizon" }, "status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "active | paused | achieved | abandoned", "title": "Status" }, "success_signal": { "anyOf": [ { "maxLength": 4000, "type": "string" }, { "type": "null" } ], "title": "Success Signal" }, "title": { "anyOf": [ { "maxLength": 200, "type": "string" }, { "type": "null" } ], "title": "Title" } }, "title": "ProposalGoalEdit", "type": "object" }, "ProposalList": { "properties": { "proposals": { "items": { "additionalProperties": true, "type": "object" }, "title": "Proposals", "type": "array" } }, "required": [ "proposals" ], "title": "ProposalList", "type": "object" }, "ProposalSuppressRequest": { "description": "Mute future proposals for a scope, and (by default) dismiss this one.", "properties": { "dismiss": { "default": true, "description": "Also resolve THIS proposal as rejected (history, not policy).", "title": "Dismiss", "type": "boolean" }, "expires_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "Optional lapse time — the mute stops applying on its own after it.", "title": "Expires At" }, "reason": { "anyOf": [ { "maxLength": 500, "type": "string" }, { "type": "null" } ], "title": "Reason" }, "scope_kind": { "default": "address", "description": "Explicit scope — muting an address never mutes its domain.", "enum": [ "address", "domain", "pattern" ], "title": "Scope Kind", "type": "string" }, "scope_value": { "anyOf": [ { "maxLength": 320, "type": "string" }, { "type": "null" } ], "description": "Defaults to the proposal's own address/domain; required for 'pattern'.", "title": "Scope Value" } }, "title": "ProposalSuppressRequest", "type": "object" }, "ProposalSuppressResponse": { "properties": { "expires_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Expires At" }, "proposal_id": { "title": "Proposal Id", "type": "string" }, "proposal_status": { "title": "Proposal Status", "type": "string" }, "scope_kind": { "title": "Scope Kind", "type": "string" }, "scope_value": { "title": "Scope Value", "type": "string" }, "suppression_id": { "title": "Suppression Id", "type": "string" } }, "required": [ "proposal_id", "proposal_status", "suppression_id", "scope_kind", "scope_value" ], "title": "ProposalSuppressResponse", "type": "object" }, "ProposalVetting": { "properties": { "adjustments": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "How the findings adjusted the proposal, or why it survives them.", "title": "Adjustments" }, "findings": { "description": "What those searches returned — prior art, reasons-not-to.", "items": { "type": "string" }, "title": "Findings", "type": "array" }, "queries": { "description": "The memory/platform searches run for this candidate.", "items": { "type": "string" }, "title": "Queries", "type": "array" } }, "required": [ "queries", "findings" ], "title": "ProposalVetting", "type": "object" }, "ProposedContact": { "properties": { "confidence": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Confidence" }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Email" }, "first_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "First Name" }, "id": { "title": "Id", "type": "string" }, "last_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Name" }, "middle_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Middle Name" }, "name": { "title": "Name", "type": "string" }, "organization": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Organization" }, "organization_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Organization Id" }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Phone" }, "relation_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Relation Type" }, "role": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Role" } }, "required": [ "id", "name" ], "title": "ProposedContact", "type": "object" }, "ProposedEvent": { "properties": { "all_day": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "All Day" }, "confidence": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Confidence" }, "date": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Date" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "end": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "End" }, "end_date": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "End Date" }, "id": { "title": "Id", "type": "string" }, "location": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Location" }, "merge_candidate": { "anyOf": [ { "$ref": "#/components/schemas/ProposedEventMergeCandidate" }, { "type": "null" } ] }, "start": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Start" }, "title": { "title": "Title", "type": "string" } }, "required": [ "id", "title" ], "title": "ProposedEvent", "type": "object" }, "ProposedEventMergeCandidate": { "properties": { "date": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Date" }, "event_id": { "title": "Event Id", "type": "string" }, "score": { "title": "Score", "type": "number" }, "signals": { "items": { "type": "string" }, "title": "Signals", "type": "array" }, "title": { "title": "Title", "type": "string" } }, "required": [ "event_id", "title", "score" ], "title": "ProposedEventMergeCandidate", "type": "object" }, "ProposedHire": { "additionalProperties": false, "description": "The employees a hire proposal asks for — a team on one proposal, with\nreporting lines by draft key exactly as ``/ai/employees/define-team``.", "properties": { "employees": { "items": { "$ref": "#/components/schemas/ProposedHireEmployee" }, "maxItems": 10, "minItems": 1, "title": "Employees", "type": "array" } }, "required": [ "employees" ], "title": "ProposedHire", "type": "object" }, "ProposedHireEmployee": { "additionalProperties": false, "description": "One employee a hire proposal asks for (TIDY-19500 F5).\n\nExactly the parts a hire card shows the person approving it — nothing a\ncard does not show (skills, scheduled work, a template, host elevation)\ncan ride a proposal into existence. Everything else is the define\ncapability's automatic default, and stays editable after the hire.\n\nTIDY-19882: a hire may land on an existing workshop instead of Tidy\ncompute. Then its model access (stated when omitted: Tidy inference, or\nthe harness's own sign-in where it cannot run that — TIDY-20125), and the\nplugins and secret files lent to it on day one, are part of what the card\nshows and approval re-checks.", "properties": { "display_name": { "maxLength": 120, "minLength": 1, "title": "Display Name", "type": "string" }, "draft_key": { "maxLength": 64, "minLength": 1, "title": "Draft Key", "type": "string" }, "model_access": { "anyOf": [ { "$ref": "#/components/schemas/ProposedHireModelAccess" }, { "type": "null" } ] }, "objectives": { "items": { "$ref": "#/components/schemas/EmployeeObjective" }, "maxItems": 3, "title": "Objectives", "type": "array" }, "plugin_lends": { "items": { "$ref": "#/components/schemas/ProposedPluginLend" }, "maxItems": 10, "title": "Plugin Lends", "type": "array" }, "reports_to": { "anyOf": [ { "$ref": "#/components/schemas/EmployeeReportsTo" }, { "type": "null" } ] }, "role_title": { "maxLength": 160, "minLength": 1, "title": "Role Title", "type": "string" }, "secret_file_lends": { "items": { "$ref": "#/components/schemas/ProposedSecretFileLend" }, "maxItems": 10, "title": "Secret File Lends", "type": "array" }, "soul_markdown": { "maxLength": 20000, "minLength": 1, "title": "Soul Markdown", "type": "string" }, "voice_id": { "anyOf": [ { "maxLength": 120, "type": "string" }, { "type": "null" } ], "title": "Voice Id" }, "workshop": { "anyOf": [ { "$ref": "#/components/schemas/ProposedHireWorkshop" }, { "type": "null" } ] } }, "required": [ "draft_key", "display_name", "role_title", "soul_markdown" ], "title": "ProposedHireEmployee", "type": "object" }, "ProposedHireModelAccess": { "description": "How a hired employee reaches a model: the define's two answers, plus\n``own_sign_in`` (TIDY-20125).\n\nOn a workshop, a harness that signs itself in (Claude Code's Claude login)\nmay run on that sign-in, which the person approving does right after they\napprove, on the card. Its login decides the models on the machine, so it\nnames no credential and no models. Which answers a harness can run is the\nharness auth catalogue's (``workshop_hire.model_access_methods``).", "properties": { "credential_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Credential Id" }, "method": { "enum": [ "tidy_inference", "api_key", "own_sign_in" ], "title": "Method", "type": "string" }, "models": { "items": { "type": "string" }, "maxItems": 8, "title": "Models", "type": "array" } }, "required": [ "method" ], "title": "ProposedHireModelAccess", "type": "object" }, "ProposedHireWorkshop": { "additionalProperties": false, "description": "TIDY-19882: the EXISTING enrolled workshop a hire lands on, and its harness.", "properties": { "harness": { "enum": [ "pi", "claude-code", "codex", "hermes", "opencode", "openclaw", "antigravity" ], "title": "Harness", "type": "string" }, "workshop_id": { "format": "uuid", "title": "Workshop Id", "type": "string" } }, "required": [ "workshop_id", "harness" ], "title": "ProposedHireWorkshop", "type": "object" }, "ProposedItemsResponse": { "properties": { "contacts": { "items": { "$ref": "#/components/schemas/ProposedContact" }, "title": "Contacts", "type": "array" }, "events": { "items": { "$ref": "#/components/schemas/ProposedEvent" }, "title": "Events", "type": "array" }, "organizations": { "items": { "$ref": "#/components/schemas/ProposedOrganization" }, "title": "Organizations", "type": "array" }, "tasks": { "items": { "$ref": "#/components/schemas/ProposedTask" }, "title": "Tasks", "type": "array" } }, "required": [ "tasks", "events", "contacts", "organizations" ], "title": "ProposedItemsResponse", "type": "object" }, "ProposedOrganization": { "properties": { "address": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Address" }, "confidence": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Confidence" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Email" }, "id": { "title": "Id", "type": "string" }, "name": { "title": "Name", "type": "string" }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Phone" }, "type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Type" }, "website": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Website" } }, "required": [ "id", "name" ], "title": "ProposedOrganization", "type": "object" }, "ProposedPluginLend": { "additionalProperties": false, "description": "TIDY-19882: one of the requester's own plugins, lent standing on day one.", "properties": { "capability_scope": { "items": { "type": "string" }, "maxItems": 16, "minItems": 1, "title": "Capability Scope", "type": "array" }, "plugin_id": { "format": "uuid", "title": "Plugin Id", "type": "string" } }, "required": [ "plugin_id", "capability_scope" ], "title": "ProposedPluginLend", "type": "object" }, "ProposedSecretFileLend": { "additionalProperties": false, "description": "TIDY-19882: one of the requester's saved dotenv files, lent standing on day one.", "properties": { "file_id": { "format": "uuid", "title": "File Id", "type": "string" } }, "required": [ "file_id" ], "title": "ProposedSecretFileLend", "type": "object" }, "ProposedTask": { "properties": { "confidence": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Confidence" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "due_date": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Due Date" }, "id": { "title": "Id", "type": "string" }, "status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Status" }, "title": { "title": "Title", "type": "string" } }, "required": [ "id", "title" ], "title": "ProposedTask", "type": "object" }, "ProsemirrorDoc": { "additionalProperties": true, "description": "Opaque ProseMirror JSON document — shape defined by TipTap at runtime.\n\nWe deliberately do not declare the inner schema: TipTap custom nodes\nevolve per-release and the SDK consumers treat the payload as opaque.\nGiving the inline `dict` a stable name avoids a schema collision in\nopenapi-python-client generation.", "title": "ProsemirrorDoc", "type": "object" }, "ProtectedCommandTarget": { "description": "Exact target tuple used by the server-authored portable command.", "properties": { "elevated_privileges": { "default": true, "title": "Elevated Privileges", "type": "boolean" }, "github_access": { "default": false, "title": "Github Access", "type": "boolean" }, "harness": { "enum": [ "pi", "claude-code", "codex", "hermes", "opencode", "openclaw", "antigravity" ], "title": "Harness", "type": "string" }, "harness_auth_method": { "anyOf": [ { "enum": [ "existing", "api_key", "bedrock", "vertex", "subscription", "tidy_inference" ], "type": "string" }, { "type": "null" } ], "title": "Harness Auth Method" }, "harness_auth_settings": { "anyOf": [ { "additionalProperties": { "type": "string" }, "type": "object" }, { "type": "null" } ], "title": "Harness Auth Settings" }, "host_arch": { "enum": [ "x86_64", "aarch64" ], "title": "Host Arch", "type": "string" }, "host_build": { "anyOf": [ { "minimum": 17763.0, "type": "integer" }, { "type": "null" } ], "title": "Host Build" }, "host_os": { "enum": [ "linux", "macos", "windows" ], "title": "Host Os", "type": "string" }, "host_os_major": { "anyOf": [ { "minimum": 12.0, "type": "integer" }, { "type": "null" } ], "title": "Host Os Major" }, "install_harness_if_missing": { "default": false, "title": "Install Harness If Missing", "type": "boolean" }, "libc": { "anyOf": [ { "enum": [ "glibc", "musl" ], "type": "string" }, { "type": "null" } ], "title": "Libc" }, "libc_min": { "anyOf": [ { "pattern": "^[0-9]+\\.[0-9]+$", "type": "string" }, { "type": "null" } ], "title": "Libc Min" }, "lifecycle": { "enum": [ "systemd-user", "launch-agent", "scheduled-task" ], "title": "Lifecycle", "type": "string" }, "working_directory": { "maxLength": 2048, "minLength": 2, "title": "Working Directory", "type": "string" } }, "required": [ "host_os", "host_arch", "harness", "lifecycle", "working_directory" ], "title": "ProtectedCommandTarget", "type": "object" }, "ProtectedControllerClaimRequest": { "additionalProperties": false, "description": "Exactly one provenance, and root's attestation where a daemon carried it.\n\n* `enrollment_token` — the installer-time branch, unchanged. Tidy handed the\n enrollment to root over HTTPS when it redeemed the owner's one-use setup\n grant; no daemon is on that path, so the token IS the provenance. An\n attestation may accompany it and is verified when it does.\n* `install_job_id` + `host_attestation` — the pushed branch. The manifest\n carried no secret, so the authority is root's signature over the\n controller public key. A key the daemon chose has no such signature.", "properties": { "enrollment_token": { "anyOf": [ { "format": "password", "maxLength": 128, "minLength": 40, "type": "string", "writeOnly": true }, { "type": "null" } ], "title": "Enrollment Token" }, "host_attestation": { "anyOf": [ { "pattern": "^[A-Za-z0-9+/]{86}==$", "type": "string" }, { "type": "null" } ], "title": "Host Attestation" }, "install_job_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Install Job Id" }, "message": { "$ref": "#/components/schemas/ControllerEnvelope" }, "signature": { "format": "password", "maxLength": 128, "minLength": 80, "title": "Signature", "type": "string", "writeOnly": true } }, "required": [ "message", "signature" ], "title": "ProtectedControllerClaimRequest", "type": "object" }, "ProtectedIsolation": { "additionalProperties": false, "properties": { "reason": { "title": "Reason", "type": "null" }, "status": { "const": "protected", "title": "Status", "type": "string" } }, "required": [ "status" ], "title": "ProtectedIsolation", "type": "object" }, "ProtectedResourceMetadataResponse": { "properties": { "authorization_servers": { "items": { "type": "string" }, "title": "Authorization Servers", "type": "array" }, "bearer_methods_supported": { "items": { "type": "string" }, "title": "Bearer Methods Supported", "type": "array" }, "resource": { "title": "Resource", "type": "string" }, "resource_documentation": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Resource Documentation" }, "resource_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Resource Name" }, "resource_policy_uri": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Resource Policy Uri" }, "resource_tos_uri": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Resource Tos Uri" }, "scopes_supported": { "items": { "type": "string" }, "title": "Scopes Supported", "type": "array" } }, "required": [ "resource", "authorization_servers", "scopes_supported", "bearer_methods_supported" ], "title": "ProtectedResourceMetadataResponse", "type": "object" }, "ProtectedSetupCommand": { "properties": { "bootstrap_sha256": { "pattern": "^[0-9a-f]{64}$", "title": "Bootstrap Sha256", "type": "string" }, "bootstrap_url": { "title": "Bootstrap Url", "type": "string" }, "cleanup": { "enum": [ "trap", "finally" ], "title": "Cleanup", "type": "string" }, "clipboard_payload_base64": { "title": "Clipboard Payload Base64", "type": "string" }, "clipboard_payload_sha256": { "pattern": "^[0-9a-f]{64}$", "title": "Clipboard Payload Sha256", "type": "string" }, "expires_at": { "format": "date-time", "title": "Expires At", "type": "string" }, "schema_version": { "const": 1, "default": 1, "title": "Schema Version", "type": "integer" }, "secret_transport": { "const": "protected_file", "default": "protected_file", "title": "Secret Transport", "type": "string" }, "shell": { "enum": [ "posix", "powershell" ], "title": "Shell", "type": "string" }, "single_use": { "const": true, "default": true, "title": "Single Use", "type": "boolean" }, "target": { "$ref": "#/components/schemas/ProtectedCommandTarget" } }, "required": [ "shell", "target", "clipboard_payload_base64", "clipboard_payload_sha256", "bootstrap_url", "bootstrap_sha256", "expires_at", "cleanup" ], "title": "ProtectedSetupCommand", "type": "object" }, "ProvenanceFileVersion": { "properties": { "content_sha256": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Content Sha256" }, "created_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Created At" }, "file_id": { "title": "File Id", "type": "string" }, "file_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "File Name" }, "version": { "title": "Version", "type": "integer" } }, "required": [ "file_id", "version" ], "title": "ProvenanceFileVersion", "type": "object" }, "ProvenanceLink": { "description": "One session↔turn attribution for a commit, tombstones included.", "properties": { "agent_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Agent Name" }, "authored_ref": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Authored Ref" }, "conversation_title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Conversation Title" }, "match_basis": { "default": "authored_ref", "title": "Match Basis", "type": "string" }, "matrix_room_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Matrix Room Id" }, "matrix_thread_root_event_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Matrix Thread Root Event Id" }, "removed_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Removed At" }, "removed_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Removed Reason" }, "repository": { "default": "", "title": "Repository", "type": "string" }, "session_id": { "title": "Session Id", "type": "string" }, "superseded_by_sha": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Superseded By Sha" }, "turn_ordinal": { "title": "Turn Ordinal", "type": "integer" } }, "required": [ "session_id", "turn_ordinal" ], "title": "ProvenanceLink", "type": "object" }, "ProvenanceRecord": { "description": "One generation of this artifact.", "properties": { "byo_routed": { "default": false, "description": "Whether the run reached the account's own provider — derived from the model string that was sent, never from key possession.", "title": "Byo Routed", "type": "boolean" }, "facet_slug": { "title": "Facet Slug", "type": "string" }, "generated_at": { "title": "Generated At", "type": "string" }, "id": { "title": "Id", "type": "string" }, "instructions": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Instruction override used, if any", "title": "Instructions" }, "job_id": { "title": "Job Id", "type": "string" }, "model": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "The model that actually served this run. NULL on records written before spend provenance existed (TIDY-15874).", "title": "Model" }, "model_lane": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Model Lane" }, "produced_by": { "default": "tier", "description": "Which producer made this artifact: 'tier' (the declared producer tier) or 'virtual_employee' (the principal's own agent, TIDY-15717). The artifact is owned by the principal in both cases.", "title": "Produced By", "type": "string" }, "redacted_source_count": { "default": 0, "description": "Sources on this record the caller may not see", "title": "Redacted Source Count", "type": "integer" }, "result_id": { "title": "Result Id", "type": "string" }, "result_type": { "title": "Result Type", "type": "string" }, "sources": { "items": { "$ref": "#/components/schemas/ProvenanceSource" }, "title": "Sources", "type": "array" } }, "required": [ "id", "job_id", "result_type", "result_id", "facet_slug", "generated_at", "sources" ], "title": "ProvenanceRecord", "type": "object" }, "ProvenanceSeenResponse": { "description": "Result of marking a contact's field provenance seen for the caller.", "properties": { "contact_id": { "title": "Contact Id", "type": "string" }, "marked": { "title": "Marked", "type": "integer" } }, "required": [ "contact_id", "marked" ], "title": "ProvenanceSeenResponse", "type": "object" }, "ProvenanceSource": { "description": "One source in a generation's frozen snapshot, as this caller sees it.", "properties": { "bundle_item_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "The bundle item this source was", "title": "Bundle Item Id" }, "external_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "URL for an external (web/media) source", "title": "External Url" }, "marker": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Citation number this source carried in the prompt; null when omitted", "title": "Marker" }, "omitted": { "default": false, "description": "In the bundle but NOT in the output", "title": "Omitted", "type": "boolean" }, "omitted_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Why it contributed nothing", "title": "Omitted Reason" }, "primitive_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Typed id of the source primitive; null when external, redacted, or gone", "title": "Primitive Id" }, "primitive_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Type of the source primitive, if any", "title": "Primitive Type" }, "redacted": { "default": false, "description": "The caller may not see this source; type only, never the title", "title": "Redacted", "type": "boolean" }, "scope_note": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "The user's note on this source, if any", "title": "Scope Note" }, "source_kind": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "primitive | container | external | capture", "title": "Source Kind" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Title AT GENERATION TIME; null when redacted", "title": "Title" }, "tombstoned": { "default": false, "description": "The source has been deleted; the frozen title stands in for it", "title": "Tombstoned", "type": "boolean" } }, "title": "ProvenanceSource", "type": "object" }, "ProvenanceToolCall": { "properties": { "call_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Call Id" }, "kind": { "title": "Kind", "type": "string" }, "occurred_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Occurred At" }, "operation_id": { "title": "Operation Id", "type": "string" }, "tool": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Tool" } }, "required": [ "operation_id", "kind" ], "title": "ProvenanceToolCall", "type": "object" }, "ProviderActionRequest": { "additionalProperties": false, "properties": { "action": { "enum": [ "start", "stop", "destroy", "reconcile", "retry_enrollment" ], "title": "Action", "type": "string" }, "confirmation": { "anyOf": [ { "maxLength": 256, "type": "string" }, { "type": "null" } ], "title": "Confirmation" }, "expected_resource_id": { "maxLength": 256, "minLength": 1, "title": "Expected Resource Id", "type": "string" }, "request_key": { "maxLength": 128, "minLength": 1, "title": "Request Key", "type": "string" } }, "required": [ "action", "request_key", "expected_resource_id" ], "title": "ProviderActionRequest", "type": "object" }, "ProviderAuthorization": { "additionalProperties": false, "properties": { "external_id": { "anyOf": [ { "maxLength": 256, "type": "string" }, { "type": "null" } ], "title": "External Id" }, "ovh": { "anyOf": [ { "$ref": "#/components/schemas/OvhCredentials" }, { "type": "null" } ] }, "role_arn": { "anyOf": [ { "maxLength": 2048, "type": "string" }, { "type": "null" } ], "title": "Role Arn" }, "secret": { "anyOf": [ { "format": "password", "type": "string", "writeOnly": true }, { "type": "null" } ], "title": "Secret" }, "type": { "enum": [ "api_token", "assume_role", "ovh" ], "title": "Type", "type": "string" } }, "required": [ "type" ], "title": "ProviderAuthorization", "type": "object" }, "ProviderCapabilitiesModel": { "description": "What the provider can do right now — never aspirational.", "properties": { "agent_credentials": { "default": false, "title": "Agent Credentials", "type": "boolean" }, "create_repository": { "default": false, "title": "Create Repository", "type": "boolean" }, "list_branches": { "default": false, "title": "List Branches", "type": "boolean" }, "list_repositories": { "default": false, "title": "List Repositories", "type": "boolean" }, "object_sync": { "default": false, "title": "Object Sync", "type": "boolean" }, "read_file": { "default": false, "title": "Read File", "type": "boolean" }, "web_urls": { "default": false, "title": "Web Urls", "type": "boolean" } }, "title": "ProviderCapabilitiesModel", "type": "object" }, "ProviderConnectImapRequest": { "description": "Request to connect a provider via IMAP credentials.", "properties": { "caldav_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "CalDAV server URL for calendar sync (e.g. https://caldav.fastmail.com/dav/calendars)", "title": "Caldav Url" }, "email_address": { "description": "Email address", "title": "Email Address", "type": "string" }, "imap_host": { "description": "IMAP server hostname", "title": "Imap Host", "type": "string" }, "imap_port": { "default": 993, "description": "IMAP server port", "title": "Imap Port", "type": "integer" }, "password": { "description": "App-specific password", "title": "Password", "type": "string" }, "provider_type": { "$ref": "#/components/schemas/ProviderType", "description": "Provider to connect" }, "smtp_host": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "SMTP server hostname", "title": "Smtp Host" }, "smtp_port": { "default": 587, "description": "SMTP server port", "title": "Smtp Port", "type": "integer" } }, "required": [ "provider_type", "email_address", "password", "imap_host" ], "title": "ProviderConnectImapRequest", "type": "object" }, "ProviderConnectOption": { "description": "What connecting one registered provider needs, on THIS deployment.\n\n`connectable` is false when a deployment precondition the member cannot\nsupply is absent — Lightsail's delegated role can only trust a source\nprincipal this deployment actually has. Saying so here is what keeps a\npicker from offering a provider whose connect step can only 503.", "properties": { "authorization": { "enum": [ "api_token", "assume_role", "ovh" ], "title": "Authorization", "type": "string" }, "connectable": { "title": "Connectable", "type": "boolean" }, "provider": { "enum": [ "digitalocean", "hetzner", "lightsail", "ovh" ], "title": "Provider", "type": "string" }, "unavailable_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Unavailable Reason" } }, "required": [ "provider", "authorization", "connectable" ], "title": "ProviderConnectOption", "type": "object" }, "ProviderConnectionResponse": { "description": "A provider connection record returned by the API.", "properties": { "auth_method": { "$ref": "#/components/schemas/AuthMethod", "description": "Authentication method" }, "created_at": { "description": "When the connection was created", "format": "date-time", "title": "Created At", "type": "string" }, "display_name": { "description": "User-facing connection name", "title": "Display Name", "type": "string" }, "email": { "description": "Primary email address", "title": "Email", "type": "string" }, "has_app_password": { "default": false, "description": "Whether a user-supplied app-specific password is on record. Used by the UI to surface the explicit 'Clear stored password' action (TIDY-7730).", "title": "Has App Password", "type": "boolean" }, "has_drive_access": { "default": true, "description": "Google connections only: whether the account is connected for Drive (used_by holds 'drive', TIDY-19604). Non-Google connections always report True — the flag is meaningless for them. Lets clients resolve a Drive-capable connection without exposing raw scope material (TIDY-17556 / D14).", "title": "Has Drive Access", "type": "boolean" }, "id": { "description": "Connection UUID", "title": "Id", "type": "string" }, "last_sync_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "Last successful sync", "title": "Last Sync At" }, "needs_reconsent": { "default": false, "description": "Whether the connection holds a stale/over-broad OAuth scope, or lacks one that what it is used for requires, and should be reconnected (TIDY-12952, TIDY-19604). Currently only computed for Google connections.", "title": "Needs Reconsent", "type": "boolean" }, "provider_type": { "$ref": "#/components/schemas/ProviderType", "description": "Provider type" }, "status": { "$ref": "#/components/schemas/ConnectionStatus", "description": "Connection status" }, "sync_error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Most recent sync error", "title": "Sync Error" }, "tenant_id": { "description": "Tenant UUID", "title": "Tenant Id", "type": "string" }, "used_by": { "description": "What the connection is used for: any of mail, calendar, contacts, drive (TIDY-19604). A mailbox includes 'mail'; an account connected without it, e.g. ['calendar'] (TIDY-19293) or ['drive'], is not a mailbox.", "items": { "type": "string" }, "title": "Used By", "type": "array" } }, "required": [ "id", "tenant_id", "provider_type", "auth_method", "status", "display_name", "email", "created_at" ], "title": "ProviderConnectionResponse", "type": "object" }, "ProviderDecisionRequest": { "properties": { "connection_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Connection Id" }, "decision": { "enum": [ "offered", "connected", "skipped" ], "title": "Decision", "type": "string" } }, "required": [ "decision" ], "title": "ProviderDecisionRequest", "type": "object" }, "ProviderRequest": { "properties": { "desktop": { "default": false, "title": "Desktop", "type": "boolean" }, "provider": { "enum": [ "google", "azure" ], "title": "Provider", "type": "string" } }, "required": [ "provider" ], "title": "ProviderRequest", "type": "object" }, "ProviderResponse": { "properties": { "authorize_url": { "title": "Authorize Url", "type": "string" } }, "required": [ "authorize_url" ], "title": "ProviderResponse", "type": "object" }, "ProviderType": { "description": "Supported provider types — canonical FW3 vocabulary.", "enum": [ "google", "microsoft", "zoho", "apple", "yahoo", "generic_imap" ], "title": "ProviderType", "type": "string" }, "ProviderUsage": { "description": "One provider's slice: call count, cloud cost (USD), and total tokens.", "properties": { "calls": { "default": 0, "title": "Calls", "type": "integer" }, "cost": { "default": 0.0, "title": "Cost", "type": "number" }, "total_tokens": { "default": 0, "title": "Total Tokens", "type": "integer" } }, "title": "ProviderUsage", "type": "object" }, "ProvisionRequest": { "additionalProperties": false, "properties": { "availability_zone": { "anyOf": [ { "maxLength": 128, "type": "string" }, { "type": "null" } ], "title": "Availability Zone" }, "catalog_revision": { "format": "uuid", "title": "Catalog Revision", "type": "string" }, "confirmed_quote_id": { "maxLength": 256, "minLength": 1, "title": "Confirmed Quote Id", "type": "string" }, "connection_id": { "format": "uuid", "title": "Connection Id", "type": "string" }, "image_id": { "maxLength": 256, "minLength": 1, "title": "Image Id", "type": "string" }, "region": { "maxLength": 128, "minLength": 1, "title": "Region", "type": "string" }, "request_key": { "maxLength": 128, "minLength": 1, "title": "Request Key", "type": "string" }, "size_id": { "maxLength": 256, "minLength": 1, "title": "Size Id", "type": "string" } }, "required": [ "connection_id", "catalog_revision", "region", "image_id", "size_id", "request_key", "confirmed_quote_id" ], "title": "ProvisionRequest", "type": "object" }, "ProvisionUserRequest": { "properties": { "tenant_id": { "title": "Tenant Id", "type": "string" }, "user_id": { "title": "User Id", "type": "string" } }, "required": [ "user_id", "tenant_id" ], "title": "ProvisionUserRequest", "type": "object" }, "ProvisionUserResponse": { "properties": { "access_token": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Access Token" }, "device_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Device Id" }, "matrix_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Matrix Id" } }, "required": [ "matrix_id", "access_token" ], "title": "ProvisionUserResponse", "type": "object" }, "PruneRequest": { "properties": { "dry_run": { "default": true, "title": "Dry Run", "type": "boolean" }, "keep_last": { "default": 3, "maximum": 100.0, "minimum": 1.0, "title": "Keep Last", "type": "integer" }, "versions": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Versions" } }, "title": "PruneRequest", "type": "object" }, "PruneResponse": { "properties": { "bytes": { "title": "Bytes", "type": "integer" }, "candidate_ids": { "items": { "type": "string" }, "title": "Candidate Ids", "type": "array" }, "dry_run": { "title": "Dry Run", "type": "boolean" }, "paths": { "items": { "type": "string" }, "title": "Paths", "type": "array" }, "removed": { "title": "Removed", "type": "integer" }, "retained_versions": { "items": { "type": "string" }, "title": "Retained Versions", "type": "array" }, "versions": { "items": { "type": "string" }, "title": "Versions", "type": "array" } }, "required": [ "dry_run", "versions", "retained_versions", "candidate_ids", "paths", "bytes", "removed" ], "title": "PruneResponse", "type": "object" }, "PseudonymizeRequest": { "properties": { "tenant_id": { "format": "uuid", "title": "Tenant Id", "type": "string" }, "user_id": { "format": "uuid", "title": "User Id", "type": "string" } }, "required": [ "user_id", "tenant_id" ], "title": "PseudonymizeRequest", "type": "object" }, "PseudonymizeResponse": { "properties": { "pseudonym": { "title": "Pseudonym", "type": "string" }, "rows_updated": { "title": "Rows Updated", "type": "integer" } }, "required": [ "rows_updated", "pseudonym" ], "title": "PseudonymizeResponse", "type": "object" }, "PublicBookingCreate": { "description": "Submit a booking against a slot.", "properties": { "intake": { "additionalProperties": true, "title": "Intake", "type": "object" }, "slot_start": { "description": "Slot start (any tz-aware ISO; normalized to UTC)", "format": "date-time", "title": "Slot Start", "type": "string" }, "slug": { "description": "Booking page slug", "maxLength": 64, "minLength": 1, "title": "Slug", "type": "string" } }, "required": [ "slug", "slot_start" ], "title": "PublicBookingCreate", "type": "object" }, "PublicBookingPageResponse": { "description": "The public page — business-facing fields only, no owner PII.", "properties": { "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "intake_form": { "items": { "additionalProperties": true, "type": "object" }, "title": "Intake Form", "type": "array" }, "service": { "$ref": "#/components/schemas/PublicServiceInfo" }, "slug": { "title": "Slug", "type": "string" }, "timezone": { "title": "Timezone", "type": "string" }, "title": { "title": "Title", "type": "string" } }, "required": [ "slug", "title", "description", "timezone", "service", "intake_form" ], "title": "PublicBookingPageResponse", "type": "object" }, "PublicEnvValue": { "description": "A non-secret env value a turn receives beside its credentials (TIDY-19802\nF2): a shipped connection's API address. The harness need not redact it;\nit travels only with its connection's secret, never alone.", "properties": { "env_key": { "title": "Env Key", "type": "string" }, "id": { "title": "Id", "type": "string" }, "value": { "title": "Value", "type": "string" } }, "required": [ "id", "env_key", "value" ], "title": "PublicEnvValue", "type": "object" }, "PublicFormHostBody": { "properties": { "public_form_host": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Hostname such as forms.example.com. Blank clears the setting.", "title": "Public Form Host" }, "unsubscribe_publication_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "A published form publication of this tenant to use as the unsubscribe form. Null clears it. OMITTING the key leaves the current designation alone.", "title": "Unsubscribe Publication Id" } }, "title": "PublicFormHostBody", "type": "object" }, "PublicFormHostResponse": { "properties": { "effective_host": { "title": "Effective Host", "type": "string" }, "help_text": { "default": "Public form and per-row links are built on this host. It must sit under a domain you have verified for sending — Tidy checks mail-auth ownership of the domain, not control of the web host itself, so point the host at Tidy with a CNAME before using it. Leave blank to keep Tidy's own host.", "title": "Help Text", "type": "string" }, "public_form_host": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Public Form Host" }, "unsubscribe_help_text": { "default": "Mail Tidy sends carries a one-click unsubscribe link. Point it at one of your published forms and each recipient gets their OWN link to it, so submitting the form can run whatever automation you wrote — set consent, record a reason, anything. Leave it unset to keep Tidy's built-in unsubscribe page.", "title": "Unsubscribe Help Text", "type": "string" }, "unsubscribe_publication_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Unsubscribe Publication Id" } }, "required": [ "public_form_host", "effective_host" ], "title": "PublicFormHostResponse", "type": "object" }, "PublicFormSubmitResponse": { "properties": { "message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Message" }, "ok": { "title": "Ok", "type": "boolean" }, "redirect_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Redirect Url" } }, "required": [ "ok" ], "title": "PublicFormSubmitResponse", "type": "object" }, "PublicServiceInfo": { "properties": { "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "duration_min": { "title": "Duration Min", "type": "integer" }, "name": { "title": "Name", "type": "string" } }, "required": [ "name", "duration_min", "description" ], "title": "PublicServiceInfo", "type": "object" }, "PublicSigningContext": { "properties": { "consent_statement": { "title": "Consent Statement", "type": "string" }, "document_html": { "title": "Document Html", "type": "string" }, "signable": { "title": "Signable", "type": "boolean" }, "signer_name": { "title": "Signer Name", "type": "string" }, "status": { "title": "Status", "type": "string" } }, "required": [ "status", "signer_name", "consent_statement", "document_html", "signable" ], "title": "PublicSigningContext", "type": "object" }, "PublicWorkspaceTemplateListItem": { "description": "One published template as seen on the public gallery.", "properties": { "chips": { "items": { "type": "string" }, "title": "Chips", "type": "array" }, "family": { "title": "Family", "type": "string" }, "hero_media": { "additionalProperties": true, "title": "Hero Media", "type": "object" }, "name": { "title": "Name", "type": "string" }, "slug": { "title": "Slug", "type": "string" }, "summary": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Summary" }, "version": { "title": "Version", "type": "integer" }, "what_you_get": { "$ref": "#/components/schemas/WorkspaceTemplateSummary" } }, "required": [ "slug", "name", "family", "version", "what_you_get" ], "title": "PublicWorkspaceTemplateListItem", "type": "object" }, "PublicWorkspaceTemplateResponse": { "description": "Public detail — adds the hand-written usage guide. Still summary-only.", "properties": { "chips": { "items": { "type": "string" }, "title": "Chips", "type": "array" }, "family": { "title": "Family", "type": "string" }, "hero_media": { "additionalProperties": true, "title": "Hero Media", "type": "object" }, "name": { "title": "Name", "type": "string" }, "slug": { "title": "Slug", "type": "string" }, "summary": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Summary" }, "usage_guide": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Usage Guide" }, "version": { "title": "Version", "type": "integer" }, "what_you_get": { "$ref": "#/components/schemas/WorkspaceTemplateSummary" } }, "required": [ "slug", "name", "family", "version", "what_you_get" ], "title": "PublicWorkspaceTemplateResponse", "type": "object" }, "PublicationSlide": { "description": "One frozen slide within a publication (index + a signed PNG URL).", "properties": { "height": { "default": 2160, "title": "Height", "type": "integer" }, "index": { "title": "Index", "type": "integer" }, "url": { "description": "Short-lived signed PNG URL.", "title": "Url", "type": "string" }, "width": { "default": 3840, "title": "Width", "type": "integer" } }, "required": [ "index", "url" ], "title": "PublicationSlide", "type": "object" }, "PublishDeckRequest": { "description": "Body for `POST /api/v1/presentations/{note_id}/publish`.", "properties": { "title": { "anyOf": [ { "maxLength": 300, "type": "string" }, { "type": "null" } ], "description": "Human name for this version. Defaults to the deck title + publish date when omitted.", "title": "Title" } }, "title": "PublishDeckRequest", "type": "object" }, "PublishDeliverableResponse": { "description": "`created` on the first publish of a (project, path); `updated` after.", "properties": { "file_id": { "title": "File Id", "type": "string" }, "links": { "$ref": "#/components/schemas/DeliverableProviderLinks" }, "mime_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Mime Type" }, "name": { "title": "Name", "type": "string" }, "path": { "title": "Path", "type": "string" }, "published_commit": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Published Commit" }, "repo_full_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Repo Full Name" }, "repo_provider": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Repo Provider" }, "result": { "enum": [ "created", "updated" ], "title": "Result", "type": "string" }, "size_bytes": { "title": "Size Bytes", "type": "integer" }, "version": { "title": "Version", "type": "integer" } }, "required": [ "result", "file_id", "name", "path", "version", "size_bytes", "links" ], "title": "PublishDeliverableResponse", "type": "object" }, "PublishFormRequest": { "properties": { "publication_config": { "$ref": "#/components/schemas/FormPublicationConfig" } }, "required": [ "publication_config" ], "title": "PublishFormRequest", "type": "object" }, "PublishFormResponse": { "properties": { "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "facet_slug": { "title": "Facet Slug", "type": "string" }, "id": { "title": "Id", "type": "string" }, "public_url": { "title": "Public Url", "type": "string" }, "status": { "title": "Status", "type": "string" }, "target_table": { "title": "Target Table", "type": "string" }, "token": { "title": "Token", "type": "string" }, "warnings": { "items": { "$ref": "#/components/schemas/PublishWarning" }, "title": "Warnings", "type": "array" } }, "required": [ "id", "token", "status", "facet_slug", "target_table", "public_url", "created_at" ], "title": "PublishFormResponse", "type": "object" }, "PublishWarning": { "properties": { "code": { "title": "Code", "type": "string" }, "node_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Node Id" } }, "required": [ "code" ], "title": "PublishWarning", "type": "object" }, "PullLatestResponse": { "description": "The version pull-latest appended, and the commit it came from.", "properties": { "commit": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Commit" }, "file_id": { "title": "File Id", "type": "string" }, "links": { "$ref": "#/components/schemas/DeliverableProviderLinks" }, "size_bytes": { "title": "Size Bytes", "type": "integer" }, "version": { "title": "Version", "type": "integer" } }, "required": [ "file_id", "version", "size_bytes", "links" ], "title": "PullLatestResponse", "type": "object" }, "PullRequestCreateRequest": { "description": "Open a pull request on a repository (TIDY-18241 / R23).", "properties": { "base": { "description": "Branch the PR merges into", "title": "Base", "type": "string" }, "body": { "anyOf": [ { "maxLength": 65536, "type": "string" }, { "type": "null" } ], "title": "Body" }, "head": { "description": "Branch whose commits go into the PR", "title": "Head", "type": "string" }, "repo_full_name": { "description": "owner/name", "title": "Repo Full Name", "type": "string" }, "title": { "maxLength": 256, "minLength": 1, "title": "Title", "type": "string" } }, "required": [ "repo_full_name", "head", "base", "title" ], "title": "PullRequestCreateRequest", "type": "object" }, "PullRequestCreateResponse": { "properties": { "base": { "title": "Base", "type": "string" }, "created_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Created At" }, "head": { "title": "Head", "type": "string" }, "number": { "title": "Number", "type": "integer" }, "provider_id": { "title": "Provider Id", "type": "string" }, "repo_full_name": { "title": "Repo Full Name", "type": "string" }, "state": { "title": "State", "type": "string" }, "title": { "title": "Title", "type": "string" }, "web_url": { "title": "Web Url", "type": "string" } }, "required": [ "provider_id", "repo_full_name", "number", "title", "web_url", "head", "base", "state" ], "title": "PullRequestCreateResponse", "type": "object" }, "PullRequestIngest": { "properties": { "head_sha": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Head Sha" }, "links": { "default": [], "items": { "$ref": "#/components/schemas/EvidenceLinkIn" }, "title": "Links", "type": "array" }, "number": { "minimum": 1.0, "title": "Number", "type": "integer" }, "provider": { "default": "github", "title": "Provider", "type": "string" }, "repository": { "minLength": 1, "title": "Repository", "type": "string" }, "source_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Source Url" }, "state": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "State" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Title" } }, "required": [ "repository", "number" ], "title": "PullRequestIngest", "type": "object" }, "PushJobProgress": { "properties": { "at": { "format": "date-time", "title": "At", "type": "string" }, "detail": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Detail" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Error" }, "state": { "enum": [ "running", "ready", "error", "unverified" ], "title": "State", "type": "string" }, "step": { "title": "Step", "type": "string" } }, "required": [ "step", "state", "at" ], "title": "PushJobProgress", "type": "object" }, "QALabelCreate": { "properties": { "episode_id": { "title": "Episode Id", "type": "string" }, "label_data": { "additionalProperties": true, "default": {}, "title": "Label Data", "type": "object" }, "label_type": { "title": "Label Type", "type": "string" } }, "required": [ "episode_id", "label_type" ], "title": "QALabelCreate", "type": "object" }, "QALabelResponse": { "properties": { "episode_id": { "title": "Episode Id", "type": "string" }, "id": { "title": "Id", "type": "string" }, "label_data": { "additionalProperties": true, "title": "Label Data", "type": "object" }, "label_type": { "title": "Label Type", "type": "string" }, "labeled_at": { "title": "Labeled At", "type": "string" }, "labeled_by": { "title": "Labeled By", "type": "string" } }, "required": [ "id", "episode_id", "labeled_by", "labeled_at", "label_type", "label_data" ], "title": "QALabelResponse", "type": "object" }, "QASampleEpisode": { "properties": { "duration_seconds": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Duration Seconds" }, "episode_id": { "title": "Episode Id", "type": "string" }, "quality_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Quality Status" }, "speaker_count": { "default": 0, "title": "Speaker Count", "type": "integer" } }, "required": [ "episode_id" ], "title": "QASampleEpisode", "type": "object" }, "QualityDistribution": { "properties": { "failed": { "default": 0, "title": "Failed", "type": "integer" }, "high": { "default": 0, "title": "High", "type": "integer" }, "low": { "default": 0, "title": "Low", "type": "integer" }, "medium": { "default": 0, "title": "Medium", "type": "integer" }, "not_yet_scored": { "default": 0, "title": "Not Yet Scored", "type": "integer" } }, "title": "QualityDistribution", "type": "object" }, "QualityLowFailedEpisode": { "properties": { "episode_id": { "title": "Episode Id", "type": "string" }, "guid": { "title": "Guid", "type": "string" }, "mean_word_confidence": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Mean Word Confidence" }, "quality_flag_reasons": { "default": [], "items": { "type": "string" }, "title": "Quality Flag Reasons", "type": "array" }, "quality_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Quality Status" }, "rss_feed_url": { "title": "Rss Feed Url", "type": "string" }, "show_title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Show Title" }, "title": { "title": "Title", "type": "string" }, "updated_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Updated At" } }, "required": [ "episode_id", "title", "rss_feed_url", "guid" ], "title": "QualityLowFailedEpisode", "type": "object" }, "QualityOverviewResponse": { "properties": { "distribution": { "$ref": "#/components/schemas/QualityDistribution" }, "flag_reason_prevalence": { "additionalProperties": { "type": "integer" }, "default": {}, "title": "Flag Reason Prevalence", "type": "object" }, "mean_word_confidence": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Mean Word Confidence" }, "recent_low_failed": { "default": [], "items": { "$ref": "#/components/schemas/QualityLowFailedEpisode" }, "title": "Recent Low Failed", "type": "array" }, "scored_episodes": { "title": "Scored Episodes", "type": "integer" }, "total_episodes": { "title": "Total Episodes", "type": "integer" } }, "required": [ "distribution", "total_episodes", "scored_episodes" ], "title": "QualityOverviewResponse", "type": "object" }, "QuarantineAttachment": { "description": "Per-attachment scan metadata surfaced in the quarantine list.", "properties": { "content_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Content Type" }, "filename": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Filename" }, "id": { "format": "uuid", "title": "Id", "type": "string" }, "scan_signature": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Scan Signature" }, "scan_status": { "title": "Scan Status", "type": "string" } }, "required": [ "id", "scan_status" ], "title": "QuarantineAttachment", "type": "object" }, "QuarantineEmailItem": { "properties": { "attachments": { "items": { "$ref": "#/components/schemas/QuarantineAttachment" }, "title": "Attachments", "type": "array" }, "from_address": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "From Address" }, "from_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "From Name" }, "has_infected_attachments": { "title": "Has Infected Attachments", "type": "boolean" }, "id": { "format": "uuid", "title": "Id", "type": "string" }, "quarantine_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Quarantine Reason" }, "quarantine_status": { "title": "Quarantine Status", "type": "string" }, "quarantined_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Quarantined At" }, "received_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "description": "Original send timestamp (email_canonical.sent_at).", "title": "Received At" }, "subject": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Subject" } }, "required": [ "id", "quarantine_status", "has_infected_attachments", "attachments" ], "title": "QuarantineEmailItem", "type": "object" }, "QuarantineListResponse": { "properties": { "items": { "items": { "$ref": "#/components/schemas/QuarantineEmailItem" }, "title": "Items", "type": "array" }, "total": { "title": "Total", "type": "integer" } }, "required": [ "items", "total" ], "title": "QuarantineListResponse", "type": "object" }, "QuarantineRequest": { "properties": { "episode_id": { "title": "Episode Id", "type": "string" } }, "required": [ "episode_id" ], "title": "QuarantineRequest", "type": "object" }, "QueryAuthoringCapabilitiesResponse": { "description": "The canonical authoring vocabulary (R6 inspect; TIDY-15408 R116/D31).\n\nEverything an agent needs BEFORE authoring: the QuerySpec operator and\ncontext-variable registries, layouts and their field slots, chart kinds and\naggregates, the forms vocabulary, the containers output can land in, the\nwrite actions this caller may invoke, and the tenant's existing facet\ndefinitions (reuse before invent).\n\nBounded by construction: `sections` selects the slices the caller wants and\nevery returned section but `facets` is a fixed-size registry; `facets`\npages through `facet_page`. Sections the caller did not ask for are absent,\nso a consumer reads `sections` rather than assuming a field is present.", "properties": { "actions": { "anyOf": [ { "items": { "$ref": "#/components/schemas/ActionCapability" }, "type": "array" }, { "type": "null" } ], "default": null, "title": "Actions" }, "capabilities_version": { "title": "Capabilities Version", "type": "integer" }, "charts": { "anyOf": [ { "$ref": "#/components/schemas/ChartCapabilities" }, { "type": "null" } ], "default": null }, "container_types": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "default": null, "title": "Container Types" }, "containers": { "anyOf": [ { "items": { "$ref": "#/components/schemas/ContainerCapability" }, "type": "array" }, { "type": "null" } ], "default": null, "title": "Containers" }, "context_variables": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "default": null, "title": "Context Variables" }, "facet_page": { "anyOf": [ { "$ref": "#/components/schemas/CapabilityPageInfo" }, { "type": "null" } ], "default": null }, "facets": { "anyOf": [ { "items": { "$ref": "#/components/schemas/FacetSummary" }, "type": "array" }, { "type": "null" } ], "default": null, "title": "Facets" }, "field_types": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "default": null, "title": "Field Types" }, "forms": { "anyOf": [ { "$ref": "#/components/schemas/FormCapabilities" }, { "type": "null" } ], "default": null }, "formula_functions": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "default": null, "title": "Formula Functions" }, "formula_result_types": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "default": null, "title": "Formula Result Types" }, "layouts": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "default": null, "title": "Layouts" }, "query_spec_version": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Query Spec Version" }, "record_operators": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "default": null, "title": "Record Operators" }, "sections": { "items": { "type": "string" }, "title": "Sections", "type": "array" }, "structural_record_fields": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "default": null, "title": "Structural Record Fields" }, "view_types": { "anyOf": [ { "items": { "$ref": "#/components/schemas/ViewTypeCapability" }, "type": "array" }, { "type": "null" } ], "default": null, "title": "View Types" } }, "required": [ "capabilities_version", "sections" ], "title": "QueryAuthoringCapabilitiesResponse", "type": "object" }, "QueryPreviewRequest": { "description": "Validate + preview a records QuerySpec — side-effect free.", "properties": { "facet": { "description": "Facet slug to query.", "minLength": 1, "title": "Facet", "type": "string" }, "filters": { "additionalProperties": true, "description": "QuerySpec V1 filter group {logic, conditions} (legacy operator aliases accepted).", "title": "QueryPreviewFilters", "type": "object" }, "layout": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Layout you intend to render (table/kanban/calendar/timeline/gantt/card/gallery/planning/outline/chart/hierarchy). Resolves the facet's view mapping and returns the ephemeral working-panel binding alongside the rows, so the same call proves the query AND the rendering.", "title": "Layout" }, "limit": { "default": 20, "description": "Sample size.", "maximum": 100.0, "minimum": 1.0, "title": "Limit", "type": "integer" }, "sorts": { "description": "Ordered sort clauses [{field, direction, nulls?}].", "items": { "additionalProperties": true, "type": "object" }, "title": "Sorts", "type": "array" }, "view_state": { "additionalProperties": true, "description": "Per-layout config validated with the layout (chart {kind, dimension, measure, ratio?} / hierarchy {parentField|linkType, …}).", "title": "QueryPreviewViewState", "type": "object" } }, "required": [ "facet" ], "title": "QueryPreviewRequest", "type": "object" }, "QueryPreviewResponse": { "description": "Ordered sample under the caller's member-visible predicate.", "properties": { "ephemeral": { "anyOf": [ { "$ref": "#/components/schemas/EphemeralPreview" }, { "type": "null" } ], "default": null, "description": "Working-panel descriptor for this preview. Present only when the query is valid AND the layout resolves — there is nothing temporary to show for a spec that cannot render." }, "issues": { "description": "Structured problems: {path, code, message, allowed?}.", "items": { "additionalProperties": true, "type": "object" }, "title": "Issues", "type": "array" }, "resolved_view": { "anyOf": [ { "$ref": "#/components/schemas/ResolvedViewMapping" }, { "type": "null" } ], "default": null, "description": "Present when the request named a layout." }, "rows": { "items": { "$ref": "#/components/schemas/QueryPreviewRow" }, "title": "Rows", "type": "array" }, "total_matched": { "default": 0, "title": "Total Matched", "type": "integer" }, "truncated": { "default": false, "title": "Truncated", "type": "boolean" }, "valid": { "title": "Valid", "type": "boolean" } }, "required": [ "valid" ], "title": "QueryPreviewResponse", "type": "object" }, "QueryPreviewRow": { "properties": { "id": { "title": "Id", "type": "string" }, "properties": { "additionalProperties": true, "title": "QueryPreviewRowProperties", "type": "object" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Title" } }, "required": [ "id" ], "title": "QueryPreviewRow", "type": "object" }, "QuickApproveRequest": { "description": "Request to quickly approve a suggestion using its defaults.", "properties": { "backfill": { "default": false, "description": "If true, retroactively link past items matching keywords", "title": "Backfill", "type": "boolean" }, "days_back": { "default": 90, "description": "Number of days to search back for backfill", "maximum": 365.0, "minimum": 1.0, "title": "Days Back", "type": "integer" }, "suggestion_id": { "description": "UUID of the suggestion to approve", "title": "Suggestion Id", "type": "string" } }, "required": [ "suggestion_id" ], "title": "QuickApproveRequest", "type": "object" }, "QuickStats": { "properties": { "queue_depth": { "default": 0, "title": "Queue Depth", "type": "integer" }, "search_query_rate_recent": { "default": 0, "title": "Search Query Rate Recent", "type": "integer" }, "transcription_minutes_today": { "default": 0.0, "title": "Transcription Minutes Today", "type": "number" } }, "title": "QuickStats", "type": "object" }, "QuotaErrorDetail": { "properties": { "error": { "default": "storage_quota_exceeded", "title": "Error", "type": "string" }, "message": { "title": "Message", "type": "string" }, "quota_bytes": { "title": "Quota Bytes", "type": "integer" }, "used_bytes": { "title": "Used Bytes", "type": "integer" } }, "required": [ "used_bytes", "quota_bytes", "message" ], "title": "QuotaErrorDetail", "type": "object" }, "QuotaStatusModel": { "description": "What the panel shows before the user spends (decision 8).", "properties": { "limit": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Daily cap; null when uncapped.", "title": "Limit" }, "remaining": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Null when uncapped.", "title": "Remaining" }, "resets_at": { "title": "Resets At", "type": "string" }, "timezone": { "title": "Timezone", "type": "string" }, "used": { "title": "Used", "type": "integer" } }, "required": [ "limit", "used", "remaining", "resets_at", "timezone" ], "title": "QuotaStatusModel", "type": "object" }, "RankingRolloutAdvanceRequest": { "properties": { "expected_version": { "description": "The rollout version the caller believes is current (CAS).", "minimum": 1.0, "title": "Expected Version", "type": "integer" } }, "required": [ "expected_version" ], "title": "RankingRolloutAdvanceRequest", "type": "object" }, "RankingRolloutAdvanceResult": { "properties": { "active_percentage": { "title": "Active Percentage", "type": "integer" }, "advanced": { "title": "Advanced", "type": "boolean" }, "blocking": { "items": { "type": "string" }, "title": "Blocking", "type": "array" }, "decision": { "additionalProperties": true, "title": "Decision", "type": "object" }, "surface": { "title": "Surface", "type": "string" }, "version": { "title": "Version", "type": "integer" } }, "required": [ "surface", "advanced", "active_percentage", "version", "blocking", "decision" ], "title": "RankingRolloutAdvanceResult", "type": "object" }, "RankingRolloutRollbackRequest": { "properties": { "reason": { "maxLength": 500, "minLength": 1, "title": "Reason", "type": "string" } }, "required": [ "reason" ], "title": "RankingRolloutRollbackRequest", "type": "object" }, "RankingRolloutRollbackResult": { "properties": { "active_percentage": { "title": "Active Percentage", "type": "integer" }, "already_rolled_back": { "default": false, "title": "Already Rolled Back", "type": "boolean" }, "surface": { "title": "Surface", "type": "string" }, "version": { "title": "Version", "type": "integer" } }, "required": [ "surface", "active_percentage", "version" ], "title": "RankingRolloutRollbackResult", "type": "object" }, "RankingRolloutStatus": { "properties": { "active_percentage": { "title": "Active Percentage", "type": "integer" }, "arms": { "additionalProperties": true, "title": "Arms", "type": "object" }, "blocking": { "items": { "type": "string" }, "title": "Blocking", "type": "array" }, "control_config_version_id": { "title": "Control Config Version Id", "type": "string" }, "decision": { "additionalProperties": true, "title": "Decision", "type": "object" }, "experiment_id": { "title": "Experiment Id", "type": "string" }, "promotable": { "title": "Promotable", "type": "boolean" }, "stage_duration_days": { "title": "Stage Duration Days", "type": "number" }, "surface": { "title": "Surface", "type": "string" }, "treatment_config_version_id": { "title": "Treatment Config Version Id", "type": "string" }, "version": { "title": "Version", "type": "integer" } }, "required": [ "surface", "active_percentage", "version", "experiment_id", "treatment_config_version_id", "control_config_version_id", "stage_duration_days", "promotable", "blocking", "decision", "arms" ], "title": "RankingRolloutStatus", "type": "object" }, "ReceivedHere": { "description": "THIS env's own receive view from ``podcast_corpus_ingest_log`` — truth\nfor \"what reached HERE\", independent of any dag reachability.", "properties": { "episodes_ingested": { "default": 0, "title": "Episodes Ingested", "type": "integer" }, "last_writeback_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Last Writeback At" }, "writebacks_last_24h": { "default": 0, "title": "Writebacks Last 24H", "type": "integer" }, "writebacks_last_7d": { "default": 0, "title": "Writebacks Last 7D", "type": "integer" } }, "title": "ReceivedHere", "type": "object" }, "RecentAuth": { "properties": { "amr": { "items": { "type": "string" }, "title": "Amr", "type": "array" }, "auth_time": { "format": "date-time", "title": "Auth Time", "type": "string" }, "expires_at": { "format": "date-time", "title": "Expires At", "type": "string" } }, "required": [ "auth_time", "expires_at", "amr" ], "title": "RecentAuth", "type": "object" }, "RecentEmojiRequest": { "properties": { "emoji": { "maxLength": 64, "minLength": 1, "title": "Emoji", "type": "string" } }, "required": [ "emoji" ], "title": "RecentEmojiRequest", "type": "object" }, "RecentEmojiResponse": { "properties": { "emoji": { "title": "Emoji", "type": "string" }, "last_used_at": { "format": "date-time", "title": "Last Used At", "type": "string" }, "use_count": { "title": "Use Count", "type": "integer" } }, "required": [ "emoji", "use_count", "last_used_at" ], "title": "RecentEmojiResponse", "type": "object" }, "RechunkResponse": { "description": "Response from rechunking a document.", "properties": { "chunks_created": { "title": "Chunks Created", "type": "integer" }, "document_id": { "title": "Document Id", "type": "string" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error" }, "success": { "title": "Success", "type": "boolean" } }, "required": [ "success", "chunks_created", "document_id" ], "title": "RechunkResponse", "type": "object" }, "RecipeOpenRequest": { "properties": { "digest_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Digest Id" }, "ledger_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Ledger Id" } }, "title": "RecipeOpenRequest", "type": "object" }, "RecipeOpenResponse": { "properties": { "marked": { "title": "Marked", "type": "integer" } }, "required": [ "marked" ], "title": "RecipeOpenResponse", "type": "object" }, "RecipePreferenceResponse": { "description": "A single user_recipe_preferences row.", "properties": { "account_id": { "format": "uuid", "title": "Account Id", "type": "string" }, "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "force_server_side": { "title": "Force Server Side", "type": "boolean" }, "id": { "format": "uuid", "title": "Id", "type": "string" }, "is_paused": { "title": "Is Paused", "type": "boolean" }, "paused_until": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Paused Until" }, "recipe_slug": { "title": "Recipe Slug", "type": "string" }, "tenant_id": { "format": "uuid", "title": "Tenant Id", "type": "string" }, "updated_at": { "format": "date-time", "title": "Updated At", "type": "string" } }, "required": [ "id", "tenant_id", "account_id", "recipe_slug", "is_paused", "force_server_side", "created_at", "updated_at" ], "title": "RecipePreferenceResponse", "type": "object" }, "RecipePreferenceUpdate": { "description": "Request body for pausing/resuming a recipe.", "properties": { "force_server_side": { "default": false, "description": "Opt out of local-AI for this recipe (CC S3 routing).", "title": "Force Server Side", "type": "boolean" }, "is_paused": { "description": "True to pause this recipe for the caller.", "title": "Is Paused", "type": "boolean" }, "paused_until": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "Optional auto-resume timestamp (ISO 8601 UTC). When this time passes the pause is treated as cleared. Must be in the future.", "title": "Paused Until" } }, "required": [ "is_paused" ], "title": "RecipePreferenceUpdate", "type": "object" }, "RecipeRunDetail": { "properties": { "attention_disposition": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Attention Disposition" }, "cost_usd": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Cost Usd" }, "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "definition_id": { "format": "uuid", "title": "Definition Id", "type": "string" }, "delegation_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Delegation Id" }, "eligibility": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Eligibility" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error" }, "executor_kind": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Executor Kind" }, "executor_ref": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Executor Ref" }, "finished_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Finished At" }, "id": { "format": "uuid", "title": "Id", "type": "string" }, "latency_ms": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Latency Ms" }, "local_ai_used": { "title": "Local Ai Used", "type": "boolean" }, "mode": { "title": "Mode", "type": "string" }, "model_used": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Model Used" }, "outcome_detail": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Outcome Detail" }, "output_refs": { "items": { "additionalProperties": true, "type": "object" }, "title": "Output Refs", "type": "array" }, "principal_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Principal Id" }, "replay_session_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Replay Session Id" }, "rollback_of_run_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Rollback Of Run Id" }, "rollout_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Rollout Id" }, "scheduled_action_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Scheduled Action Id" }, "started_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Started At" }, "status": { "title": "Status", "type": "string" }, "suppression_disposition": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Suppression Disposition" }, "target_key": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Target Key" }, "tenant_id": { "format": "uuid", "title": "Tenant Id", "type": "string" }, "tokens_in": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Tokens In" }, "tokens_out": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Tokens Out" }, "trigger_event_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Trigger Event Id" }, "trigger_source": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Trigger Source" }, "version_id": { "format": "uuid", "title": "Version Id", "type": "string" } }, "required": [ "id", "mode", "replay_session_id", "definition_id", "version_id", "rollout_id", "tenant_id", "principal_id", "delegation_id", "trigger_source", "trigger_event_id", "scheduled_action_id", "target_key", "eligibility", "suppression_disposition", "attention_disposition", "status", "outcome_detail", "executor_kind", "executor_ref", "model_used", "local_ai_used", "tokens_in", "tokens_out", "cost_usd", "latency_ms", "output_refs", "rollback_of_run_id", "error", "created_at", "started_at", "finished_at" ], "title": "RecipeRunDetail", "type": "object" }, "RecipeRunPackInvocation": { "properties": { "cache_disposition": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cache Disposition" }, "consumer_ref": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Consumer Ref" }, "consumer_type": { "title": "Consumer Type", "type": "string" }, "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error" }, "freshness_age_s": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Freshness Age S" }, "id": { "format": "uuid", "title": "Id", "type": "string" }, "input_hash": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Input Hash" }, "latency_ms": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Latency Ms" }, "outcome": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Outcome" }, "output_bytes": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Output Bytes" }, "pack_id": { "format": "uuid", "title": "Pack Id", "type": "string" }, "pack_slug": { "title": "Pack Slug", "type": "string" }, "pack_version_id": { "format": "uuid", "title": "Pack Version Id", "type": "string" }, "principal_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Principal Id" }, "run_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Run Id" }, "source_watermarks": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Source Watermarks" }, "tenant_id": { "format": "uuid", "title": "Tenant Id", "type": "string" } }, "required": [ "id", "run_id", "consumer_type", "consumer_ref", "pack_id", "pack_slug", "pack_version_id", "tenant_id", "principal_id", "input_hash", "source_watermarks", "cache_disposition", "freshness_age_s", "outcome", "latency_ms", "output_bytes", "error", "created_at" ], "title": "RecipeRunPackInvocation", "type": "object" }, "RecipientInput": { "additionalProperties": true, "description": "One recipient chip as the compose client stores it — an explicit address,\na group chip (``type='group'`` + id/group_id), or an org chip\n(``type='organization'`` + id/organization_id). Permissive by design so the\nvalidate-recipients preview accepts the exact draft recipient shape.", "properties": { "address": { "default": "", "description": "Email address (empty for chips)", "title": "Address", "type": "string" }, "group_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Group id for a group chip", "title": "Group Id" }, "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Entity id (group/org chips)", "title": "Id" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Display name", "title": "Name" }, "organization_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Organization id for an org chip", "title": "Organization Id" }, "type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "'contact' | 'group' | 'organization'", "title": "Type" } }, "title": "RecipientInput", "type": "object" }, "RecipientValidationResponse": { "description": "Preview of send-time expansion without sending (TIDY-14747).", "properties": { "issues": { "description": "Every flag the same expansion would surface at send", "items": { "$ref": "#/components/schemas/ExpansionIssue" }, "title": "Issues", "type": "array" }, "resolved_counts": { "additionalProperties": { "type": "integer" }, "description": "Deduped resolved address count per field ('to'/'cc'/'bcc') + 'total'", "title": "Resolved Counts", "type": "object" } }, "required": [ "resolved_counts" ], "title": "RecipientValidationResponse", "type": "object" }, "ReclassifyRequest": { "properties": { "apply_to_all_from_sender": { "default": false, "description": "Update all emails from this sender", "title": "Apply To All From Sender", "type": "boolean" }, "category": { "description": "New triage category", "title": "Category", "type": "string" }, "create_sender_rule": { "default": false, "description": "Create/update sender forced_category rule", "title": "Create Sender Rule", "type": "boolean" } }, "required": [ "category" ], "title": "ReclassifyRequest", "type": "object" }, "ReclassifyResponse": { "properties": { "category_forced": { "default": false, "title": "Category Forced", "type": "boolean" }, "email_id": { "format": "uuid", "title": "Email Id", "type": "string" }, "emails_updated": { "default": 1, "title": "Emails Updated", "type": "integer" }, "new_category": { "title": "New Category", "type": "string" }, "new_inbox_split": { "title": "New Inbox Split", "type": "string" }, "seed_proposal": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Seed Proposal" }, "sender_rule_created": { "default": false, "title": "Sender Rule Created", "type": "boolean" }, "success": { "default": true, "title": "Success", "type": "boolean" } }, "required": [ "email_id", "new_category", "new_inbox_split" ], "title": "ReclassifyResponse", "type": "object" }, "ReconcileRequest": { "properties": { "dry_run": { "default": true, "title": "Dry Run", "type": "boolean" } }, "title": "ReconcileRequest", "type": "object" }, "ReconcileResponse": { "properties": { "accounted": { "title": "Accounted", "type": "integer" }, "bytes": { "title": "Bytes", "type": "integer" }, "dry_run": { "title": "Dry Run", "type": "boolean" }, "objects": { "title": "Objects", "type": "integer" }, "paths": { "items": { "type": "string" }, "title": "Paths", "type": "array" }, "removed": { "title": "Removed", "type": "integer" } }, "required": [ "dry_run", "objects", "accounted", "paths", "bytes", "removed" ], "title": "ReconcileResponse", "type": "object" }, "ReconciliationEntry": { "properties": { "bill_amount_usd": { "title": "Bill Amount Usd", "type": "number" }, "bill_tidy_share_usd": { "title": "Bill Tidy Share Usd", "type": "number" }, "divergence_ratio": { "title": "Divergence Ratio", "type": "number" }, "external_amount_usd": { "title": "External Amount Usd", "type": "number" }, "logged_cost_usd": { "title": "Logged Cost Usd", "type": "number" }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Notes" }, "period_end": { "format": "date", "title": "Period End", "type": "string" }, "period_start": { "format": "date", "title": "Period Start", "type": "string" }, "provider": { "title": "Provider", "type": "string" }, "status": { "title": "Status", "type": "string" } }, "required": [ "provider", "period_start", "period_end", "bill_amount_usd", "external_amount_usd", "bill_tidy_share_usd", "logged_cost_usd", "divergence_ratio", "status" ], "title": "ReconciliationEntry", "type": "object" }, "ReconciliationPrimitives": { "properties": { "contacts": { "default": [], "items": { "additionalProperties": true, "type": "object" }, "title": "Contacts", "type": "array" }, "events": { "default": [], "items": { "additionalProperties": true, "type": "object" }, "title": "Events", "type": "array" }, "news": { "default": [], "items": { "additionalProperties": true, "type": "object" }, "title": "News", "type": "array" }, "notes": { "default": [], "items": { "additionalProperties": true, "type": "object" }, "title": "Notes", "type": "array" }, "reminders": { "default": [], "items": { "additionalProperties": true, "type": "object" }, "title": "Reminders", "type": "array" }, "tasks": { "default": [], "items": { "additionalProperties": true, "type": "object" }, "title": "Tasks", "type": "array" } }, "title": "ReconciliationPrimitives", "type": "object" }, "ReconciliationResponse": { "properties": { "docId": { "title": "Docid", "type": "string" }, "metrics": { "additionalProperties": true, "title": "Metrics", "type": "object" }, "pipelineRun": { "$ref": "#/components/schemas/PipelineRunInfo" }, "primitives": { "$ref": "#/components/schemas/ReconciliationPrimitives" } }, "required": [ "pipelineRun", "metrics", "primitives", "docId" ], "title": "ReconciliationResponse", "type": "object" }, "ReconciliationReviewRequest": { "properties": { "evidence_kind": { "description": "What the operator verified with the provider.", "enum": [ "provider_absent", "provider_failed" ], "title": "Evidence Kind", "type": "string" }, "evidence_ref": { "description": "Opaque operator reference to the evidence (ticket, log id).", "maxLength": 256, "title": "Evidence Ref", "type": "string" }, "expected_state_version": { "description": "The retry_generation the reviewer observed — an optimistic-concurrency guard.", "minimum": 0.0, "title": "Expected State Version", "type": "integer" } }, "required": [ "expected_state_version", "evidence_kind", "evidence_ref" ], "title": "ReconciliationReviewRequest", "type": "object" }, "ReconciliationReviewResponse": { "properties": { "id": { "format": "uuid", "title": "Id", "type": "string" }, "manual_review_required": { "title": "Manual Review Required", "type": "boolean" }, "manual_reviewed_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Manual Reviewed At" }, "state": { "title": "State", "type": "string" } }, "required": [ "id", "state", "manual_review_required" ], "title": "ReconciliationReviewResponse", "type": "object" }, "RecordAuthor": { "description": "Who created a record: a member, or a virtual employee (TIDY-19705 F9).", "properties": { "account_id": { "title": "Account Id", "type": "string" }, "display_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Display Name" }, "kind": { "enum": [ "member", "agent" ], "title": "Kind", "type": "string" } }, "required": [ "account_id", "kind" ], "title": "RecordAuthor", "type": "object" }, "RecordBatchCreateRequest": { "properties": { "facet_slug": { "minLength": 1, "title": "Facet Slug", "type": "string" }, "rows": { "items": { "$ref": "#/components/schemas/RecordBatchItem" }, "maxItems": 50, "minItems": 1, "title": "Rows", "type": "array" } }, "required": [ "facet_slug", "rows" ], "title": "RecordBatchCreateRequest", "type": "object" }, "RecordBatchCreateResponse": { "properties": { "facet_slug": { "title": "Facet Slug", "type": "string" }, "results": { "items": { "$ref": "#/components/schemas/RecordBatchResult" }, "title": "Results", "type": "array" } }, "required": [ "facet_slug", "results" ], "title": "RecordBatchCreateResponse", "type": "object" }, "RecordBatchItem": { "description": "One row in a batch create. ``key`` is the caller's stable idempotency\nkey — retries with the same key update the same row, never duplicate.", "properties": { "key": { "maxLength": 200, "minLength": 1, "title": "Key", "type": "string" }, "properties": { "additionalProperties": true, "title": "RecordBatchItemProperties", "type": "object" }, "search_text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Search Text" } }, "required": [ "key" ], "title": "RecordBatchItem", "type": "object" }, "RecordBatchResult": { "properties": { "action": { "enum": [ "created", "updated", "unchanged", "rejected" ], "title": "Action", "type": "string" }, "issues": { "items": { "additionalProperties": true, "type": "object" }, "title": "Issues", "type": "array" }, "key": { "title": "Key", "type": "string" }, "record_id": { "title": "Record Id", "type": "string" } }, "required": [ "key", "record_id", "action" ], "title": "RecordBatchResult", "type": "object" }, "RecordCheck": { "properties": { "checked_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Checked At" }, "expected": { "title": "Expected", "type": "string" }, "name": { "title": "Name", "type": "string" }, "observed": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Observed" }, "ok": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "title": "Ok" }, "required": { "title": "Required", "type": "boolean" }, "type": { "title": "Type", "type": "string" } }, "required": [ "name", "type", "expected", "required" ], "title": "RecordCheck", "type": "object" }, "RecordCreateRequest": { "description": "Request body for creating a record.\n\nAccepts an optional client-supplied `id` so PowerSync CRUD sync uploads\n(TIDY-7048) can POST with the same UUID the local INSERT used. `search_text`\nand `source_type`/`source_id` pass through from the sync payload.", "properties": { "access_scope_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Access Scope Id" }, "approval_status": { "default": "approved", "title": "Approval Status", "type": "string" }, "facet_slug": { "title": "Facet Slug", "type": "string" }, "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Client-provided ID for PowerSync sync", "title": "Id" }, "parent_note_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Parent Note Id" }, "properties": { "additionalProperties": true, "title": "RecordCreateProperties", "type": "object" }, "search_text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Search Text" }, "source_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Source Id" }, "source_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Source Type" }, "tags": { "items": { "type": "string" }, "title": "Tags", "type": "array" }, "visibility": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "private | shared. Omitted: private, or shared when created inside a shared parent note or record.", "title": "Visibility" } }, "required": [ "facet_slug" ], "title": "RecordCreateRequest", "type": "object" }, "RecordFieldReminderRequest": { "description": "Opt a record's datetime field in/out of a reminder (TIDY-14226 R5).", "properties": { "enabled": { "description": "True = bind a reminder at the stored timestamp; False = clear it.", "title": "Enabled", "type": "boolean" }, "field_key": { "description": "Facet field key holding the timestamp.", "minLength": 1, "title": "Field Key", "type": "string" } }, "required": [ "field_key", "enabled" ], "title": "RecordFieldReminderRequest", "type": "object" }, "RecordFieldReminderResponse": { "description": "Result of a field-reminder binding change.", "properties": { "field_key": { "title": "Field Key", "type": "string" }, "fire_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "When the bound reminder fires (canonical UTC).", "title": "Fire At" }, "record_id": { "title": "Record Id", "type": "string" }, "status": { "description": "created | updated | cleared | invalid | not_found", "title": "Status", "type": "string" } }, "required": [ "record_id", "field_key", "status" ], "title": "RecordFieldReminderResponse", "type": "object" }, "RecordGrantRequest": { "properties": { "action": { "maxLength": 256, "title": "Action", "type": "string" }, "conversation_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Required for scope=session", "title": "Conversation Id" }, "matched_rule_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Matched Rule Id" }, "member_account_id": { "description": "The human who answered the prompt", "title": "Member Account Id", "type": "string" }, "request_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Request Id" }, "scope": { "description": "session | always ('once' is never stored)", "title": "Scope", "type": "string" }, "target": { "default": "", "maxLength": 256, "title": "Target", "type": "string" } }, "required": [ "scope", "action", "member_account_id" ], "title": "RecordGrantRequest", "type": "object" }, "RecordHostFingerprintRequest": { "properties": { "fingerprint_sha256": { "maxLength": 128, "minLength": 1, "title": "Fingerprint Sha256", "type": "string" }, "host_label": { "maxLength": 256, "minLength": 1, "title": "Host Label", "type": "string" }, "key_type": { "enum": [ "ssh-ed25519", "ssh-rsa", "ecdsa-sha2-nistp256", "ecdsa-sha2-nistp384", "ecdsa-sha2-nistp521" ], "title": "Key Type", "type": "string" } }, "required": [ "host_label", "key_type", "fingerprint_sha256" ], "title": "RecordHostFingerprintRequest", "type": "object" }, "RecordId": { "description": "Typed primitive ID for records (prefix 'R').", "examples": [ "R-550e8400-e29b-41d4-a716-446655440000" ], "pattern": "^R-[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "title": "RecordId", "type": "string", "x-tidy-typed-id-prefix": "R", "x-tidy-typed-id-table": "records" }, "RecordListResponse": { "description": "Response for listing records.", "properties": { "records": { "items": { "$ref": "#/components/schemas/RecordResponse" }, "title": "Records", "type": "array" }, "total": { "default": 0, "title": "Total", "type": "integer" } }, "title": "RecordListResponse", "type": "object" }, "RecordResponse": { "description": "Record entry returned by API endpoints.", "properties": { "access_scope_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Access Scope Id" }, "approval_status": { "default": "approved", "title": "Approval Status", "type": "string" }, "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "created_by": { "anyOf": [ { "$ref": "#/components/schemas/RecordAuthor" }, { "type": "null" } ], "default": null, "description": "Who created the record; null for a record that predates creator tracking." }, "deleted_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Deleted At" }, "facet_slug": { "title": "Facet Slug", "type": "string" }, "id": { "title": "Id", "type": "string" }, "owner_id": { "title": "Owner Id", "type": "string" }, "owner_is_agent": { "default": false, "title": "Owner Is Agent", "type": "boolean" }, "parent_note_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Parent Note Id" }, "properties": { "additionalProperties": true, "title": "RecordResponseProperties", "type": "object" }, "requires_review": { "default": false, "title": "Requires Review", "type": "boolean" }, "search_text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Search Text" }, "source_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Source Id" }, "source_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Source Type" }, "tags": { "items": { "type": "string" }, "title": "Tags", "type": "array" }, "tenant_id": { "title": "Tenant Id", "type": "string" }, "updated_at": { "format": "date-time", "title": "Updated At", "type": "string" }, "view_binding": { "anyOf": [ { "$ref": "#/components/schemas/ViewBinding" }, { "type": "null" } ], "default": null, "description": "A saved database view's read only (facet_slug 'database'): what its layout draws from its facet's definition now (TIDY-18514)." }, "visibility": { "default": "private", "title": "Visibility", "type": "string" } }, "required": [ "id", "tenant_id", "owner_id", "facet_slug", "properties", "created_at", "updated_at" ], "title": "RecordResponse", "type": "object" }, "RecordUpdateRequest": { "description": "Request body for partially updating a record.\n\nPowerSync PATCH uploads surface every synced column. Record endpoints must\naccept search_text/source_type/source_id/approval_status so sync PATCH\nround-trips succeed (TIDY-7048).", "properties": { "approval_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Approval Status" }, "parent_note_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Parent Note Id" }, "properties": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "RFC 7386-style merge-patch: top-level keys merge into the stored properties; an explicit JSON null value DELETES that key; omitted keys are preserved. Mutually exclusive with `properties_delta`.", "title": "RecordUpdateProperties" }, "properties_delta": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "ONLY the changed keys, merged atomically under a row lock (`properties || delta`); null values are stored as null. Mutually exclusive with `properties`.", "title": "RecordUpdatePropertiesDelta" }, "search_text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Search Text" }, "source_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Source Id" }, "source_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Source Type" }, "tags": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Tags" }, "visibility": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Visibility" } }, "title": "RecordUpdateRequest", "type": "object" }, "RecurrenceHealthResponse": { "properties": { "broken_chains": { "items": { "$ref": "#/components/schemas/BrokenChainModel" }, "title": "Broken Chains", "type": "array" } }, "required": [ "broken_chains" ], "title": "RecurrenceHealthResponse", "type": "object" }, "ReferenceExtractionDetailResponse": { "properties": { "attachment_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Attachment Id" }, "attachment_storage_path": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Attachment Storage Path" }, "classification": { "additionalProperties": true, "title": "Classification", "type": "object" }, "content_markdown": { "default": "", "title": "Content Markdown", "type": "string" }, "crawl_metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "title": "Crawl Metadata" }, "created_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Created At" }, "docling_metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "title": "Docling Metadata" }, "email_id": { "title": "Email Id", "type": "string" }, "extracted": { "additionalProperties": true, "title": "Extracted", "type": "object" }, "extraction_result": { "additionalProperties": true, "title": "Extraction Result", "type": "object" }, "id": { "title": "Id", "type": "string" }, "metadata_only": { "default": false, "title": "Metadata Only", "type": "boolean" }, "per_document_routing": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Per Document Routing" }, "prompt_variant": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Prompt Variant" }, "routing_decision": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Routing Decision" }, "source_content_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Source Content Type" }, "source_domain": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Source Domain" }, "source_filename": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Source Filename" }, "source_title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Source Title" }, "source_type": { "title": "Source Type", "type": "string" }, "source_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Source Url" }, "summary": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Summary" }, "updated_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Updated At" } }, "required": [ "id", "email_id", "source_type" ], "title": "ReferenceExtractionDetailResponse", "type": "object" }, "ReferenceFilterCondition": { "description": "One leaf condition, e.g. ``{field: 'tag', operator: 'equals', value: 'barn-build'}``.", "properties": { "field": { "title": "Field", "type": "string" }, "operator": { "default": "equals", "title": "Operator", "type": "string" }, "value": { "title": "Value" } }, "required": [ "field" ], "title": "ReferenceFilterCondition", "type": "object" }, "ReferenceFilterGroup": { "description": "A ``FilterGroup`` — the same shape the S2 grammar parser emits.", "properties": { "conditions": { "items": { "anyOf": [ { "$ref": "#/components/schemas/ReferenceFilterGroup" }, { "$ref": "#/components/schemas/ReferenceFilterCondition" } ] }, "title": "Conditions", "type": "array" }, "logic": { "default": "and", "enum": [ "and", "or" ], "title": "Logic", "type": "string" } }, "title": "ReferenceFilterGroup", "type": "object" }, "ReferenceGatherRequest": { "description": "A universal-filter gather request — one FilterGroup, optional cap.", "properties": { "filter": { "$ref": "#/components/schemas/ReferenceFilterGroup", "description": "The universal-filter FilterGroup (tagged / linked structural conditions)." }, "limit": { "default": 200, "description": "Maximum references to return.", "maximum": 500.0, "minimum": 1.0, "title": "Limit", "type": "integer" } }, "required": [ "filter" ], "title": "ReferenceGatherRequest", "type": "object" }, "ReferenceGatherResponse": { "description": "The member-visible references a gather resolved to.", "properties": { "count": { "title": "Count", "type": "integer" }, "references": { "items": { "$ref": "#/components/schemas/GatheredReference" }, "title": "References", "type": "array" } }, "required": [ "references", "count" ], "title": "ReferenceGatherResponse", "type": "object" }, "ReferenceReadResponse": { "description": "One referenceable row, as an employee resolving its typed id sees it.", "properties": { "fields": { "additionalProperties": true, "description": "A small, bounded set of the row's fields; empty values are omitted.", "title": "Reference Fields", "type": "object" }, "id": { "description": "The typed id, exactly as asked for (`SK-`).", "title": "Id", "type": "string" }, "label": { "title": "Label", "type": "string" }, "primitive": { "description": "Canonical primitive type (`skill`, `group`, …).", "title": "Primitive", "type": "string" }, "truncated": { "description": "True when a free-text field was cut to fit.", "title": "Truncated", "type": "boolean" } }, "required": [ "id", "primitive", "label", "fields", "truncated" ], "title": "ReferenceReadResponse", "type": "object" }, "ReformatTextRequest": { "description": "Request to reformat text via AI.", "properties": { "text": { "description": "Text to reformat", "maxLength": 50000, "minLength": 1, "title": "Text", "type": "string" } }, "required": [ "text" ], "title": "ReformatTextRequest", "type": "object" }, "ReformatTextResponse": { "description": "Response from AI text reformatting.", "properties": { "reformatted_text": { "title": "Reformatted Text", "type": "string" } }, "required": [ "reformatted_text" ], "title": "ReformatTextResponse", "type": "object" }, "RefreshAfterVerifyRequest": { "description": "Request body for refresh-after-verify (TIDY-9373).\n\nSame shape as the exchange request: the frontend passes the current\nSupabase access token (cookie or bearer) and we re-run the exchange\nflow so the freshly-flipped `email_confirmed_at` propagates into a\nnew Tidy bearer.", "properties": { "resource": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Resource" }, "supabase_access_token": { "title": "Supabase Access Token", "type": "string" } }, "required": [ "supabase_access_token" ], "title": "RefreshAfterVerifyRequest", "type": "object" }, "RefreshFoldersRequest": { "properties": { "email_source_id": { "description": "email_source_configs.id", "format": "uuid", "title": "Email Source Id", "type": "string" } }, "required": [ "email_source_id" ], "title": "RefreshFoldersRequest", "type": "object" }, "RefreshFoldersResponse": { "properties": { "discovered": { "title": "Discovered", "type": "integer" }, "new": { "title": "New", "type": "integer" }, "updated": { "default": 0, "title": "Updated", "type": "integer" } }, "required": [ "discovered", "new" ], "title": "RefreshFoldersResponse", "type": "object" }, "RefusedModelPlugin": { "description": "The lent model plugin whose key or address was refused (TIDY-20073 F2).\n\nWhile an employee is ``needs_reauth`` because a turn on a plugin's key was\nrefused, the remedy is that plugin, not a sign-in, so the surfaces name it\nand open it. Read from the turn's execution receipt, never the connector.", "properties": { "id": { "title": "Id", "type": "string" }, "name": { "title": "Name", "type": "string" } }, "required": [ "id", "name" ], "title": "RefusedModelPlugin", "type": "object" }, "RegeneratePreviewRequest": { "properties": { "drawing_version": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Drawing Version" }, "tenant_id": { "format": "uuid", "title": "Tenant Id", "type": "string" } }, "required": [ "tenant_id" ], "title": "RegeneratePreviewRequest", "type": "object" }, "RegeneratePreviewResponse": { "properties": { "drawing_version": { "title": "Drawing Version", "type": "integer" }, "note_id": { "title": "Note Id", "type": "string" }, "preview_status": { "title": "Preview Status", "type": "string" }, "preview_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Preview Url" } }, "required": [ "note_id", "drawing_version", "preview_url", "preview_status" ], "title": "RegeneratePreviewResponse", "type": "object" }, "RegisterAliasRequest": { "description": "Register a new send-as alias with the provider.", "properties": { "display_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Display name for the alias", "title": "Display Name" }, "email": { "description": "Alias email address to register", "title": "Email", "type": "string" } }, "required": [ "email" ], "title": "RegisterAliasRequest", "type": "object" }, "RegisterOAuthAppRequest": { "properties": { "allowed_scopes": { "items": { "type": "string" }, "title": "Allowed Scopes", "type": "array" }, "client_type": { "enum": [ "web", "native" ], "title": "Client Type", "type": "string" }, "homepage_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Homepage Url" }, "logo_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Logo Url" }, "name": { "maxLength": 120, "minLength": 1, "title": "Name", "type": "string" }, "redirect_uris": { "items": { "type": "string" }, "title": "Redirect Uris", "type": "array" } }, "required": [ "name", "client_type", "allowed_scopes" ], "title": "RegisterOAuthAppRequest", "type": "object" }, "RegisterOAuthAppResponse": { "properties": { "client_secret": { "title": "Client Secret", "type": "string" }, "record": { "$ref": "#/components/schemas/OAuthAppPublic" } }, "required": [ "record", "client_secret" ], "title": "RegisterOAuthAppResponse", "type": "object" }, "ReharvestResponse": { "description": "Result of a force re-harvest enqueue.\n\n``queued`` is True when a NEW outbox job was created; False (with\n``already_pending``) when an in-flight harvest for this email was found and\nreused instead of double-queuing. ``job_id`` is the ingestion_jobs row id\n(the new one, or the existing pending one on a double-submit).", "properties": { "already_pending": { "default": false, "title": "Already Pending", "type": "boolean" }, "email_id": { "format": "uuid", "title": "Email Id", "type": "string" }, "job_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "default": null, "title": "Job Id" }, "queued": { "title": "Queued", "type": "boolean" } }, "required": [ "queued", "email_id" ], "title": "ReharvestResponse", "type": "object" }, "RehomeInstallationRequest": { "description": "Owner-confirmed re-home of a foreign-principal portable installation\ninto its workshop's resident daemon (TIDY-18675).\n\n``workshop_id`` may be omitted: the employee's assigned workshop is the\ntarget, and a re-home to any OTHER workshop is a move (`workshop_moves`),\nnot a takeover.", "properties": { "confirmation_slug": { "maxLength": 80, "minLength": 2, "title": "Confirmation Slug", "type": "string" }, "expected_generation": { "minimum": 0.0, "title": "Expected Generation", "type": "integer" }, "reason": { "maxLength": 500, "minLength": 8, "title": "Reason", "type": "string" }, "workshop_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Workshop Id" } }, "required": [ "expected_generation", "reason", "confirmation_slug" ], "title": "RehomeInstallationRequest", "type": "object" }, "RehomeInstallationResponse": { "properties": { "generation": { "title": "Generation", "type": "integer" }, "host_instance_id": { "format": "uuid", "title": "Host Instance Id", "type": "string" }, "installation_id": { "format": "uuid", "title": "Installation Id", "type": "string" }, "rehome_receipt_id": { "format": "uuid", "title": "Rehome Receipt Id", "type": "string" }, "server_time": { "format": "date-time", "title": "Server Time", "type": "string" }, "workshop_id": { "format": "uuid", "title": "Workshop Id", "type": "string" } }, "required": [ "installation_id", "workshop_id", "host_instance_id", "generation", "rehome_receipt_id", "server_time" ], "title": "RehomeInstallationResponse", "type": "object" }, "RejectMemoryRequest": { "properties": { "always_reject_pattern": { "default": false, "title": "Always Reject Pattern", "type": "boolean" }, "extracted_data": { "additionalProperties": true, "title": "Extracted Data", "type": "object" }, "primitive_type": { "maxLength": 64, "title": "Primitive Type", "type": "string" } }, "required": [ "primitive_type" ], "title": "RejectMemoryRequest", "type": "object" }, "RejectMemoryResponse": { "properties": { "fingerprint": { "title": "Fingerprint", "type": "string" }, "remembered": { "title": "Remembered", "type": "boolean" } }, "required": [ "remembered", "fingerprint" ], "title": "RejectMemoryResponse", "type": "object" }, "RejectPortraitResponse": { "properties": { "portrait": { "$ref": "#/components/schemas/PortraitModel" } }, "required": [ "portrait" ], "title": "RejectPortraitResponse", "type": "object" }, "RejectRequest": { "description": "Request body for rejection with optional reason.", "properties": { "reason": { "anyOf": [ { "maxLength": 500, "type": "string" }, { "type": "null" } ], "title": "Reason" } }, "title": "RejectRequest", "type": "object" }, "RejectedEvent": { "properties": { "code": { "title": "Code", "type": "string" }, "index": { "title": "Index", "type": "integer" } }, "required": [ "index", "code" ], "title": "RejectedEvent", "type": "object" }, "RejectedItem": { "description": "A single rejected primitive.", "properties": { "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Description" }, "id": { "title": "Id", "type": "string" }, "rejected_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Rejected At" }, "rejection_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Rejection Reason" }, "source": { "anyOf": [ { "$ref": "#/components/schemas/RejectedSourceInfo" }, { "type": "null" } ], "default": null }, "title": { "title": "Title", "type": "string" }, "type": { "title": "Type", "type": "string" } }, "required": [ "id", "type", "title", "created_at" ], "title": "RejectedItem", "type": "object" }, "RejectedListResponse": { "description": "Response for listing rejected items.", "properties": { "has_more": { "title": "Has More", "type": "boolean" }, "items": { "items": { "$ref": "#/components/schemas/RejectedItem" }, "title": "Items", "type": "array" }, "total": { "title": "Total", "type": "integer" } }, "required": [ "items", "total", "has_more" ], "title": "RejectedListResponse", "type": "object" }, "RejectedSourceInfo": { "description": "Source information for a rejected item.", "properties": { "email_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Email Id" }, "sender": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Sender" }, "subject": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Subject" }, "type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Type" } }, "title": "RejectedSourceInfo", "type": "object" }, "RelatedEmailItem": { "description": "An email related to a project suggestion.\n\nRelated: KCC-3473, KCC-A-108", "properties": { "id": { "description": "Email UUID", "title": "Id", "type": "string" }, "match_reason": { "description": "Why this email matches (keyword, sender domain, etc.)", "title": "Match Reason", "type": "string" }, "match_score": { "description": "Relevance score 0.0-1.0", "maximum": 1.0, "minimum": 0.0, "title": "Match Score", "type": "number" }, "received_at": { "description": "When email was received", "format": "date-time", "title": "Received At", "type": "string" }, "sender": { "description": "Sender email address", "title": "Sender", "type": "string" }, "subject": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Email subject", "title": "Subject" } }, "required": [ "id", "sender", "received_at", "match_score", "match_reason" ], "title": "RelatedEmailItem", "type": "object" }, "RelatedEmailsResponse": { "description": "Response with emails related to a project suggestion.\n\nUsed in: GET /api/v1/projects/suggestions/{id}/related-emails\n\nRelated: KCC-3473, KCC-A-108", "properties": { "related_emails": { "description": "List of related emails", "items": { "$ref": "#/components/schemas/RelatedEmailItem" }, "title": "Related Emails", "type": "array" }, "suggestion_id": { "description": "UUID of the suggestion", "title": "Suggestion Id", "type": "string" }, "total": { "default": 0, "description": "Total number of related emails", "title": "Total", "type": "integer" } }, "required": [ "suggestion_id" ], "title": "RelatedEmailsResponse", "type": "object" }, "RelatedItem": { "description": "Extracted entity link from note content.", "properties": { "id": { "description": "Entity UUID", "title": "Id", "type": "string" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Entity title/name", "title": "Title" }, "type": { "description": "Entity type: task, event, contact", "title": "Type", "type": "string" } }, "required": [ "type", "id" ], "title": "RelatedItem", "type": "object" }, "RelatedPrimitivesResponse": { "description": "Linked references with full details.\n\nUsed in:\n - GET /api/v1/primitives/{type}/{id}/related", "properties": { "hidden_related": { "default": 0, "description": "Linked rows on this page hidden by the member-visible predicate", "title": "Hidden Related", "type": "integer" }, "linked_references": { "description": "Linked references", "items": { "anyOf": [ { "$ref": "#/components/schemas/EventSummary" }, { "$ref": "#/components/schemas/api_service__models__links__ContactSummary" }, { "$ref": "#/components/schemas/api_service__models__links__TaskSummary" }, { "$ref": "#/components/schemas/NoteSummary" }, { "$ref": "#/components/schemas/NewsSummary" }, { "$ref": "#/components/schemas/api_service__models__links__OrganizationSummary" }, { "$ref": "#/components/schemas/PodcastEpisodeSummary" }, { "$ref": "#/components/schemas/EmailSummary" }, { "$ref": "#/components/schemas/FileSummary" } ] }, "title": "Linked References", "type": "array" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Cursor for next page", "title": "Next Cursor" }, "total": { "description": "Total count of linked references", "title": "Total", "type": "integer" } }, "required": [ "linked_references", "total" ], "title": "RelatedPrimitivesResponse", "type": "object" }, "RelationshipTypeCreate": { "description": "Input for POST /api/v1/relationship-types.", "properties": { "inverse_label": { "anyOf": [ { "maxLength": 120, "type": "string" }, { "type": "null" } ], "description": "Optional inverse label", "title": "Inverse Label" }, "label": { "description": "Human label", "maxLength": 120, "minLength": 1, "title": "Label", "type": "string" } }, "required": [ "label" ], "title": "RelationshipTypeCreate", "type": "object" }, "RelationshipTypeRecord": { "description": "One tenant-created relationship type.", "properties": { "created_at": { "description": "Row creation timestamp", "format": "date-time", "title": "Created At", "type": "string" }, "id": { "description": "Relationship type UUID", "title": "Id", "type": "string" }, "inverse_label": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Optional inverse label (e.g. 'has vendor')", "title": "Inverse Label" }, "label": { "description": "Normalized human label (e.g. 'is vendor for')", "title": "Label", "type": "string" } }, "required": [ "id", "label", "created_at" ], "title": "RelationshipTypeRecord", "type": "object" }, "RelationshipTypesResponse": { "description": "Merged dropdown vocabulary (D3): builtin + custom + observed.", "properties": { "builtin": { "description": "Built-in coarse relationship types", "items": { "type": "string" }, "title": "Builtin", "type": "array" }, "custom": { "description": "Tenant-created relationship types", "items": { "$ref": "#/components/schemas/RelationshipTypeRecord" }, "title": "Custom", "type": "array" }, "observed": { "description": "Distinct predicates observed on live links", "items": { "$ref": "#/components/schemas/ObservedPredicate" }, "title": "Observed", "type": "array" } }, "required": [ "builtin", "custom", "observed" ], "title": "RelationshipTypesResponse", "type": "object" }, "RelayMessageModel": { "properties": { "body": { "default": "", "title": "Body", "type": "string" }, "event_id": { "title": "Event Id", "type": "string" }, "hint": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Hint" }, "is_own": { "title": "Is Own", "type": "boolean" }, "kind": { "default": "text", "title": "Kind", "type": "string" }, "origin_server_ts": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Origin Server Ts" }, "sender": { "title": "Sender", "type": "string" }, "sender_display_name": { "title": "Sender Display Name", "type": "string" } }, "required": [ "event_id", "sender", "sender_display_name", "is_own" ], "title": "RelayMessageModel", "type": "object" }, "ReleaseLegalHoldResponse": { "properties": { "ok": { "default": true, "title": "Ok", "type": "boolean" }, "released_at": { "format": "date-time", "title": "Released At", "type": "string" } }, "required": [ "released_at" ], "title": "ReleaseLegalHoldResponse", "type": "object" }, "ReleaseRequest": { "properties": { "agent_member_id": { "description": "agent_members.id whose claim is released", "title": "Agent Member Id", "type": "string" }, "outcome": { "enum": [ "completed", "crashed", "handoff" ], "title": "Outcome", "type": "string" } }, "required": [ "agent_member_id", "outcome" ], "title": "ReleaseRequest", "type": "object" }, "ReleaseResponse": { "properties": { "activity": { "additionalProperties": true, "title": "Activity", "type": "object" }, "released": { "title": "Released", "type": "boolean" } }, "required": [ "released", "activity" ], "title": "ReleaseResponse", "type": "object" }, "RemindResult": { "properties": { "reminded": { "title": "Reminded", "type": "boolean" }, "status": { "title": "Status", "type": "string" } }, "required": [ "status", "reminded" ], "title": "RemindResult", "type": "object" }, "ReminderCreate": { "description": "Input schema for POST /api/v1/reminders (new reminder creation).\n\nValidation Rules:\n - title: Required, 1-500 characters\n - description: Optional, max 2000 characters\n - reminder_date: Required, must be ISO 8601 datetime\n - delivery_methods: Optional, defaults to 'push'\n - metadata: Optional, JSON object for delivery config\n - source_type: Optional, defaults to 'manual'\n - source_id: Optional, UUID reference to source\n\nExample:\n {\n \"title\": \"Soccer practice at Lincoln Park\",\n \"description\": \"Don't forget to bring water bottle\",\n \"reminder_date\": \"2025-11-20T09:00:00Z\",\n \"delivery_methods\": \"push,email\",\n \"metadata\": {\n \"email\": \"parent@example.com\"\n }\n }\n\nRelated: Reminder CRUD Operations Feature", "examples": [ { "delivery_methods": "push,email", "description": "Don't forget to bring water bottle", "metadata": { "email": "parent@example.com" }, "reminder_date": "2025-11-20T09:00:00Z", "title": "Soccer practice at Lincoln Park" } ], "properties": { "delivery_methods": { "default": "push", "description": "Comma-separated delivery methods: email, sms, push, calendar", "examples": [ "push", "email,sms", "push,calendar" ], "title": "Delivery Methods", "type": "string" }, "description": { "anyOf": [ { "maxLength": 2000, "type": "string" }, { "type": "null" } ], "description": "Optional detailed description (max 2000 characters)", "examples": [ "Don't forget to bring water bottle and shin guards" ], "title": "Description" }, "instruction": { "anyOf": [ { "maxLength": 10000, "type": "string" }, { "type": "null" } ], "description": "Agentic instruction executed at fire time (required when tier=agentic)", "examples": [ "Check my calendar for tomorrow and text me a summary" ], "title": "Instruction" }, "is_recurring": { "default": false, "description": "Whether this reminder repeats", "title": "Is Recurring", "type": "boolean" }, "metadata": { "additionalProperties": true, "description": "Flexible JSON config for delivery (phone numbers, email, device tokens, calendar IDs)", "examples": [ { "email": "parent@example.com", "phone": "+1234567890" } ], "title": "Metadata", "type": "object" }, "recurrence_day_of_month": { "anyOf": [ { "maximum": 31.0, "minimum": 1.0, "type": "integer" }, { "type": "null" } ], "description": "Day of month for monthly recurrence (1-31)", "title": "Recurrence Day Of Month" }, "recurrence_days_of_week": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "description": "Days of week for weekly recurrence: ['mon', 'wed', 'fri']", "title": "Recurrence Days Of Week" }, "recurrence_end_date": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "When recurrence should stop (null = indefinite)", "title": "Recurrence End Date" }, "recurrence_interval": { "anyOf": [ { "minimum": 1.0, "type": "integer" }, { "type": "null" } ], "default": 1, "description": "Interval for recurrence (e.g., every 2 weeks)", "title": "Recurrence Interval" }, "recurrence_pattern": { "anyOf": [ { "pattern": "^(daily|weekly|monthly|yearly|custom)$", "type": "string" }, { "type": "null" } ], "description": "Recurrence pattern: daily, weekly, monthly, yearly, custom", "title": "Recurrence Pattern" }, "reminder_date": { "description": "When the reminder should be delivered (ISO 8601)", "examples": [ "2025-11-20T09:00:00Z" ], "format": "date-time", "title": "Reminder Date", "type": "string" }, "source_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional reference to source email/document (UUID)", "examples": [ "email-uuid-xyz789" ], "title": "Source Id" }, "source_type": { "default": "manual", "description": "How reminder was created (manual|extracted_email|extracted_document)", "examples": [ "manual", "extracted_email" ], "pattern": "^(manual|extracted_email|extracted_document)$", "title": "Source Type", "type": "string" }, "tier": { "default": "static", "description": "Execution tier: static | agentic (agentic requires a non-empty instruction)", "examples": [ "static", "agentic" ], "pattern": "^(static|agentic)$", "title": "Tier", "type": "string" }, "title": { "description": "Reminder title (required, 1-500 characters)", "examples": [ "Soccer practice at Lincoln Park" ], "maxLength": 500, "minLength": 1, "title": "Title", "type": "string" }, "urgent": { "default": false, "description": "Override quiet hours — deliver immediately even inside the user's quiet window", "title": "Urgent", "type": "boolean" } }, "required": [ "title", "reminder_date" ], "title": "ReminderCreate", "type": "object" }, "ReminderId": { "description": "Typed primitive ID for reminders (prefix 'Y').", "examples": [ "Y-550e8400-e29b-41d4-a716-446655440000" ], "pattern": "^Y-[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "title": "ReminderId", "type": "string", "x-tidy-typed-id-prefix": "Y", "x-tidy-typed-id-table": "reminders" }, "ReminderParseAlternative": { "description": "A candidate datetime interpretation for reminder creation.", "properties": { "grain": { "title": "Grain", "type": "string" }, "id": { "title": "Id", "type": "string" }, "preview": { "title": "Preview", "type": "string" }, "resolved_datetime": { "title": "Resolved Datetime", "type": "string" }, "source": { "title": "Source", "type": "string" } }, "required": [ "id", "resolved_datetime", "preview", "grain", "source" ], "title": "ReminderParseAlternative", "type": "object" }, "ReminderParseRequest": { "description": "Payload for reminder NLP parsing.", "properties": { "reference_time": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Reference Time" }, "text": { "maxLength": 280, "minLength": 1, "title": "Text", "type": "string" }, "timezone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Timezone" } }, "required": [ "text" ], "title": "ReminderParseRequest", "type": "object" }, "ReminderParseResponse": { "description": "Response for reminder NLP parse requests.", "properties": { "alternatives": { "items": { "$ref": "#/components/schemas/ReminderParseAlternative" }, "title": "Alternatives", "type": "array" }, "ambiguous": { "default": false, "title": "Ambiguous", "type": "boolean" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error" }, "grain": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Grain" }, "preview": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Preview" }, "resolved_datetime": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Resolved Datetime" }, "success": { "title": "Success", "type": "boolean" }, "text": { "title": "Text", "type": "string" }, "timezone": { "title": "Timezone", "type": "string" } }, "required": [ "success", "text", "timezone" ], "title": "ReminderParseResponse", "type": "object" }, "ReminderResponse": { "description": "Complete reminder object returned by API endpoints.\n\nUsed in:\n - GET /api/v1/reminders (list response items)\n - GET /api/v1/reminders/{id} (single reminder detail)\n - POST /api/v1/reminders (created reminder response, 201)\n - PATCH /api/v1/reminders/{id} (updated reminder response)\n\nAttributes:\n id: Unique UUID identifier (system-generated)\n account_id: User who owns this reminder (UUID)\n title: Reminder title (required, 1-500 characters)\n description: Optional detailed description\n reminder_date: When the reminder should be delivered (ISO 8601)\n delivery_methods: Comma-separated delivery methods (email, sms, push, calendar)\n status: Reminder lifecycle state (pending|sent|cancelled|failed)\n metadata: Flexible JSON for delivery config (phone, email, device tokens, etc.)\n source_type: How reminder was created (manual|extracted_email|extracted_document)\n source_id: Optional reference to source email/document (UUID)\n created_at: ISO 8601 timestamp of reminder creation\n updated_at: ISO 8601 timestamp of last modification\n sent_at: ISO 8601 timestamp of delivery (null if not sent)\n\nExample (Full Detail):\n {\n \"id\": \"a1b2c3d4-e5f6-4789-abcd-ef1234567890\",\n \"account_id\": \"11111111-1111-1111-1111-111111111111\",\n \"title\": \"Soccer practice at Lincoln Park\",\n \"description\": \"Don't forget to bring water bottle and shin guards\",\n \"reminder_date\": \"2025-11-20T09:00:00Z\",\n \"delivery_methods\": \"push,email\",\n \"status\": \"pending\",\n \"metadata\": {\n \"email\": \"parent@example.com\",\n \"push_tokens\": [\"device_token_abc123\"]\n },\n \"source_type\": \"extracted_email\",\n \"source_id\": \"email-uuid-xyz789\",\n \"created_at\": \"2025-11-19T14:30:22.123Z\",\n \"updated_at\": \"2025-11-19T14:30:22.123Z\",\n \"sent_at\": null\n }\n\nRelated: Reminder CRUD Operations Feature", "examples": [ { "account_id": "11111111-1111-1111-1111-111111111111", "created_at": "2025-11-19T14:30:22.123Z", "delivery_methods": "push,email", "description": "Don't forget to bring water bottle and shin guards", "id": "a1b2c3d4-e5f6-4789-abcd-ef1234567890", "metadata": { "email": "parent@example.com", "push_tokens": [ "device_token_abc123" ] }, "reminder_date": "2025-11-20T09:00:00Z", "sent_at": null, "source_id": "email-uuid-xyz789", "source_type": "extracted_email", "status": "pending", "title": "Soccer practice at Lincoln Park", "updated_at": "2025-11-19T14:30:22.123Z" } ], "properties": { "account_id": { "description": "Account ID that owns this reminder (UUID v4)", "examples": [ "11111111-1111-1111-1111-111111111111" ], "title": "Account Id", "type": "string" }, "created_at": { "description": "ISO 8601 timestamp of reminder creation", "examples": [ "2025-11-19T14:30:22.123Z" ], "format": "date-time", "title": "Created At", "type": "string" }, "delivery_methods": { "default": "push", "description": "Comma-separated delivery methods: email, sms, push, calendar", "examples": [ "push", "email,sms", "push,calendar" ], "title": "Delivery Methods", "type": "string" }, "description": { "anyOf": [ { "maxLength": 2000, "type": "string" }, { "type": "null" } ], "default": null, "description": "Optional detailed description", "examples": [ "Don't forget to bring water bottle and shin guards" ], "title": "Description" }, "id": { "description": "Unique reminder identifier (UUID v4 format)", "examples": [ "a1b2c3d4-e5f6-4789-abcd-ef1234567890" ], "title": "Id", "type": "string" }, "instruction": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Agentic instruction executed by the assistant at fire time (tier=agentic only)", "examples": [ "Check my calendar for tomorrow and text me a summary" ], "title": "Instruction" }, "is_recurring": { "default": false, "description": "Whether this reminder repeats", "title": "Is Recurring", "type": "boolean" }, "metadata": { "additionalProperties": true, "description": "Flexible JSON config for delivery (phone numbers, email, device tokens, calendar IDs)", "examples": [ { "email": "parent@example.com", "phone": "+1234567890", "push_tokens": [ "token1" ] } ], "title": "Metadata", "type": "object" }, "parent_reminder_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Links generated instances to original recurring reminder (UUID)", "title": "Parent Reminder Id" }, "recurrence_day_of_month": { "anyOf": [ { "maximum": 31, "minimum": 1, "type": "integer" }, { "type": "null" } ], "default": null, "description": "Day of month for monthly recurrence (1-31)", "title": "Recurrence Day Of Month" }, "recurrence_days_of_week": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "default": null, "description": "Days of week for weekly recurrence: ['mon', 'wed', 'fri']", "title": "Recurrence Days Of Week" }, "recurrence_end_date": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "description": "When recurrence should stop (null = indefinite)", "title": "Recurrence End Date" }, "recurrence_interval": { "anyOf": [ { "minimum": 1, "type": "integer" }, { "type": "null" } ], "default": 1, "description": "Interval for recurrence (e.g., every 2 weeks)", "title": "Recurrence Interval" }, "recurrence_pattern": { "anyOf": [ { "pattern": "^(daily|weekly|monthly|yearly|custom)$", "type": "string" }, { "type": "null" } ], "default": null, "description": "Recurrence pattern: daily, weekly, monthly, yearly, custom", "title": "Recurrence Pattern" }, "reminder_date": { "description": "When the reminder should be delivered (ISO 8601)", "examples": [ "2025-11-20T09:00:00Z" ], "format": "date-time", "title": "Reminder Date", "type": "string" }, "sent_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "description": "ISO 8601 timestamp of delivery (null if not sent)", "examples": [ "2025-11-20T09:00:00Z", null ], "title": "Sent At" }, "source_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Optional reference to source email/document (UUID)", "examples": [ "email-uuid-xyz789" ], "title": "Source Id" }, "source_type": { "default": "manual", "description": "How reminder was created (manual|extracted_email|extracted_document)", "examples": [ "manual", "extracted_email" ], "pattern": "^(manual|extracted_email|extracted_document)$", "title": "Source Type", "type": "string" }, "status": { "default": "pending", "description": "Reminder lifecycle state (pending|running|sent|cancelled|failed)", "examples": [ "pending", "running", "sent" ], "pattern": "^(pending|running|sent|cancelled|failed)$", "title": "Status", "type": "string" }, "tier": { "default": "static", "description": "Execution tier: static (deliver stored payload) | agentic (wake the assistant at fire time)", "examples": [ "static", "agentic" ], "pattern": "^(static|agentic)$", "title": "Tier", "type": "string" }, "title": { "description": "Reminder title (required, 1-500 characters)", "examples": [ "Soccer practice at Lincoln Park", "Parent-teacher conference" ], "maxLength": 500, "minLength": 1, "title": "Title", "type": "string" }, "updated_at": { "description": "ISO 8601 timestamp of last modification", "examples": [ "2025-11-19T14:30:22.123Z" ], "format": "date-time", "title": "Updated At", "type": "string" }, "urgent": { "default": false, "description": "Override quiet hours — deliver immediately even inside the user's quiet window", "title": "Urgent", "type": "boolean" } }, "required": [ "id", "account_id", "title", "reminder_date", "created_at", "updated_at" ], "title": "ReminderResponse", "type": "object" }, "ReminderTemplateCreate": { "description": "Request model for creating a new reminder template", "properties": { "default_delivery_methods": { "default": "push", "description": "Default delivery methods (comma-separated)", "title": "Default Delivery Methods", "type": "string" }, "default_description": { "anyOf": [ { "maxLength": 2000, "type": "string" }, { "type": "null" } ], "description": "Default reminder description", "title": "Default Description" }, "default_metadata": { "additionalProperties": true, "description": "Default metadata (email, phone, etc.)", "title": "Default Metadata", "type": "object" }, "description": { "anyOf": [ { "maxLength": 500, "type": "string" }, { "type": "null" } ], "description": "Template description", "title": "Description" }, "name": { "description": "Template name", "maxLength": 200, "title": "Name", "type": "string" }, "title": { "description": "Default reminder title", "maxLength": 500, "title": "Title", "type": "string" } }, "required": [ "name", "title" ], "title": "ReminderTemplateCreate", "type": "object" }, "ReminderTemplateResponse": { "description": "Response model for reminder template", "properties": { "account_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "default": null, "description": "Account ID (null for system templates)", "title": "Account Id" }, "created_at": { "description": "Template creation timestamp", "format": "date-time", "title": "Created At", "type": "string" }, "default_delivery_methods": { "default": "push", "description": "Default delivery methods (comma-separated)", "title": "Default Delivery Methods", "type": "string" }, "default_description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Default reminder description", "title": "Default Description" }, "default_metadata": { "additionalProperties": true, "description": "Default metadata (email, phone, etc.)", "title": "Default Metadata", "type": "object" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Template description", "title": "Description" }, "id": { "description": "Unique template ID", "format": "uuid", "title": "Id", "type": "string" }, "is_system": { "default": false, "description": "Whether this is a system template", "title": "Is System", "type": "boolean" }, "name": { "description": "Template name", "title": "Name", "type": "string" }, "title": { "description": "Default reminder title", "title": "Title", "type": "string" }, "updated_at": { "description": "Template last update timestamp", "format": "date-time", "title": "Updated At", "type": "string" } }, "required": [ "id", "name", "title", "created_at", "updated_at" ], "title": "ReminderTemplateResponse", "type": "object" }, "ReminderTemplateUpdate": { "description": "Request model for updating an existing reminder template", "properties": { "default_delivery_methods": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Default delivery methods (comma-separated)", "title": "Default Delivery Methods" }, "default_description": { "anyOf": [ { "maxLength": 2000, "type": "string" }, { "type": "null" } ], "description": "Default reminder description", "title": "Default Description" }, "default_metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "Default metadata (email, phone, etc.)", "title": "Default Metadata" }, "description": { "anyOf": [ { "maxLength": 500, "type": "string" }, { "type": "null" } ], "description": "Template description", "title": "Description" }, "name": { "anyOf": [ { "maxLength": 200, "type": "string" }, { "type": "null" } ], "description": "Template name", "title": "Name" }, "title": { "anyOf": [ { "maxLength": 500, "type": "string" }, { "type": "null" } ], "description": "Default reminder title", "title": "Title" } }, "title": "ReminderTemplateUpdate", "type": "object" }, "ReminderUpdate": { "description": "Input schema for PATCH /api/v1/reminders/{id} (partial updates).\n\nAll fields optional (partial update pattern).\nOnly provided fields will be updated.\n\nValidation Rules:\n - title: If provided, 1-500 characters\n - description: If provided, max 2000 characters\n - reminder_date: If provided, must be ISO 8601 datetime\n - delivery_methods: If provided, comma-separated list\n - status: If provided, must be valid status\n - metadata: If provided, JSON object (replaces existing)\n\nExample (Update status and delivery time):\n {\n \"reminder_date\": \"2025-11-21T10:00:00Z\",\n \"status\": \"pending\"\n }\n\nExample (Cancel reminder):\n {\n \"status\": \"cancelled\"\n }\n\nRelated: Reminder CRUD Operations Feature", "examples": [ { "reminder_date": "2025-11-21T10:00:00Z", "status": "pending" }, { "status": "cancelled" } ], "properties": { "delivery_methods": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Comma-separated delivery methods: email, sms, push, calendar", "examples": [ "push,email" ], "title": "Delivery Methods" }, "description": { "anyOf": [ { "maxLength": 2000, "type": "string" }, { "type": "null" } ], "description": "Optional detailed description (max 2000 characters)", "examples": [ "Don't forget to bring water bottle" ], "title": "Description" }, "instruction": { "anyOf": [ { "maxLength": 10000, "type": "string" }, { "type": "null" } ], "description": "Agentic instruction executed at fire time (required when tier=agentic)", "title": "Instruction" }, "is_recurring": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Whether this reminder repeats", "title": "Is Recurring" }, "metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "Flexible JSON config for delivery (replaces existing metadata)", "examples": [ { "email": "newemail@example.com" } ], "title": "Metadata" }, "recurrence_day_of_month": { "anyOf": [ { "maximum": 31.0, "minimum": 1.0, "type": "integer" }, { "type": "null" } ], "description": "Day of month for monthly recurrence (1-31)", "title": "Recurrence Day Of Month" }, "recurrence_days_of_week": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "description": "Days of week for weekly recurrence: ['mon', 'wed', 'fri']", "title": "Recurrence Days Of Week" }, "recurrence_end_date": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "When recurrence should stop (null = indefinite)", "title": "Recurrence End Date" }, "recurrence_interval": { "anyOf": [ { "minimum": 1.0, "type": "integer" }, { "type": "null" } ], "description": "Interval for recurrence (e.g., every 2 weeks)", "title": "Recurrence Interval" }, "recurrence_pattern": { "anyOf": [ { "pattern": "^(daily|weekly|monthly|yearly|custom)$", "type": "string" }, { "type": "null" } ], "description": "Recurrence pattern: daily, weekly, monthly, yearly, custom", "title": "Recurrence Pattern" }, "reminder_date": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "When the reminder should be delivered (ISO 8601)", "examples": [ "2025-11-20T09:00:00Z" ], "title": "Reminder Date" }, "status": { "anyOf": [ { "pattern": "^(pending|running|sent|cancelled|failed)$", "type": "string" }, { "type": "null" } ], "description": "Reminder lifecycle state (pending|running|sent|cancelled|failed)", "examples": [ "pending", "cancelled" ], "title": "Status" }, "tier": { "anyOf": [ { "pattern": "^(static|agentic)$", "type": "string" }, { "type": "null" } ], "description": "Execution tier: static | agentic", "examples": [ "static", "agentic" ], "title": "Tier" }, "title": { "anyOf": [ { "maxLength": 500, "minLength": 1, "type": "string" }, { "type": "null" } ], "description": "Reminder title (1-500 characters)", "examples": [ "Soccer practice at Lincoln Park" ], "title": "Title" }, "urgent": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Override quiet hours — deliver immediately even inside the user's quiet window", "title": "Urgent" } }, "title": "ReminderUpdate", "type": "object" }, "RemoveBlockOp": { "additionalProperties": false, "description": "Remove ONE top-level block holding only an embed of, or a wiki link\nto, ``typed_id`` — the block no span can match (TIDY-19537).", "properties": { "index": { "anyOf": [ { "minimum": 0.0, "type": "integer" }, { "type": "null" } ], "title": "Index" }, "op": { "const": "remove_block", "title": "Op", "type": "string" }, "typed_id": { "maxLength": 64, "minLength": 3, "title": "Typed Id", "type": "string" } }, "required": [ "op", "typed_id" ], "title": "RemoveBlockOp", "type": "object" }, "RemoveSeatResponse": { "properties": { "removed_user_id": { "title": "Removed User Id", "type": "string" }, "seats_remaining": { "title": "Seats Remaining", "type": "integer" } }, "required": [ "removed_user_id", "seats_remaining" ], "title": "RemoveSeatResponse", "type": "object" }, "RemoveSlideOp": { "additionalProperties": false, "properties": { "op": { "const": "remove_slide", "title": "Op", "type": "string" }, "slide": { "maximum": 500.0, "minimum": 1.0, "title": "Slide", "type": "integer" } }, "required": [ "op", "slide" ], "title": "RemoveSlideOp", "type": "object" }, "RenameGroupRequest": { "description": "Request to rename a group.", "properties": { "custom_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Custom Name" } }, "title": "RenameGroupRequest", "type": "object" }, "RenameGroupResponse": { "description": "Response after renaming a group.", "properties": { "custom_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Custom Name" }, "group_id": { "title": "Group Id", "type": "string" } }, "required": [ "group_id", "custom_name" ], "title": "RenameGroupResponse", "type": "object" }, "RenameSpeakersRequest": { "properties": { "updates": { "items": { "$ref": "#/components/schemas/SpeakerUpdate" }, "minItems": 1, "title": "Updates", "type": "array" } }, "required": [ "updates" ], "title": "RenameSpeakersRequest", "type": "object" }, "RenameSpeakersResponse": { "properties": { "id": { "title": "Id", "type": "string" }, "speaker_map": { "additionalProperties": true, "title": "Speaker Map", "type": "object" }, "summary_note_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Summary Note Id" } }, "required": [ "id", "speaker_map" ], "title": "RenameSpeakersResponse", "type": "object" }, "RenameTabRequest": { "properties": { "title": { "maxLength": 200, "minLength": 1, "title": "Title", "type": "string" } }, "required": [ "title" ], "title": "RenameTabRequest", "type": "object" }, "RenderPresentationRequest": { "description": "Body for `POST /api/v1/presentations/{note_id}/render`.", "properties": { "node": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional node id → a cropped element PNG of that node (S9 flattening input) instead of full slides.", "title": "Node" }, "persist": { "default": true, "description": "When true (default) the manifest cache row is upserted. When false (agent-loop ephemeral renders) signed URLs are returned without touching the cache.", "title": "Persist", "type": "boolean" }, "slides": { "anyOf": [ { "items": { "type": "integer" }, "type": "array" }, { "type": "null" } ], "description": "Slide indices to render. Omit / empty → render every slide in the deck (the renderer discovers the count).", "title": "Slides" } }, "title": "RenderPresentationRequest", "type": "object" }, "RenderRecipientRequest": { "properties": { "campaign_id": { "title": "Campaign Id", "type": "string" }, "recipient_id": { "title": "Recipient Id", "type": "string" }, "tenant_id": { "title": "Tenant Id", "type": "string" } }, "required": [ "tenant_id", "campaign_id", "recipient_id" ], "title": "RenderRecipientRequest", "type": "object" }, "RenewInvitesRequest": { "properties": { "amount": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Amount" } }, "title": "RenewInvitesRequest", "type": "object" }, "RenewRequest": { "properties": { "days": { "default": 30, "maximum": 365.0, "minimum": 1.0, "title": "Days", "type": "integer" } }, "title": "RenewRequest", "type": "object" }, "RenewedConsentRequest": { "properties": { "rationale": { "title": "Rationale", "type": "string" } }, "required": [ "rationale" ], "title": "RenewedConsentRequest", "type": "object" }, "RenewedConsentResponse": { "properties": { "definition_id": { "format": "uuid", "title": "Definition Id", "type": "string" }, "renewed_consent_rationale": { "title": "Renewed Consent Rationale", "type": "string" }, "renewed_consent_requested": { "title": "Renewed Consent Requested", "type": "boolean" } }, "required": [ "definition_id", "renewed_consent_requested", "renewed_consent_rationale" ], "title": "RenewedConsentResponse", "type": "object" }, "ReorderFocusQueueRequest": { "properties": { "email_ids": { "items": { "type": "string" }, "maxItems": 250, "title": "Email Ids", "type": "array" } }, "title": "ReorderFocusQueueRequest", "type": "object" }, "ReorderFocusQueueResponse": { "properties": { "count": { "default": 0, "title": "Count", "type": "integer" } }, "title": "ReorderFocusQueueResponse", "type": "object" }, "ReorderItemsRequest": { "description": "The FULL ordered id list — not a move instruction.\n\nSending the whole order lets the server apply it in one statement instead of\none UPDATE per row, which on a 200-item bundle is the difference between 1\nand 200 PowerSync oplog ops per drag.", "properties": { "item_ids": { "items": { "format": "uuid", "type": "string" }, "minItems": 1, "title": "Item Ids", "type": "array" } }, "required": [ "item_ids" ], "title": "ReorderItemsRequest", "type": "object" }, "ReorderPinItem": { "properties": { "event_id": { "title": "Event Id", "type": "string" }, "sort_order": { "title": "Sort Order", "type": "integer" } }, "required": [ "event_id", "sort_order" ], "title": "ReorderPinItem", "type": "object" }, "ReorderPinsRequest": { "properties": { "pins": { "items": { "$ref": "#/components/schemas/ReorderPinItem" }, "maxItems": 100, "title": "Pins", "type": "array" } }, "title": "ReorderPinsRequest", "type": "object" }, "ReorderSlideOp": { "additionalProperties": false, "description": "Move a slide to sit after slide number ``after`` (0 = to the front).\n\nSame positional vocabulary as ``insert_slide`` on purpose: \"after slide 3\"\nmeans one thing across the whole family rather than two.", "properties": { "after": { "maximum": 500.0, "minimum": 0.0, "title": "After", "type": "integer" }, "op": { "const": "reorder_slide", "title": "Op", "type": "string" }, "slide": { "maximum": 500.0, "minimum": 1.0, "title": "Slide", "type": "integer" } }, "required": [ "op", "slide", "after" ], "title": "ReorderSlideOp", "type": "object" }, "ReorderTabsRequest": { "properties": { "ordered_ids": { "description": "Tab ids in the new order", "items": { "type": "string" }, "title": "Ordered Ids", "type": "array" } }, "required": [ "ordered_ids" ], "title": "ReorderTabsRequest", "type": "object" }, "ReorderWorkstationsRequest": { "description": "Ordered workstation ids — positions are assigned 1..N in list order.", "properties": { "ids": { "items": { "type": "string" }, "maxItems": 200, "minItems": 1, "title": "Ids", "type": "array" } }, "required": [ "ids" ], "title": "ReorderWorkstationsRequest", "type": "object" }, "RepairDanglingSourceRefsRequest": { "description": "Request body for legacy ``email_source_id`` repair.", "properties": { "apply": { "default": false, "description": "Dry-run by default. Set true to apply the relink.", "title": "Apply", "type": "boolean" }, "legacy_source_id": { "description": "Dangling email_source_id currently stamped on email_canonical rows.", "format": "uuid", "title": "Legacy Source Id", "type": "string" }, "target_source_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "description": "Optional active email_source_configs.id. If omitted, the endpoint must prove exactly one active target from preserved metadata.", "title": "Target Source Id" }, "tenant_id": { "description": "Tenant that owns the rows.", "format": "uuid", "title": "Tenant Id", "type": "string" } }, "required": [ "tenant_id", "legacy_source_id" ], "title": "RepairDanglingSourceRefsRequest", "type": "object" }, "RepairDanglingSourceRefsResponse": { "description": "Response payload for source-reference repair dry-runs and writes.", "properties": { "legacy_source_id": { "title": "Legacy Source Id", "type": "string" }, "matched_count": { "title": "Matched Count", "type": "integer" }, "proof": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Proof" }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Reason" }, "row_count": { "title": "Row Count", "type": "integer" }, "status": { "title": "Status", "type": "string" }, "target_source_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Target Source Id" }, "tenant_id": { "title": "Tenant Id", "type": "string" }, "updated_count": { "title": "Updated Count", "type": "integer" } }, "required": [ "status", "tenant_id", "legacy_source_id", "target_source_id", "row_count", "matched_count", "updated_count", "proof", "reason" ], "title": "RepairDanglingSourceRefsResponse", "type": "object" }, "RepairResponse": { "properties": { "definition_id": { "format": "uuid", "title": "Definition Id", "type": "string" }, "fire_at": { "format": "date-time", "title": "Fire At", "type": "string" }, "scheduled_action_id": { "format": "uuid", "title": "Scheduled Action Id", "type": "string" }, "version_id": { "format": "uuid", "title": "Version Id", "type": "string" } }, "required": [ "definition_id", "version_id", "scheduled_action_id", "fire_at" ], "title": "RepairResponse", "type": "object" }, "RepairStripeLinkResponse": { "properties": { "cleared_customer_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Cleared Customer Id" }, "cleared_subscription_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Cleared Subscription Id" }, "subscription_status": { "title": "Subscription Status", "type": "string" }, "tenant_id": { "title": "Tenant Id", "type": "string" } }, "required": [ "tenant_id", "subscription_status" ], "title": "RepairStripeLinkResponse", "type": "object" }, "ReplaceBlocksOp": { "additionalProperties": false, "description": "Replace a run of whole lines, from the one holding ``start`` through\nthe one holding ``end``, with markdown.\n\nThe region edit for a body with no heading to scope it — a pasted text\ntable becomes a real table in place. Every block outside the run keeps\nits identity, as with ``replace_section``. Inside one list the run is\njust those items, and a run that would remove a line the caller did not\nname (part of a table, a quote or a nested list) is refused (TIDY-20179).", "properties": { "end": { "anyOf": [ { "maxLength": 2000, "minLength": 1, "type": "string" }, { "type": "null" } ], "description": "Text inside the LAST line to replace, unique from start's line on. Omit to replace start's line alone.", "title": "End" }, "markdown": { "description": "What replaces the run: a GFM pipe table becomes a table, `- [ ]` a checklist, `![[X-]]` a live embed.", "maxLength": 100000, "minLength": 1, "title": "Markdown", "type": "string" }, "op": { "const": "replace_blocks", "title": "Op", "type": "string" }, "start": { "description": "Text inside the FIRST line to replace, unique in the body. Inside one list the run is just those items; a run that would cut off other lines of a table, list or quote is refused.", "maxLength": 2000, "minLength": 1, "title": "Start", "type": "string" } }, "required": [ "op", "start", "markdown" ], "title": "ReplaceBlocksOp", "type": "object" }, "ReplaceSectionOp": { "additionalProperties": false, "description": "Replace the body of ONE heading's section with markdown (TIDY-19511).\n\nThe bounded mid-body edit a whole-body PUT used to stand in for: the\nheading stays, the blocks under it (down to the next heading of the same\nor a higher level) are replaced, and every block outside the section keeps\nits identity — embeds and wiki links elsewhere are never rebuilt.", "properties": { "heading": { "description": "The heading's own text, matched trimmed and case-insensitively; it must title exactly one heading. Sub-headings under it belong to the section and are replaced with it.", "maxLength": 2000, "minLength": 1, "title": "Heading", "type": "string" }, "markdown": { "description": "The section's new body, without the heading line. `![[X-]]` becomes a live embed and `[[X-]]` a wiki link.", "maxLength": 100000, "minLength": 1, "title": "Markdown", "type": "string" }, "op": { "const": "replace_section", "title": "Op", "type": "string" } }, "required": [ "op", "heading", "markdown" ], "title": "ReplaceSectionOp", "type": "object" }, "ReplaceSpanOp": { "additionalProperties": false, "properties": { "new": { "maxLength": 10000, "minLength": 1, "title": "New", "type": "string" }, "old": { "maxLength": 10000, "minLength": 1, "title": "Old", "type": "string" }, "op": { "const": "replace_span", "title": "Op", "type": "string" } }, "required": [ "op", "old", "new" ], "title": "ReplaceSpanOp", "type": "object" }, "ReplayArtifactAttachment": { "description": "A processed attachment an email carried. ``storage_path`` is the object\npointer the app opens/downloads (served via the attachments storage route).", "properties": { "content_type": { "title": "Content Type", "type": "string" }, "filename": { "title": "Filename", "type": "string" }, "id": { "title": "Id", "type": "string" }, "storage_path": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Storage Path" } }, "required": [ "id", "filename", "content_type" ], "title": "ReplayArtifactAttachment", "type": "object" }, "ReplayArtifactCalendarEvent": { "properties": { "id": { "title": "Id", "type": "string" }, "start_time": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Start Time" }, "summary": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Summary" } }, "required": [ "id" ], "title": "ReplayArtifactCalendarEvent", "type": "object" }, "ReplayArtifactContact": { "properties": { "approval_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Approval Status" }, "display_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Display Name" }, "id": { "title": "Id", "type": "string" } }, "required": [ "id" ], "title": "ReplayArtifactContact", "type": "object" }, "ReplayArtifactDocument": { "description": "One itemized harvest reference (docling document OR crawled url) an email\ndeposited. ``source_type`` discriminates the two. ``success`` is the harvest\noutcome (False = the docling/crawl attempt failed, per its metadata). The\ncanonical markdown is NOT inlined — fetch it from the content sub-endpoint.", "properties": { "content_char_count": { "default": 0, "title": "Content Char Count", "type": "integer" }, "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "domain": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Domain" }, "filename": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Filename" }, "id": { "title": "Id", "type": "string" }, "source_type": { "title": "Source Type", "type": "string" }, "success": { "default": true, "title": "Success", "type": "boolean" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Title" }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Url" } }, "required": [ "id", "source_type", "created_at" ], "title": "ReplayArtifactDocument", "type": "object" }, "ReplayArtifactOrganization": { "properties": { "approval_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Approval Status" }, "id": { "title": "Id", "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Name" } }, "required": [ "id" ], "title": "ReplayArtifactOrganization", "type": "object" }, "ReplayArtifactReminder": { "properties": { "approval_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Approval Status" }, "id": { "title": "Id", "type": "string" }, "reminder_date": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Reminder Date" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Title" } }, "required": [ "id" ], "title": "ReplayArtifactReminder", "type": "object" }, "ReplayArtifacts": { "description": "Per-journey harvest artifacts — what this email deposited into the graph.\n\nEvery counter is per-email-attributable via a real column (see\n``_artifact_summary``). Deliberately EXCLUDED because no per-email\nattribution path exists (TIDY-13208 — documented, not faked):\ninsight facets (writer populates neither email_id nor pipeline_run_id),\nentity summaries, and embedding chunks. ``orgs_pending`` is forward-only:\norganizations.source_email_id was added in migration\n20260707163126 with no backfill, so historical org rows report 0.", "properties": { "attachments": { "default": 0, "title": "Attachments", "type": "integer" }, "calendar_events": { "default": 0, "title": "Calendar Events", "type": "integer" }, "contacts_new": { "default": 0, "title": "Contacts New", "type": "integer" }, "contacts_pending": { "default": 0, "title": "Contacts Pending", "type": "integer" }, "docs_extracted": { "default": 0, "title": "Docs Extracted", "type": "integer" }, "docs_failed": { "default": 0, "title": "Docs Failed", "type": "integer" }, "facts_written": { "default": 0, "title": "Facts Written", "type": "integer" }, "links_created": { "default": 0, "title": "Links Created", "type": "integer" }, "orgs_pending": { "default": 0, "title": "Orgs Pending", "type": "integer" }, "urls_crawled": { "default": 0, "title": "Urls Crawled", "type": "integer" }, "urls_failed": { "default": 0, "title": "Urls Failed", "type": "integer" } }, "title": "ReplayArtifacts", "type": "object" }, "ReplayCompareResponse": { "properties": { "eligibility_deltas": { "items": { "additionalProperties": true, "type": "object" }, "title": "Eligibility Deltas", "type": "array" }, "output_diffs": { "items": { "additionalProperties": true, "type": "object" }, "title": "Output Diffs", "type": "array" }, "session_a": { "additionalProperties": true, "title": "Session A", "type": "object" }, "session_b": { "additionalProperties": true, "title": "Session B", "type": "object" }, "trigger_comparisons": { "items": { "additionalProperties": true, "type": "object" }, "title": "Trigger Comparisons", "type": "array" } }, "required": [ "session_a", "session_b", "trigger_comparisons", "eligibility_deltas", "output_diffs" ], "title": "ReplayCompareResponse", "type": "object" }, "ReplayDayCalendarEvent": { "description": "One openable DISTINCT calendar event the day's emails harvested — the\nitemized rows behind the \"N CALENDAR\" chip (TIDY-13501). ``event_status`` is\nthe calendar_events approval state (approved / pending) the click-through\nfilters on.", "properties": { "event_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Event Status" }, "id": { "title": "Id", "type": "string" }, "start_time": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Start Time" }, "summary": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Summary" } }, "required": [ "id" ], "title": "ReplayDayCalendarEvent", "type": "object" }, "ReplayDocumentContentResponse": { "description": "The canonical markdown for one harvest reference row (kept out of the\nitemized list to keep it light).", "properties": { "content_char_count": { "default": 0, "title": "Content Char Count", "type": "integer" }, "content_markdown": { "default": "", "title": "Content Markdown", "type": "string" }, "email_id": { "title": "Email Id", "type": "string" }, "id": { "title": "Id", "type": "string" }, "source_type": { "title": "Source Type", "type": "string" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Title" } }, "required": [ "id", "email_id", "source_type" ], "title": "ReplayDocumentContentResponse", "type": "object" }, "ReplayEvent": { "properties": { "action": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Action" }, "cost_class": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Cost Class" }, "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "detail": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Detail" }, "event_type": { "title": "Event Type", "type": "string" }, "execution_locus": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Execution Locus" }, "locus_device_kind": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Locus Device Kind" }, "locus_device_label": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Locus Device Label" }, "locus_eligible": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "title": "Locus Eligible" }, "rule_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Rule Id" }, "rule_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Rule Name" }, "seq": { "title": "Seq", "type": "integer" }, "stage": { "title": "Stage", "type": "string" }, "tower_class": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Tower Class" } }, "required": [ "seq", "stage", "event_type", "created_at" ], "title": "ReplayEvent", "type": "object" }, "ReplayFacetCreation": { "description": "One facet creation and WHERE it ran (TIDY-15774 / F12-S5, R10/D10).\n\nFacet creations ride the SAME ``defense_events`` substrate as email and file\njourneys (``subject_type='facet'``), so the locus fields on ``events`` are\nthe ones TIDY-14521 / TIDY-15747 already project and the shared stepper\nalready renders — no facet-specific badge, label or vocabulary.\n\n``facet_id`` is the primitive the creation produced, absent when the run\nproduced nothing (a refused confidence gate, an edge run that failed). Such\na row still reports honestly rather than disappearing.", "properties": { "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "events": { "default": [], "items": { "$ref": "#/components/schemas/ReplayEvent" }, "title": "Events", "type": "array" }, "execution_locus": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Execution Locus" }, "execution_runtime": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Execution Runtime" }, "facet_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Facet Id" }, "facet_kind": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Facet Kind" }, "locus_device_kind": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Locus Device Kind" }, "locus_device_label": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Locus Device Label" }, "locus_eligible": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "title": "Locus Eligible" }, "locus_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Locus Reason" } }, "required": [ "created_at" ], "title": "ReplayFacetCreation", "type": "object" }, "ReplayFileItem": { "description": "One item in the File System pen population (D3): a direct upload\n(``kind='upload'``, ``file_id`` set) OR an email attachment\n(``kind='email_attachment'``, ``email_id`` set). Until email attachments\nbecome ``files`` rows, the pen serves this explicit union so its count equals\nits click-through population (the round-10 count==click-through contract).", "properties": { "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "email_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Email Id" }, "file_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "File Id" }, "filename": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Filename" }, "id": { "title": "Id", "type": "string" }, "import_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Import Status" }, "kind": { "title": "Kind", "type": "string" }, "mime_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Mime Type" } }, "required": [ "id", "kind", "created_at" ], "title": "ReplayFileItem", "type": "object" }, "ReplayJourney": { "properties": { "arrived_at": { "format": "date-time", "title": "Arrived At", "type": "string" }, "artifacts": { "$ref": "#/components/schemas/ReplayArtifacts" }, "calendar_routed": { "default": false, "title": "Calendar Routed", "type": "boolean" }, "category": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Category" }, "disposition": { "default": null, "title": "Disposition" }, "email_id": { "title": "Email Id", "type": "string" }, "events": { "items": { "$ref": "#/components/schemas/ReplayEvent" }, "title": "Events", "type": "array" }, "inbox_split": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Inbox Split" }, "outcome": { "$ref": "#/components/schemas/ReplayOutcome" }, "reclassifications": { "default": [], "items": { "$ref": "#/components/schemas/ReplayReclassification" }, "title": "Reclassifications", "type": "array" }, "screening_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Screening Status" }, "sender": { "$ref": "#/components/schemas/ReplaySender" }, "subject": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Subject" } }, "required": [ "email_id", "arrived_at", "sender", "outcome", "artifacts", "events" ], "title": "ReplayJourney", "type": "object" }, "ReplayMemory": { "description": "A displayable memory row an email deposited into the graph — a\n``linked_references`` provenance edge resolved to its target's display\nname. ``text`` is the fact/display text when the edge carries one (usually\nnull for auto-extracted edges); ``target_name`` is the display driver.", "properties": { "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "email_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Email Id" }, "id": { "title": "Id", "type": "string" }, "link_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Link Type" }, "target_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Target Name" }, "target_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Target Type" }, "text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Text" } }, "required": [ "id", "created_at" ], "title": "ReplayMemory", "type": "object" }, "ReplayOutcome": { "properties": { "decided_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Decided At" }, "decided_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Decided Status" }, "final_action": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Final Action" }, "lane": { "title": "Lane", "type": "string" }, "screening_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Screening Id" }, "tower_class": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Tower Class" } }, "required": [ "lane" ], "title": "ReplayOutcome", "type": "object" }, "ReplayPayload": { "description": "A file/upload defense journey for the day — payloads ride the SAME\nsubstrate as email journeys (``defense_events.subject_type='file'``, written\nby S2). Payloads route Harvest → File System DIRECTLY; they NEVER ride the\nteleporter (D7), so this model carries NO ``reclassifications`` /\n``calendar_routed`` fields.", "properties": { "arrived_at": { "format": "date-time", "title": "Arrived At", "type": "string" }, "artifacts": { "$ref": "#/components/schemas/ReplayArtifacts" }, "events": { "items": { "$ref": "#/components/schemas/ReplayEvent" }, "title": "Events", "type": "array" }, "file_id": { "title": "File Id", "type": "string" }, "filename": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Filename" }, "import_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Import Status" }, "mime_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Mime Type" }, "outcome": { "$ref": "#/components/schemas/ReplayPayloadOutcome" }, "size_bytes": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Size Bytes" } }, "required": [ "file_id", "arrived_at", "outcome", "artifacts", "events" ], "title": "ReplayPayload", "type": "object" }, "ReplayPayloadOutcome": { "description": "A payload's terminal lane, derived from its post.completion action (S2/D8).\n\n``file_system`` — settled in the File System pen (``files.import_status='ready'``);\n``failed`` — the run died (docling zero-content / dispatch error), still a\nFiles-view row → still pen population, rendered as the failed beat;\n``in_flight`` — no ``post.completion`` event yet (still walking). Reporting a\nstill-processing payload as ``file_system`` would be a dishonest count (R7),\nso it stays ``in_flight`` until it terminally settles.", "properties": { "lane": { "title": "Lane", "type": "string" } }, "required": [ "lane" ], "title": "ReplayPayloadOutcome", "type": "object" }, "ReplayReclassification": { "description": "A user split-move against this email during the day (Teleporter),\nemitted as a ``defense.counter_action`` outbox event by the reclassify\nendpoint. ``to_split`` is the destination split the user chose.", "properties": { "at": { "format": "date-time", "title": "At", "type": "string" }, "to_split": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "To Split" } }, "required": [ "at" ], "title": "ReplayReclassification", "type": "object" }, "ReplaySender": { "properties": { "avatar_schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Avatar Schema" }, "contact_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Contact Id" }, "display_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Display Name" }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Email" }, "photo_source": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Photo Source" }, "photo_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Photo Url" } }, "title": "ReplaySender", "type": "object" }, "ReplaySentItem": { "description": "A message the member sent during the day — an exit-lane departure\n(TIDY-13353 / R5). Outbound mail has no gate decisions, harvest, or\ndistricts, so it is a lightweight parallel array, NOT a synthetic\n``ReplayJourney`` (D5). ``to_address`` / ``to_name`` are the first To\nrecipient for display; both may be null when the email has no recipients.", "properties": { "email_id": { "title": "Email Id", "type": "string" }, "sent_at": { "format": "date-time", "title": "Sent At", "type": "string" }, "subject": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Subject" }, "to_address": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "To Address" }, "to_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "To Name" } }, "required": [ "email_id", "sent_at" ], "title": "ReplaySentItem", "type": "object" }, "ReplaySessionCreateRequest": { "properties": { "definition_version_set": { "items": { "$ref": "#/components/schemas/VersionSetEntry" }, "title": "Definition Version Set", "type": "array" }, "event_cap": { "default": 10000, "title": "Event Cap", "type": "integer" }, "inference_budget_usd": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Inference Budget Usd" }, "inference_mode": { "default": "frozen", "title": "Inference Mode", "type": "string" }, "pack_version_overrides": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Pack Version Overrides" }, "principal_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Principal Id" }, "tenant_id": { "format": "uuid", "title": "Tenant Id", "type": "string" }, "window_end": { "format": "date-time", "title": "Window End", "type": "string" }, "window_start": { "format": "date-time", "title": "Window Start", "type": "string" } }, "required": [ "tenant_id", "window_start", "window_end", "definition_version_set" ], "title": "ReplaySessionCreateRequest", "type": "object" }, "ReplaySessionListResponse": { "properties": { "sessions": { "items": { "$ref": "#/components/schemas/ReplaySessionResponse" }, "title": "Sessions", "type": "array" } }, "required": [ "sessions" ], "title": "ReplaySessionListResponse", "type": "object" }, "ReplaySessionResponse": { "properties": { "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "definition_version_set": { "items": { "additionalProperties": true, "type": "object" }, "title": "Definition Version Set", "type": "array" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error" }, "event_cap": { "title": "Event Cap", "type": "integer" }, "finished_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Finished At" }, "id": { "format": "uuid", "title": "Id", "type": "string" }, "inference_budget_usd": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Inference Budget Usd" }, "inference_mode": { "title": "Inference Mode", "type": "string" }, "pack_version_overrides": { "additionalProperties": true, "title": "Pack Version Overrides", "type": "object" }, "principal_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Principal Id" }, "started_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Started At" }, "stats": { "additionalProperties": true, "title": "Stats", "type": "object" }, "status": { "title": "Status", "type": "string" }, "tenant_id": { "format": "uuid", "title": "Tenant Id", "type": "string" }, "window_end": { "format": "date-time", "title": "Window End", "type": "string" }, "window_start": { "format": "date-time", "title": "Window Start", "type": "string" } }, "required": [ "id", "tenant_id", "principal_id", "window_start", "window_end", "definition_version_set", "pack_version_overrides", "inference_mode", "inference_budget_usd", "event_cap", "status", "stats", "error", "created_at", "started_at", "finished_at" ], "title": "ReplaySessionResponse", "type": "object" }, "ReplayStats": { "properties": { "blocked": { "default": 0, "title": "Blocked", "type": "integer" }, "calendar_events_distinct": { "default": 0, "title": "Calendar Events Distinct", "type": "integer" }, "emails_total": { "default": 0, "title": "Emails Total", "type": "integer" }, "files_total": { "default": 0, "title": "Files Total", "type": "integer" }, "harvested": { "default": 0, "title": "Harvested", "type": "integer" }, "held": { "default": 0, "title": "Held", "type": "integer" }, "important": { "default": 0, "title": "Important", "type": "integer" }, "processed": { "default": 0, "title": "Processed", "type": "integer" } }, "title": "ReplayStats", "type": "object" }, "ReplayTower": { "properties": { "fired_count": { "title": "Fired Count", "type": "integer" }, "rule_count": { "title": "Rule Count", "type": "integer" }, "tower_class": { "title": "Tower Class", "type": "string" } }, "required": [ "tower_class", "rule_count", "fired_count" ], "title": "ReplayTower", "type": "object" }, "ReplyCardRequest": { "description": "Request body for replying to a card.", "properties": { "attachments": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "description": "Optional attachments with the reply", "title": "Attachments" }, "content": { "description": "The reply text content", "maxLength": 10000, "minLength": 1, "title": "Content", "type": "string" } }, "required": [ "content" ], "title": "ReplyCardRequest", "type": "object" }, "ReplyCardResponse": { "description": "Response for card reply.", "properties": { "cardId": { "description": "ID of the card", "title": "Cardid", "type": "string" }, "message": { "description": "Human-readable status message", "title": "Message", "type": "string" }, "sectionCount": { "description": "Total sections after reply", "title": "Sectioncount", "type": "integer" }, "status": { "description": "Processing status after reply", "title": "Status", "type": "string" } }, "required": [ "cardId", "sectionCount", "status", "message" ], "title": "ReplyCardResponse", "type": "object" }, "ReplyContextResponse": { "description": "Response for GET /emails/{email_id}/reply-context. TIDY-4196.", "properties": { "cc_addresses": { "items": { "type": "string" }, "title": "Cc Addresses", "type": "array" }, "email_id": { "title": "Email Id", "type": "string" }, "from_address": { "title": "From Address", "type": "string" }, "from_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "From Name" }, "quoted_html": { "description": "Quoted original email body as HTML, always populated", "title": "Quoted Html", "type": "string" }, "sent_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Sent At" }, "subject": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Subject" }, "thread_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Thread Id" }, "to_addresses": { "items": { "type": "string" }, "title": "To Addresses", "type": "array" } }, "required": [ "email_id", "from_address", "quoted_html" ], "title": "ReplyContextResponse", "type": "object" }, "ReplyMatrixRoomMessageRequest": { "properties": { "body": { "maxLength": 10000, "minLength": 1, "title": "Body", "type": "string" }, "formatted_body": { "anyOf": [ { "maxLength": 40000, "type": "string" }, { "type": "null" } ], "title": "Formatted Body" }, "mentions": { "items": { "$ref": "#/components/schemas/MatrixMentionRequest" }, "title": "Mentions", "type": "array" } }, "required": [ "body" ], "title": "ReplyMatrixRoomMessageRequest", "type": "object" }, "ReplyQueueItem": { "properties": { "display_subject": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Display Subject" }, "from_address": { "title": "From Address", "type": "string" }, "from_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "From Name" }, "id": { "format": "uuid", "title": "Id", "type": "string" }, "is_read": { "default": true, "title": "Is Read", "type": "boolean" }, "is_starred": { "default": true, "title": "Is Starred", "type": "boolean" }, "sent_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Sent At" }, "snippet": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Snippet" }, "subject": { "title": "Subject", "type": "string" }, "thread_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "default": null, "title": "Thread Id" } }, "required": [ "id", "subject", "from_address" ], "title": "ReplyQueueItem", "type": "object" }, "ReplyQueueResponse": { "properties": { "count": { "default": 0, "title": "Count", "type": "integer" }, "items": { "items": { "$ref": "#/components/schemas/ReplyQueueItem" }, "title": "Items", "type": "array" } }, "title": "ReplyQueueResponse", "type": "object" }, "ReplyRequest": { "description": "Request body for creating a reply.", "properties": { "bcc_recipients": { "anyOf": [ { "items": { "$ref": "#/components/schemas/EmailRecipient" }, "type": "array" }, { "type": "null" } ], "description": "Editable Bcc override from the compose client", "title": "Bcc Recipients" }, "body_html": { "default": "", "description": "Initial body content", "title": "Body Html", "type": "string" }, "body_markdown": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The body as Markdown; raw HTML in it stays text. The server renders it into body_prosemirror, body_html and body_text, so send it instead of those three. A reply's or forward's quoted original is kept below it.", "title": "Body Markdown" }, "body_text": { "default": "", "description": "Plain text body", "title": "Body Text", "type": "string" }, "cc_recipients": { "anyOf": [ { "items": { "$ref": "#/components/schemas/EmailRecipient" }, "type": "array" }, { "type": "null" } ], "description": "Editable Cc override from the compose client", "title": "Cc Recipients" }, "mode": { "default": "reply", "description": "Reply mode: reply (to sender), reply_all (to all), reply_private (to sender, new thread)", "enum": [ "reply", "reply_all", "reply_private" ], "title": "Mode", "type": "string" }, "quoted_body_text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Editable plain-text quoted-original override", "title": "Quoted Body Text" }, "subject": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Editable reply subject override", "title": "Subject" }, "to_recipients": { "anyOf": [ { "items": { "$ref": "#/components/schemas/EmailRecipient" }, "type": "array" }, { "type": "null" } ], "description": "Editable To override from the compose client", "title": "To Recipients" } }, "title": "ReplyRequest", "type": "object" }, "ReportCoverModel": { "description": "Author-controlled cover / title block for a report export (TIDY-14037).", "properties": { "client_block": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Client Block" }, "date": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Date" }, "subtitle": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Subtitle" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Title" } }, "title": "ReportCoverModel", "type": "object" }, "ReportSpamRequest": { "properties": { "attempt_unsubscribe": { "default": true, "description": "Try RFC 8058 one-click unsubscribe", "title": "Attempt Unsubscribe", "type": "boolean" }, "block_sender": { "default": true, "description": "Block the sender address", "title": "Block Sender", "type": "boolean" } }, "title": "ReportSpamRequest", "type": "object" }, "ReportSpamResponse": { "properties": { "actions_taken": { "items": { "type": "string" }, "title": "Actions Taken", "type": "array" }, "defense_rule_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Defense Rule Id" }, "email_id": { "format": "uuid", "title": "Email Id", "type": "string" }, "sender_email": { "title": "Sender Email", "type": "string" }, "undo_available_until": { "format": "date-time", "title": "Undo Available Until", "type": "string" } }, "required": [ "email_id", "sender_email", "actions_taken", "undo_available_until" ], "title": "ReportSpamResponse", "type": "object" }, "RepresentativeFace": { "properties": { "box": { "$ref": "#/components/schemas/FaceBox" }, "face_id": { "format": "uuid", "title": "Face Id", "type": "string" }, "photo_id": { "format": "uuid", "title": "Photo Id", "type": "string" }, "thumbnail_path": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Thumbnail Path" } }, "required": [ "face_id", "photo_id", "box" ], "title": "RepresentativeFace", "type": "object" }, "ReprocessFileResponse": { "description": "202 response — the file was queued for pipeline reprocessing (TIDY-13591).\n\n``queued`` is True when a fresh run was dispatched; False (with\n``already_pending``) when an in-flight run for this file was reused.", "properties": { "already_pending": { "default": false, "title": "Already Pending", "type": "boolean" }, "queued": { "title": "Queued", "type": "boolean" }, "trace_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Trace Id" } }, "required": [ "queued" ], "title": "ReprocessFileResponse", "type": "object" }, "RequestCapabilityResponse": { "properties": { "request_id": { "title": "Request Id", "type": "string" } }, "required": [ "request_id" ], "title": "RequestCapabilityResponse", "type": "object" }, "RequeueResponse": { "description": "Response for DLQ requeue endpoint.", "properties": { "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error" }, "messages_requeued": { "title": "Messages Requeued", "type": "integer" }, "original_queue": { "title": "Original Queue", "type": "string" }, "queue_name": { "title": "Queue Name", "type": "string" }, "success": { "title": "Success", "type": "boolean" } }, "required": [ "success", "queue_name", "messages_requeued", "original_queue" ], "title": "RequeueResponse", "type": "object" }, "RequireCapabilityApprovalUpdate": { "properties": { "require_capability_approval": { "title": "Require Capability Approval", "type": "boolean" } }, "required": [ "require_capability_approval" ], "title": "RequireCapabilityApprovalUpdate", "type": "object" }, "RequirementCoverage": { "description": "Computed coverage for one requirement.", "properties": { "active_work": { "title": "Active Work", "type": "integer" }, "contributions": { "default": [], "items": { "$ref": "#/components/schemas/CoverageContribution" }, "title": "Contributions", "type": "array" }, "coverage": { "title": "Coverage", "type": "string" }, "done_work": { "title": "Done Work", "type": "integer" }, "has_passing_evidence": { "title": "Has Passing Evidence", "type": "boolean" }, "hidden_contributions": { "title": "Hidden Contributions", "type": "integer" }, "open_work": { "title": "Open Work", "type": "integer" }, "requirement_id": { "title": "Requirement Id", "type": "string" }, "total_work": { "title": "Total Work", "type": "integer" } }, "required": [ "requirement_id", "coverage", "total_work", "done_work", "active_work", "open_work", "hidden_contributions", "has_passing_evidence" ], "title": "RequirementCoverage", "type": "object" }, "RequirementReportEntry": { "description": "One requirement's coverage + evidence gaps in the report.", "properties": { "coverage": { "title": "Coverage", "type": "string" }, "missing": { "default": [], "items": { "type": "string" }, "title": "Missing", "type": "array" }, "regression": { "default": false, "title": "Regression", "type": "boolean" }, "requirement_id": { "title": "Requirement Id", "type": "string" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Title" } }, "required": [ "requirement_id", "coverage" ], "title": "RequirementReportEntry", "type": "object" }, "RescheduleRequest": { "properties": { "slot_start": { "format": "date-time", "title": "Slot Start", "type": "string" } }, "required": [ "slot_start" ], "title": "RescheduleRequest", "type": "object" }, "ResearchClaimIn": { "properties": { "citations": { "items": { "type": "string" }, "title": "Citations", "type": "array" }, "text": { "title": "Text", "type": "string" }, "topic": { "default": "General", "title": "Topic", "type": "string" } }, "required": [ "text" ], "title": "ResearchClaimIn", "type": "object" }, "ResearchReport": { "description": "The report read back: its outline (``mode=outline``) or one section.\n\n``response_contract`` is part of the result, not advice — an agent answers\nonly from the returned content and carries ``citation.markdown``.", "properties": { "citation": { "$ref": "#/components/schemas/ResearchReportCitation" }, "intro": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Intro" }, "intro_truncated": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "title": "Intro Truncated" }, "mode": { "enum": [ "outline", "section" ], "title": "Mode", "type": "string" }, "note_id": { "title": "Note Id", "type": "string" }, "response_contract": { "items": { "type": "string" }, "title": "Response Contract", "type": "array" }, "run_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Run Id" }, "section": { "anyOf": [ { "$ref": "#/components/schemas/ResearchReportSection" }, { "type": "null" } ], "default": null }, "sections": { "anyOf": [ { "items": { "$ref": "#/components/schemas/ResearchReportHeading" }, "type": "array" }, { "type": "null" } ], "default": null, "title": "Sections" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Title" }, "total_chars": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Total Chars" } }, "required": [ "mode", "note_id", "citation", "response_contract" ], "title": "ResearchReport", "type": "object" }, "ResearchReportCitation": { "properties": { "markdown": { "title": "Markdown", "type": "string" }, "note_id": { "title": "Note Id", "type": "string" }, "note_url": { "title": "Note Url", "type": "string" } }, "required": [ "note_id", "note_url", "markdown" ], "title": "ResearchReportCitation", "type": "object" }, "ResearchReportHeading": { "properties": { "chars": { "title": "Chars", "type": "integer" }, "heading": { "title": "Heading", "type": "string" }, "index": { "title": "Index", "type": "integer" }, "level": { "title": "Level", "type": "integer" } }, "required": [ "index", "heading", "level", "chars" ], "title": "ResearchReportHeading", "type": "object" }, "ResearchReportSection": { "properties": { "chars": { "title": "Chars", "type": "integer" }, "content": { "title": "Content", "type": "string" }, "heading": { "title": "Heading", "type": "string" }, "index": { "title": "Index", "type": "integer" }, "level": { "title": "Level", "type": "integer" }, "truncated": { "title": "Truncated", "type": "boolean" } }, "required": [ "index", "heading", "level", "chars", "content", "truncated" ], "title": "ResearchReportSection", "type": "object" }, "ResearchRun": { "properties": { "elapsed": { "title": "Elapsed", "type": "string" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Error" }, "eta_hint": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Eta Hint" }, "note_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Note Id" }, "note_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Note Url" }, "run_id": { "title": "Run Id", "type": "string" }, "started_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Started At" }, "status": { "title": "Status", "type": "string" }, "summary": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Summary" }, "title": { "title": "Title", "type": "string" } }, "required": [ "run_id", "title", "status", "elapsed" ], "title": "ResearchRun", "type": "object" }, "ResearchRunList": { "properties": { "runs": { "items": { "$ref": "#/components/schemas/ResearchRun" }, "title": "Runs", "type": "array" }, "scope": { "title": "Scope", "type": "string" } }, "required": [ "scope", "runs" ], "title": "ResearchRunList", "type": "object" }, "ResearchRunStartRequest": { "properties": { "consent_token": { "anyOf": [ { "maxLength": 2048, "type": "string" }, { "type": "null" } ], "description": "After the member agrees, echo the consent_token from a checkpoint_required 402.", "title": "Consent Token" }, "journal_destination": { "default": "link", "description": "link = report note linked from today's journal; inline = findings written into it.", "enum": [ "link", "inline" ], "title": "Journal Destination", "type": "string" }, "report_type": { "default": "research_report", "description": "research_report ~2-5 min; detailed_report / deep ~10-15 min.", "enum": [ "research_report", "detailed_report", "deep" ], "title": "Report Type", "type": "string" }, "tone": { "anyOf": [ { "maxLength": 120, "type": "string" }, { "type": "null" } ], "title": "Tone" }, "topic": { "description": "The research question.", "maxLength": 4000, "minLength": 1, "title": "Topic", "type": "string" } }, "required": [ "topic" ], "title": "ResearchRunStartRequest", "type": "object" }, "ResearchRunStarted": { "properties": { "eta_hint": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Eta Hint" }, "message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Message" }, "run_id": { "title": "Run Id", "type": "string" }, "status": { "title": "Status", "type": "string" } }, "required": [ "run_id", "status" ], "title": "ResearchRunStarted", "type": "object" }, "ResearchSourceIn": { "properties": { "accessed_at": { "default": "", "title": "Accessed At", "type": "string" }, "title": { "default": "", "title": "Title", "type": "string" }, "url": { "title": "Url", "type": "string" } }, "required": [ "url" ], "title": "ResearchSourceIn", "type": "object" }, "ResendOkResponse": { "properties": { "ok": { "default": true, "title": "Ok", "type": "boolean" } }, "title": "ResendOkResponse", "type": "object" }, "ResendVerificationRequest": { "properties": { "email": { "format": "email", "title": "Email", "type": "string" } }, "required": [ "email" ], "title": "ResendVerificationRequest", "type": "object" }, "ResetTenantResponse": { "description": "Response for tenant reset.", "properties": { "items_deleted": { "additionalProperties": true, "title": "Items Deleted", "type": "object" }, "message": { "title": "Message", "type": "string" }, "success": { "title": "Success", "type": "boolean" } }, "required": [ "success", "message", "items_deleted" ], "title": "ResetTenantResponse", "type": "object" }, "ResolutionResponse": { "description": "The reviewable state of the working set (TIDY-15677).\n\nOver-cap and still-processing are computed on read, never stored: they are\na function of the items and the tenant's caps at this moment, so a stored\nflag could only be stale. ``can_generate`` is the single gate a client (or\nF3's generation engine) reads; ``blocking_detail`` is the sentence it shows.", "properties": { "blocking_detail": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Blocking Detail" }, "blocking_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Blocking Reason" }, "can_generate": { "title": "Can Generate", "type": "boolean" }, "empty_count": { "title": "Empty Count", "type": "integer" }, "instruction_count": { "default": 0, "description": "Selected items carrying the user's own steering.", "title": "Instruction Count", "type": "integer" }, "instruction_ready_count": { "default": 0, "description": "Of those, how many a member has reviewed and confirmed.", "title": "Instruction Ready Count", "type": "integer" }, "item_count": { "title": "Item Count", "type": "integer" }, "max_items": { "title": "Max Items", "type": "integer" }, "max_tokens": { "title": "Max Tokens", "type": "integer" }, "over_cap": { "title": "Over Cap", "type": "boolean" }, "processing_count": { "title": "Processing Count", "type": "integer" }, "source_count": { "default": 0, "description": "Selected items that are citeable evidence. `item_count` stays the total the caps are evaluated against — an instruction consumes context too — but a bundle with instructions and no source has nothing to apply them to.", "title": "Source Count", "type": "integer" }, "token_estimate": { "title": "Token Estimate", "type": "integer" }, "unavailable_count": { "title": "Unavailable Count", "type": "integer" } }, "required": [ "item_count", "token_estimate", "max_items", "max_tokens", "over_cap", "processing_count", "unavailable_count", "empty_count", "can_generate" ], "title": "ResolutionResponse", "type": "object" }, "ResolveAllRequest": { "description": "Bulk-resolve every pending orphan with one chosen remediation.", "properties": { "action": { "enum": [ "promote_to_own", "discard" ], "title": "Action", "type": "string" } }, "required": [ "action" ], "title": "ResolveAllRequest", "type": "object" }, "ResolveAllResponse": { "description": "Result of the bulk resolve-all action.", "properties": { "action": { "enum": [ "promote_to_own", "discard" ], "title": "Action", "type": "string" }, "ok": { "default": true, "title": "Ok", "type": "boolean" }, "redirected_facet_count": { "default": 0, "title": "Redirected Facet Count", "type": "integer" }, "resolved_count": { "title": "Resolved Count", "type": "integer" }, "soft_deleted_facet_count": { "default": 0, "title": "Soft Deleted Facet Count", "type": "integer" } }, "required": [ "action", "resolved_count" ], "title": "ResolveAllResponse", "type": "object" }, "ResolveBindingResponse": { "properties": { "definition_id": { "format": "uuid", "title": "Definition Id", "type": "string" }, "rollout_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Rollout Id" }, "route": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Route" }, "tenant_id": { "format": "uuid", "title": "Tenant Id", "type": "string" }, "version_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Version Id" } }, "required": [ "definition_id", "tenant_id", "rollout_id", "version_id", "route" ], "title": "ResolveBindingResponse", "type": "object" }, "ResolveClusterRequest": { "properties": { "contact_id": { "format": "uuid", "title": "Contact Id", "type": "string" } }, "required": [ "contact_id" ], "title": "ResolveClusterRequest", "type": "object" }, "ResolveClusterResponse": { "properties": { "affected_photo_ids": { "items": { "format": "uuid", "type": "string" }, "title": "Affected Photo Ids", "type": "array" }, "cluster_id": { "format": "uuid", "title": "Cluster Id", "type": "string" }, "contact_id": { "format": "uuid", "title": "Contact Id", "type": "string" }, "linked_faces": { "title": "Linked Faces", "type": "integer" } }, "required": [ "cluster_id", "contact_id", "linked_faces", "affected_photo_ids" ], "title": "ResolveClusterResponse", "type": "object" }, "ResolveNameHint": { "properties": { "near_page_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Typed page id to boost candidates linked from / near it.", "examples": [ "N-..." ], "title": "Near Page Id" }, "tag": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Boost candidates carrying this tag.", "title": "Tag" } }, "title": "ResolveNameHint", "type": "object" }, "ResolveNameRequest": { "properties": { "hint": { "anyOf": [ { "$ref": "#/components/schemas/ResolveNameHint" }, { "type": "null" } ] }, "mode": { "const": "name", "default": "name", "description": "Always 'name' for this endpoint (kept for symmetry with the identifier resolver).", "title": "Mode", "type": "string" }, "value": { "description": "Bare page name to resolve by title/alias.", "examples": [ "Vendor Review", "REPS" ], "title": "Value", "type": "string" } }, "required": [ "value" ], "title": "ResolveNameRequest", "type": "object" }, "ResolveNameResponse": { "properties": { "alternatives": { "description": "All OTHER matching typed page ids; [] when unambiguous.", "items": { "type": "string" }, "title": "Alternatives", "type": "array" }, "ambiguous": { "description": "True when more than one candidate matched.", "title": "Ambiguous", "type": "boolean" }, "match_kind": { "description": "exact_alias | exact_title | prefix | substring | none.", "title": "Match Kind", "type": "string" }, "resolved": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Chosen typed page id, or null on zero matches.", "title": "Resolved" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Canonical title of the resolved page (D7).", "title": "Title" } }, "required": [ "ambiguous", "match_kind" ], "title": "ResolveNameResponse", "type": "object" }, "ResolveOrganizationDraftConflictRequest": { "description": "Conflict target selected from the typed publish 409.", "properties": { "existing_organization_id": { "format": "uuid", "title": "Existing Organization Id", "type": "string" } }, "required": [ "existing_organization_id" ], "title": "ResolveOrganizationDraftConflictRequest", "type": "object" }, "ResolveOrganizationDraftConflictResponse": { "description": "Outcome after approving the survivor (if needed) and merging the draft.", "properties": { "draft_id": { "format": "uuid", "title": "Draft Id", "type": "string" }, "existing_organization_approved": { "title": "Existing Organization Approved", "type": "boolean" }, "merge_id": { "format": "uuid", "title": "Merge Id", "type": "string" }, "organization_id": { "format": "uuid", "title": "Organization Id", "type": "string" }, "resolved": { "title": "Resolved", "type": "boolean" } }, "required": [ "resolved", "draft_id", "organization_id", "existing_organization_approved", "merge_id" ], "title": "ResolveOrganizationDraftConflictResponse", "type": "object" }, "ResolveOrphanRequest": { "description": "Resolve one orphan group with a chosen remediation.", "properties": { "action": { "enum": [ "promote_to_own", "discard" ], "title": "Action", "type": "string" }, "target_entity_id": { "title": "Target Entity Id", "type": "string" }, "target_entity_type": { "enum": [ "contact", "organization" ], "title": "Target Entity Type", "type": "string" } }, "required": [ "target_entity_id", "target_entity_type", "action" ], "title": "ResolveOrphanRequest", "type": "object" }, "ResolveOrphanResponse": { "description": "Result of resolving one orphan group.", "properties": { "action": { "enum": [ "promote_to_own", "discard" ], "title": "Action", "type": "string" }, "new_entity_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "New Entity Id" }, "ok": { "default": true, "title": "Ok", "type": "boolean" }, "redirected_facet_count": { "default": 0, "title": "Redirected Facet Count", "type": "integer" }, "soft_deleted_facet_count": { "default": 0, "title": "Soft Deleted Facet Count", "type": "integer" } }, "required": [ "action" ], "title": "ResolveOrphanResponse", "type": "object" }, "ResolveRequest": { "properties": { "value": { "description": "Identifier to resolve. Accepts a full typed UUID, bare UUID, short ID, YYYY-MM-DD date, case-insensitive project shortcode or exact project name. Visible shortcode matches outrank names; duplicate visible names return 422 with candidates. A typed ID cut short to at least its first 8 UUID characters resolves when exactly one item you can see starts with it; several return 422 `ambiguous_typed_id` with candidates.", "examples": [ "KITCHEN-ACTIVITY-3", "Kitchen", "Kitchen Remodel", "2026-05-04" ], "title": "Value", "type": "string" } }, "required": [ "value" ], "title": "ResolveRequest", "type": "object" }, "ResolveResponse": { "properties": { "id": { "title": "Id", "type": "string" }, "kind": { "title": "Kind", "type": "string" }, "short_id": { "title": "Short Id", "type": "string" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Title" } }, "required": [ "kind", "id", "short_id" ], "title": "ResolveResponse", "type": "object" }, "ResolveSuggestionRequest": { "properties": { "action": { "title": "Action", "type": "string" }, "target_entity_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Target Entity Id" } }, "required": [ "action" ], "title": "ResolveSuggestionRequest", "type": "object" }, "ResolvedLinkedReferenceListResponse": { "description": "Paginated list of resolved linked-reference rows.", "properties": { "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Cursor for next page", "title": "Next Cursor" }, "references": { "description": "Resolved linked-reference rows", "items": { "$ref": "#/components/schemas/ResolvedLinkedReferenceRecord" }, "title": "References", "type": "array" }, "total": { "description": "Total count of matching rows", "title": "Total", "type": "integer" } }, "required": [ "references", "total" ], "title": "ResolvedLinkedReferenceListResponse", "type": "object" }, "ResolvedLinkedReferenceRecord": { "description": "Resolved linked-reference row with source container metadata for UI consumers.\n\nTyped-ID emit (TIDY-8940 / R7): ``target_id`` is rewritten with the\nprefix that addresses ``target_type``; ``source_container_id`` uses\n``source_container_type``; ``source_note_id`` is always a note\n(N-). Unknown types fall back to bare UUID with a warning so\nS7 can clean up legacy rows.", "properties": { "created_at": { "description": "Row creation timestamp", "format": "date-time", "title": "Created At", "type": "string" }, "display_text": { "description": "Rendered inline label captured from the editor", "title": "Display Text", "type": "string" }, "fact_text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Extracted fact sentence backing the link (null when absent)", "title": "Fact Text" }, "id": { "description": "Linked reference UUID", "title": "Id", "type": "string" }, "metadata": { "additionalProperties": true, "description": "Reference metadata", "title": "Metadata", "type": "object" }, "predicate": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Normalized human relationship label (null when absent)", "title": "Predicate" }, "provenance_status": { "description": "Whether source provenance is precise or container-level legacy", "enum": [ "precise", "legacy_container" ], "title": "Provenance Status", "type": "string" }, "source_archived": { "default": false, "description": "True when the source is an archived activity (TIDY-14986 badge)", "title": "Source Archived", "type": "boolean" }, "source_block_excerpt": { "default": "", "description": "Cached block excerpt", "title": "Source Block Excerpt", "type": "string" }, "source_block_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Stable source block UUID when precise provenance exists", "title": "Source Block Id" }, "source_container_id": { "description": "Source container UUID", "title": "Source Container Id", "type": "string" }, "source_container_type": { "description": "Surface type used to reopen the source", "enum": [ "event", "contact", "task", "activity", "note", "journal", "news_update", "email", "reminder", "organization", "calendar_event", "podcast_episode", "project", "comment", "record", "file", "canonical_document", "processed_attachment", "crawled_content", "entity", "chunk", "insight", "email_canonical", "scm_object", "notebook", "user", "account", "photo", "evidence_commit", "evidence_pull_request", "evidence_validation_run", "evidence_running_work", "employee_dm", "skill" ], "title": "Source Container Type", "type": "string" }, "source_fields": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "default": null, "description": "For a journal date binding: every source field (due_date, start, end, facet:.) that binds the source to this journal, sorted. Null for every other reference.", "title": "Source Fields" }, "source_note_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Canonical note UUID that authored the link (null for non-note sources)", "title": "Source Note Id" }, "source_note_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Note subtype for note-backed sources when available", "title": "Source Note Type" }, "source_title": { "description": "Human-readable source container title", "title": "Source Title", "type": "string" }, "target_id": { "description": "Referenced primitive UUID", "title": "Target Id", "type": "string" }, "target_state": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Resolved state of an external (SCM) target (open/merged/closed/draft). Null for internal targets and for kinds that carry no state.", "title": "Target State" }, "target_title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Resolved title of an external (SCM) target; falls back to the stored display_text when the object is severed or gone. Null for internal targets.", "title": "Target Title" }, "target_type": { "description": "Referenced primitive type", "enum": [ "event", "contact", "task", "activity", "note", "journal", "news_update", "email", "reminder", "organization", "calendar_event", "podcast_episode", "project", "comment", "record", "file", "canonical_document", "processed_attachment", "crawled_content", "entity", "chunk", "insight", "email_canonical", "scm_object", "photo", "tab", "attachment" ], "title": "Target Type", "type": "string" }, "trigger_style": { "description": "Original inline trigger used to author the reference", "enum": [ "wiki", "at", "none" ], "title": "Trigger Style", "type": "string" }, "updated_at": { "description": "Row update timestamp", "format": "date-time", "title": "Updated At", "type": "string" } }, "required": [ "id", "target_type", "target_id", "source_container_type", "source_container_id", "source_title", "display_text", "trigger_style", "provenance_status", "created_at", "updated_at" ], "title": "ResolvedLinkedReferenceRecord", "type": "object" }, "ResolvedParamPreview": { "description": "A mapped (non-prompt) param the server already resolved, returned with a\n``prompt_needed`` response so the prompt modal can show the DEFAULTED value\nread-only — e.g. the recipient picked from the contact's primary email —\nalongside the fields the user fills in (TIDY-11014). Confirmation, not input.", "properties": { "key": { "description": "Handler/workflow input name", "title": "Key", "type": "string" }, "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Human description of where the value came from", "title": "Label" }, "source": { "description": "Param source: system | property | formula", "title": "Source", "type": "string" }, "value": { "description": "Resolved display value (empty string if none)", "title": "Value", "type": "string" } }, "required": [ "key", "value", "source" ], "title": "ResolvedParamPreview", "type": "object" }, "ResolvedViewMapping": { "description": "How the requested layout binds to the facet — the R117/D31 answer.\n\n``supported`` false does not mean the query is invalid; it means THIS facet\ncannot render THIS layout, and ``valid_layouts`` lists the ones it can.", "properties": { "issues": { "description": "Layout-config problems (chart/hierarchy), same {path, code, message, allowed?} shape.", "items": { "additionalProperties": true, "type": "object" }, "title": "Issues", "type": "array" }, "layout": { "title": "Layout", "type": "string" }, "mapping": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "The facet's view_mappings. the layout would draw, each slot {property: } (TIDY-18514); null when it reads no facet mapping or a required slot is unmet.", "title": "ResolvedViewMappingSlots" }, "missing_required": { "description": "Field slots the facet does not satisfy for this layout.", "items": { "type": "string" }, "title": "Missing Required", "type": "array" }, "renderer": { "default": "database-view", "description": "Canonical renderer the saved/ephemeral view uses.", "title": "Renderer", "type": "string" }, "supported": { "title": "Supported", "type": "boolean" }, "valid_layouts": { "description": "Layouts this facet CAN render.", "items": { "type": "string" }, "title": "Valid Layouts", "type": "array" } }, "required": [ "layout", "supported" ], "title": "ResolvedViewMapping", "type": "object" }, "ResourceScopeGrantRequest": { "properties": { "expires_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Expires At" }, "grantee_account_id": { "format": "uuid", "title": "Grantee Account Id", "type": "string" }, "rights": { "items": { "type": "string" }, "maxItems": 6, "minItems": 1, "title": "Rights", "type": "array" } }, "required": [ "grantee_account_id", "rights" ], "title": "ResourceScopeGrantRequest", "type": "object" }, "ResourceScopeResponse": { "properties": { "effective_rights": { "items": { "type": "string" }, "title": "Effective Rights", "type": "array" }, "generation": { "title": "Generation", "type": "integer" }, "grant_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Grant Id" }, "scope_id": { "title": "Scope Id", "type": "string" } }, "required": [ "scope_id", "generation", "effective_rights" ], "title": "ResourceScopeResponse", "type": "object" }, "ResponseTimeByHour": { "properties": { "avg_seconds": { "title": "Avg Seconds", "type": "number" }, "count": { "title": "Count", "type": "integer" }, "hour": { "title": "Hour", "type": "integer" } }, "required": [ "hour", "avg_seconds", "count" ], "title": "ResponseTimeByHour", "type": "object" }, "ResponseTimeByPeriod": { "properties": { "avg_seconds": { "title": "Avg Seconds", "type": "number" }, "count": { "title": "Count", "type": "integer" }, "period": { "title": "Period", "type": "string" } }, "required": [ "period", "avg_seconds", "count" ], "title": "ResponseTimeByPeriod", "type": "object" }, "ResponseTimeStats": { "properties": { "avg_seconds": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Avg Seconds" }, "median_seconds": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Median Seconds" }, "p90_seconds": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "P90 Seconds" } }, "required": [ "avg_seconds", "median_seconds", "p90_seconds" ], "title": "ResponseTimeStats", "type": "object" }, "ResponseTimesResponse": { "properties": { "incoming": { "$ref": "#/components/schemas/ResponseTimeStats" }, "outgoing": { "$ref": "#/components/schemas/OutgoingResponseTimes" } }, "required": [ "outgoing", "incoming" ], "title": "ResponseTimesResponse", "type": "object" }, "RestoreResponse": { "description": "Response for restore action.", "properties": { "id": { "title": "Id", "type": "string" }, "status": { "title": "Status", "type": "string" }, "type": { "title": "Type", "type": "string" }, "updated_at": { "format": "date-time", "title": "Updated At", "type": "string" } }, "required": [ "id", "type", "status", "updated_at" ], "title": "RestoreResponse", "type": "object" }, "ResumeDecisionRequest": { "description": "Body for /auth/resume-decision (TIDY-17596).\n\nThe resume branch decision itself lives in the web layer's\n``/auth/resume`` route — the ONLY place that decision is made\n(TIDY-16043/17568). This endpoint records the resolved branch in the\ntamper-evident audit chain: ``operator`` on the platform chain,\ncustomer-plane branches on the caller's tenant chain.", "properties": { "branch": { "enum": [ "operator", "customer", "invite", "onboarding" ], "title": "Branch", "type": "string" }, "next": { "anyOf": [ { "maxLength": 512, "type": "string" }, { "type": "null" } ], "title": "Next" } }, "required": [ "branch" ], "title": "ResumeDecisionRequest", "type": "object" }, "ResumeTaskRequest": { "properties": { "conversation_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Conversation Id" }, "plan_id": { "title": "Plan Id", "type": "string" } }, "required": [ "plan_id" ], "title": "ResumeTaskRequest", "type": "object" }, "ResumeTaskResponse": { "properties": { "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Reason" }, "resumed": { "title": "Resumed", "type": "boolean" }, "status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Status" } }, "required": [ "resumed" ], "title": "ResumeTaskResponse", "type": "object" }, "ResumeVerificationRequest": { "properties": { "email": { "format": "email", "title": "Email", "type": "string" }, "password": { "minLength": 8, "title": "Password", "type": "string" } }, "required": [ "email", "password" ], "title": "ResumeVerificationRequest", "type": "object" }, "RetainedWarningModel": { "properties": { "count": { "title": "Count", "type": "integer" }, "reason": { "title": "Reason", "type": "string" }, "store": { "title": "Store", "type": "string" } }, "required": [ "store", "count", "reason" ], "title": "RetainedWarningModel", "type": "object" }, "RetentionPolicyRequest": { "properties": { "mode": { "enum": [ "keep_forever", "delete_after_days", "hide_after_days" ], "title": "Mode", "type": "string" }, "retention_days": { "anyOf": [ { "maximum": 3650.0, "minimum": 1.0, "type": "integer" }, { "type": "null" } ], "title": "Retention Days" }, "room_id": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "title": "Room Id" }, "scope": { "enum": [ "workspace", "room" ], "title": "Scope", "type": "string" } }, "required": [ "scope", "mode" ], "title": "RetentionPolicyRequest", "type": "object" }, "RetentionPolicyResponse": { "properties": { "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "id": { "title": "Id", "type": "string" }, "mode": { "enum": [ "keep_forever", "delete_after_days", "hide_after_days" ], "title": "Mode", "type": "string" }, "retention_days": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Retention Days" }, "room_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Room Id" }, "room_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Room Name" }, "scope": { "enum": [ "workspace", "room" ], "title": "Scope", "type": "string" }, "tenant_id": { "title": "Tenant Id", "type": "string" }, "updated_at": { "format": "date-time", "title": "Updated At", "type": "string" } }, "required": [ "id", "tenant_id", "scope", "mode", "created_at", "updated_at" ], "title": "RetentionPolicyResponse", "type": "object" }, "RetentionResult": { "properties": { "hard_deleted": { "title": "Hard Deleted", "type": "integer" }, "soft_deleted": { "title": "Soft Deleted", "type": "integer" } }, "required": [ "soft_deleted", "hard_deleted" ], "title": "RetentionResult", "type": "object" }, "RetentionRoomOption": { "properties": { "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Name" }, "room_id": { "title": "Room Id", "type": "string" } }, "required": [ "room_id" ], "title": "RetentionRoomOption", "type": "object" }, "RetentionRunResponse": { "properties": { "matrix_redacted_count": { "title": "Matrix Redacted Count", "type": "integer" }, "mrs_deleted_count": { "title": "Mrs Deleted Count", "type": "integer" }, "reconcile_queued_count": { "title": "Reconcile Queued Count", "type": "integer" }, "redactions_queued": { "title": "Redactions Queued", "type": "integer" } }, "required": [ "redactions_queued", "matrix_redacted_count", "mrs_deleted_count", "reconcile_queued_count" ], "title": "RetentionRunResponse", "type": "object" }, "RetirementResponse": { "properties": { "audit": { "additionalProperties": true, "title": "Audit", "type": "object" } }, "required": [ "audit" ], "title": "RetirementResponse", "type": "object" }, "RetranscribeResponse": { "properties": { "transcription_kicked_off": { "title": "Transcription Kicked Off", "type": "boolean" } }, "required": [ "transcription_kicked_off" ], "title": "RetranscribeResponse", "type": "object" }, "RetranscribeResult": { "properties": { "deduped": { "title": "Deduped", "type": "boolean" }, "enqueued": { "title": "Enqueued", "type": "boolean" }, "episode_id": { "title": "Episode Id", "type": "string" } }, "required": [ "episode_id", "enqueued", "deduped" ], "title": "RetranscribeResult", "type": "object" }, "RetroApplyResponse": { "properties": { "applied_count": { "title": "Applied Count", "type": "integer" }, "rule_id": { "title": "Rule Id", "type": "string" } }, "required": [ "applied_count", "rule_id" ], "title": "RetroApplyResponse", "type": "object" }, "RetryFailedJobResult": { "description": "P4 S1 (R-P4.2): retry re-dispatches via the P3 client as a NEW request.", "properties": { "new_batch_id": { "format": "uuid", "title": "New Batch Id", "type": "string" }, "new_request_ref": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "New Request Ref" }, "request_ref": { "format": "uuid", "title": "Request Ref", "type": "string" }, "status": { "title": "Status", "type": "string" } }, "required": [ "request_ref", "new_batch_id", "new_request_ref", "status" ], "title": "RetryFailedJobResult", "type": "object" }, "RetryParkedStepResponse": { "description": "Outcome of retrying an automation step parked on an offline employee.", "properties": { "outcome": { "title": "Outcome", "type": "string" }, "run_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Run Status" } }, "required": [ "outcome" ], "title": "RetryParkedStepResponse", "type": "object" }, "RetryPipelineRequest": { "description": "Request to retry a pipeline run.", "properties": { "from_stage": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Stage to retry from (optional)", "title": "From Stage" } }, "title": "RetryPipelineRequest", "type": "object" }, "ReverseGeocodeRequest": { "description": "Request body for reverse geocoding.", "properties": { "latitude": { "description": "GPS latitude coordinate", "maximum": 90.0, "minimum": -90.0, "title": "Latitude", "type": "number" }, "longitude": { "description": "GPS longitude coordinate", "maximum": 180.0, "minimum": -180.0, "title": "Longitude", "type": "number" } }, "required": [ "latitude", "longitude" ], "title": "ReverseGeocodeRequest", "type": "object" }, "ReverseGeocodeResponse": { "description": "Response from reverse geocoding.", "properties": { "address": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Formatted street address", "title": "Address" }, "latitude": { "description": "Input latitude", "title": "Latitude", "type": "number" }, "locality": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "City/locality name", "title": "Locality" }, "longitude": { "description": "Input longitude", "title": "Longitude", "type": "number" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "POI/business name if available", "title": "Name" }, "region": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "State/region name", "title": "Region" } }, "required": [ "latitude", "longitude" ], "title": "ReverseGeocodeResponse", "type": "object" }, "ReviewCountsResponse": { "description": "Response for review counts by type.", "properties": { "contacts": { "default": 0, "title": "Contacts", "type": "integer" }, "events": { "default": 0, "title": "Events", "type": "integer" }, "notes": { "default": 0, "title": "Notes", "type": "integer" }, "organizations": { "default": 0, "title": "Organizations", "type": "integer" }, "tasks": { "default": 0, "title": "Tasks", "type": "integer" }, "total": { "default": 0, "title": "Total", "type": "integer" } }, "title": "ReviewCountsResponse", "type": "object" }, "ReviewItem": { "description": "Unified review item across all types.", "properties": { "address": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Address" }, "all_day": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "title": "All Day" }, "confidence": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "title": "Confidence" }, "contact_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Contact Count" }, "content": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Content" }, "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Description" }, "due_date": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Due Date" }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Email" }, "email_addresses": { "anyOf": [ { "items": {}, "type": "array" }, { "type": "null" } ], "default": null, "title": "Email Addresses" }, "end_time": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "End Time" }, "event_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Event Type" }, "id": { "title": "Id", "type": "string" }, "location": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Location" }, "org_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Org Type" }, "organization": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Organization" }, "organization_ids": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "default": null, "title": "Organization Ids" }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Phone" }, "phone_numbers": { "anyOf": [ { "items": {}, "type": "array" }, { "type": "null" } ], "default": null, "title": "Phone Numbers" }, "priority": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Priority" }, "review_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Review Reason" }, "role": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Role" }, "source_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Source Id" }, "source_sender": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Source Sender" }, "source_subject": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Source Subject" }, "start_time": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Start Time" }, "status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Status" }, "title": { "title": "Title", "type": "string" }, "type": { "title": "Type", "type": "string" }, "website": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Website" } }, "required": [ "id", "type", "title", "created_at" ], "title": "ReviewItem", "type": "object" }, "ReviewListResponse": { "description": "Response for listing review items.", "properties": { "items": { "items": { "$ref": "#/components/schemas/ReviewItem" }, "title": "Items", "type": "array" }, "total": { "title": "Total", "type": "integer" }, "type_counts": { "additionalProperties": true, "title": "Type Counts", "type": "object" } }, "required": [ "items", "total" ], "title": "ReviewListResponse", "type": "object" }, "ReviewMeetingBooked": { "properties": { "ends_at": { "title": "Ends At", "type": "string" }, "event_id": { "title": "Event Id", "type": "string" }, "proposals": { "title": "Proposals", "type": "integer" }, "starts_at": { "title": "Starts At", "type": "string" } }, "required": [ "event_id", "starts_at", "ends_at", "proposals" ], "title": "ReviewMeetingBooked", "type": "object" }, "ReviewOAuthAppResponse": { "properties": { "ok": { "title": "Ok", "type": "boolean" }, "review_status": { "title": "Review Status", "type": "string" } }, "required": [ "ok", "review_status" ], "title": "ReviewOAuthAppResponse", "type": "object" }, "ReviewRequest": { "properties": { "status": { "enum": [ "approved", "rejected" ], "title": "Status", "type": "string" } }, "required": [ "status" ], "title": "ReviewRequest", "type": "object" }, "RevocationResponse": { "properties": { "already_revoked": { "title": "Already Revoked", "type": "boolean" }, "id": { "title": "Id", "type": "string" }, "revoked": { "title": "Revoked", "type": "boolean" } }, "required": [ "id", "revoked", "already_revoked" ], "title": "RevocationResponse", "type": "object" }, "RevokeAgentPatsResponse": { "properties": { "ok": { "title": "Ok", "type": "boolean" }, "revoked": { "title": "Revoked", "type": "integer" } }, "required": [ "ok", "revoked" ], "title": "RevokeAgentPatsResponse", "type": "object" }, "RevokeAllResponse": { "properties": { "revoked_count": { "title": "Revoked Count", "type": "integer" } }, "required": [ "revoked_count" ], "title": "RevokeAllResponse", "type": "object" }, "RevokeConnectedAppResponse": { "properties": { "ok": { "title": "Ok", "type": "boolean" }, "revoked_count": { "title": "Revoked Count", "type": "integer" } }, "required": [ "ok", "revoked_count" ], "title": "RevokeConnectedAppResponse", "type": "object" }, "RevokeDevicesResponse": { "description": "Result of a device-revocation (sign-out-everywhere + forced wipe).", "properties": { "families_revoked": { "title": "Families Revoked", "type": "integer" }, "wiped_at": { "format": "date-time", "title": "Wiped At", "type": "string" } }, "required": [ "families_revoked", "wiped_at" ], "title": "RevokeDevicesResponse", "type": "object" }, "RevokeGuestRequest": { "properties": { "reason": { "maxLength": 500, "minLength": 1, "title": "Reason", "type": "string" } }, "required": [ "reason" ], "title": "RevokeGuestRequest", "type": "object" }, "RevokeGuestResponse": { "properties": { "guest_account_id": { "title": "Guest Account Id", "type": "string" }, "revoked_at": { "format": "date-time", "title": "Revoked At", "type": "string" }, "rooms_left": { "items": { "type": "string" }, "title": "Rooms Left", "type": "array" } }, "required": [ "guest_account_id", "revoked_at" ], "title": "RevokeGuestResponse", "type": "object" }, "RevokeLinkResponse": { "properties": { "changed": { "title": "Changed", "type": "boolean" }, "ok": { "title": "Ok", "type": "boolean" } }, "required": [ "ok", "changed" ], "title": "RevokeLinkResponse", "type": "object" }, "RevokePATResponse": { "properties": { "changed": { "title": "Changed", "type": "boolean" }, "ok": { "title": "Ok", "type": "boolean" } }, "required": [ "ok", "changed" ], "title": "RevokePATResponse", "type": "object" }, "RevokePublicationResponse": { "properties": { "id": { "title": "Id", "type": "string" }, "status": { "title": "Status", "type": "string" } }, "required": [ "id", "status" ], "title": "RevokePublicationResponse", "type": "object" }, "RevokeWorkspaceWideResponse": { "properties": { "ok": { "title": "Ok", "type": "boolean" }, "revoked_count": { "title": "Revoked Count", "type": "integer" } }, "required": [ "ok", "revoked_count" ], "title": "RevokeWorkspaceWideResponse", "type": "object" }, "RingItem": { "properties": { "caller_account_id": { "format": "uuid", "title": "Caller Account Id", "type": "string" }, "caller_avatar_ref": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Caller Avatar Ref" }, "caller_display_name": { "title": "Caller Display Name", "type": "string" }, "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "expires_at": { "format": "date-time", "title": "Expires At", "type": "string" }, "huddle_id": { "format": "uuid", "title": "Huddle Id", "type": "string" }, "realtime_sequence": { "title": "Realtime Sequence", "type": "integer" }, "recipient_state": { "title": "Recipient State", "type": "string" }, "ring_id": { "format": "uuid", "title": "Ring Id", "type": "string" }, "ring_token_ref": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Ring Token Ref" }, "room_id": { "title": "Room Id", "type": "string" }, "state": { "title": "State", "type": "string" }, "terminal_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Terminal Reason" } }, "required": [ "ring_id", "huddle_id", "room_id", "caller_account_id", "caller_display_name", "state", "created_at", "expires_at", "realtime_sequence", "recipient_state" ], "title": "RingItem", "type": "object" }, "RingListResponse": { "properties": { "items": { "items": { "$ref": "#/components/schemas/RingItem" }, "title": "Items", "type": "array" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Next Cursor" } }, "required": [ "items" ], "title": "RingListResponse", "type": "object" }, "RingPreferencesResponse": { "properties": { "account_id": { "format": "uuid", "title": "Account Id", "type": "string" }, "quiet_hours_end": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Quiet Hours End" }, "quiet_hours_start": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Quiet Hours Start" }, "quiet_hours_timezone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Quiet Hours Timezone" }, "ring_enabled": { "title": "Ring Enabled", "type": "boolean" }, "room_overrides": { "additionalProperties": { "type": "boolean" }, "title": "Room Overrides", "type": "object" }, "version": { "title": "Version", "type": "integer" } }, "required": [ "account_id", "ring_enabled", "room_overrides", "version" ], "title": "RingPreferencesResponse", "type": "object" }, "RingPreferencesUpdate": { "description": "Full replacement of the member's preference row.", "properties": { "quiet_hours_end": { "anyOf": [ { "pattern": "^([01][0-9]|2[0-3]):[0-5][0-9]$", "type": "string" }, { "type": "null" } ], "title": "Quiet Hours End" }, "quiet_hours_start": { "anyOf": [ { "pattern": "^([01][0-9]|2[0-3]):[0-5][0-9]$", "type": "string" }, { "type": "null" } ], "title": "Quiet Hours Start" }, "quiet_hours_timezone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Quiet Hours Timezone" }, "ring_enabled": { "default": true, "title": "Ring Enabled", "type": "boolean" }, "room_overrides": { "additionalProperties": { "type": "boolean" }, "title": "Room Overrides", "type": "object" }, "version": { "minimum": 1.0, "title": "Version", "type": "integer" } }, "required": [ "version" ], "title": "RingPreferencesUpdate", "type": "object" }, "RingStateResponse": { "properties": { "realtime_sequence": { "title": "Realtime Sequence", "type": "integer" }, "ring_id": { "format": "uuid", "title": "Ring Id", "type": "string" }, "state": { "title": "State", "type": "string" }, "terminal_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Terminal Reason" } }, "required": [ "ring_id", "state", "realtime_sequence" ], "title": "RingStateResponse", "type": "object" }, "RingTokenRequest": { "properties": { "ring_token": { "title": "Ring Token", "type": "string" } }, "required": [ "ring_token" ], "title": "RingTokenRequest", "type": "object" }, "RoleUpdate": { "properties": { "role": { "enum": [ "owner", "tenant_admin", "developer", "member", "guest" ], "title": "Role", "type": "string" } }, "required": [ "role" ], "title": "RoleUpdate", "type": "object" }, "RoleUpdateRequest": { "description": "Request model for updating a member's role.", "properties": { "role": { "description": "New role to assign (Owner, Admin, Member, or Viewer). Only an Owner may grant, change or revoke Owner and Admin; an Admin manages Members and Viewers.", "enum": [ "Owner", "Admin", "Member", "Viewer" ], "examples": [ "Admin", "Member", "Viewer" ], "title": "Role", "type": "string" } }, "required": [ "role" ], "title": "RoleUpdateRequest", "type": "object" }, "RoleUpdateResponse": { "description": "Response model for role update.", "properties": { "account_id": { "description": "UUID of member whose role was updated", "title": "Account Id", "type": "string" }, "role": { "description": "New role assigned", "title": "Role", "type": "string" }, "updated_at": { "description": "Timestamp of role update", "format": "date-time", "title": "Updated At", "type": "string" } }, "required": [ "account_id", "role", "updated_at" ], "title": "RoleUpdateResponse", "type": "object" }, "RollbackLegacyRequest": { "properties": { "installation_id": { "format": "uuid", "title": "Installation Id", "type": "string" }, "legacy_device_id": { "maxLength": 255, "minLength": 1, "title": "Legacy Device Id", "type": "string" }, "migration_request_id": { "format": "uuid", "title": "Migration Request Id", "type": "string" }, "rollback_receipt": { "maxLength": 512, "minLength": 32, "title": "Rollback Receipt", "type": "string" } }, "required": [ "installation_id", "migration_request_id", "rollback_receipt", "legacy_device_id" ], "title": "RollbackLegacyRequest", "type": "object" }, "RollbackLegacyResponse": { "properties": { "matrix_access_token": { "title": "Matrix Access Token", "type": "string" }, "matrix_device_id": { "title": "Matrix Device Id", "type": "string" }, "status": { "const": "restored", "title": "Status", "type": "string" } }, "required": [ "status", "matrix_access_token", "matrix_device_id" ], "title": "RollbackLegacyResponse", "type": "object" }, "RolloutConfigResponse": { "description": "The tenant's active rollout config.\n\n``version`` is ``None`` for a tenant that has never been configured — the\nabsence IS the dogfood-only default, and it is what the caller passes back\nas ``expected_version`` on their first activation.", "properties": { "configured": { "title": "Configured", "type": "boolean" }, "mode": { "title": "Mode", "type": "string" }, "percentage": { "title": "Percentage", "type": "integer" }, "previous_version": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Previous Version" }, "verdict_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "default": null, "title": "Verdict Id" }, "version": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Version" } }, "required": [ "mode", "percentage", "configured" ], "title": "RolloutConfigResponse", "type": "object" }, "RolloutConfigUpdate": { "properties": { "expected_version": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "The version the caller believes is active; None for an unconfigured tenant.", "title": "Expected Version" }, "mode": { "enum": [ "dogfood", "general", "disabled" ], "title": "Mode", "type": "string" }, "percentage": { "default": 0, "maximum": 100.0, "minimum": 0.0, "title": "Percentage", "type": "integer" }, "verdict_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "description": "TIDY-15436 signed promotion verdict — required for mode='general'.", "title": "Verdict Id" } }, "required": [ "mode" ], "title": "RolloutConfigUpdate", "type": "object" }, "RolloutCreateRequest": { "properties": { "cohort_key": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cohort Key" }, "cohort_salt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cohort Salt" }, "definition_id": { "format": "uuid", "title": "Definition Id", "type": "string" }, "percentage": { "anyOf": [ { "exclusiveMinimum": 0.0, "maximum": 100.0, "type": "integer" }, { "type": "null" } ], "title": "Percentage" }, "reason": { "minLength": 1, "title": "Reason", "type": "string" }, "route": { "enum": [ "global", "tenants", "cohort", "staged" ], "title": "Route", "type": "string" }, "tenant_ids": { "anyOf": [ { "items": { "format": "uuid", "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Tenant Ids" }, "treatment": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Treatment" }, "version_id": { "format": "uuid", "title": "Version Id", "type": "string" } }, "required": [ "definition_id", "version_id", "route", "reason" ], "title": "RolloutCreateRequest", "type": "object" }, "RolloutPatchRequest": { "properties": { "action": { "enum": [ "rebind", "pause", "resume", "close" ], "title": "Action", "type": "string" }, "reason": { "minLength": 1, "title": "Reason", "type": "string" }, "version_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Version Id" } }, "required": [ "action", "reason" ], "title": "RolloutPatchRequest", "type": "object" }, "RolloutPolicyRequest": { "properties": { "expected_version": { "anyOf": [ { "minimum": 1.0, "type": "integer" }, { "type": "null" } ], "title": "Expected Version" }, "mode": { "enum": [ "dogfood", "general", "disabled" ], "title": "Mode", "type": "string" }, "reason": { "maxLength": 500, "minLength": 1, "title": "Reason", "type": "string" }, "verdict_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Verdict Id" } }, "required": [ "mode", "reason" ], "title": "RolloutPolicyRequest", "type": "object" }, "RolloutPolicyResponse": { "properties": { "configured": { "default": false, "title": "Configured", "type": "boolean" }, "mode": { "default": "disabled", "title": "Mode", "type": "string" }, "previous_version": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Previous Version" }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Reason" }, "verdict_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "default": null, "title": "Verdict Id" }, "version": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Version" } }, "title": "RolloutPolicyResponse", "type": "object" }, "RolloutResponse": { "properties": { "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "definition_id": { "format": "uuid", "title": "Definition Id", "type": "string" }, "id": { "format": "uuid", "title": "Id", "type": "string" }, "route": { "title": "Route", "type": "string" }, "status": { "title": "Status", "type": "string" }, "version_id": { "format": "uuid", "title": "Version Id", "type": "string" } }, "required": [ "id", "definition_id", "version_id", "route", "status", "created_at" ], "title": "RolloutResponse", "type": "object" }, "RolloutRollbackRequest": { "properties": { "target_version": { "anyOf": [ { "minimum": 1.0, "type": "integer" }, { "type": "null" } ], "description": "Version to restore; defaults to the active version's predecessor.", "title": "Target Version" } }, "title": "RolloutRollbackRequest", "type": "object" }, "RoomKeyRequestBody": { "description": "POST /api/v1/matrix/room-key-requests body.", "properties": { "device_id": { "maxLength": 255, "minLength": 1, "title": "Device Id", "type": "string" }, "room_id": { "maxLength": 255, "minLength": 1, "title": "Room Id", "type": "string" }, "sender_device_id": { "anyOf": [ { "enum": [ "tidy-hosted-relay", "tidy-employee-relay" ], "type": "string" }, { "type": "null" } ], "description": "The sending managed device; requires sender_matrix_user_id.", "title": "Sender Device Id" }, "sender_matrix_user_id": { "anyOf": [ { "maxLength": 255, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Sender Matrix User Id" }, "session_id": { "maxLength": 255, "minLength": 1, "title": "Session Id", "type": "string" } }, "required": [ "room_id", "session_id", "device_id" ], "title": "RoomKeyRequestBody", "type": "object" }, "RoomKeyRequestResponse": { "description": "Whether the room key was sent — never the key.", "properties": { "delivered": { "title": "Delivered", "type": "boolean" }, "outcome": { "title": "Outcome", "type": "string" } }, "required": [ "delivered", "outcome" ], "title": "RoomKeyRequestResponse", "type": "object" }, "RoomKeySessionBlob": { "description": "One backed-up megolm session's encrypted blob (PkMessage parts).", "properties": { "ciphertext": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Ciphertext" }, "ephemeral": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Ephemeral" }, "first_message_index": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "First Message Index" }, "mac": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Mac" } }, "title": "RoomKeySessionBlob", "type": "object" }, "RoomKeysResponse": { "description": "Recovered room-key material for a single room (service-scoped).\n\nCarries the megolm backup PRIVATE key (scoped to backups — strictly less\npowerful than the recovery key) plus encrypted per-session blobs. The\nconsuming service does the olm decryption (PkDecryption + group session).", "properties": { "backup_private_key": { "title": "Backup Private Key", "type": "string" }, "key_backup_version": { "title": "Key Backup Version", "type": "string" }, "sessions": { "additionalProperties": { "$ref": "#/components/schemas/RoomKeySessionBlob" }, "title": "Sessions", "type": "object" } }, "required": [ "key_backup_version", "backup_private_key", "sessions" ], "title": "RoomKeysResponse", "type": "object" }, "RoomPolicyPatch": { "properties": { "can_be_dmd_by": { "anyOf": [ { "pattern": "^(everyone|members|admins|nobody)$", "type": "string" }, { "type": "null" } ], "title": "Can Be Dmd By" }, "may_initiate_dm": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "May Initiate Dm" }, "mention_only": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Mention Only" }, "present": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Present" } }, "title": "RoomPolicyPatch", "type": "object" }, "RoomPolicyRequest": { "properties": { "ai_employee_id": { "format": "uuid", "title": "Ai Employee Id", "type": "string" }, "can_be_dmd_by": { "default": "members", "pattern": "^(everyone|members|admins|nobody)$", "title": "Can Be Dmd By", "type": "string" }, "may_initiate_dm": { "default": false, "title": "May Initiate Dm", "type": "boolean" }, "mention_only": { "default": true, "title": "Mention Only", "type": "boolean" }, "present": { "default": true, "title": "Present", "type": "boolean" }, "room_id": { "minLength": 1, "title": "Room Id", "type": "string" } }, "required": [ "room_id", "ai_employee_id" ], "title": "RoomPolicyRequest", "type": "object" }, "RoomPolicyResponse": { "properties": { "ai_employee_id": { "format": "uuid", "title": "Ai Employee Id", "type": "string" }, "can_be_dmd_by": { "title": "Can Be Dmd By", "type": "string" }, "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "id": { "format": "uuid", "title": "Id", "type": "string" }, "matrix_room_id": { "title": "Matrix Room Id", "type": "string" }, "may_initiate_dm": { "title": "May Initiate Dm", "type": "boolean" }, "mention_only": { "title": "Mention Only", "type": "boolean" }, "present": { "title": "Present", "type": "boolean" }, "tenant_id": { "format": "uuid", "title": "Tenant Id", "type": "string" }, "updated_at": { "format": "date-time", "title": "Updated At", "type": "string" } }, "required": [ "id", "tenant_id", "matrix_room_id", "ai_employee_id", "present", "can_be_dmd_by", "may_initiate_dm", "mention_only", "created_at", "updated_at" ], "title": "RoomPolicyResponse", "type": "object" }, "RoomResponse": { "properties": { "canvas_note_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Canvas Note Id" }, "created_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Created At" }, "federated_with_server": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Federated With Server" }, "federation_state": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Federation State" }, "guest_member_count": { "default": 0, "title": "Guest Member Count", "type": "integer" }, "id": { "title": "Id", "type": "string" }, "is_shared_channel": { "default": false, "title": "Is Shared Channel", "type": "boolean" }, "name": { "title": "Name", "type": "string" }, "project_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Project Id" }, "project_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Project Name" }, "room_id": { "title": "Room Id", "type": "string" }, "room_type": { "title": "Room Type", "type": "string" }, "shared_with_tenant_ids": { "items": { "type": "string" }, "title": "Shared With Tenant Ids", "type": "array" } }, "required": [ "id", "room_id", "name", "room_type" ], "title": "RoomResponse", "type": "object" }, "RootGitCredentialRequest": { "properties": { "repository": { "maxLength": 2048, "minLength": 1, "title": "Repository", "type": "string" } }, "required": [ "repository" ], "title": "RootGitCredentialRequest", "type": "object" }, "RootGitCredentialResponse": { "properties": { "expires_at": { "format": "date-time", "title": "Expires At", "type": "string" }, "token": { "title": "Token", "type": "string" }, "username": { "title": "Username", "type": "string" } }, "required": [ "username", "token", "expires_at" ], "title": "RootGitCredentialResponse", "type": "object" }, "RosterPluginAccessPlan": { "description": "Every employee a roster redeploy would move, with its plan for the target.", "properties": { "employees": { "items": { "$ref": "#/components/schemas/EmployeeDeployPlan" }, "title": "Employees", "type": "array" }, "target_workshop_id": { "title": "Target Workshop Id", "type": "string" } }, "required": [ "target_workshop_id", "employees" ], "title": "RosterPluginAccessPlan", "type": "object" }, "RotateTokenResponse": { "properties": { "id": { "title": "Id", "type": "string" }, "public_url": { "title": "Public Url", "type": "string" }, "token": { "title": "Token", "type": "string" } }, "required": [ "id", "token", "public_url" ], "title": "RotateTokenResponse", "type": "object" }, "RoutingChangeRequest": { "properties": { "actor": { "title": "Actor", "type": "string" }, "expected_version": { "title": "Expected Version", "type": "integer" }, "family": { "title": "Family", "type": "string" }, "verdict_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Verdict Id" } }, "required": [ "family", "expected_version", "actor" ], "title": "RoutingChangeRequest", "type": "object" }, "RoutingStateResponse": { "properties": { "routing": { "additionalProperties": true, "title": "Routing", "type": "object" } }, "required": [ "routing" ], "title": "RoutingStateResponse", "type": "object" }, "RowLinkResponse": { "properties": { "item_id": { "title": "Item Id", "type": "string" }, "item_table": { "title": "Item Table", "type": "string" }, "publication_id": { "title": "Publication Id", "type": "string" }, "token": { "title": "Token", "type": "string" }, "url": { "title": "Url", "type": "string" } }, "required": [ "publication_id", "item_table", "item_id", "token", "url" ], "title": "RowLinkResponse", "type": "object" }, "RuleHealthResponse": { "properties": { "band": { "title": "Band", "type": "string" }, "rule_id": { "title": "Rule Id", "type": "string" }, "score": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Score" }, "signal_counts": { "additionalProperties": { "type": "integer" }, "title": "Signal Counts", "type": "object" }, "signals": { "items": { "$ref": "#/components/schemas/HealthSignal" }, "title": "Signals", "type": "array" }, "trend": { "title": "Trend", "type": "string" } }, "required": [ "rule_id", "score", "band", "trend", "signal_counts", "signals" ], "title": "RuleHealthResponse", "type": "object" }, "RuleMatch": { "description": "A rule's match: every ``conditions`` term AND, when ``any_of`` is\nnon-empty, at least one of its terms — \"from X and (A or B)\".\n\nOne OR group, never nested: it is what a narrow mute needs (the sender,\nand any of several highlighted phrases), and anything wider is separate\nrules. Evaluate through :meth:`matches` so no consumer can drop the group\n— an evaluator that ignored it would match MORE mail than the rule says.", "properties": { "any_of": { "items": { "$ref": "#/components/schemas/MatchCondition" }, "title": "Any Of", "type": "array" }, "conditions": { "items": { "$ref": "#/components/schemas/MatchCondition" }, "title": "Conditions", "type": "array" } }, "title": "RuleMatch", "type": "object" }, "RunDetailResponse": { "properties": { "pack_invocations": { "items": { "$ref": "#/components/schemas/RecipeRunPackInvocation" }, "title": "Pack Invocations", "type": "array" }, "run": { "$ref": "#/components/schemas/RecipeRunDetail" } }, "required": [ "run", "pack_invocations" ], "title": "RunDetailResponse", "type": "object" }, "RunExtractionResponse": { "properties": { "batch_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Batch Id" }, "chunks_written": { "default": 0, "title": "Chunks Written", "type": "integer" }, "dispatched": { "title": "Dispatched", "type": "integer" }, "episodes_considered": { "title": "Episodes Considered", "type": "integer" }, "failed": { "title": "Failed", "type": "integer" }, "index_failed": { "default": 0, "title": "Index Failed", "type": "integer" }, "indexed": { "default": 0, "title": "Indexed", "type": "integer" }, "mentions_written": { "title": "Mentions Written", "type": "integer" } }, "required": [ "episodes_considered", "dispatched", "failed", "mentions_written" ], "title": "RunExtractionResponse", "type": "object" }, "RunListResponse": { "properties": { "runs": { "items": { "$ref": "#/components/schemas/RunSummary" }, "title": "Runs", "type": "array" } }, "required": [ "runs" ], "title": "RunListResponse", "type": "object" }, "RunRef": { "properties": { "id": { "title": "Id", "type": "string" }, "kind": { "title": "Kind", "type": "string" } }, "required": [ "kind", "id" ], "title": "RunRef", "type": "object" }, "RunRequested": { "properties": { "id": { "title": "Id", "type": "string" }, "status": { "default": "requested", "title": "Status", "type": "string" } }, "required": [ "id" ], "title": "RunRequested", "type": "object" }, "RunSummary": { "properties": { "cost_usd": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Cost Usd" }, "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "definition_id": { "format": "uuid", "title": "Definition Id", "type": "string" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error" }, "executor_kind": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Executor Kind" }, "executor_ref": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Executor Ref" }, "finished_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Finished At" }, "id": { "format": "uuid", "title": "Id", "type": "string" }, "latency_ms": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Latency Ms" }, "mode": { "title": "Mode", "type": "string" }, "model_used": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Model Used" }, "pack_invocation_count": { "default": 0, "title": "Pack Invocation Count", "type": "integer" }, "principal_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Principal Id" }, "rollout_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Rollout Id" }, "scheduled_action_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Scheduled Action Id" }, "started_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Started At" }, "status": { "title": "Status", "type": "string" }, "target_key": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Target Key" }, "tenant_id": { "format": "uuid", "title": "Tenant Id", "type": "string" }, "trigger_source": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Trigger Source" }, "version_id": { "format": "uuid", "title": "Version Id", "type": "string" } }, "required": [ "id", "mode", "definition_id", "version_id", "rollout_id", "tenant_id", "principal_id", "trigger_source", "scheduled_action_id", "target_key", "status", "executor_kind", "executor_ref", "model_used", "cost_usd", "latency_ms", "error", "created_at", "started_at", "finished_at" ], "title": "RunSummary", "type": "object" }, "RunnableBrowserAccount": { "properties": { "account_id": { "format": "uuid", "title": "Account Id", "type": "string" }, "allowed_origins": { "items": { "type": "string" }, "title": "Allowed Origins", "type": "array" }, "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Label" }, "origin_policy": { "enum": [ "open", "allowlist" ], "title": "Origin Policy", "type": "string" }, "startup_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Startup Url" }, "workshop_id": { "format": "uuid", "title": "Workshop Id", "type": "string" }, "workshop_name": { "title": "Workshop Name", "type": "string" } }, "required": [ "account_id", "label", "workshop_id", "workshop_name", "origin_policy", "allowed_origins", "startup_url" ], "title": "RunnableBrowserAccount", "type": "object" }, "RunnableBrowserAccountsResponse": { "description": "The browsing accounts the caller may run (``execute``), with the site policy\neach one enforces (TIDY-19316). Changing a policy stays the owner's (D17).", "properties": { "accounts": { "items": { "$ref": "#/components/schemas/RunnableBrowserAccount" }, "title": "Accounts", "type": "array" } }, "required": [ "accounts" ], "title": "RunnableBrowserAccountsResponse", "type": "object" }, "RunningWorkIngest": { "description": "Work the employee is RUNNING right now, as a link the owner can open.\n\nTIDY-17350 (F10 as narrowed by D13): the workshop exposes a URL; Tidy links\nit, labels it, and reports the health the connector observed — with the\ntime it was observed. Tidy never probes the URL and never proxies it, so\n``health_state`` is always someone else's reading, never ours.", "properties": { "health_detail": { "anyOf": [ { "maxLength": 300, "type": "string" }, { "type": "null" } ], "title": "Health Detail" }, "health_state": { "default": "unknown", "enum": [ "up", "unreachable", "gone", "unknown" ], "title": "Health State", "type": "string" }, "label": { "default": "", "maxLength": 200, "title": "Label", "type": "string" }, "last_checked_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Last Checked At" }, "links": { "default": [], "items": { "$ref": "#/components/schemas/EvidenceLinkIn" }, "title": "Links", "type": "array" }, "url": { "maxLength": 2000, "minLength": 1, "title": "Url", "type": "string" }, "workshop": { "default": "", "maxLength": 200, "title": "Workshop", "type": "string" } }, "required": [ "url" ], "title": "RunningWorkIngest", "type": "object" }, "RuntimeAsk": { "properties": { "credential_descriptor": { "title": "Credential Descriptor", "type": "string" }, "credential_id": { "title": "Credential Id", "type": "string" }, "expires_at": { "format": "date-time", "title": "Expires At", "type": "string" }, "id": { "title": "Id", "type": "string" }, "purpose": { "title": "Purpose", "type": "string" }, "request_id": { "title": "Request Id", "type": "string" }, "state": { "enum": [ "open", "approved", "declined", "expired" ], "title": "State", "type": "string" } }, "required": [ "id", "request_id", "credential_id", "credential_descriptor", "purpose", "state", "expires_at" ], "title": "RuntimeAsk", "type": "object" }, "RuntimeAskCreate": { "properties": { "conversation_id": { "format": "uuid", "title": "Conversation Id", "type": "string" }, "credential_id": { "format": "uuid", "title": "Credential Id", "type": "string" }, "purpose": { "maxLength": 1000, "minLength": 1, "title": "Purpose", "type": "string" }, "request_id": { "maxLength": 256, "minLength": 1, "title": "Request Id", "type": "string" }, "ttl_seconds": { "default": 900, "maximum": 3600.0, "minimum": 30.0, "title": "Ttl Seconds", "type": "integer" } }, "required": [ "conversation_id", "request_id", "credential_id", "purpose" ], "title": "RuntimeAskCreate", "type": "object" }, "RuntimeAskResolution": { "properties": { "grant": { "anyOf": [ { "$ref": "#/components/schemas/CredentialGrant" }, { "type": "null" } ], "default": null }, "id": { "title": "Id", "type": "string" }, "state": { "enum": [ "open", "approved", "declined", "expired" ], "title": "State", "type": "string" } }, "required": [ "id", "state" ], "title": "RuntimeAskResolution", "type": "object" }, "RuntimeRootResponse": { "properties": { "mode": { "enum": [ "employee", "workshop" ], "title": "Mode", "type": "string" }, "root_path": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Root Path" }, "workshop_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Workshop Id" } }, "required": [ "mode", "root_path", "workshop_id" ], "title": "RuntimeRootResponse", "type": "object" }, "RuntimeSkillInfo": { "description": "One VE runtime skill the installer ships (TIDY-14349 S3 / D4).", "properties": { "description": { "default": "", "title": "Description", "type": "string" }, "name": { "title": "Name", "type": "string" }, "version": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Version" } }, "required": [ "name" ], "title": "RuntimeSkillInfo", "type": "object" }, "RuntimeSkillInfo-Input": { "description": "One VE runtime skill the installer ships (TIDY-14349 S3 / D4).", "properties": { "description": { "default": "", "title": "Description", "type": "string" }, "name": { "title": "Name", "type": "string" }, "version": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Version" } }, "required": [ "name" ], "title": "RuntimeSkillInfo", "type": "object" }, "RuntimeSkillInfo-Output": {}, "RuntimeTokenResponse": { "properties": { "delivery_kind": { "enum": [ "scoped_token", "env_key", "stdio_config", "env_binding" ], "title": "Delivery Kind", "type": "string" }, "env_key": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Env Key" }, "expires_at": { "format": "date-time", "title": "Expires At", "type": "string" }, "plugin_id": { "title": "Plugin Id", "type": "string" }, "repositories": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "default": null, "title": "Repositories" }, "shipment_id": { "title": "Shipment Id", "type": "string" }, "stdio": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "title": "Stdio" }, "value": { "title": "Value", "type": "string" } }, "required": [ "shipment_id", "plugin_id", "delivery_kind", "value", "expires_at" ], "title": "RuntimeTokenResponse", "type": "object" }, "SMSSettingsResponse": { "description": "Response model for SMS notification settings.", "properties": { "phone_number": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Phone number in E.164 format", "title": "Phone Number" }, "phone_verified": { "default": false, "description": "Whether phone is verified", "title": "Phone Verified", "type": "boolean" }, "sms_consent_given": { "default": false, "description": "TCPA consent acknowledgment", "title": "Sms Consent Given", "type": "boolean" }, "sms_consent_timestamp": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "description": "Timestamp when consent was given", "title": "Sms Consent Timestamp" }, "sms_enabled": { "description": "Whether SMS is enabled", "title": "Sms Enabled", "type": "boolean" } }, "required": [ "sms_enabled" ], "title": "SMSSettingsResponse", "type": "object" }, "SMSSettingsUpdate": { "description": "Request model for updating SMS notification settings.\n\nPartial-update-safe (TIDY-12862 / D3, extended by TIDY-18057): every field\nis preserve-on-omit. The settings flow commits each step independently\n(enable, then consent, then phone, then verify), so a step-shaped body —\n``{\"phone_number\": \"+1…\"}`` alone, or a consent-only PUT — MUST be\naccepted and MUST NOT clobber anything already on file. That flow is what\nthe model previously contradicted: ``sms_enabled`` was the one field with\nno default, so every step-shaped PUT was a 400 ``validation_failed``\n(TIDY-18046's silent, permanent collapse).\n\nSemantics now:\n\n- Omitting ``sms_enabled`` leaves the stored value untouched. An explicit\n ``false`` disables; an explicit ``true`` enables. A body that omits\n ``sms_enabled`` can never *enable* SMS — on the rare path where the\n preferences row does not exist yet, the created row is disabled.\n- Omitting ``sms_consent_given`` / ``sms_consent_timestamp`` leaves the\n stored consent audit columns byte-identical (TCPA; unchanged).\n- A body carrying NO value at all is a **400**, raised before any write\n (TIDY-18062). It used to be a silent no-op 200 (TIDY-18057, ``d04c6423a4``);\n Dave reversed that on the TIDY-18062 build: partial bodies are legal and\n an empty one can only be a caller bug, and a 200 lets that bug ship\n silently — the exact failure class that hid TIDY-18046 for its whole\n existence. ``PUT /notifications/preferences`` applies the same rule, so\n the two doors agree; that agreement is the point of the collapse.\n\nMatches the sibling ``UpdateWidePreferencesRequest`` on\n``PUT /notifications/preferences`` on both counts.", "properties": { "phone_number": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Phone number (E.164 or 10-digit US; normalized to E.164)", "title": "Phone Number" }, "sms_consent_given": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "TCPA consent acknowledgment. Omit/None to preserve the stored consent value (preserve-on-omit); a boolean explicitly writes it.", "title": "Sms Consent Given" }, "sms_consent_timestamp": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "Timestamp when consent was given. Omit/None to preserve the stored value; written only when consent is being recorded.", "title": "Sms Consent Timestamp" }, "sms_enabled": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Enable/disable SMS notifications. Omit/None to preserve the stored value (preserve-on-omit); a boolean explicitly writes it. An omitted value never enables SMS.", "title": "Sms Enabled" } }, "title": "SMSSettingsUpdate", "type": "object" }, "SampleConversation": { "description": "A sample conversation from a group.", "properties": { "email_id": { "title": "Email Id", "type": "string" }, "sent_at": { "format": "date-time", "title": "Sent At", "type": "string" }, "subject": { "title": "Subject", "type": "string" }, "thread_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Thread Id" } }, "required": [ "subject", "thread_id", "email_id", "sent_at" ], "title": "SampleConversation", "type": "object" }, "SandboxElevation": { "description": "A request, and the grant it became.", "properties": { "agent_account_id": { "title": "Agent Account Id", "type": "string" }, "conversation_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Conversation Id" }, "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "decided_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Decided At" }, "expires_at": { "format": "date-time", "title": "Expires At", "type": "string" }, "id": { "title": "Id", "type": "string" }, "kind": { "enum": [ "docker_mount", "docker_container", "host_setup" ], "title": "Kind", "type": "string" }, "message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "On a request, what the asking employee should do now; on an allow, what the person allowing must know now (TIDY-20019: a device opens only once its workshop updates).", "title": "Message" }, "project_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Project Id" }, "push_job_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Push Job Id" }, "reason": { "title": "Reason", "type": "string" }, "risk": { "title": "Risk", "type": "string" }, "scope": { "anyOf": [ { "enum": [ "once", "project", "employee" ], "type": "string" }, { "type": "null" } ], "default": null, "title": "Scope" }, "spec": { "additionalProperties": true, "title": "Spec", "type": "object" }, "state": { "enum": [ "pending", "approved", "denied", "revoked", "expired", "succeeded", "failed" ], "title": "State", "type": "string" }, "title": { "title": "Title", "type": "string" }, "workshop_id": { "title": "Workshop Id", "type": "string" } }, "required": [ "id", "kind", "spec", "state", "title", "risk", "reason", "workshop_id", "agent_account_id", "expires_at", "created_at" ], "title": "SandboxElevation", "type": "object" }, "SandboxElevationAllow": { "properties": { "scope": { "description": "once: the asking conversation's next turn that uses it; project: every turn of the employee in the request's project; employee: every turn of the employee.", "enum": [ "once", "project", "employee" ], "title": "Scope", "type": "string" } }, "required": [ "scope" ], "title": "SandboxElevationAllow", "type": "object" }, "SandboxElevationRequest": { "description": "What an employee's turn asks for: one class, exactly specified.", "properties": { "kind": { "description": "docker_mount: one host path into your containers; docker_container: container settings the Docker filter refuses; host_setup: root setup steps on the workshop.", "enum": [ "docker_mount", "docker_container", "host_setup" ], "title": "Kind", "type": "string" }, "path": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "docker_mount: the absolute host path, exactly as refused.", "title": "Path" }, "preset": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "host_setup: a named set of steps instead (tidy_dev_box).", "title": "Preset" }, "read_only": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "docker_mount: true (the default) for a read-only mount.", "title": "Read Only" }, "reason": { "description": "Why, in plain words — the workshop's administrators read it.", "maxLength": 1000, "minLength": 10, "title": "Reason", "type": "string" }, "refusal": { "anyOf": [ { "maxLength": 500, "type": "string" }, { "type": "null" } ], "description": "The refusal you hit, verbatim.", "title": "Refusal" }, "settings": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "description": "docker_container: privileged, host_namespace:, capability:, device:/dev/, device_requests, unconfined_security.", "title": "Settings" }, "steps": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "description": "host_setup: {\"step\":\"sysctl\",\"key\":…,\"value\":…}; host folders belong in the workshop's own tree and need no root.", "title": "Steps" } }, "required": [ "kind", "reason" ], "title": "SandboxElevationRequest", "type": "object" }, "SandboxMetaResponse": { "properties": { "last_active_at": { "anyOf": [ {}, { "type": "null" } ], "title": "Last Active At" }, "reset_count": { "default": 0, "title": "Reset Count", "type": "integer" }, "seed_version": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Seed Version" }, "seeded_at": { "anyOf": [ {}, { "type": "null" } ], "title": "Seeded At" }, "tenant_id": { "title": "Tenant Id", "type": "string" } }, "required": [ "tenant_id" ], "title": "SandboxMetaResponse", "type": "object" }, "SandboxResetResponse": { "properties": { "counts": { "additionalProperties": { "type": "integer" }, "title": "Counts", "type": "object" }, "reset_count": { "title": "Reset Count", "type": "integer" }, "seed_version": { "title": "Seed Version", "type": "string" }, "tenant_id": { "title": "Tenant Id", "type": "string" } }, "required": [ "tenant_id", "seed_version", "reset_count", "counts" ], "title": "SandboxResetResponse", "type": "object" }, "SaveAnimatedAvatarResponse": { "description": "Where a saved animated avatar landed (TIDY-19211).", "properties": { "photo_id": { "title": "Photo Id", "type": "string" }, "storage_path": { "title": "Storage Path", "type": "string" } }, "required": [ "photo_id", "storage_path" ], "title": "SaveAnimatedAvatarResponse", "type": "object" }, "SaveAsTemplateRequest": { "properties": { "agent_account_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Agent Account Id" }, "ai_employee_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Ai Employee Id" }, "name": { "maxLength": 120, "minLength": 1, "title": "Name", "type": "string" }, "summary": { "default": "", "maxLength": 500, "title": "Summary", "type": "string" } }, "required": [ "name" ], "title": "SaveAsTemplateRequest", "type": "object" }, "SaveAsTemplateResponse": { "properties": { "template_id": { "title": "Template Id", "type": "string" }, "template_key": { "title": "Template Key", "type": "string" } }, "required": [ "template_id", "template_key" ], "title": "SaveAsTemplateResponse", "type": "object" }, "SaveLibraryRequest": { "properties": { "libraryItems": { "items": {}, "title": "Libraryitems", "type": "array" } }, "required": [ "libraryItems" ], "title": "SaveLibraryRequest", "type": "object" }, "SaveLibraryResponse": { "properties": { "libraryItems": { "items": {}, "title": "Libraryitems", "type": "array" }, "success": { "title": "Success", "type": "boolean" } }, "required": [ "success", "libraryItems" ], "title": "SaveLibraryResponse", "type": "object" }, "SaveMessageRequest": { "properties": { "event_id": { "title": "Event Id", "type": "string" }, "message_preview": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Message Preview" }, "note": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Note" }, "room_id": { "title": "Room Id", "type": "string" }, "sender_matrix_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Sender Matrix Id" } }, "required": [ "room_id", "event_id" ], "title": "SaveMessageRequest", "type": "object" }, "SavedMessageResponse": { "properties": { "eventId": { "title": "Eventid", "type": "string" }, "id": { "format": "uuid", "title": "Id", "type": "string" }, "messagePreview": { "title": "Messagepreview", "type": "string" }, "roomId": { "title": "Roomid", "type": "string" }, "savedAt": { "format": "date-time", "title": "Savedat", "type": "string" }, "senderAvatarUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Senderavatarurl" }, "senderDisplayName": { "title": "Senderdisplayname", "type": "string" }, "tags": { "items": { "type": "string" }, "title": "Tags", "type": "array" }, "tenantId": { "format": "uuid", "title": "Tenantid", "type": "string" }, "userId": { "format": "uuid", "title": "Userid", "type": "string" } }, "required": [ "id", "tenantId", "userId", "roomId", "eventId", "messagePreview", "senderDisplayName", "savedAt" ], "title": "SavedMessageResponse", "type": "object" }, "SavedMessagesPage": { "properties": { "items": { "items": { "$ref": "#/components/schemas/SavedMessageResponse" }, "title": "Items", "type": "array" }, "nextPage": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Nextpage" } }, "required": [ "items" ], "title": "SavedMessagesPage", "type": "object" }, "SavedQueryCreate": { "properties": { "cron_schedule": { "anyOf": [ { "maxLength": 120, "type": "string" }, { "type": "null" } ], "title": "Cron Schedule" }, "name": { "maxLength": 200, "minLength": 1, "title": "Name", "type": "string" }, "query_definition": { "additionalProperties": true, "title": "Query Definition", "type": "object" } }, "required": [ "name", "query_definition" ], "title": "SavedQueryCreate", "type": "object" }, "SavedQueryPatch": { "properties": { "cron_schedule": { "anyOf": [ { "maxLength": 120, "type": "string" }, { "type": "null" } ], "title": "Cron Schedule" }, "name": { "anyOf": [ { "maxLength": 200, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Name" }, "query_definition": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Query Definition" } }, "title": "SavedQueryPatch", "type": "object" }, "SavedQueryResponse": { "properties": { "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "cron_schedule": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Cron Schedule" }, "id": { "format": "uuid", "title": "Id", "type": "string" }, "last_run_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Last Run At" }, "name": { "title": "Name", "type": "string" }, "query_definition": { "additionalProperties": true, "title": "Query Definition", "type": "object" }, "updated_at": { "format": "date-time", "title": "Updated At", "type": "string" } }, "required": [ "id", "name", "query_definition", "created_at", "updated_at" ], "title": "SavedQueryResponse", "type": "object" }, "SavedQueryRunResponse": { "properties": { "row_count": { "title": "Row Count", "type": "integer" }, "rows": { "items": { "additionalProperties": true, "type": "object" }, "title": "Rows", "type": "array" }, "view": { "title": "View", "type": "string" } }, "required": [ "view", "row_count", "rows" ], "title": "SavedQueryRunResponse", "type": "object" }, "SavedSearchCreate": { "description": "Request to create a saved search.", "properties": { "description": { "anyOf": [ { "maxLength": 500, "type": "string" }, { "type": "null" } ], "description": "Optional description", "title": "Description" }, "filters": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "Parsed filters for quick application", "title": "Filters" }, "name": { "description": "Display name", "maxLength": 100, "minLength": 1, "title": "Name", "type": "string" }, "query": { "description": "Search query", "maxLength": 1000, "minLength": 1, "title": "Query", "type": "string" }, "room_id_filter": { "anyOf": [ { "maxLength": 500, "type": "string" }, { "type": "null" } ], "title": "Room Id Filter" }, "scope": { "default": "global", "enum": [ "global", "chat", "notes", "mail", "tasks", "podcast" ], "title": "Scope", "type": "string" } }, "required": [ "name", "query" ], "title": "SavedSearchCreate", "type": "object" }, "SavedSearchListResponse": { "description": "Response with list of saved searches.", "properties": { "searches": { "items": { "$ref": "#/components/schemas/SavedSearchResponse" }, "title": "Searches", "type": "array" }, "total": { "title": "Total", "type": "integer" } }, "required": [ "searches", "total" ], "title": "SavedSearchListResponse", "type": "object" }, "SavedSearchResponse": { "description": "Response with saved search details.", "properties": { "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "filters": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Filters" }, "id": { "format": "uuid", "title": "Id", "type": "string" }, "last_used_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Last Used At" }, "name": { "title": "Name", "type": "string" }, "query": { "title": "Query", "type": "string" }, "room_id_filter": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Room Id Filter" }, "scope": { "title": "Scope", "type": "string" }, "updated_at": { "format": "date-time", "title": "Updated At", "type": "string" }, "use_count": { "title": "Use Count", "type": "integer" } }, "required": [ "id", "name", "query", "description", "filters", "scope", "room_id_filter", "use_count", "last_used_at", "created_at", "updated_at" ], "title": "SavedSearchResponse", "type": "object" }, "SavedSearchUpdate": { "description": "Request to update a saved search.", "properties": { "description": { "anyOf": [ { "maxLength": 500, "type": "string" }, { "type": "null" } ], "title": "Description" }, "filters": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Filters" }, "name": { "anyOf": [ { "maxLength": 100, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Name" }, "query": { "anyOf": [ { "maxLength": 1000, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Query" }, "room_id_filter": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Room Id Filter" }, "scope": { "anyOf": [ { "enum": [ "global", "chat", "notes", "mail", "tasks", "podcast" ], "type": "string" }, { "type": "null" } ], "title": "Scope" } }, "title": "SavedSearchUpdate", "type": "object" }, "SavedViewContainer": { "description": "Discriminated authoring target (TIDY-14227 R6).\n\n- ``project`` — the view is parented to the project's page note and pinned\n into its saved-views nav (the original D16 form). ``id`` = project id.\n- ``note`` — the view's records row is parented to the note (an embedded\n view the note can render). ``id`` = note id.\n- ``workspace`` — a standalone view (no parent note); it surfaces in the\n workspace's Database Views nav. ``id`` is not required.", "properties": { "id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "description": "Target project/note id. Not required for 'workspace'.", "title": "Id" }, "type": { "enum": [ "project", "note", "workspace" ], "title": "Type", "type": "string" } }, "required": [ "type" ], "title": "SavedViewContainer", "type": "object" }, "SavedViewCreateRequest": { "description": "Request body to author (create/upsert) a saved database view.\n\nThe single canonical saved-view form (D16): facet data source + filters +\nlayout + sort + per-layout view state + title. Idempotent by\n(container, title). ``container`` generalizes the original project-only\ntarget (TIDY-14227); ``project_id`` remains as the additive back-compat\nspelling of ``container={type: 'project', id}``.", "properties": { "aggregates": { "additionalProperties": { "type": "string" }, "description": "Column aggregates the view renders: field_key -> aggregate function (e.g. {'due_datetime': 'count'}). Persisted at properties.aggregates, the location the renderer reads (TIDY-14305 / B6). Empty by default.", "title": "Aggregates", "type": "object" }, "confirm_overwrite": { "default": false, "description": "Ledgered writes only: update an existing same-title view instead of suffixing. The explicit confirmation D32 requires.", "title": "Confirm Overwrite", "type": "boolean" }, "container": { "anyOf": [ { "$ref": "#/components/schemas/SavedViewContainer" }, { "type": "null" } ], "description": "Authoring target: project, note, or workspace (standalone)." }, "facet": { "description": "Facet slug the view queries (e.g. 'task').", "minLength": 1, "title": "Facet", "type": "string" }, "filters": { "additionalProperties": true, "description": "FilterGroup JSON (logic + conditions), including within_subtree.", "title": "Filters", "type": "object" }, "layout": { "description": "View layout: table/kanban/calendar/timeline/gantt/card/gallery/planning/outline/chart/hierarchy. Validated against the facet's view mappings; chart and hierarchy are validated against their 'view_state' config instead (they bind fields there, not in the facet).", "title": "Layout", "type": "string" }, "operation_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "description": "Principal-owned agent operation id (TIDY-15409 D32). When present the write is ledgered: a retry with the same id and the same input replays the recorded result instead of authoring a second view, and a same-title view this operation did not create is NEVER updated — it gets a ' (N)' suffix unless you name 'target_saved_view_id' + 'target_version' or set 'confirm_overwrite'. Omit it for the legacy upsert-by-(container, title).", "title": "Operation Id" }, "pinned": { "default": true, "description": "Pin the view into the project's saved-views nav (default true).", "title": "Pinned", "type": "boolean" }, "project_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "description": "Legacy target: the project the view attaches to. Prefer 'container'.", "title": "Project Id" }, "sort": { "items": { "$ref": "#/components/schemas/SavedViewSortClause" }, "title": "Sort", "type": "array" }, "target_saved_view_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "description": "Update THIS view explicitly. Requires 'target_version'; a version that no longer matches is a 409 rather than a silent overwrite.", "title": "Target Saved View Id" }, "target_version": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "The version you read from the view you intend to replace (the 'version' field of a previous author/preview response).", "title": "Target Version" }, "title": { "description": "View title; upsert key with project.", "minLength": 1, "title": "Title", "type": "string" }, "view_state": { "additionalProperties": true, "description": "Per-layout view state, persisted at properties.layout_settings (e.g. Gantt zoom/collapse). The 'chart' and 'hierarchy' sections are validated (TIDY-15410): chart {kind, dimension: {field, bucket?}, measure: {fn, field?}, ratio?} and hierarchy {parentField|linkType, orientation, defaultDepth, viewportMode, nodeTypes, arrangements}. A chart view must carry a chart config.", "title": "View State", "type": "object" }, "visible_columns": { "description": "Ordered field keys the view shows as columns; empty means the renderer's default column set. Persisted at properties.visible_columns (TIDY-14305).", "items": { "type": "string" }, "title": "Visible Columns", "type": "array" } }, "required": [ "title", "facet", "layout" ], "title": "SavedViewCreateRequest", "type": "object" }, "SavedViewCreateResponse": { "description": "Result of authoring a saved view.", "properties": { "action": { "enum": [ "created", "updated" ], "title": "Action", "type": "string" }, "binding": { "anyOf": [ { "$ref": "#/components/schemas/ViewBinding" }, { "type": "null" } ], "default": null, "description": "What the view draws from its facet's definition, resolved by the same check that admitted it (TIDY-18514)." }, "container_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "default": null, "title": "Container Id" }, "container_type": { "default": "project", "enum": [ "project", "note", "workspace" ], "title": "Container Type", "type": "string" }, "database_facet_id": { "format": "uuid", "title": "Database Facet Id", "type": "string" }, "facet": { "title": "Facet", "type": "string" }, "layout": { "title": "Layout", "type": "string" }, "operation_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "default": null, "description": "Echo of the ledgered agent operation, when one was used.", "title": "Operation Id" }, "pinned": { "title": "Pinned", "type": "boolean" }, "project_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "default": null, "title": "Project Id" }, "replayed": { "default": false, "description": "True when this response was replayed from the operation ledger rather than authored now.", "title": "Replayed", "type": "boolean" }, "resolved_title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "The title actually written when a D32 collision forced a ' (N)' suffix; absent when it equals the requested title.", "title": "Resolved Title" }, "title": { "title": "Title", "type": "string" }, "version": { "default": 0, "description": "Optimistic-concurrency token for this view (epoch microseconds of its updated_at). Send it back as 'target_version' to update this exact view.", "title": "Version", "type": "integer" } }, "required": [ "database_facet_id", "title", "layout", "facet", "action", "pinned" ], "title": "SavedViewCreateResponse", "type": "object" }, "SavedViewDeleteResponse": { "description": "What deleting a saved view removed (TIDY-19456).", "properties": { "database_facet_id": { "format": "uuid", "title": "Database Facet Id", "type": "string" }, "deleted": { "default": true, "title": "Deleted", "type": "boolean" }, "operation_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "default": null, "description": "Echo of the ledgered agent operation, when one was used.", "title": "Operation Id" }, "removed_from_note_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "default": null, "description": "The note whose body the view's database node was taken out of; absent when no note you can edit embedded it.", "title": "Removed From Note Id" }, "replayed": { "default": false, "description": "True when this response was replayed from the operation ledger rather than performed now.", "title": "Replayed", "type": "boolean" }, "title": { "title": "Title", "type": "string" }, "unpinned": { "default": 0, "description": "How many of your saved-views nav pins for it were removed.", "title": "Unpinned", "type": "integer" } }, "required": [ "database_facet_id", "title" ], "title": "SavedViewDeleteResponse", "type": "object" }, "SavedViewId": { "description": "Typed primitive ID for saved_views (prefix 'W').", "examples": [ "W-550e8400-e29b-41d4-a716-446655440000" ], "pattern": "^W-[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "title": "SavedViewId", "type": "string", "x-tidy-typed-id-prefix": "W", "x-tidy-typed-id-table": "saved_views" }, "SavedViewSortClause": { "description": "A single sort clause carried into the saved view's sort_order\n(QuerySpec V1 SortClause).", "properties": { "direction": { "default": "asc", "enum": [ "asc", "desc" ], "title": "Direction", "type": "string" }, "field": { "minLength": 1, "title": "Field", "type": "string" }, "nulls": { "anyOf": [ { "enum": [ "first", "last" ], "type": "string" }, { "type": "null" } ], "description": "Explicit null placement (TIDY-14224); executor type default when absent.", "title": "Nulls" } }, "required": [ "field" ], "title": "SavedViewSortClause", "type": "object" }, "ScanResponse": { "description": "Response from scanning for stale emails.", "properties": { "new_follow_ups": { "title": "New Follow Ups", "type": "integer" }, "total_pending": { "title": "Total Pending", "type": "integer" } }, "required": [ "new_follow_ups", "total_pending" ], "title": "ScanResponse", "type": "object" }, "ScheduleDeletionRequest": { "description": "Request model for scheduling account deletion (TIDY-7383).", "properties": { "confirm_email": { "anyOf": [ { "maxLength": 320, "type": "string" }, { "type": "null" } ], "deprecated": true, "description": "Ignored. Never an authentication factor.", "title": "Confirm Email" }, "immediate": { "default": false, "description": "If true, execute immediately (owners only)", "title": "Immediate", "type": "boolean" }, "password": { "anyOf": [ { "maxLength": 1024, "type": "string" }, { "type": "null" } ], "deprecated": true, "description": "Ignored. Use the session-bound step-up API.", "title": "Password" }, "reason": { "anyOf": [ { "maxLength": 500, "type": "string" }, { "type": "null" } ], "title": "Reason" } }, "title": "ScheduleDeletionRequest", "type": "object" }, "ScheduleResponse": { "description": "Response for both schedule endpoints.", "properties": { "changed": { "title": "Changed", "type": "boolean" }, "state": { "title": "State", "type": "string" } }, "required": [ "changed", "state" ], "title": "ScheduleResponse", "type": "object" }, "ScheduleSendRequest": { "description": "Request body for scheduling a send.", "properties": { "email_source_config_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "description": "Email source to use", "title": "Email Source Config Id" }, "scheduled_send_at": { "description": "When to send the email", "format": "date-time", "title": "Scheduled Send At", "type": "string" } }, "required": [ "scheduled_send_at" ], "title": "ScheduleSendRequest", "type": "object" }, "ScheduleSendResponse": { "description": "Response for schedule operation.", "properties": { "id": { "description": "Draft UUID", "format": "uuid", "title": "Id", "type": "string" }, "message": { "description": "Result message", "title": "Message", "type": "string" }, "scheduled_send_at": { "description": "Scheduled send time", "format": "date-time", "title": "Scheduled Send At", "type": "string" }, "success": { "description": "Whether scheduling succeeded", "title": "Success", "type": "boolean" } }, "required": [ "id", "success", "message", "scheduled_send_at" ], "title": "ScheduleSendResponse", "type": "object" }, "ScheduledFireNotifyRequest": { "properties": { "fire_at": { "format": "date-time", "title": "Fire At", "type": "string" }, "job_id": { "format": "uuid", "title": "Job Id", "type": "string" }, "tenant_id": { "format": "uuid", "title": "Tenant Id", "type": "string" } }, "required": [ "tenant_id", "job_id", "fire_at" ], "title": "ScheduledFireNotifyRequest", "type": "object" }, "ScheduledJobCreate": { "properties": { "agent_account_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The employee that runs the job. Omitted means the CALLER, which is how a VE schedules its own duty.", "title": "Agent Account Id" }, "browser_run": { "deprecated": true, "description": "Retired: requests naming this field return 410 browser_runs_retired. Ask the employee in chat.", "title": "Browser Run" }, "command": { "anyOf": [ { "maxLength": 4000, "type": "string" }, { "type": "null" } ], "description": "One shell command line the employee's workshop runs at each fire, with no model turn. Workshop employees only.", "title": "Command" }, "command_timeout_sec": { "anyOf": [ { "maximum": 3600.0, "minimum": 1.0, "type": "integer" }, { "type": "null" } ], "description": "Seconds before a run is stopped and recorded as failed. Default 300.", "title": "Command Timeout Sec" }, "conversation_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Server conversation context for DM/room runAs defaults. The server binds it to the creator and employee before use.", "title": "Conversation Id" }, "credential_ids": { "description": "Credential ids this job may request at fire time.", "items": { "format": "uuid", "type": "string" }, "maxItems": 32, "title": "Credential Ids", "type": "array" }, "cron": { "default": "", "description": "Five-field cron, the simple path. Empty exactly when the recurrence fields below carry the schedule instead.", "maxLength": 200, "title": "Cron", "type": "string" }, "ends_at": { "anyOf": [ { "maxLength": 10, "type": "string" }, { "type": "null" } ], "description": "YYYY-MM-DD. No run after this date.", "title": "Ends At" }, "max_runs": { "anyOf": [ { "maximum": 1000.0, "minimum": 1.0, "type": "integer" }, { "type": "null" } ], "description": "With repeats='number of times': how many scheduled runs, 1 to 1000.", "title": "Max Runs" }, "name": { "maxLength": 200, "minLength": 1, "title": "Name", "type": "string" }, "prompt": { "default": "", "description": "What the employee does each time the job fires. For a script job, what it is woken with when the command fails; empty records a failure on the job's runs and wakes no one.", "maxLength": 20000, "title": "Prompt", "type": "string" }, "provenance": { "default": "ve", "title": "Provenance", "type": "string" }, "recurrence_byday": { "anyOf": [ { "items": { "type": "string" }, "maxItems": 7, "type": "array" }, { "type": "null" } ], "description": "Weekday names, or the single entry 'business day'. Weekly takes every listed day; monthly and yearly take exactly one.", "title": "Recurrence Byday" }, "recurrence_freq": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "weekly | monthly | yearly. Omit for a cron job.", "title": "Recurrence Freq" }, "recurrence_interval": { "anyOf": [ { "maximum": 52.0, "minimum": 1.0, "type": "integer" }, { "type": "null" } ], "description": "1 is every period, 2 every other. Above 1 needs starts_at.", "title": "Recurrence Interval" }, "recurrence_position": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "first | second | third | fourth | last. Monthly/yearly only.", "title": "Recurrence Position" }, "recurrence_time": { "anyOf": [ { "maxLength": 5, "type": "string" }, { "type": "null" } ], "description": "24-hour HH:MM in the job's timezone.", "title": "Recurrence Time" }, "repeats": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "'until stopped' (the default) or 'number of times'.", "title": "Repeats" }, "run_as": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "owner | scope_shared | scope_floor. Omitted defaults to owner in DM/home contexts and scope_shared in rooms.", "title": "Run As" }, "starts_at": { "anyOf": [ { "maxLength": 10, "type": "string" }, { "type": "null" } ], "description": "YYYY-MM-DD. No run before this date.", "title": "Starts At" }, "timezone": { "default": "UTC", "description": "Accepted and ignored (TIDY-19335): a job always runs in the timezone of the person it acts for, which the response echoes.", "maxLength": 64, "title": "Timezone", "type": "string" } }, "required": [ "name" ], "title": "ScheduledJobCreate", "type": "object" }, "ScheduledJobCreated": { "properties": { "command": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Command" }, "consent_state": { "default": "not_required", "title": "Consent State", "type": "string" }, "cron": { "title": "Cron", "type": "string" }, "enabled": { "title": "Enabled", "type": "boolean" }, "existing": { "default": false, "title": "Existing", "type": "boolean" }, "id": { "title": "Id", "type": "string" }, "name": { "title": "Name", "type": "string" }, "private_to_requester": { "default": false, "title": "Private To Requester", "type": "boolean" }, "provenance": { "title": "Provenance", "type": "string" }, "run_as": { "title": "Run As", "type": "string" }, "run_as_status": { "default": "active", "title": "Run As Status", "type": "string" }, "timezone": { "title": "Timezone", "type": "string" } }, "required": [ "id", "name", "cron", "timezone", "enabled", "provenance", "run_as" ], "title": "ScheduledJobCreated", "type": "object" }, "ScheduledMessageRequest": { "properties": { "payload": { "additionalProperties": true, "title": "Payload", "type": "object" }, "room_id": { "title": "Room Id", "type": "string" }, "scheduled_for": { "format": "date-time", "title": "Scheduled For", "type": "string" } }, "required": [ "room_id", "scheduled_for", "payload" ], "title": "ScheduledMessageRequest", "type": "object" }, "ScheduledMessageResponse": { "properties": { "account_id": { "format": "uuid", "title": "Account Id", "type": "string" }, "attempts": { "title": "Attempts", "type": "integer" }, "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "id": { "format": "uuid", "title": "Id", "type": "string" }, "last_error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Error" }, "payload": { "additionalProperties": true, "title": "Payload", "type": "object" }, "room_id": { "title": "Room Id", "type": "string" }, "scheduled_for": { "format": "date-time", "title": "Scheduled For", "type": "string" }, "sent_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Sent At" }, "sent_event_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Sent Event Id" }, "status": { "title": "Status", "type": "string" }, "tenant_id": { "format": "uuid", "title": "Tenant Id", "type": "string" }, "updated_at": { "format": "date-time", "title": "Updated At", "type": "string" } }, "required": [ "id", "tenant_id", "account_id", "room_id", "scheduled_for", "payload", "status", "attempts", "last_error", "sent_event_id", "sent_at", "created_at", "updated_at" ], "title": "ScheduledMessageResponse", "type": "object" }, "ScheduledTrigger": { "additionalProperties": false, "description": "Fires on a cron schedule or relative to a date field on the item.", "properties": { "cron": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cron" }, "kind": { "const": "scheduled", "title": "Kind", "type": "string" }, "offset": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO-8601 duration offset from relative_to_field, e.g. 'P1D' or '-PT2H'.", "title": "Offset" }, "relative_to_field": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Relative To Field" } }, "required": [ "kind" ], "title": "ScheduledTrigger", "type": "object" }, "SchedulingRoleResponse": { "description": "The caller's iTIP standing on one event (TIDY-16963).", "properties": { "can_counter": { "default": false, "title": "Can Counter", "type": "boolean" }, "can_resend": { "default": false, "title": "Can Resend", "type": "boolean" }, "event_id": { "title": "Event Id", "type": "string" }, "ics_method": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Ics Method" }, "organizer_email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Organizer Email" }, "organizer_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Organizer Name" }, "other_attendee_count": { "default": 0, "title": "Other Attendee Count", "type": "integer" }, "role": { "enum": [ "organizer", "attendee", "none" ], "title": "Role", "type": "string" }, "self_email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The address the caller is invited as, if any.", "title": "Self Email" }, "sequence": { "default": 0, "title": "Sequence", "type": "integer" } }, "required": [ "event_id", "role" ], "title": "SchedulingRoleResponse", "type": "object" }, "ScmChangedFileUrl": { "description": "One changed file of a commit, with its blob-at-ref deep link (R10).\n\nThe URL is derived server-side through the provider's builders like every\nother SCM link (D2); the client renders it, never composes it.", "properties": { "path": { "title": "Path", "type": "string" }, "url": { "title": "Url", "type": "string" } }, "required": [ "path", "url" ], "title": "ScmChangedFileUrl", "type": "object" }, "ScmDiffHunk": { "properties": { "header": { "title": "Header", "type": "string" }, "lines": { "default": [], "items": { "$ref": "#/components/schemas/ScmDiffLine" }, "title": "Lines", "type": "array" }, "new_lines": { "title": "New Lines", "type": "integer" }, "new_start": { "title": "New Start", "type": "integer" }, "old_lines": { "title": "Old Lines", "type": "integer" }, "old_start": { "title": "Old Start", "type": "integer" } }, "required": [ "header", "old_start", "old_lines", "new_start", "new_lines" ], "title": "ScmDiffHunk", "type": "object" }, "ScmDiffLine": { "properties": { "kind": { "enum": [ "context", "added", "removed" ], "title": "Kind", "type": "string" }, "new_line": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "New Line" }, "old_line": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Old Line" }, "text": { "title": "Text", "type": "string" } }, "required": [ "kind", "text" ], "title": "ScmDiffLine", "type": "object" }, "ScmFileDiff": { "properties": { "additions": { "default": 0, "title": "Additions", "type": "integer" }, "deletions": { "default": 0, "title": "Deletions", "type": "integer" }, "hunks": { "default": [], "items": { "$ref": "#/components/schemas/ScmDiffHunk" }, "title": "Hunks", "type": "array" }, "old_path": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Old Path" }, "path": { "title": "Path", "type": "string" }, "status": { "enum": [ "added", "modified", "deleted", "renamed", "copied" ], "title": "Status", "type": "string" }, "truncated": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "title": "Truncated" }, "unavailable_reason": { "anyOf": [ { "enum": [ "binary", "submodule", "denied_name", "too_large" ], "type": "string" }, { "type": "null" } ], "default": null, "title": "Unavailable Reason" } }, "required": [ "path", "status" ], "title": "ScmFileDiff", "type": "object" }, "ScmObjectContentResponse": { "description": "Live provider content for one SCM object (TIDY-17132 / S5, R5).\n\nNothing here is stored metadata — the payload is fetched live from the\nprovider with a per-operation repo-scoped token (D7), which is never part\nof this response and never logged. ``truncated`` is honest: when the\ncontent exceeds ``max_bytes`` the payload is capped and the flag says so —\nnever silently shortened.", "properties": { "content": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "title": "Content" }, "id": { "title": "Id", "type": "string" }, "kind": { "enum": [ "commit", "pr", "issue", "file_at_ref" ], "title": "Kind", "type": "string" }, "natural_key": { "title": "Natural Key", "type": "string" }, "provider": { "title": "Provider", "type": "string" }, "repo_full_name": { "title": "Repo Full Name", "type": "string" }, "size_bytes": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Size Bytes" }, "text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Text" }, "text_decodable": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "title": "Text Decodable" }, "truncated": { "default": false, "title": "Truncated", "type": "boolean" }, "truncated_note": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Truncated Note" }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Url" } }, "required": [ "id", "kind", "provider", "repo_full_name", "natural_key" ], "title": "ScmObjectContentResponse", "type": "object" }, "ScmObjectDiffResponse": { "description": "One SCM object's changes, parsed and redacted once on the server.\n\n``scope`` is always ``ref`` — a commit, a PR, or a file at a ref is an\nexplicit point in history, not a working tree — and ``scope_detail`` names\nwhich, so the viewer's header says what it is showing.", "properties": { "file_count": { "default": 0, "title": "File Count", "type": "integer" }, "files": { "default": [], "items": { "$ref": "#/components/schemas/ScmFileDiff" }, "title": "Files", "type": "array" }, "repo_handle": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Repo Handle" }, "scope": { "const": "ref", "default": "ref", "title": "Scope", "type": "string" }, "scope_detail": { "title": "Scope Detail", "type": "string" }, "snapshot_hash": { "default": "", "title": "Snapshot Hash", "type": "string" }, "truncated": { "default": false, "title": "Truncated", "type": "boolean" } }, "required": [ "scope_detail" ], "title": "ScmObjectDiffResponse", "type": "object" }, "ScmObjectResponse": { "description": "One SCM object from the metadata index, plus its live-derived URL.\n\n``url`` is computed per request from the provider builders (D2) — it is\nnever stored, so a repo rename or provider change can never serve a stale\nlink.", "properties": { "author_login": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Author Login" }, "author_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Author Name" }, "authored_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Authored At" }, "changed_file_urls": { "default": [], "items": { "$ref": "#/components/schemas/ScmChangedFileUrl" }, "title": "Changed File Urls", "type": "array" }, "first_referenced_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "First Referenced At" }, "id": { "title": "Id", "type": "string" }, "kind": { "enum": [ "commit", "pr", "issue", "file_at_ref" ], "title": "Kind", "type": "string" }, "metadata": { "additionalProperties": true, "title": "Metadata", "type": "object" }, "natural_key": { "title": "Natural Key", "type": "string" }, "provider": { "title": "Provider", "type": "string" }, "removed": { "title": "Removed", "type": "boolean" }, "removed_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Removed Reason" }, "repo_full_name": { "title": "Repo Full Name", "type": "string" }, "state": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "State" }, "sync_severed": { "title": "Sync Severed", "type": "boolean" }, "title": { "title": "Title", "type": "string" }, "url": { "title": "Url", "type": "string" } }, "required": [ "id", "kind", "title", "provider", "repo_full_name", "natural_key", "metadata", "sync_severed", "removed", "url" ], "title": "ScmObjectResponse", "type": "object" }, "ScmObjectSearchResponse": { "description": "The search endpoint's envelope.", "properties": { "results": { "items": { "$ref": "#/components/schemas/ScmObjectSearchRow" }, "title": "Results", "type": "array" }, "total_count": { "title": "Total Count", "type": "integer" } }, "required": [ "results", "total_count" ], "title": "ScmObjectSearchResponse", "type": "object" }, "ScmObjectSearchRow": { "description": "One hit of ``searchScmObjects`` (TIDY-17132 / S5).\n\nThe same vocabulary the unified-search lane and the picker render: a typed\nid to link, kind/state/author for the label, and the live-derived native\nURL (D2) so no client composes a provider link.", "properties": { "author_login": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Author Login" }, "authored_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Authored At" }, "id": { "title": "Id", "type": "string" }, "kind": { "enum": [ "commit", "pr", "issue", "file_at_ref" ], "title": "Kind", "type": "string" }, "natural_key": { "title": "Natural Key", "type": "string" }, "provider": { "title": "Provider", "type": "string" }, "repo_full_name": { "title": "Repo Full Name", "type": "string" }, "state": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "State" }, "title": { "default": "", "title": "Title", "type": "string" }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Url" } }, "required": [ "id", "kind", "provider", "repo_full_name", "natural_key" ], "title": "ScmObjectSearchRow", "type": "object" }, "ScmObjectSuggestResponse": { "description": "The suggest endpoint's envelope.", "properties": { "results": { "items": { "$ref": "#/components/schemas/ScmObjectSuggestRow" }, "title": "Results", "type": "array" } }, "required": [ "results" ], "title": "ScmObjectSuggestResponse", "type": "object" }, "ScmObjectSuggestRow": { "description": "One picker typeahead hit (TIDY-17130 / S3, R7).\n\nThe minimal projection the picker renders: a typed id to insert, the kind\nto pick an icon, and enough label text (message/title/author/SHA) for the\nuser to tell two hits apart. The full ``ScmObjectResponse`` — with its\nlive-derived URL and file fan-out — is the read path's shape, not this.", "properties": { "author_login": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Author Login" }, "authored_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Authored At" }, "id": { "title": "Id", "type": "string" }, "kind": { "enum": [ "commit", "pr", "issue", "file_at_ref" ], "title": "Kind", "type": "string" }, "natural_key": { "title": "Natural Key", "type": "string" }, "state": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "State" }, "title": { "default": "", "title": "Title", "type": "string" } }, "required": [ "id", "kind", "natural_key" ], "title": "ScmObjectSuggestRow", "type": "object" }, "ScopeCatalogBundle": { "properties": { "name": { "title": "Name", "type": "string" }, "scopes": { "items": { "type": "string" }, "title": "Scopes", "type": "array" }, "title": { "title": "Title", "type": "string" } }, "required": [ "name", "title", "scopes" ], "title": "ScopeCatalogBundle", "type": "object" }, "ScopeCatalogEntry": { "properties": { "category": { "title": "Category", "type": "string" }, "description": { "title": "Description", "type": "string" }, "destructive": { "title": "Destructive", "type": "boolean" }, "title": { "title": "Title", "type": "string" }, "value": { "title": "Value", "type": "string" } }, "required": [ "value", "title", "description", "category", "destructive" ], "title": "ScopeCatalogEntry", "type": "object" }, "ScopeCatalogResponse": { "properties": { "bundles": { "items": { "$ref": "#/components/schemas/ScopeCatalogBundle" }, "title": "Bundles", "type": "array" }, "scopes": { "items": { "$ref": "#/components/schemas/ScopeCatalogEntry" }, "title": "Scopes", "type": "array" } }, "required": [ "scopes", "bundles" ], "title": "ScopeCatalogResponse", "type": "object" }, "ScoreBreakdownResponse": { "description": "Full score breakdown showing each factor's contribution.", "properties": { "factors": { "items": { "$ref": "#/components/schemas/ScoreFactorResponse" }, "title": "Factors", "type": "array" }, "total": { "title": "Total", "type": "number" } }, "required": [ "total", "factors" ], "title": "ScoreBreakdownResponse", "type": "object" }, "ScoreFactorResponse": { "description": "Single scoring factor in a score breakdown.", "properties": { "input": { "anyOf": [ { "type": "string" }, { "type": "integer" }, { "type": "number" }, { "type": "boolean" } ], "title": "Input" }, "max": { "title": "Max", "type": "number" }, "name": { "title": "Name", "type": "string" }, "value": { "title": "Value", "type": "number" } }, "required": [ "name", "value", "input", "max" ], "title": "ScoreFactorResponse", "type": "object" }, "ScratchpadResponse": { "properties": { "content": { "title": "Content", "type": "string" }, "note_id": { "title": "Note Id", "type": "string" }, "project_id": { "title": "Project Id", "type": "string" }, "title": { "title": "Title", "type": "string" }, "updated_at": { "format": "date-time", "title": "Updated At", "type": "string" } }, "required": [ "note_id", "project_id", "title", "content", "updated_at" ], "title": "ScratchpadResponse", "type": "object" }, "ScratchpadSetRequest": { "properties": { "content": { "description": "Full markdown checklist body", "minLength": 1, "title": "Content", "type": "string" } }, "required": [ "content" ], "title": "ScratchpadSetRequest", "type": "object" }, "ScreeningStatsResponse": { "properties": { "approved_count": { "title": "Approved Count", "type": "integer" }, "blocked_count": { "title": "Blocked Count", "type": "integer" }, "pending_count": { "title": "Pending Count", "type": "integer" } }, "required": [ "pending_count", "approved_count", "blocked_count" ], "title": "ScreeningStatsResponse", "type": "object" }, "SealedEnvelope": { "additionalProperties": false, "description": "A secret sealed in the browser to the connector's re-auth key.\n\nTIDY-19271 — the only shape a sign-in secret may take on its way through\nTidy: ciphertext the server relays and cannot open. Every field is bounded\nbase64/hex and nothing else is accepted, so a plaintext token cannot ride\nin beside it.", "properties": { "alg": { "const": "x25519-hkdf-aes256gcm", "title": "Alg", "type": "string" }, "ct": { "maxLength": 16384, "minLength": 1, "pattern": "^[A-Za-z0-9+/]+=*$", "title": "Ct", "type": "string" }, "epk": { "maxLength": 256, "minLength": 1, "pattern": "^[A-Za-z0-9+/]+=*$", "title": "Epk", "type": "string" }, "nonce": { "maxLength": 64, "minLength": 1, "pattern": "^[A-Za-z0-9+/]+=*$", "title": "Nonce", "type": "string" }, "recipient_key_id": { "maxLength": 64, "minLength": 1, "pattern": "^[0-9a-f]+$", "title": "Recipient Key Id", "type": "string" } }, "required": [ "alg", "epk", "nonce", "ct", "recipient_key_id" ], "title": "SealedEnvelope", "type": "object" }, "SeatInviteRequest": { "properties": { "email": { "title": "Email", "type": "string" }, "role": { "default": "Member", "enum": [ "Member", "Viewer" ], "title": "Role", "type": "string" } }, "required": [ "email" ], "title": "SeatInviteRequest", "type": "object" }, "SeatItem": { "description": "A seat the workspace bought, and who is in it.", "properties": { "billing_active": { "default": true, "description": "False only for a legacy invitation not yet billed; its seat starts billing on acceptance.", "title": "Billing Active", "type": "boolean" }, "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "id": { "title": "Id", "type": "string" }, "invitation_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Invitation Code" }, "invitation_email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Invitation Email" }, "invitation_expires_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Invitation Expires At" }, "invitation_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Invitation Id" }, "invitation_role": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Invitation Role" }, "occupant_account_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Occupant Account Id" }, "occupant_email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Occupant Email" }, "occupant_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Occupant Name" }, "state": { "description": "occupied: a member sits in it. pending: an invitation was sent into it. vacant: paid and open.", "enum": [ "occupied", "pending", "vacant" ], "title": "State", "type": "string" }, "tier": { "title": "Tier", "type": "string" } }, "required": [ "id", "tier", "state", "created_at" ], "title": "SeatItem", "type": "object" }, "SeatPurchaseRequest": { "properties": { "email": { "title": "Email", "type": "string" }, "expected_amount_cents": { "anyOf": [ { "minimum": 0.0, "type": "integer" }, { "type": "null" } ], "description": "The confirmed quote's amount_due_now_cents. A changed price refuses the purchase (409) before charging.", "title": "Expected Amount Cents" }, "proration_date": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "The confirmed quote's proration_date (unix seconds), valid for five minutes.", "title": "Proration Date" }, "role": { "default": "Member", "enum": [ "Member", "Viewer" ], "title": "Role", "type": "string" }, "tier": { "enum": [ "core", "plus", "max" ], "title": "Tier", "type": "string" } }, "required": [ "tier", "email" ], "title": "SeatPurchaseRequest", "type": "object" }, "SeatPurchaseResponse": { "properties": { "charged_cents": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "What Stripe charged for the seat; null when not billed now.", "title": "Charged Cents" }, "invitation_sent": { "title": "Invitation Sent", "type": "boolean" }, "invoice_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Invoice Id" }, "message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Why the invitation was not sent; the seat is paid and can be re-invited into.", "title": "Message" }, "seat": { "$ref": "#/components/schemas/SeatItem" } }, "required": [ "seat", "invitation_sent" ], "title": "SeatPurchaseResponse", "type": "object" }, "SeatQuoteResponse": { "description": "What one more seat at ``tier`` costs, before anything is charged.", "properties": { "amount_due_now_cents": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Charged when the purchase is confirmed: the seat prorated for the rest of the current billing period, monthly or annual; 0 during a Stripe trial.", "title": "Amount Due Now Cents" }, "billed": { "description": "now: confirming charges amount_due_now_cents. with_plan: no subscription yet, the seat is billed with the plan at checkout. never: the workspace is billing exempt.", "enum": [ "now", "with_plan", "never" ], "title": "Billed", "type": "string" }, "billing_interval": { "anyOf": [ { "enum": [ "monthly", "annual" ], "type": "string" }, { "type": "null" } ], "default": null, "title": "Billing Interval" }, "currency": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Currency" }, "proration_date": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Pass back to POST /billing/seats to be charged this quote.", "title": "Proration Date" }, "renews_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "description": "When the seat next renews with the subscription.", "title": "Renews At" }, "seats_billed_now": { "default": 1, "description": "Seats of this tier the purchase bills. Legacy pending invitations are excluded until their own acceptance.", "title": "Seats Billed Now", "type": "integer" }, "tier": { "title": "Tier", "type": "string" }, "unit_amount_cents": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "One seat of this tier, per billing interval.", "title": "Unit Amount Cents" } }, "required": [ "tier", "billed" ], "title": "SeatQuoteResponse", "type": "object" }, "SeatRemovalResponse": { "properties": { "seat_id": { "title": "Seat Id", "type": "string" }, "seats_remaining": { "title": "Seats Remaining", "type": "integer" }, "tier": { "title": "Tier", "type": "string" } }, "required": [ "seat_id", "tier", "seats_remaining" ], "title": "SeatRemovalResponse", "type": "object" }, "SecretFileChoice": { "additionalProperties": false, "description": "Lend one of the person's own secret files with the skill (TIDY-20019 F9):\none the plan offered for a requirement it answers whole.", "properties": { "record_id": { "format": "uuid", "title": "Record Id", "type": "string" } }, "required": [ "record_id" ], "title": "SecretFileChoice", "type": "object" }, "SecretFileCreate": { "properties": { "format": { "enum": [ "dotenv", "raw" ], "title": "Format", "type": "string" }, "text": { "anyOf": [ { "maxLength": 131072, "type": "string" }, { "type": "null" } ], "title": "Text" }, "title": { "maxLength": 200, "minLength": 1, "title": "Title", "type": "string" } }, "required": [ "title", "format" ], "title": "SecretFileCreate", "type": "object" }, "SecretFileEntry": { "properties": { "key": { "title": "Key", "type": "string" }, "value": { "title": "Value", "type": "string" } }, "required": [ "key", "value" ], "title": "SecretFileEntry", "type": "object" }, "SecretFileLend": { "properties": { "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "employee_account_id": { "title": "Employee Account Id", "type": "string" }, "id": { "title": "Id", "type": "string" } }, "required": [ "id", "employee_account_id", "created_at" ], "title": "SecretFileLend", "type": "object" }, "SecretFileLendCreate": { "description": "The virtual employee whose turns carry every key of the file.", "properties": { "employee_account_id": { "format": "uuid", "title": "Employee Account Id", "type": "string" } }, "required": [ "employee_account_id" ], "title": "SecretFileLendCreate", "type": "object" }, "SecretFileLendsResponse": { "description": "The employees a file is lent to — never a value.", "properties": { "lends": { "items": { "$ref": "#/components/schemas/SecretFileLend" }, "title": "Lends", "type": "array" } }, "required": [ "lends" ], "title": "SecretFileLendsResponse", "type": "object" }, "SecretFileProposalCreate": { "description": "What an agent asks its owner to save. Never the content: the file's\nbytes go to the one-time upload address this answers with — or, with\n``upload: false``, there are none: the owner's existing file is deployed\nas it is (TIDY-19414 F16 S5).", "properties": { "deploy": { "default": false, "title": "Deploy", "type": "boolean" }, "file_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "File Id" }, "format": { "anyOf": [ { "enum": [ "dotenv", "raw" ], "type": "string" }, { "type": "null" } ], "title": "Format" }, "reason": { "maxLength": 1000, "minLength": 10, "title": "Reason", "type": "string" }, "targets": { "items": { "$ref": "#/components/schemas/SecretFileProposalTargetCreate" }, "maxItems": 20, "title": "Targets", "type": "array" }, "title": { "anyOf": [ { "maxLength": 200, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Title" }, "upload": { "default": true, "title": "Upload", "type": "boolean" } }, "required": [ "reason" ], "title": "SecretFileProposalCreate", "type": "object" }, "SecretFileProposalResponse": { "description": "A proposal by name and fingerprint — never a value.", "properties": { "applied_file_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Applied File Id" }, "deploy": { "default": false, "title": "Deploy", "type": "boolean" }, "deployed": { "items": { "$ref": "#/components/schemas/SecretFileTarget" }, "title": "Deployed", "type": "array" }, "encoding": { "anyOf": [ { "enum": [ "text", "base64" ], "type": "string" }, { "type": "null" } ], "default": null, "title": "Encoding" }, "expires_at": { "title": "Expires At", "type": "string" }, "file_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "File Id" }, "format": { "enum": [ "dotenv", "raw" ], "title": "Format", "type": "string" }, "id": { "title": "Id", "type": "string" }, "key_count": { "default": 0, "title": "Key Count", "type": "integer" }, "keys": { "items": { "type": "string" }, "title": "Keys", "type": "array" }, "message": { "title": "Message", "type": "string" }, "sha256": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Sha256" }, "size_bytes": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Size Bytes" }, "state": { "enum": [ "awaiting_upload", "pending", "applied", "declined", "expired" ], "title": "State", "type": "string" }, "targets": { "items": { "$ref": "#/components/schemas/SecretFileProposalTarget" }, "title": "Targets", "type": "array" }, "title": { "title": "Title", "type": "string" }, "upload": { "default": true, "title": "Upload", "type": "boolean" }, "upload_expires_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Upload Expires At" }, "upload_token": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Upload Token" }, "upload_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Upload Url" } }, "required": [ "id", "state", "title", "format", "expires_at", "message" ], "title": "SecretFileProposalResponse", "type": "object" }, "SecretFileProposalTarget": { "properties": { "location": { "enum": [ "home", "project" ], "title": "Location", "type": "string" }, "mode": { "enum": [ "0600", "0400", "0640", "0440", "0644", "0444" ], "title": "Mode", "type": "string" }, "path": { "title": "Path", "type": "string" }, "root_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Root Id" }, "workshop": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Workshop" }, "workshop_id": { "title": "Workshop Id", "type": "string" } }, "required": [ "workshop_id", "location", "path", "mode" ], "title": "SecretFileProposalTarget", "type": "object" }, "SecretFileProposalTargetCreate": { "description": "A place a proposed file goes. An employee names it as it sees it from its\nown box (TIDY-20046 F1): its workshop by leaving ``workshop_id`` out, a\nproject folder by the path its shell is in. Either way it is checked as an\nowner's target is, now and again on approval.", "properties": { "location": { "enum": [ "home", "project" ], "title": "Location", "type": "string" }, "mode": { "default": "0600", "enum": [ "0600", "0400", "0640", "0440", "0644", "0444" ], "title": "Mode", "type": "string" }, "path": { "maxLength": 512, "minLength": 1, "title": "Path", "type": "string" }, "root_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Root Id" }, "root_path": { "anyOf": [ { "maxLength": 1024, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Root Path" }, "workshop_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Workshop Id" } }, "required": [ "location", "path" ], "title": "SecretFileProposalTargetCreate", "type": "object" }, "SecretFileResponse": { "description": "What the member may see without a fresh sign-in: no value, ever.", "properties": { "content_updated_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Content Updated At" }, "encoding": { "default": "text", "enum": [ "text", "base64" ], "title": "Encoding", "type": "string" }, "format": { "enum": [ "dotenv", "raw" ], "title": "Format", "type": "string" }, "id": { "title": "Id", "type": "string" }, "key_count": { "title": "Key Count", "type": "integer" }, "keys": { "items": { "type": "string" }, "title": "Keys", "type": "array" }, "size_bytes": { "title": "Size Bytes", "type": "integer" }, "title": { "title": "Title", "type": "string" } }, "required": [ "id", "title", "format", "keys", "key_count", "size_bytes" ], "title": "SecretFileResponse", "type": "object" }, "SecretFileRevealResponse": { "description": "The whole file after a fresh sign-in. Every one is audited.", "properties": { "content_updated_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Content Updated At" }, "encoding": { "default": "text", "enum": [ "text", "base64" ], "title": "Encoding", "type": "string" }, "entries": { "items": { "$ref": "#/components/schemas/SecretFileEntry" }, "title": "Entries", "type": "array" }, "format": { "enum": [ "dotenv", "raw" ], "title": "Format", "type": "string" }, "id": { "title": "Id", "type": "string" }, "key_count": { "title": "Key Count", "type": "integer" }, "keys": { "items": { "type": "string" }, "title": "Keys", "type": "array" }, "size_bytes": { "title": "Size Bytes", "type": "integer" }, "text": { "title": "Text", "type": "string" }, "title": { "title": "Title", "type": "string" } }, "required": [ "id", "title", "format", "keys", "key_count", "size_bytes", "text", "entries" ], "title": "SecretFileRevealResponse", "type": "object" }, "SecretFileSave": { "description": "One write. ``replace`` takes ``text`` as the whole file; ``merge`` folds\nthe pasted ``KEY=value`` lines in ``text`` into it; ``edit`` sets each key\nin ``values`` and removes each key in ``remove``. A set value is written\nexactly as given after ``KEY=``.", "properties": { "format": { "anyOf": [ { "enum": [ "dotenv", "raw" ], "type": "string" }, { "type": "null" } ], "title": "Format" }, "mode": { "enum": [ "replace", "merge", "edit" ], "title": "Mode", "type": "string" }, "remove": { "items": { "type": "string" }, "title": "Remove", "type": "array" }, "text": { "anyOf": [ { "maxLength": 131072, "type": "string" }, { "type": "null" } ], "title": "Text" }, "values": { "additionalProperties": { "type": "string" }, "title": "SecretFileSaveValues", "type": "object" } }, "required": [ "mode" ], "title": "SecretFileSave", "type": "object" }, "SecretFileTarget": { "properties": { "checked_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Checked At" }, "deployed_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Deployed At" }, "deployed_version": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Deployed Version" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Error" }, "id": { "title": "Id", "type": "string" }, "location": { "enum": [ "home", "project" ], "title": "Location", "type": "string" }, "mode": { "enum": [ "0600", "0400", "0640", "0440", "0644", "0444" ], "title": "Mode", "type": "string" }, "path": { "title": "Path", "type": "string" }, "resolved_path": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Resolved Path" }, "root_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Root Id" }, "state": { "anyOf": [ { "enum": [ "in_sync", "changed", "missing", "failed" ], "type": "string" }, { "type": "null" } ], "default": null, "title": "State" }, "workshop_id": { "title": "Workshop Id", "type": "string" } }, "required": [ "id", "workshop_id", "location", "path", "mode" ], "title": "SecretFileTarget", "type": "object" }, "SecretFileTargetCreate": { "description": "Where a secret file goes: a workshop, and a path in the home of the\naccount its employees run as or in one of its Project Roots.", "properties": { "location": { "enum": [ "home", "project" ], "title": "Location", "type": "string" }, "mode": { "default": "0600", "enum": [ "0600", "0400", "0640", "0440", "0644", "0444" ], "title": "Mode", "type": "string" }, "path": { "maxLength": 512, "minLength": 1, "title": "Path", "type": "string" }, "root_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Root Id" }, "workshop_id": { "format": "uuid", "title": "Workshop Id", "type": "string" } }, "required": [ "workshop_id", "location", "path" ], "title": "SecretFileTargetCreate", "type": "object" }, "SecretFileTargetSelection": { "description": "The targets to act on; omitted, every target of the file.", "properties": { "target_ids": { "anyOf": [ { "items": { "format": "uuid", "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Target Ids" } }, "title": "SecretFileTargetSelection", "type": "object" }, "SecretFileTargetsResponse": { "description": "A file's targets after the change — never a value, never a hash.", "properties": { "targets": { "items": { "$ref": "#/components/schemas/SecretFileTarget" }, "title": "Targets", "type": "array" } }, "required": [ "targets" ], "title": "SecretFileTargetsResponse", "type": "object" }, "SeedDeclineRequest": { "properties": { "match_dimension": { "title": "Match Dimension", "type": "string" }, "match_value": { "title": "Match Value", "type": "string" }, "moment": { "title": "Moment", "type": "string" } }, "required": [ "moment", "match_dimension", "match_value" ], "title": "SeedDeclineRequest", "type": "object" }, "SeedDeclineResponse": { "properties": { "recorded": { "title": "Recorded", "type": "boolean" }, "suppressed_until": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Suppressed Until" } }, "required": [ "recorded" ], "title": "SeedDeclineResponse", "type": "object" }, "SeedProposalResponse": { "properties": { "proposal": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "title": "Proposal" }, "suppressed": { "default": false, "title": "Suppressed", "type": "boolean" } }, "title": "SeedProposalResponse", "type": "object" }, "SeedRequest": { "properties": { "context": { "additionalProperties": true, "description": "Moment context (sender…).", "title": "Context", "type": "object" }, "email_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Source email for context enrichment.", "title": "Email Id" }, "moment": { "description": "Seeding moment, e.g. block_sender / reclassify.", "title": "Moment", "type": "string" } }, "required": [ "moment" ], "title": "SeedRequest", "type": "object" }, "SelectionHandleRequest": { "additionalProperties": false, "description": "One captured selection.\n\n``offset`` is the capturing surface's own character offset of the span\ninside its block — a disambiguator, not a locator: the server picks the\noccurrence nearest it and signs that occurrence index. ``capture_from``\n/ ``capture_to`` are ProseMirror positions carried as DEBUG metadata\nonly; they shift under collab and are never used to resolve anything\n(TIDY-A-1356).\n\nThere is deliberately no client-supplied before/after context and no\nclient-supplied block hash: the server derives BOTH from authoritative\nstate, so the staleness proof is not written by the party it is about,\nand there is no cross-language text-extraction contract to drift.", "properties": { "block_ids": { "items": { "type": "string" }, "maxItems": 32, "minItems": 1, "title": "Block Ids", "type": "array" }, "capture_from": { "anyOf": [ { "minimum": 0.0, "type": "integer" }, { "type": "null" } ], "title": "Capture From" }, "capture_to": { "anyOf": [ { "minimum": 0.0, "type": "integer" }, { "type": "null" } ], "title": "Capture To" }, "offset": { "default": 0, "minimum": 0.0, "title": "Offset", "type": "integer" }, "text": { "maxLength": 10000, "minLength": 1, "title": "Text", "type": "string" }, "typed_id": { "maxLength": 64, "minLength": 3, "title": "Typed Id", "type": "string" } }, "required": [ "typed_id", "text", "block_ids" ], "title": "SelectionHandleRequest", "type": "object" }, "SelectionHandleResponse": { "properties": { "expires_at": { "title": "Expires At", "type": "string" }, "handle": { "title": "Handle", "type": "string" }, "typed_id": { "title": "Typed Id", "type": "string" } }, "required": [ "handle", "typed_id", "expires_at" ], "title": "SelectionHandleResponse", "type": "object" }, "SelfBulkGrantItem": { "properties": { "action": { "enum": [ "read", "read_write" ], "title": "Action", "type": "string" }, "container_ref": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Container Ref" }, "delegatee_account_id": { "format": "uuid", "title": "Delegatee Account Id", "type": "string" }, "delegatee_member_type": { "enum": [ "human", "virtual_employee" ], "title": "Delegatee Member Type", "type": "string" }, "expires_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Expires At" }, "facet_keys": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Facet Keys" }, "resource_type": { "enum": [ "calendar", "notes", "projects", "contacts", "activities", "inbox", "photos", "podcasts", "files", "structure", "sessions", "records" ], "title": "Resource Type", "type": "string" } }, "required": [ "resource_type", "delegatee_account_id", "delegatee_member_type", "action" ], "title": "SelfBulkGrantItem", "type": "object" }, "SelfBulkGrantRequest": { "properties": { "items": { "items": { "$ref": "#/components/schemas/SelfBulkGrantItem" }, "title": "Items", "type": "array" } }, "required": [ "items" ], "title": "SelfBulkGrantRequest", "type": "object" }, "SelfCredentialRecoveryRequest": { "properties": { "agent_account_id": { "format": "uuid", "title": "Agent Account Id", "type": "string" }, "host_continuity_token": { "maxLength": 512, "minLength": 32, "title": "Host Continuity Token", "type": "string" }, "host_instance_id": { "format": "uuid", "title": "Host Instance Id", "type": "string" }, "idempotency_key": { "format": "uuid", "title": "Idempotency Key", "type": "string" }, "installation_id": { "format": "uuid", "title": "Installation Id", "type": "string" }, "machine_fingerprint": { "maxLength": 512, "minLength": 16, "title": "Machine Fingerprint", "type": "string" }, "manifest_sha256": { "pattern": "^[0-9a-f]{64}$", "title": "Manifest Sha256", "type": "string" } }, "required": [ "agent_account_id", "installation_id", "host_instance_id", "machine_fingerprint", "host_continuity_token", "manifest_sha256", "idempotency_key" ], "title": "SelfCredentialRecoveryRequest", "type": "object" }, "SelfMcpDeploymentAck": { "description": "The connector's report of one deployment sync pass.", "properties": { "conversation_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Conversation Id" }, "manifest_hash": { "maxLength": 64, "title": "Manifest Hash", "type": "string" }, "results": { "items": { "$ref": "#/components/schemas/McpDeploymentAckEntry" }, "maxItems": 128, "title": "Results", "type": "array" }, "room_id": { "anyOf": [ { "maxLength": 512, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Room Id" }, "runtime": { "anyOf": [ { "maxLength": 32, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Runtime" }, "turn_credential": { "anyOf": [ { "format": "password", "maxLength": 512, "minLength": 1, "type": "string", "writeOnly": true }, { "type": "null" } ], "title": "Turn Credential" }, "turn_ref": { "anyOf": [ { "maxLength": 512, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Turn Ref" }, "witnesses": { "items": { "$ref": "#/components/schemas/McpToolsWitness" }, "maxItems": 128, "title": "Witnesses", "type": "array" } }, "required": [ "manifest_hash" ], "title": "SelfMcpDeploymentAck", "type": "object" }, "SelfMcpDeploymentAckResponse": { "properties": { "stale_manifest": { "default": false, "title": "Stale Manifest", "type": "boolean" }, "updated": { "default": 0, "title": "Updated", "type": "integer" }, "witnesses_recorded": { "default": 0, "title": "Witnesses Recorded", "type": "integer" } }, "title": "SelfMcpDeploymentAckResponse", "type": "object" }, "SelfMcpDeploymentMaterializeResponse": { "description": "The env map for this employee's deployed MCP connections.\n\nValues ride TLS to the box once and land ONLY in the harness environment\nfile; configs reference them as ``${KEY}``. A connection that failed auth\nresolution appears in ``errors`` so its deployment row goes loud-error\ninstead of silently unauthenticated.", "properties": { "env": { "additionalProperties": { "type": "string" }, "title": "Env", "type": "object" }, "errors": { "items": { "$ref": "#/components/schemas/McpDeploymentEnvError" }, "maxItems": 64, "title": "Errors", "type": "array" } }, "title": "SelfMcpDeploymentMaterializeResponse", "type": "object" }, "SelfMcpDeploymentResponse": { "description": "The calling employee's desired deployment set.\n\n``workshop_id`` is null for an employee assigned to no live workshop — a\nvalid empty manifest, not an error (the legacy fused installs have no\nworkshop to deploy to).", "properties": { "manifest_hash": { "maxLength": 64, "title": "Manifest Hash", "type": "string" }, "servers": { "items": { "$ref": "#/components/schemas/McpDeploymentServer" }, "maxItems": 64, "title": "Servers", "type": "array" }, "workshop_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Workshop Id" } }, "required": [ "manifest_hash" ], "title": "SelfMcpDeploymentResponse", "type": "object" }, "SelfMcpTurnDeliveryRequest": { "description": "One turn's MCP delivery, asked by the connector for that turn.", "properties": { "conversation_id": { "format": "uuid", "title": "Conversation Id", "type": "string" }, "room_id": { "maxLength": 512, "minLength": 1, "title": "Room Id", "type": "string" }, "runtime": { "maxLength": 32, "minLength": 1, "title": "Runtime", "type": "string" }, "turn_credential": { "format": "password", "maxLength": 512, "minLength": 1, "title": "Turn Credential", "type": "string", "writeOnly": true }, "turn_ref": { "maxLength": 512, "minLength": 1, "title": "Turn Ref", "type": "string" } }, "required": [ "turn_credential", "turn_ref", "room_id", "conversation_id", "runtime" ], "title": "SelfMcpTurnDeliveryRequest", "type": "object" }, "SelfMcpTurnDeliveryResponse": { "description": "What one turn's audience may use, and the values only it receives.\n\nTIDY-19557 F2b: the connector writes these values into that audience's\nown harness MCP config for the turn — never into any process environment\nand never into the employee's shared harness environment file.", "properties": { "audience": { "maxLength": 300, "title": "Audience", "type": "string" }, "connections": { "items": { "$ref": "#/components/schemas/McpTurnConnection" }, "maxItems": 64, "title": "Connections", "type": "array" }, "env": { "additionalProperties": { "type": "string" }, "title": "Mcp Turn Delivery Env", "type": "object" }, "errors": { "items": { "$ref": "#/components/schemas/McpDeploymentEnvError" }, "maxItems": 128, "title": "Errors", "type": "array" }, "integrations": { "additionalProperties": { "$ref": "#/components/schemas/McpToolSource" }, "title": "Mcp Turn Delivery Integrations", "type": "object" }, "lends": { "items": { "$ref": "#/components/schemas/McpTurnLend" }, "maxItems": 64, "title": "Lends", "type": "array" }, "manifest_hash": { "maxLength": 64, "title": "Manifest Hash", "type": "string" } }, "required": [ "manifest_hash", "audience" ], "title": "SelfMcpTurnDeliveryResponse", "type": "object" }, "SelfRevokeRuntimeRequest": { "properties": { "idempotency_key": { "format": "uuid", "title": "Idempotency Key", "type": "string" }, "installation_id": { "format": "uuid", "title": "Installation Id", "type": "string" }, "reason": { "const": "local_uninstall", "title": "Reason", "type": "string" } }, "required": [ "installation_id", "idempotency_key", "reason" ], "title": "SelfRevokeRuntimeRequest", "type": "object" }, "SelfRevokeRuntimeResponse": { "properties": { "account_id": { "format": "uuid", "title": "Account Id", "type": "string" }, "idempotency_key": { "format": "uuid", "title": "Idempotency Key", "type": "string" }, "revoked_at": { "format": "date-time", "title": "Revoked At", "type": "string" }, "status": { "enum": [ "revoked", "already_revoked" ], "title": "Status", "type": "string" } }, "required": [ "status", "account_id", "revoked_at", "idempotency_key" ], "title": "SelfRevokeRuntimeResponse", "type": "object" }, "SelfSkillBundleAck": { "properties": { "blocked": { "items": { "$ref": "#/components/schemas/SkillBundleRefusal" }, "maxItems": 64, "title": "Blocked", "type": "array" }, "bundle_hash": { "default": "", "maxLength": 128, "title": "Bundle Hash", "type": "string" }, "error": { "anyOf": [ { "maxLength": 1000, "type": "string" }, { "type": "null" } ], "title": "Error" }, "installs": { "items": { "$ref": "#/components/schemas/SkillInstallAckEntry" }, "maxItems": 64, "title": "Installs", "type": "array" }, "local_skills": { "anyOf": [ { "items": { "$ref": "#/components/schemas/LocalSkillReport" }, "maxItems": 256, "type": "array" }, { "type": "null" } ], "title": "Local Skills" }, "removed": { "default": 0, "title": "Removed", "type": "integer" }, "runtime": { "anyOf": [ { "maxLength": 64, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Runtime" }, "shadowed_locally": { "items": { "type": "string" }, "maxItems": 64, "title": "Shadowed Locally", "type": "array" }, "status": { "enum": [ "ok", "failed" ], "title": "Status", "type": "string" }, "written": { "default": 0, "title": "Written", "type": "integer" } }, "required": [ "status" ], "title": "SelfSkillBundleAck", "type": "object" }, "SelfSkillBundleAckResponse": { "properties": { "assignments_updated": { "title": "Assignments Updated", "type": "integer" }, "recorded": { "title": "Recorded", "type": "boolean" } }, "required": [ "recorded", "assignments_updated" ], "title": "SelfSkillBundleAckResponse", "type": "object" }, "SelfSkillBundleEntry": { "description": "One materializable skill, as the connector receives it.", "properties": { "content_hash": { "title": "Content Hash", "type": "string" }, "credentials": { "items": { "$ref": "#/components/schemas/SkillCredentialSlotStatus" }, "title": "Credentials", "type": "array" }, "description": { "title": "Description", "type": "string" }, "files": { "anyOf": [ { "items": { "$ref": "#/components/schemas/SkillMaterializedFile" }, "maxItems": 64, "minItems": 1, "type": "array" }, { "type": "null" } ], "default": null, "title": "Files" }, "markdown": { "title": "Markdown", "type": "string" }, "name": { "title": "Name", "type": "string" }, "open_conflict_versions": { "items": { "type": "integer" }, "title": "Open Conflict Versions", "type": "array" }, "placement": { "default": "harness_global", "enum": [ "harness_global", "project_scoped" ], "title": "Placement", "type": "string" }, "project_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Project Id" }, "project_root": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Project Root" }, "scripts": { "items": { "$ref": "#/components/schemas/SkillScriptFile" }, "title": "Scripts", "type": "array" }, "skill_id": { "title": "Skill Id", "type": "string" }, "skill_md_variant": { "anyOf": [ { "enum": [ "linux", "macos", "windows" ], "type": "string" }, { "type": "null" } ], "default": null, "title": "Skill Md Variant" }, "slug": { "title": "Slug", "type": "string" }, "sync_mode": { "enum": [ "tracked", "pinned" ], "title": "Sync Mode", "type": "string" }, "version": { "title": "Version", "type": "integer" } }, "required": [ "skill_id", "slug", "name", "description", "version", "content_hash", "markdown", "sync_mode" ], "title": "SelfSkillBundleEntry", "type": "object" }, "SelfSkillBundleResponse": { "description": "Everything the calling virtual employee should hold on disk.\n\nCarries content inline: the whole bundle is bounded (64 skills, each a\nmarkdown page), and a second round trip per file would buy nothing — the\nconnector already writes only the entries whose hash moved.", "properties": { "assignment_ids": { "items": { "type": "string" }, "title": "Assignment Ids", "type": "array" }, "bundle_format": { "default": "legacy", "enum": [ "legacy", "files" ], "title": "Bundle Format", "type": "string" }, "bundle_hash": { "title": "Bundle Hash", "type": "string" }, "receipt_epoch": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Receipt Epoch" }, "skills": { "items": { "$ref": "#/components/schemas/SelfSkillBundleEntry" }, "title": "Skills", "type": "array" } }, "required": [ "bundle_hash" ], "title": "SelfSkillBundleResponse", "type": "object" }, "SendDraftRequest": { "description": "Request body for sending a draft.", "properties": { "delegated_by": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "description": "TIDY-10691: account id of a delegator to send ON BEHALF OF. The caller MUST hold an active read_write inbox delegation grant from this account; a read-only grant or no grant rejects the send. The from_alias must belong to the delegator's provider connection. Omit for an own-mailbox send (unchanged behavior).", "title": "Delegated By" }, "email_source_config_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "description": "Email source to send from (legacy). Resolved to provider_connection_id.", "title": "Email Source Config Id" }, "from_alias": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Alias email address to use in From header. Must be configured on the source.", "title": "From Alias" }, "provider_connection_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "description": "Provider connection to send from. Takes precedence over email_source_config_id.", "title": "Provider Connection Id" }, "signature_override_template_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "description": "TIDY-8976 (S9): force a specific signature template for THIS reply, bypassing the within/outside default selection. The override template is rendered through the same EmailRenderer pipeline; if the id is null (default), the within/outside slot is selected based on recipient domain classification.", "title": "Signature Override Template Id" }, "suppress_signature": { "default": false, "description": "TIDY-15634: the client already composed the signature into the draft body (the Android composer shows it inline so the user can edit or delete it before sending). Server-side append is skipped for THIS send so the recipient never receives it twice. Default false keeps the invisible server-append behavior every existing client relies on.", "title": "Suppress Signature", "type": "boolean" }, "tags": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "description": "Optional semantic tags to persist on the sent email record.", "title": "Tags" }, "wait_for_send": { "default": false, "description": "If true, skip the 15s undo grace period and await the provider send before returning. The response then reflects the actual send outcome (success=true with provider message_id, or 5xx on failure). Used by agentic / MCP callers (TIDY-8631) where there is no UI to surface a deferred failure. Default false preserves the web UI's undo behavior.", "title": "Wait For Send", "type": "boolean" } }, "title": "SendDraftRequest", "type": "object" }, "SendDraftResponse": { "description": "Response for send operation.", "properties": { "client_action": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "What the client should do next: 'poll' or 'new_operation'", "title": "Client Action" }, "expansion_warnings": { "description": "Non-blocking recipient-expansion flags (TIDY-14747): group members with no address / unaddressable org members. The send proceeded; nothing was silently dropped.", "items": { "$ref": "#/components/schemas/ExpansionIssue" }, "title": "Expansion Warnings", "type": "array" }, "id": { "description": "Draft UUID", "format": "uuid", "title": "Id", "type": "string" }, "manifest_state": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Embed-manifest state: pending_send | sent | void | terminal_ambiguous", "title": "Manifest State" }, "message": { "description": "Result message", "title": "Message", "type": "string" }, "message_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Sent message ID", "title": "Message Id" }, "reconciliation_pending": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "description": "True when the send operation's outcome is still being reconciled. The client MUST NOT re-send; it polls this endpoint per the max-12/60s polling contract.", "title": "Reconciliation Pending" }, "reconciliation_recovered": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "description": "True when a provider status check proved the original operation was delivered after all; the identity was recorded without re-sending.", "title": "Reconciliation Recovered" }, "retry_after_seconds": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Seconds to wait before polling again", "title": "Retry After Seconds" }, "sent_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "description": "When email was sent", "title": "Sent At" }, "success": { "description": "Whether send succeeded", "title": "Success", "type": "boolean" }, "undo_deadline": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "description": "Deadline to undo send (5 seconds after sent_at)", "title": "Undo Deadline" } }, "required": [ "id", "success", "message" ], "title": "SendDraftResponse", "type": "object" }, "SendInviteRequest": { "properties": { "recipient_email": { "title": "Recipient Email", "type": "string" } }, "required": [ "recipient_email" ], "title": "SendInviteRequest", "type": "object" }, "SendInvitesRequest": { "additionalProperties": false, "description": "Request body for sending calendar invites to event attendees.", "properties": { "attendee_emails": { "description": "Optional attendee email subset. Empty means send to all attendees.", "items": { "type": "string" }, "title": "Attendee Emails", "type": "array" }, "email_source_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Email source to send from. Defaults to first active source.", "title": "Email Source Id" }, "resend": { "default": false, "description": "Send even to attendees already invited (invite_sent_at set). Default False skips them so repeat calls never double-send.", "title": "Resend", "type": "boolean" } }, "title": "SendInvitesRequest", "type": "object" }, "SendInvitesResponse": { "description": "Response body for send-invites endpoint.", "properties": { "event_id": { "title": "Event Id", "type": "string" }, "ics_uid": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Ics Uid" }, "invited_attendees": { "items": { "type": "string" }, "title": "Invited Attendees", "type": "array" }, "organizer_email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Organizer Email" }, "request_sent": { "title": "Request Sent", "type": "boolean" }, "skipped_already_invited": { "items": { "type": "string" }, "title": "Skipped Already Invited", "type": "array" } }, "required": [ "event_id", "request_sent" ], "title": "SendInvitesResponse", "type": "object" }, "SendMatrixRoomMessageRequest": { "properties": { "body": { "maxLength": 10000, "minLength": 1, "title": "Body", "type": "string" }, "client_message_id": { "anyOf": [ { "maxLength": 255, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Client Message Id" }, "formatted_body": { "anyOf": [ { "maxLength": 40000, "type": "string" }, { "type": "null" } ], "title": "Formatted Body" }, "mentions": { "items": { "$ref": "#/components/schemas/MatrixMentionRequest" }, "title": "Mentions", "type": "array" } }, "required": [ "body" ], "title": "SendMatrixRoomMessageRequest", "type": "object" }, "SendMatrixRoomMessageResponse": { "properties": { "event_id": { "title": "Event Id", "type": "string" } }, "required": [ "event_id" ], "title": "SendMatrixRoomMessageResponse", "type": "object" }, "SendMessageRequest": { "properties": { "body_text": { "maxLength": 10000, "minLength": 1, "title": "Body Text", "type": "string" }, "client_message_id": { "maxLength": 255, "minLength": 1, "title": "Client Message Id", "type": "string" } }, "required": [ "body_text", "client_message_id" ], "title": "SendMessageRequest", "type": "object" }, "SendMessageResponse": { "properties": { "event_id": { "title": "Event Id", "type": "string" } }, "required": [ "event_id" ], "title": "SendMessageResponse", "type": "object" }, "SendNowResponse": { "properties": { "campaign_id": { "title": "Campaign Id", "type": "string" }, "counts": { "$ref": "#/components/schemas/PreflightCounts" }, "snapshot_count": { "title": "Snapshot Count", "type": "integer" }, "status": { "title": "Status", "type": "string" } }, "required": [ "campaign_id", "status", "snapshot_count", "counts" ], "title": "SendNowResponse", "type": "object" }, "SendRawSmsRequest": { "description": "Public payload for tidy_sms_send (MCP) and other agency callers.", "properties": { "category": { "default": "agent_send", "description": "Audit category for tracking the send", "title": "Category", "type": "string" }, "channel": { "default": "sms", "description": "Channel ('sms' only)", "title": "Channel", "type": "string" }, "message": { "maxLength": 1600, "minLength": 1, "title": "Message", "type": "string" }, "tenant_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Tenant Id" }, "to_phone": { "description": "Recipient phone number (E.164)", "title": "To Phone", "type": "string" } }, "required": [ "to_phone", "message" ], "title": "SendRawSmsRequest", "type": "object" }, "SendRawSmsResponse": { "properties": { "cost_cents": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Cost Cents" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error" }, "message_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Message Id" }, "status": { "title": "Status", "type": "string" }, "success": { "title": "Success", "type": "boolean" } }, "required": [ "success", "status" ], "title": "SendRawSmsResponse", "type": "object" }, "SendUpdatesRequest": { "additionalProperties": false, "description": "Request body for the send-updates endpoint (TIDY-14317).", "properties": { "email_source_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Email source to send from. Defaults to the organizer's source.", "title": "Email Source Id" }, "time_changed": { "default": false, "description": "This re-send announces a RESCHEDULE, so every attendee's PARTSTAT resets to NEEDS-ACTION per RFC 5546 §3.2.2 (TIDY-16963). Leave false for a correction (title, location) — that must not discard answers people already gave.", "title": "Time Changed", "type": "boolean" } }, "title": "SendUpdatesRequest", "type": "object" }, "SendUpdatesResponse": { "description": "Response body for the send-updates endpoint.", "properties": { "attendee_count": { "default": 0, "title": "Attendee Count", "type": "integer" }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Why nothing was sent (not_organizer, no_attendees, ...).", "title": "Reason" }, "sent": { "title": "Sent", "type": "boolean" }, "sequence": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "The bumped iCalendar SEQUENCE when an update was sent.", "title": "Sequence" } }, "required": [ "sent" ], "title": "SendUpdatesResponse", "type": "object" }, "SenderEngagementMetrics": { "description": "Per-sender read-engagement from interaction telemetry (TIDY-13031).\n\nOwner-scoped. ``reply_latency_bucket`` is server-derived from sent-mail\ncorrelation, never client-captured.", "properties": { "actions": { "additionalProperties": { "type": "integer" }, "title": "Actions", "type": "object" }, "opens": { "default": 0, "title": "Opens", "type": "integer" }, "read_time_buckets": { "additionalProperties": { "type": "integer" }, "title": "Read Time Buckets", "type": "object" }, "replies": { "default": 0, "title": "Replies", "type": "integer" }, "reply_latency_bucket": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Reply Latency Bucket" } }, "title": "SenderEngagementMetrics", "type": "object" }, "SenderListResponse": { "properties": { "items": { "items": { "$ref": "#/components/schemas/SenderScreeningItem" }, "title": "Items", "type": "array" }, "limit": { "title": "Limit", "type": "integer" }, "offset": { "title": "Offset", "type": "integer" }, "total": { "title": "Total", "type": "integer" } }, "required": [ "items", "total", "limit", "offset" ], "title": "SenderListResponse", "type": "object" }, "SenderLogoResolveRequest": { "properties": { "domain": { "maxLength": 253, "minLength": 3, "title": "Domain", "type": "string" } }, "required": [ "domain" ], "title": "SenderLogoResolveRequest", "type": "object" }, "SenderLogoResponse": { "properties": { "domain": { "title": "Domain", "type": "string" }, "error_detail": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Error Detail" }, "next_retry_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Next Retry At" }, "original_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Original Url" }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Reason" }, "resolved_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Resolved At" }, "source": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Source" }, "status": { "title": "Status", "type": "string" }, "storage_path": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Storage Path" }, "thumbnail_base64": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Thumbnail Base64" }, "updated_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Updated At" } }, "required": [ "domain", "status" ], "title": "SenderLogoResponse", "type": "object" }, "SenderPreviewAttachment": { "properties": { "content_type": { "default": "", "title": "Content Type", "type": "string" }, "filename": { "default": "", "title": "Filename", "type": "string" }, "size_bytes": { "default": 0, "title": "Size Bytes", "type": "integer" } }, "title": "SenderPreviewAttachment", "type": "object" }, "SenderPreviewResponse": { "properties": { "preview_attachments": { "default": [], "items": { "$ref": "#/components/schemas/SenderPreviewAttachment" }, "title": "Preview Attachments", "type": "array" }, "preview_body_html": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Preview Body Html" }, "preview_body_text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Preview Body Text" }, "preview_email_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "default": null, "title": "Preview Email Id" }, "preview_sent_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Preview Sent At" }, "preview_subject": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Preview Subject" } }, "title": "SenderPreviewResponse", "type": "object" }, "SenderRuleResponse": { "description": "Response for PATCH /screening/senders/{id}.", "properties": { "email_address": { "title": "Email Address", "type": "string" }, "forced_category": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Forced Category" }, "id": { "format": "uuid", "title": "Id", "type": "string" }, "screening_status": { "title": "Screening Status", "type": "string" }, "updated_at": { "format": "date-time", "title": "Updated At", "type": "string" } }, "required": [ "id", "email_address", "screening_status", "updated_at" ], "title": "SenderRuleResponse", "type": "object" }, "SenderRuleUpdate": { "description": "Request body for PATCH /screening/senders/{id}.", "properties": { "forced_category": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Forced Category" } }, "title": "SenderRuleUpdate", "type": "object" }, "SenderScreeningItem": { "properties": { "auto_approve_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Auto Approve Reason" }, "auto_approved": { "default": false, "title": "Auto Approved", "type": "boolean" }, "block_scope": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": "address", "title": "Block Scope" }, "display_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Display Name" }, "email_address": { "title": "Email Address", "type": "string" }, "email_count": { "title": "Email Count", "type": "integer" }, "first_seen_at": { "format": "date-time", "title": "First Seen At", "type": "string" }, "id": { "format": "uuid", "title": "Id", "type": "string" }, "last_seen_at": { "format": "date-time", "title": "Last Seen At", "type": "string" }, "preview_body_html": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Preview Body Html" }, "preview_body_text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Preview Body Text" }, "preview_email_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "default": null, "title": "Preview Email Id" }, "preview_sent_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Preview Sent At" }, "preview_snippet": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Preview Snippet" }, "preview_subject": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Preview Subject" }, "preview_subjects": { "default": [], "items": { "type": "string" }, "title": "Preview Subjects", "type": "array" }, "screened_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Screened At" }, "screening_status": { "title": "Screening Status", "type": "string" }, "sender_domain": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Sender Domain" } }, "required": [ "id", "email_address", "screening_status", "email_count", "first_seen_at", "last_seen_at" ], "title": "SenderScreeningItem", "type": "object" }, "SenderScreeningKey": { "properties": { "email_address": { "title": "Email Address", "type": "string" }, "email_count": { "default": 0, "title": "Email Count", "type": "integer" }, "id": { "title": "Id", "type": "string" }, "kind": { "title": "Kind", "type": "string" }, "screening_status": { "title": "Screening Status", "type": "string" } }, "required": [ "id", "email_address", "kind", "screening_status" ], "title": "SenderScreeningKey", "type": "object" }, "SenderVipRequest": { "description": "Body of POST /emails/{email_id}/sender/vip.", "properties": { "is_vip": { "description": "True to mark sender as VIP (is_starred=TRUE on the contact); False to demote.", "title": "Is Vip", "type": "boolean" } }, "required": [ "is_vip" ], "title": "SenderVipRequest", "type": "object" }, "SenderVipResponse": { "description": "Response for sender VIP promotion.", "properties": { "contact_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "description": "The affected contact's UUID. NULL only when set_vip=false and no contact exists for the sender — that's a no-op.", "title": "Contact Id" }, "email_id": { "format": "uuid", "title": "Email Id", "type": "string" }, "is_vip": { "title": "Is Vip", "type": "boolean" }, "success": { "default": true, "title": "Success", "type": "boolean" } }, "required": [ "email_id", "is_vip" ], "title": "SenderVipResponse", "type": "object" }, "SendingDomainCreate": { "properties": { "connection_id": { "description": "esp_connection the identity is provisioned through.", "title": "Connection Id", "type": "string" }, "default_from_local": { "default": "hello", "maxLength": 64, "minLength": 1, "title": "Default From Local", "type": "string" }, "domain": { "maxLength": 253, "minLength": 3, "pattern": "^[A-Za-z0-9.-]+$", "title": "Domain", "type": "string" }, "is_default_identity": { "default": false, "title": "Is Default Identity", "type": "boolean" }, "mail_from_subdomain": { "default": "mail", "maxLength": 63, "minLength": 1, "pattern": "^[A-Za-z0-9-]+$", "title": "Mail From Subdomain", "type": "string" } }, "required": [ "connection_id", "domain" ], "title": "SendingDomainCreate", "type": "object" }, "SendingDomainResponse": { "properties": { "connection_id": { "title": "Connection Id", "type": "string" }, "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "default_from_local": { "title": "Default From Local", "type": "string" }, "dkim_tokens": { "items": { "type": "string" }, "title": "Dkim Tokens", "type": "array" }, "domain": { "title": "Domain", "type": "string" }, "from_identity": { "description": "default_from_local@domain — the pickable identity.", "title": "From Identity", "type": "string" }, "id": { "title": "Id", "type": "string" }, "is_default_identity": { "title": "Is Default Identity", "type": "boolean" }, "last_checked_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Last Checked At" }, "mail_from_subdomain": { "title": "Mail From Subdomain", "type": "string" }, "records": { "description": "The exact DNS records to add, merged with the last check results (observed/ok per record — partial propagation shows exactly which records fail).", "items": { "$ref": "#/components/schemas/RecordCheck" }, "title": "Records", "type": "array" }, "setup_guide": { "additionalProperties": true, "title": "Setup Guide", "type": "object" }, "status": { "title": "Status", "type": "string" }, "status_detail": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Status Detail" }, "tenant_id": { "title": "Tenant Id", "type": "string" }, "updated_at": { "format": "date-time", "title": "Updated At", "type": "string" }, "verified_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Verified At" } }, "required": [ "id", "tenant_id", "connection_id", "domain", "status", "mail_from_subdomain", "default_from_local", "from_identity", "is_default_identity", "created_at", "updated_at" ], "title": "SendingDomainResponse", "type": "object" }, "SendingDomainUpdate": { "properties": { "default_from_local": { "anyOf": [ { "maxLength": 64, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Default From Local" }, "is_default_identity": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is Default Identity" } }, "title": "SendingDomainUpdate", "type": "object" }, "SendingIdentity": { "properties": { "connection_id": { "title": "Connection Id", "type": "string" }, "domain": { "title": "Domain", "type": "string" }, "from_identity": { "title": "From Identity", "type": "string" }, "is_default_identity": { "title": "Is Default Identity", "type": "boolean" }, "sending_domain_id": { "title": "Sending Domain Id", "type": "string" } }, "required": [ "sending_domain_id", "domain", "from_identity", "is_default_identity", "connection_id" ], "title": "SendingIdentity", "type": "object" }, "ServiceAccountMutationResponse": { "properties": { "changed": { "title": "Changed", "type": "boolean" }, "ok": { "title": "Ok", "type": "boolean" } }, "required": [ "ok", "changed" ], "title": "ServiceAccountMutationResponse", "type": "object" }, "ServiceAccountPublic": { "properties": { "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "created_by": { "title": "Created By", "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Description" }, "expires_at": { "format": "date-time", "title": "Expires At", "type": "string" }, "id": { "title": "Id", "type": "string" }, "last_used_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Last Used At" }, "name": { "title": "Name", "type": "string" }, "prefix": { "title": "Prefix", "type": "string" }, "scopes": { "items": { "type": "string" }, "title": "Scopes", "type": "array" } }, "required": [ "id", "name", "prefix", "scopes", "expires_at", "created_by", "created_at" ], "title": "ServiceAccountPublic", "type": "object" }, "ServiceBreakdown": { "properties": { "cache_hits": { "default": 0, "title": "Cache Hits", "type": "integer" }, "calls": { "default": 0, "title": "Calls", "type": "integer" }, "cost_usd": { "default": 0.0, "title": "Cost Usd", "type": "number" }, "hit_rate_pct": { "default": 0.0, "title": "Hit Rate Pct", "type": "number" }, "service": { "title": "Service", "type": "string" }, "total_tokens": { "default": 0, "title": "Total Tokens", "type": "integer" } }, "required": [ "service" ], "title": "ServiceBreakdown", "type": "object" }, "ServiceCoverage": { "properties": { "last_webhook_seen": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Last Webhook Seen" }, "priced_calls": { "default": 0, "title": "Priced Calls", "type": "integer" }, "priced_pct": { "default": 0.0, "title": "Priced Pct", "type": "number" }, "service_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Service Name" }, "total_calls": { "default": 0, "title": "Total Calls", "type": "integer" }, "unattributed_calls": { "default": 0, "title": "Unattributed Calls", "type": "integer" }, "unattributed_pct": { "default": 0.0, "title": "Unattributed Pct", "type": "number" }, "unpriced_calls": { "default": 0, "title": "Unpriced Calls", "type": "integer" }, "unpriced_pct": { "default": 0.0, "title": "Unpriced Pct", "type": "number" } }, "title": "ServiceCoverage", "type": "object" }, "SessionAttentionNotifyRequest": { "description": "One phase transition the router decided is worth a human's attention.", "properties": { "account_id": { "description": "The conversation owner — the recipient.", "title": "Account Id", "type": "string" }, "agent_name": { "title": "Agent Name", "type": "string" }, "coalesce_key": { "description": "The card this alert lands on; shared inside a coalescing window.", "title": "Coalesce Key", "type": "string" }, "conversation_id": { "title": "Conversation Id", "type": "string" }, "deep_link": { "description": "tidy://session/{account}/{conversation}", "title": "Deep Link", "type": "string" }, "episode_key": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The router's episode key (request id, or turn ref). With the conversation and phase it forms the phase-transition id the channel outbox is keyed on (TIDY-16335). Optional so a router from before that story still gets its push emitted during a rolling deploy; without it the SMS/email fan-out is skipped and says so, because an un-keyed send cannot be made idempotent.", "title": "Episode Key" }, "notification_type": { "description": "One of the four conversation-attention types.", "title": "Notification Type", "type": "string" }, "phase": { "description": "The S1 phase transitioned INTO.", "title": "Phase", "type": "string" }, "reason": { "description": "The command, or the error headline.", "title": "Reason", "type": "string" }, "session_title": { "title": "Session Title", "type": "string" }, "tenant_id": { "title": "Tenant Id", "type": "string" }, "window_count": { "default": 1, "minimum": 1.0, "title": "Window Count", "type": "integer" } }, "required": [ "tenant_id", "account_id", "conversation_id", "notification_type", "phase", "agent_name", "session_title", "reason", "deep_link", "coalesce_key" ], "title": "SessionAttentionNotifyRequest", "type": "object" }, "SessionAttentionNotifyResponse": { "properties": { "channels": { "description": "One label per fan-out channel: '{sms|email}:{enqueued|digest|off|quiet_hours|no_address|duplicate}' (TIDY-16335). Empty when the engine did not emit.", "items": { "type": "string" }, "title": "Channels", "type": "array" }, "outcome": { "description": "emitted | suppressed_disabled | suppressed_quiet_hours | deduped | storm_digest", "title": "Outcome", "type": "string" } }, "required": [ "outcome" ], "title": "SessionAttentionNotifyResponse", "type": "object" }, "SessionAttentionWithdrawRequest": { "description": "A conversation that no longer waits on its person in these phases.", "properties": { "conversation_id": { "title": "Conversation Id", "type": "string" }, "phases": { "items": { "enum": [ "needs_input", "needs_approval" ], "type": "string" }, "minItems": 1, "title": "Phases", "type": "array" }, "tenant_id": { "title": "Tenant Id", "type": "string" } }, "required": [ "tenant_id", "conversation_id", "phases" ], "title": "SessionAttentionWithdrawRequest", "type": "object" }, "SessionAttentionWithdrawResponse": { "properties": { "withdrawn": { "description": "Cards taken back, across every recipient.", "title": "Withdrawn", "type": "integer" } }, "required": [ "withdrawn" ], "title": "SessionAttentionWithdrawResponse", "type": "object" }, "SessionCommitEntry": { "properties": { "authored_ref": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Authored Ref" }, "commit_sha": { "title": "Commit Sha", "type": "string" }, "file_versions": { "default": [], "items": { "$ref": "#/components/schemas/ProvenanceFileVersion" }, "title": "File Versions", "type": "array" }, "message_subject": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Message Subject" }, "provider": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Provider" }, "removed_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Removed At" }, "removed_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Removed Reason" }, "repository": { "default": "", "title": "Repository", "type": "string" }, "source_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Source Url" }, "superseded_by_sha": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Superseded By Sha" }, "turn_ordinal": { "title": "Turn Ordinal", "type": "integer" } }, "required": [ "commit_sha", "turn_ordinal" ], "title": "SessionCommitEntry", "type": "object" }, "SessionCommitsResponse": { "properties": { "commits": { "default": [], "items": { "$ref": "#/components/schemas/SessionCommitEntry" }, "title": "Commits", "type": "array" }, "session_id": { "title": "Session Id", "type": "string" } }, "required": [ "session_id" ], "title": "SessionCommitsResponse", "type": "object" }, "SessionHostMigrationActionRequest": { "properties": { "expected_current_rows_sha256": { "pattern": "^[0-9a-f]{64}$", "title": "Expected Current Rows Sha256", "type": "string" }, "migration_id": { "format": "uuid", "title": "Migration Id", "type": "string" }, "request_id": { "format": "uuid", "title": "Request Id", "type": "string" } }, "required": [ "migration_id", "request_id", "expected_current_rows_sha256" ], "title": "SessionHostMigrationActionRequest", "type": "object" }, "SessionHostMigrationPrepareRequest": { "properties": { "conversation_ids": { "items": { "format": "uuid", "type": "string" }, "maxItems": 5000, "minItems": 1, "title": "Conversation Ids", "type": "array" }, "installation_id": { "format": "uuid", "title": "Installation Id", "type": "string" }, "legacy_host": { "maxLength": 255, "minLength": 1, "title": "Legacy Host", "type": "string" }, "migration_id": { "format": "uuid", "title": "Migration Id", "type": "string" }, "new_host": { "maxLength": 255, "minLength": 1, "title": "New Host", "type": "string" }, "request_id": { "format": "uuid", "title": "Request Id", "type": "string" } }, "required": [ "installation_id", "migration_id", "legacy_host", "new_host", "conversation_ids", "request_id" ], "title": "SessionHostMigrationPrepareRequest", "type": "object" }, "SessionHostMigrationResponse": { "properties": { "conversation_count": { "minimum": 0, "title": "Conversation Count", "type": "integer" }, "current_rows_sha256": { "title": "Current Rows Sha256", "type": "string" }, "expires_at": { "format": "date-time", "title": "Expires At", "type": "string" }, "preimage_sha256": { "title": "Preimage Sha256", "type": "string" }, "receipt_id": { "format": "uuid", "title": "Receipt Id", "type": "string" }, "restored_count": { "anyOf": [ { "minimum": 0, "type": "integer" }, { "type": "null" } ], "default": null, "title": "Restored Count" }, "restored_rows_sha256": { "anyOf": [ { "pattern": "^[0-9a-f]{64}$", "type": "string" }, { "type": "null" } ], "default": null, "title": "Restored Rows Sha256" }, "row_count": { "minimum": 0, "title": "Row Count", "type": "integer" }, "status": { "enum": [ "prepared", "committed", "rolled_back", "expired" ], "title": "Status", "type": "string" } }, "required": [ "receipt_id", "status", "conversation_count", "row_count", "preimage_sha256", "current_rows_sha256", "expires_at" ], "title": "SessionHostMigrationResponse", "type": "object" }, "SessionPendingMessage": { "properties": { "content": { "title": "Content", "type": "string" }, "id": { "title": "Id", "type": "string" }, "not_picked_up": { "default": false, "description": "No recorded pickup past the default offline catch-up window; resend if still needed.", "title": "Not Picked Up", "type": "boolean" }, "queued_for_turn_boundary": { "description": "Sent while a turn was running; the employee takes it when that turn ends.", "title": "Queued For Turn Boundary", "type": "boolean" }, "sent_at": { "title": "Sent At", "type": "string" } }, "required": [ "id", "content", "sent_at", "queued_for_turn_boundary" ], "title": "SessionPendingMessage", "type": "object" }, "SessionStatusResponse": { "description": "Authoritative operator probe (the single truth the web layer trusts).", "properties": { "actor_class": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Actor Class" }, "capabilities": { "items": { "type": "string" }, "title": "Capabilities", "type": "array" }, "is_platform_operator": { "title": "Is Platform Operator", "type": "boolean" } }, "required": [ "is_platform_operator", "capabilities" ], "title": "SessionStatusResponse", "type": "object" }, "SessionTranscriptMessage": { "properties": { "content": { "title": "Content", "type": "string" }, "created_at": { "title": "Created At", "type": "string" }, "id": { "title": "Id", "type": "string" }, "role": { "description": "`user` (the member) or `assistant` (the employee).", "title": "Role", "type": "string" }, "terminal_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "How the employee's turn ended when this answer is its last word: `error` (the text is the failure notice), `interrupted`, ...", "title": "Terminal Status" } }, "required": [ "id", "role", "content", "created_at" ], "title": "SessionTranscriptMessage", "type": "object" }, "SessionTranscriptResponse": { "properties": { "agent_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Agent Name" }, "caller_is_owner": { "default": false, "description": "True when the caller is the member the conversation belongs to.", "title": "Caller Is Owner", "type": "boolean" }, "conversation_id": { "title": "Conversation Id", "type": "string" }, "has_more": { "title": "Has More", "type": "boolean" }, "messages": { "items": { "$ref": "#/components/schemas/SessionTranscriptMessage" }, "title": "Messages", "type": "array" }, "next_offset": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Next Offset" }, "shared": { "description": "True when the read ran under the member's share of this one conversation (an audited on-behalf-of read).", "title": "Shared", "type": "boolean" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Title" }, "total": { "description": "Messages matching the request, across every page.", "title": "Total", "type": "integer" }, "turn": { "anyOf": [ { "$ref": "#/components/schemas/SessionTurnStatus" }, { "type": "null" } ], "default": null, "description": "TIDY-19705 — the running turn, the latest answer, and your messages not yet in the transcript." } }, "required": [ "conversation_id", "shared", "messages", "total", "has_more" ], "title": "SessionTranscriptResponse", "type": "object" }, "SessionTurnStatus": { "description": "TIDY-19705 — where the conversation's work stands right now.", "properties": { "answered_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Answered At" }, "employee_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The employee's acting status: `active`, `offline`, ...", "title": "Employee Status" }, "failure": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The failure notice, when `state` is `failed`.", "title": "Failure" }, "last_activity_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Activity At" }, "pending": { "description": "YOUR messages to this conversation that the transcript does not hold yet: an employee's turn records what was said when it ends.", "items": { "$ref": "#/components/schemas/SessionPendingMessage" }, "title": "Pending", "type": "array" }, "state": { "description": "`working` — the employee's turn is running; `needs_attention` — it stopped to wait on someone (an approval or a question); `waiting` — your message is sent and not started yet; `not_picked_up` — no recorded pickup past the default offline catch-up window (resend if still needed); `answered`; `failed` — the turn failed (see `failure`); `idle`.", "title": "State", "type": "string" }, "turn_started_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Turn Started At" } }, "required": [ "state" ], "title": "SessionTurnStatus", "type": "object" }, "SetCellOp": { "additionalProperties": false, "properties": { "cell": { "maxLength": 32, "minLength": 2, "title": "Cell", "type": "string" }, "formula": { "anyOf": [ { "maxLength": 8192, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Formula" }, "op": { "const": "set_cell", "title": "Op", "type": "string" }, "sheet": { "anyOf": [ { "maxLength": 400, "type": "string" }, { "type": "null" } ], "title": "Sheet" }, "value": { "anyOf": [ { "type": "boolean" }, { "type": "integer" }, { "type": "number" }, { "type": "string" }, { "type": "null" } ], "title": "Value" } }, "required": [ "op", "cell" ], "title": "SetCellOp", "type": "object" }, "SetDesignRequest": { "properties": { "design_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Presentation design id to apply, or null to clear.", "title": "Design Id" } }, "title": "SetDesignRequest", "type": "object" }, "SetRangeOp": { "additionalProperties": false, "properties": { "op": { "const": "set_range", "title": "Op", "type": "string" }, "range": { "maxLength": 64, "minLength": 2, "title": "Range", "type": "string" }, "sheet": { "anyOf": [ { "maxLength": 400, "type": "string" }, { "type": "null" } ], "title": "Sheet" }, "values": { "items": { "items": { "anyOf": [ { "type": "boolean" }, { "type": "integer" }, { "type": "number" }, { "type": "string" }, { "type": "null" } ] }, "type": "array" }, "minItems": 1, "title": "Values", "type": "array" } }, "required": [ "op", "range", "values" ], "title": "SetRangeOp", "type": "object" }, "SetSlideLayoutOp": { "additionalProperties": false, "properties": { "layout": { "maxLength": 64, "minLength": 1, "title": "Layout", "type": "string" }, "op": { "const": "set_layout", "title": "Op", "type": "string" }, "slide": { "maximum": 500.0, "minimum": 1.0, "title": "Slide", "type": "integer" } }, "required": [ "op", "slide", "layout" ], "title": "SetSlideLayoutOp", "type": "object" }, "SettingResponse": { "properties": { "key": { "title": "Key", "type": "string" }, "value": { "title": "Value" } }, "required": [ "key", "value" ], "title": "SettingResponse", "type": "object" }, "SetupCheckResponse": { "properties": { "ready": { "title": "Ready", "type": "boolean" }, "setup_steps": { "items": { "$ref": "#/components/schemas/SetupStep" }, "title": "Setup Steps", "type": "array" }, "template_id": { "title": "Template Id", "type": "string" }, "workshop_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Workshop Id" } }, "required": [ "template_id", "setup_steps", "ready" ], "title": "SetupCheckResponse", "type": "object" }, "SetupStep": { "properties": { "code": { "title": "Code", "type": "string" }, "kind": { "title": "Kind", "type": "string" }, "name": { "title": "Name", "type": "string" }, "remedy": { "title": "Remedy", "type": "string" }, "status": { "title": "Status", "type": "string" } }, "required": [ "kind", "name", "status", "code", "remedy" ], "title": "SetupStep", "type": "object" }, "ShadowEvalReportResponse": { "description": "Per-class shadow evidence over the requested window.", "properties": { "classes": { "additionalProperties": true, "default": {}, "title": "Classes", "type": "object" }, "total_evals": { "title": "Total Evals", "type": "integer" }, "window_days": { "title": "Window Days", "type": "integer" } }, "required": [ "window_days", "total_evals" ], "title": "ShadowEvalReportResponse", "type": "object" }, "ShadowMetricsRunRequest": { "properties": { "window_end": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "UTC window end (exclusive).", "title": "Window End" }, "window_start": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "UTC window start (default: previous UTC day).", "title": "Window Start" } }, "title": "ShadowMetricsRunRequest", "type": "object" }, "ShadowMetricsRunResponse": { "properties": { "artifacts": { "items": { "additionalProperties": true, "type": "object" }, "title": "Artifacts", "type": "array" }, "pack_hash_drift": { "items": { "additionalProperties": true, "type": "object" }, "title": "Pack Hash Drift", "type": "array" } }, "required": [ "artifacts", "pack_hash_drift" ], "title": "ShadowMetricsRunResponse", "type": "object" }, "ShareChannelRequest": { "properties": { "peer_server_name": { "maxLength": 253, "minLength": 1, "title": "Peer Server Name", "type": "string" }, "peer_workspace_admin_email": { "anyOf": [ { "maxLength": 320, "type": "string" }, { "type": "null" } ], "title": "Peer Workspace Admin Email" } }, "required": [ "peer_server_name" ], "title": "ShareChannelRequest", "type": "object" }, "ShareChannelResponse": { "properties": { "federated_with_server": { "title": "Federated With Server", "type": "string" }, "federation_state": { "title": "Federation State", "type": "string" }, "room_id": { "title": "Room Id", "type": "string" }, "shared_channel_id": { "title": "Shared Channel Id", "type": "string" } }, "required": [ "shared_channel_id", "room_id", "federated_with_server", "federation_state" ], "title": "ShareChannelResponse", "type": "object" }, "SharedInboxMembership": { "properties": { "account_id": { "format": "uuid", "title": "Account Id", "type": "string" }, "created_at": { "title": "Created At", "type": "string" }, "provider_connection_id": { "format": "uuid", "title": "Provider Connection Id", "type": "string" }, "role": { "title": "Role", "type": "string" }, "status": { "title": "Status", "type": "string" }, "tenant_id": { "format": "uuid", "title": "Tenant Id", "type": "string" }, "updated_at": { "title": "Updated At", "type": "string" }, "version": { "title": "Version", "type": "integer" } }, "required": [ "tenant_id", "provider_connection_id", "account_id", "role", "status", "version", "created_at", "updated_at" ], "title": "SharedInboxMembership", "type": "object" }, "SharedInboxMembershipList": { "properties": { "memberships": { "items": { "$ref": "#/components/schemas/SharedInboxMembership" }, "title": "Memberships", "type": "array" } }, "required": [ "memberships" ], "title": "SharedInboxMembershipList", "type": "object" }, "SharedInboxMembershipUpsert": { "properties": { "expected_version": { "description": "0 creates; otherwise CAS against the row's version.", "minimum": 0.0, "title": "Expected Version", "type": "integer" }, "normalized_address": { "maxLength": 320, "title": "Normalized Address", "type": "string" }, "operation_id": { "format": "uuid", "title": "Operation Id", "type": "string" } }, "required": [ "operation_id", "expected_version", "normalized_address" ], "title": "SharedInboxMembershipUpsert", "type": "object" }, "SheetDataResponse": { "description": "Metadata always; ``fields``/``rows`` only when a window was requested.", "properties": { "defined_names": { "items": { "$ref": "#/components/schemas/DefinedNameSummary" }, "title": "Defined Names", "type": "array" }, "fields": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "default": null, "description": "Column descriptors {key,label,type} for the requested window.", "title": "Fields" }, "rows": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "default": null, "description": "The window's data rows, keyed by column letter.", "title": "Rows" }, "sheet": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "The sheet the requested window resolved against.", "title": "Sheet" }, "sheets": { "items": { "$ref": "#/components/schemas/SheetSummary" }, "title": "Sheets", "type": "array" }, "status": { "description": "resolved | dead_link | empty | over_limit — the same vocabulary a chart source resolves to.", "title": "Status", "type": "string" }, "tables": { "description": "Named tables in the workbook, each with its current range.", "items": { "$ref": "#/components/schemas/TableSummary" }, "title": "Tables", "type": "array" } }, "required": [ "status" ], "title": "SheetDataResponse", "type": "object" }, "SheetSummary": { "description": "One sheet and the extent of its data (not its declared grid size).", "properties": { "column_count": { "title": "Column Count", "type": "integer" }, "name": { "title": "Name", "type": "string" }, "row_count": { "title": "Row Count", "type": "integer" } }, "required": [ "name", "row_count", "column_count" ], "title": "SheetSummary", "type": "object" }, "ShieldDeclineRequest": { "description": "Auto-decline a calendar invite matched by a Shield Generator rule.", "properties": { "account_id": { "description": "Recipient account owning the invite.", "title": "Account Id", "type": "string" }, "decline_message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional decline comment sent on the ICS REPLY.", "title": "Decline Message" }, "event_id": { "description": "Calendar event UUID to decline.", "title": "Event Id", "type": "string" }, "tenant_id": { "description": "Tenant UUID owning the event.", "title": "Tenant Id", "type": "string" } }, "required": [ "tenant_id", "account_id", "event_id" ], "title": "ShieldDeclineRequest", "type": "object" }, "ShieldDeclineResponse": { "properties": { "declined": { "title": "Declined", "type": "boolean" }, "event_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Event Status" } }, "required": [ "declined" ], "title": "ShieldDeclineResponse", "type": "object" }, "ShipRequest": { "properties": { "runtime": { "anyOf": [ { "maxLength": 64, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Runtime" }, "workshop_id": { "title": "Workshop Id", "type": "string" } }, "required": [ "workshop_id" ], "title": "ShipRequest", "type": "object" }, "SignGateResponse": { "properties": { "document_note_id": { "title": "Document Note Id", "type": "string" }, "passed": { "title": "Passed", "type": "boolean" }, "reason": { "title": "Reason", "type": "string" }, "signed": { "title": "Signed", "type": "boolean" } }, "required": [ "document_note_id", "passed", "signed", "reason" ], "title": "SignGateResponse", "type": "object" }, "SignInEventRequest": { "description": "Request body for logging sign-in events.", "properties": { "failure_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Failure Reason" }, "provider": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Provider" }, "success": { "default": true, "title": "Success", "type": "boolean" } }, "title": "SignInEventRequest", "type": "object" }, "SignRequestBody": { "description": "Request to sign an outgoing HTTP request.", "properties": { "body": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional request body (will be hashed for signature)", "title": "Body" }, "headers": { "anyOf": [ { "additionalProperties": { "type": "string" }, "type": "object" }, { "type": "null" } ], "description": "Optional existing headers to include in signature", "title": "Headers" }, "method": { "description": "HTTP method (GET, POST, etc)", "title": "Method", "type": "string" }, "plugin": { "description": "The Custom API plugin to sign with: its name in Plugins, or its id", "title": "Plugin", "type": "string" }, "url": { "description": "Full request URL", "title": "Url", "type": "string" } }, "required": [ "plugin", "method", "url" ], "title": "SignRequestBody", "type": "object" }, "SignRequestResponse": { "description": "Response from signing a request.", "properties": { "canonical_string": { "description": "Canonical string that was signed (for diagnostics)", "title": "Canonical String", "type": "string" }, "headers": { "additionalProperties": { "type": "string" }, "description": "Signed headers to include in the outgoing request", "title": "Headers", "type": "object" } }, "required": [ "headers", "canonical_string" ], "title": "SignRequestResponse", "type": "object" }, "SignalBatch": { "description": "A batch of behavior signals from one client install.", "properties": { "client_id": { "maxLength": 128, "minLength": 1, "title": "Client Id", "type": "string" }, "events": { "items": { "$ref": "#/components/schemas/SignalEvent" }, "maxItems": 100, "minItems": 1, "title": "Events", "type": "array" } }, "required": [ "client_id", "events" ], "title": "SignalBatch", "type": "object" }, "SignalBatchResult": { "description": "Upload result. Duplicates are counted, not errored.\n\nTIDY-11630: `rejected` + `rejected_event_ids` let the client outbox flusher\ndrop exactly the poison events (mark them terminal) and delete the rest,\ninstead of penalizing the whole batch.", "properties": { "duplicates": { "title": "Duplicates", "type": "integer" }, "inserted": { "title": "Inserted", "type": "integer" }, "received": { "title": "Received", "type": "integer" }, "rejected": { "default": 0, "title": "Rejected", "type": "integer" }, "rejected_event_ids": { "items": { "type": "string" }, "title": "Rejected Event Ids", "type": "array" }, "suppressed": { "default": 0, "title": "Suppressed", "type": "integer" }, "suppressed_event_ids": { "items": { "type": "string" }, "title": "Suppressed Event Ids", "type": "array" } }, "required": [ "received", "inserted", "duplicates" ], "title": "SignalBatchResult", "type": "object" }, "SignalEvent": { "description": "A single behavior signal in an upload batch.\n\nTIDY-11630 (F1-S6): the per-event business rules (allowed event/target\ntypes, the occurred_at window) are NO LONGER Pydantic field validators —\nthose rejected the WHOLE 100-event batch at FastAPI body validation, so one\nstale or malformed event poisoned its 99 valid batch-mates (the offline-\nreopen 422 storm). The structural constraints (lengths, weight range, type\ncoercion) stay; the business rules move to `_validate_signal_event`, applied\nPER EVENT in the handler so a poison event is isolated and reported, not\nfatal to the batch.", "properties": { "client_event_id": { "maxLength": 128, "minLength": 1, "title": "Client Event Id", "type": "string" }, "context": { "additionalProperties": true, "title": "Context", "type": "object" }, "event_type": { "title": "Event Type", "type": "string" }, "occurred_at": { "format": "date-time", "title": "Occurred At", "type": "string" }, "source_surface": { "anyOf": [ { "maxLength": 64, "type": "string" }, { "type": "null" } ], "title": "Source Surface" }, "target_id": { "title": "Target Id", "type": "string" }, "target_id_secondary": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Target Id Secondary" }, "target_type": { "title": "Target Type", "type": "string" }, "usage_idempotency_key": { "anyOf": [ { "maxLength": 128, "type": "string" }, { "type": "null" } ], "title": "Usage Idempotency Key" }, "weight": { "default": 1.0, "maximum": 10.0, "minimum": -10.0, "title": "Weight", "type": "number" } }, "required": [ "client_event_id", "event_type", "target_type", "target_id", "occurred_at" ], "title": "SignalEvent", "type": "object" }, "SignatureRequestResponse": { "properties": { "audit": { "items": { "additionalProperties": true, "type": "object" }, "title": "Audit", "type": "array" }, "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "document_content_hash": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Document Content Hash" }, "document_note_id": { "title": "Document Note Id", "type": "string" }, "expires_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Expires At" }, "id": { "title": "Id", "type": "string" }, "retention_class": { "title": "Retention Class", "type": "string" }, "sent_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Sent At" }, "signed_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Signed At" }, "signed_pdf_file_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Signed Pdf File Id" }, "signer_email": { "title": "Signer Email", "type": "string" }, "signer_name": { "title": "Signer Name", "type": "string" }, "status": { "title": "Status", "type": "string" }, "tenant_id": { "title": "Tenant Id", "type": "string" }, "updated_at": { "format": "date-time", "title": "Updated At", "type": "string" }, "viewed_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Viewed At" } }, "required": [ "id", "tenant_id", "document_note_id", "signer_name", "signer_email", "status", "retention_class", "created_at", "updated_at" ], "title": "SignatureRequestResponse", "type": "object" }, "SignatureResolveRequest": { "description": "Recipients the signature slot is being chosen for.", "properties": { "recipients": { "description": "To/Cc/Bcc addresses of the message being composed. An empty list resolves the external slot, matching the send-time default for a message with no addressees yet.", "items": { "type": "string" }, "title": "Recipients", "type": "array" } }, "title": "SignatureResolveRequest", "type": "object" }, "SignatureResolveResponse": { "description": "The signature that WOULD be applied to a send to these recipients.", "properties": { "appended": { "description": "False when no signature applies.", "title": "Appended", "type": "boolean" }, "body_html": { "default": "", "description": "Rendered signature HTML.", "title": "Body Html", "type": "string" }, "body_text": { "default": "", "description": "Rendered signature plain text.", "title": "Body Text", "type": "string" }, "scope": { "description": "within | outside | none", "title": "Scope", "type": "string" } }, "required": [ "appended", "scope" ], "title": "SignatureResolveResponse", "type": "object" }, "SignedInSession": { "properties": { "app": { "title": "App", "type": "string" }, "current": { "default": false, "title": "Current", "type": "boolean" }, "device": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Device" }, "family_id": { "title": "Family Id", "type": "string" }, "ip_masked": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Ip Masked" }, "last_active_at": { "format": "date-time", "title": "Last Active At", "type": "string" }, "per_device_revoke_supported": { "default": true, "title": "Per Device Revoke Supported", "type": "boolean" }, "signed_in_at": { "format": "date-time", "title": "Signed In At", "type": "string" } }, "required": [ "family_id", "app", "signed_in_at", "last_active_at" ], "title": "SignedInSession", "type": "object" }, "SignedInSessionsResponse": { "properties": { "sessions": { "items": { "$ref": "#/components/schemas/SignedInSession" }, "title": "Sessions", "type": "array" } }, "required": [ "sessions" ], "title": "SignedInSessionsResponse", "type": "object" }, "Signer": { "properties": { "email": { "format": "email", "title": "Email", "type": "string" }, "name": { "maxLength": 200, "minLength": 1, "title": "Name", "type": "string" } }, "required": [ "name", "email" ], "title": "Signer", "type": "object" }, "SignupAttribution": { "description": "First-party attribution context handed off from the marketing site to\napp signup. All fields optional — an organic (no-UTM) signup still records\na signup event so the tenant is present in the chain (TIDY-12082).", "properties": { "anonymous_id": { "anyOf": [ { "maxLength": 128, "type": "string" }, { "type": "null" } ], "title": "Anonymous Id" }, "landing_path": { "anyOf": [ { "maxLength": 2048, "type": "string" }, { "type": "null" } ], "title": "Landing Path" }, "referrer": { "anyOf": [ { "maxLength": 2048, "type": "string" }, { "type": "null" } ], "title": "Referrer" }, "utm_campaign": { "anyOf": [ { "maxLength": 256, "type": "string" }, { "type": "null" } ], "title": "Utm Campaign" }, "utm_content": { "anyOf": [ { "maxLength": 256, "type": "string" }, { "type": "null" } ], "title": "Utm Content" }, "utm_medium": { "anyOf": [ { "maxLength": 256, "type": "string" }, { "type": "null" } ], "title": "Utm Medium" }, "utm_source": { "anyOf": [ { "maxLength": 256, "type": "string" }, { "type": "null" } ], "title": "Utm Source" }, "utm_term": { "anyOf": [ { "maxLength": 256, "type": "string" }, { "type": "null" } ], "title": "Utm Term" } }, "title": "SignupAttribution", "type": "object" }, "SignupRequest": { "properties": { "email": { "format": "email", "title": "Email", "type": "string" }, "human_check_token": { "anyOf": [ { "maxLength": 4096, "type": "string" }, { "type": "null" } ], "title": "Human Check Token" }, "invite_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Invite Code" }, "password": { "minLength": 8, "title": "Password", "type": "string" }, "user_metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "User Metadata" } }, "required": [ "email", "password" ], "title": "SignupRequest", "type": "object" }, "SignupResponse": { "description": "Response shape for POST /api/v1/auth/signup.\n\nUnder the gated identity model (TIDY-12626), a fresh signup creates an\nidentity with NO tenant yet — tenant birth is deferred to the invite-gated\n`/tenants/provision` boundary.\n\n * `signup_state` is the server-authoritative next step the signup page\n acts on — `needs_invite` (invite-only ON and no valid code: the client\n shows the invite step / warm waitlist, and the server has already\n captured a lead) or `needs_verify` (proceed to email verification).\n * A tenantless signup receives a one-hour, access-only bootstrap bearer:\n `verified=false`, no `tenant_id`, no scopes, and no refresh token. The\n hard-wall middleware (TIDY-9373) limits it to the pre-verification\n allowlist. A returning account with a tenant keeps the existing full\n pre-verification session shape.", "properties": { "email_confirmed_at": { "title": "Email Confirmed At" }, "expires_in": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Expires In" }, "refresh_token": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Refresh Token" }, "signup_state": { "default": "needs_verify", "title": "Signup State", "type": "string" }, "tidy_access_token": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Tidy Access Token" }, "token_type": { "default": "Bearer", "title": "Token Type", "type": "string" }, "user_id": { "title": "User Id", "type": "string" }, "verified": { "default": false, "title": "Verified", "type": "boolean" } }, "required": [ "user_id" ], "title": "SignupResponse", "type": "object" }, "SimilarProject": { "description": "A project that matches the searched name.", "properties": { "id": { "description": "Project UUID", "title": "Id", "type": "string" }, "name": { "description": "Project name", "title": "Name", "type": "string" }, "project_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Project type", "title": "Project Type" }, "similarity_score": { "description": "Similarity score (0-1)", "title": "Similarity Score", "type": "number" }, "status": { "description": "Project status", "title": "Status", "type": "string" } }, "required": [ "id", "name", "similarity_score", "status" ], "title": "SimilarProject", "type": "object" }, "SizeBreakdown": { "properties": { "large": { "title": "Large", "type": "integer" }, "one_on_one": { "title": "One On One", "type": "integer" }, "small": { "title": "Small", "type": "integer" } }, "required": [ "one_on_one", "small", "large" ], "title": "SizeBreakdown", "type": "object" }, "SkillAssetScript": { "description": "One executable file of the skill asset (TIDY-17034).\n\nDistinct from the retired per-skill `skill_scripts` rows and from\nworkflow links: these are plain files materialized next to SKILL.md.", "properties": { "language": { "default": "python", "enum": [ "python", "javascript", "typescript", "shell" ], "title": "Language", "type": "string" }, "name": { "maxLength": 128, "minLength": 1, "title": "Name", "type": "string" }, "source": { "default": "", "maxLength": 1048576, "title": "Source", "type": "string" } }, "required": [ "name" ], "title": "SkillAssetScript", "type": "object" }, "SkillBundle": { "description": "The whole authored skill (TIDY-17069 R1).\n\n``body`` EXCLUDES the frontmatter — the canonical ``SKILL.md`` is\n``frontmatter_raw + body``. ``os_variants`` are BODY-ONLY: a variant never\ncarries frontmatter of its own, so it cannot disagree with the skill's\ndeclared credentials, workflows or os.", "properties": { "body": { "default": "", "maxLength": 1048576, "title": "Body", "type": "string" }, "frontmatter_raw": { "default": "", "maxLength": 1048576, "title": "Frontmatter Raw", "type": "string" }, "os_variants": { "additionalProperties": { "type": "string" }, "title": "Os Variants", "type": "object" }, "references": { "items": { "$ref": "#/components/schemas/SkillBundleReference" }, "maxItems": 256, "title": "References", "type": "array" }, "scripts": { "items": { "$ref": "#/components/schemas/SkillAssetScript" }, "maxItems": 256, "title": "Scripts", "type": "array" } }, "title": "SkillBundle", "type": "object" }, "SkillBundleReference": { "description": "One ``references/.md`` file of the bundle (TIDY-17069).", "properties": { "content": { "default": "", "maxLength": 1048576, "title": "Content", "type": "string" }, "name": { "maxLength": 128, "minLength": 1, "title": "Name", "type": "string" } }, "required": [ "name" ], "title": "SkillBundleReference", "type": "object" }, "SkillBundleRefusal": { "description": "One skill the host refused to install, and the keys that blocked it.", "properties": { "missing_credentials": { "items": { "type": "string" }, "maxItems": 32, "title": "Missing Credentials", "type": "array" }, "slug": { "maxLength": 128, "title": "Slug", "type": "string" } }, "required": [ "slug" ], "title": "SkillBundleRefusal", "type": "object" }, "SkillCarrierPlan": { "description": "One employee carrying a skill version on one place (TIDY-20019 F10):\nevery harness (``runtime`` null) or one harness's own list, with what its\napproval of that version would need from you.", "properties": { "agent_account_id": { "title": "Agent Account Id", "type": "string" }, "plan": { "$ref": "#/components/schemas/SkillPluginAccessPlan" }, "runtime": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Runtime" }, "version": { "title": "Version", "type": "integer" } }, "required": [ "agent_account_id", "version", "plan" ], "title": "SkillCarrierPlan", "type": "object" }, "SkillCarriersPluginAccess": { "description": "The employees carrying a skill whose access you could approve and is\nstill open — what a save or a promote asks about. Ids only; names are the\nclient's own synced rows.", "properties": { "carriers": { "items": { "$ref": "#/components/schemas/SkillCarrierPlan" }, "title": "Carriers", "type": "array" }, "skill_id": { "title": "Skill Id", "type": "string" } }, "required": [ "skill_id", "carriers" ], "title": "SkillCarriersPluginAccess", "type": "object" }, "SkillCollectionAssignmentCreate": { "description": "Assign a collection, with the plugin access its skills need approved in\nthe same gesture (TIDY-19802 F2).", "properties": { "ai_employee_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Ai Employee Id" }, "assign_pending": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Assign Pending" }, "employee_account_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Employee Account Id" }, "employee_kind": { "default": "virtual_employee", "enum": [ "virtual_employee", "ai_employee" ], "title": "Employee Kind", "type": "string" }, "plugin_access": { "anyOf": [ { "items": { "$ref": "#/components/schemas/PluginAccessChoice" }, "maxItems": 16, "type": "array" }, { "type": "null" } ], "title": "Plugin Access" }, "requirements_hash": { "anyOf": [ { "maxLength": 64, "minLength": 64, "type": "string" }, { "type": "null" } ], "title": "Requirements Hash" }, "runtime": { "anyOf": [ { "maxLength": 64, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Runtime" }, "secret_files": { "anyOf": [ { "items": { "$ref": "#/components/schemas/SecretFileChoice" }, "maxItems": 16, "type": "array" }, { "type": "null" } ], "title": "Secret Files" }, "sync_mode": { "default": "tracked", "enum": [ "tracked", "pinned" ], "title": "Sync Mode", "type": "string" } }, "title": "SkillCollectionAssignmentCreate", "type": "object" }, "SkillCollectionAssignmentResponse": { "properties": { "ai_employee_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Ai Employee Id" }, "collection_id": { "title": "Collection Id", "type": "string" }, "collection_name": { "title": "Collection Name", "type": "string" }, "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "current_version_hash": { "default": "", "title": "Current Version Hash", "type": "string" }, "employee_account_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Employee Account Id" }, "employee_kind": { "enum": [ "virtual_employee", "ai_employee" ], "title": "Employee Kind", "type": "string" }, "employee_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Employee Name" }, "id": { "title": "Id", "type": "string" }, "last_synced_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Last Synced At" }, "promoted_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Promoted At" }, "promoted_version_hash": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Promoted Version Hash" }, "runtime": { "anyOf": [ { "maxLength": 64, "minLength": 1, "type": "string" }, { "type": "null" } ], "default": null, "title": "Runtime" }, "sync_error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Sync Error" }, "sync_mode": { "enum": [ "tracked", "pinned" ], "title": "Sync Mode", "type": "string" }, "sync_state": { "default": "pending", "enum": [ "pending", "ok", "failed" ], "title": "Sync State", "type": "string" }, "synced_version_hash": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Synced Version Hash" }, "update_available": { "default": false, "title": "Update Available", "type": "boolean" }, "updated_at": { "format": "date-time", "title": "Updated At", "type": "string" } }, "required": [ "id", "collection_id", "collection_name", "employee_kind", "employee_account_id", "ai_employee_id", "sync_mode", "created_at", "updated_at" ], "title": "SkillCollectionAssignmentResponse", "type": "object" }, "SkillCollectionAssignmentUpdate": { "properties": { "runtime": { "anyOf": [ { "maxLength": 64, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Runtime" }, "sync_mode": { "anyOf": [ { "enum": [ "tracked", "pinned" ], "type": "string" }, { "type": "null" } ], "title": "Sync Mode" } }, "title": "SkillCollectionAssignmentUpdate", "type": "object" }, "SkillCollectionCreate": { "properties": { "description": { "default": "", "maxLength": 2000, "title": "Description", "type": "string" }, "name": { "maxLength": 128, "minLength": 1, "title": "Name", "type": "string" }, "scope": { "default": "member", "enum": [ "member", "org" ], "title": "Scope", "type": "string" }, "skill_ids": { "items": { "type": "string" }, "maxItems": 64, "title": "Skill Ids", "type": "array" } }, "required": [ "name" ], "title": "SkillCollectionCreate", "type": "object" }, "SkillCollectionDetailResponse": { "properties": { "assignment_count": { "default": 0, "title": "Assignment Count", "type": "integer" }, "assignments": { "items": { "$ref": "#/components/schemas/SkillCollectionAssignmentResponse" }, "title": "Assignments", "type": "array" }, "can_assign": { "default": true, "title": "Can Assign", "type": "boolean" }, "can_manage": { "default": false, "title": "Can Manage", "type": "boolean" }, "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "description": { "title": "Description", "type": "string" }, "grants": { "items": { "$ref": "#/components/schemas/SkillCollectionGrantResponse" }, "title": "Grants", "type": "array" }, "id": { "title": "Id", "type": "string" }, "item_count": { "default": 0, "title": "Item Count", "type": "integer" }, "items": { "items": { "$ref": "#/components/schemas/SkillCollectionItemResponse" }, "title": "Items", "type": "array" }, "name": { "title": "Name", "type": "string" }, "owner_id": { "title": "Owner Id", "type": "string" }, "owner_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Owner Name" }, "plugin_access": { "items": { "$ref": "#/components/schemas/AppliedPluginAccess" }, "title": "Plugin Access", "type": "array" }, "scope": { "enum": [ "member", "org" ], "title": "Scope", "type": "string" }, "tenant_id": { "title": "Tenant Id", "type": "string" }, "updated_at": { "format": "date-time", "title": "Updated At", "type": "string" }, "version_hash": { "default": "", "title": "Version Hash", "type": "string" } }, "required": [ "id", "tenant_id", "owner_id", "name", "description", "scope", "created_at", "updated_at" ], "title": "SkillCollectionDetailResponse", "type": "object" }, "SkillCollectionGrantCreate": { "properties": { "grantee_account_id": { "title": "Grantee Account Id", "type": "string" }, "permission": { "default": "assign", "enum": [ "view", "assign" ], "title": "Permission", "type": "string" } }, "required": [ "grantee_account_id" ], "title": "SkillCollectionGrantCreate", "type": "object" }, "SkillCollectionGrantResponse": { "properties": { "collection_id": { "title": "Collection Id", "type": "string" }, "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "grantee_account_id": { "title": "Grantee Account Id", "type": "string" }, "grantee_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Grantee Name" }, "id": { "title": "Id", "type": "string" }, "permission": { "enum": [ "view", "assign" ], "title": "Permission", "type": "string" } }, "required": [ "id", "collection_id", "grantee_account_id", "permission", "created_at" ], "title": "SkillCollectionGrantResponse", "type": "object" }, "SkillCollectionItemResponse": { "properties": { "added_at": { "format": "date-time", "title": "Added At", "type": "string" }, "content_hash": { "title": "Content Hash", "type": "string" }, "description": { "title": "Description", "type": "string" }, "name": { "title": "Name", "type": "string" }, "skill_id": { "title": "Skill Id", "type": "string" }, "version": { "title": "Version", "type": "integer" } }, "required": [ "skill_id", "name", "description", "version", "content_hash", "added_at" ], "title": "SkillCollectionItemResponse", "type": "object" }, "SkillCollectionItemsUpdate": { "description": "Reconcile the pack to exactly these skills.", "properties": { "skill_ids": { "items": { "type": "string" }, "maxItems": 64, "title": "Skill Ids", "type": "array" } }, "title": "SkillCollectionItemsUpdate", "type": "object" }, "SkillCollectionResponse": { "properties": { "assignment_count": { "default": 0, "title": "Assignment Count", "type": "integer" }, "can_assign": { "default": true, "title": "Can Assign", "type": "boolean" }, "can_manage": { "default": false, "title": "Can Manage", "type": "boolean" }, "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "description": { "title": "Description", "type": "string" }, "id": { "title": "Id", "type": "string" }, "item_count": { "default": 0, "title": "Item Count", "type": "integer" }, "name": { "title": "Name", "type": "string" }, "owner_id": { "title": "Owner Id", "type": "string" }, "owner_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Owner Name" }, "scope": { "enum": [ "member", "org" ], "title": "Scope", "type": "string" }, "tenant_id": { "title": "Tenant Id", "type": "string" }, "updated_at": { "format": "date-time", "title": "Updated At", "type": "string" }, "version_hash": { "default": "", "title": "Version Hash", "type": "string" } }, "required": [ "id", "tenant_id", "owner_id", "name", "description", "scope", "created_at", "updated_at" ], "title": "SkillCollectionResponse", "type": "object" }, "SkillCollectionUpdate": { "properties": { "description": { "anyOf": [ { "maxLength": 2000, "type": "string" }, { "type": "null" } ], "title": "Description" }, "name": { "anyOf": [ { "maxLength": 128, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Name" }, "scope": { "anyOf": [ { "enum": [ "member", "org" ], "type": "string" }, { "type": "null" } ], "title": "Scope" } }, "title": "SkillCollectionUpdate", "type": "object" }, "SkillCopyRequest": { "description": "Explicit fork — the ONLY path that duplicates skill content (D11).", "properties": { "name": { "anyOf": [ { "maxLength": 128, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Name" } }, "title": "SkillCopyRequest", "type": "object" }, "SkillCreate": { "properties": { "asset_scripts": { "items": { "$ref": "#/components/schemas/SkillAssetScript" }, "maxItems": 32, "title": "Asset Scripts", "type": "array" }, "assistant_applicability": { "default": "assistant_and_ve", "enum": [ "assistant_and_ve", "ve_only" ], "title": "Assistant Applicability", "type": "string" }, "bundle": { "anyOf": [ { "$ref": "#/components/schemas/SkillBundle" }, { "type": "null" } ] }, "description": { "anyOf": [ { "maxLength": 2000, "type": "string" }, { "type": "null" } ], "title": "Description" }, "enabled": { "default": true, "title": "Enabled", "type": "boolean" }, "is_default": { "default": false, "title": "Is Default", "type": "boolean" }, "markdown": { "default": "", "maxLength": 200000, "title": "Markdown", "type": "string" }, "name": { "maxLength": 128, "minLength": 1, "title": "Name", "type": "string" }, "provenance": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Provenance" }, "scripts": { "items": { "$ref": "#/components/schemas/SkillScriptInput" }, "title": "Scripts", "type": "array" }, "visibility": { "default": "private", "enum": [ "private", "shared", "tenant", "global" ], "title": "Visibility", "type": "string" }, "workflow_ids": { "items": { "type": "string" }, "maxItems": 16, "title": "Workflow Ids", "type": "array" } }, "required": [ "name" ], "title": "SkillCreate", "type": "object" }, "SkillCredentialDeclaration": { "description": "A credential SLOT the skill needs — never a value (TIDY-17069 R4).", "properties": { "env_key": { "maxLength": 128, "minLength": 1, "title": "Env Key", "type": "string" }, "purpose": { "anyOf": [ { "maxLength": 500, "type": "string" }, { "type": "null" } ], "title": "Purpose" }, "required": { "default": true, "title": "Required", "type": "boolean" } }, "required": [ "env_key" ], "title": "SkillCredentialDeclaration", "type": "object" }, "SkillCredentialSlotStatus": { "description": "One declared credential SLOT and whether this employee has it filled.\n\nTIDY-17071 (S3 / R4/R5). Slot NAMES only — a value never appears here, nor\nin any payload, badge, log line or receipt derived from it.\n``credential_status`` is the state of the matching credential when one\nexists but cannot be used (``revoked`` / ``refresh_error`` /\n``rotation_required``), so the UI says why instead of \"missing\".\nTIDY-19569 F1 adds ``ambiguous`` (several usable credentials from one\nholder — never picked between); ``unsatisfiable_on_harness`` now means a\nTidy/harness control key (any runtime) or a harness with no per-turn env.", "properties": { "credential_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Credential Status" }, "delivery_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Delivery Reason" }, "delivery_state": { "anyOf": [ { "enum": [ "not_shipped", "other_workshop", "failed", "refused", "held", "pending_ack", "ready" ], "type": "string" }, { "type": "null" } ], "default": null, "title": "Delivery State" }, "env_key": { "title": "Env Key", "type": "string" }, "grant_hint": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Grant Hint" }, "grant_status": { "anyOf": [ { "enum": [ "granted", "not_granted", "ambiguous", "revoked", "refresh_error", "rotation_required", "control_key", "harness_without_env" ], "type": "string" }, { "type": "null" } ], "default": null, "title": "Grant Status" }, "plugin_kind": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Plugin Kind" }, "purpose": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Purpose" }, "required": { "default": true, "title": "Required", "type": "boolean" }, "satisfied": { "default": false, "title": "Satisfied", "type": "boolean" }, "skill_file_only": { "default": false, "title": "Skill File Only", "type": "boolean" } }, "required": [ "env_key" ], "title": "SkillCredentialSlotStatus", "type": "object" }, "SkillCustomization": { "description": "A Tidy skill and the workspace's customization of it.", "properties": { "customization_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Customization Id" }, "published_version": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Published Version" }, "skill_id": { "title": "Skill Id", "type": "string" }, "tidy_version": { "title": "Tidy Version", "type": "integer" } }, "required": [ "skill_id", "tidy_version" ], "title": "SkillCustomization", "type": "object" }, "SkillDraftAccepted": { "description": "Durably published: exactly this version is now what every tracked\ncarrier of the skill is served. A merely stored draft is never accepted.", "properties": { "content_hash": { "title": "Content Hash", "type": "string" }, "kind": { "const": "accepted", "title": "Kind", "type": "string" }, "projection": { "enum": [ "canonical", "linux", "macos", "windows" ], "title": "Projection", "type": "string" }, "skill_id": { "title": "Skill Id", "type": "string" }, "version": { "title": "Version", "type": "integer" } }, "required": [ "kind", "skill_id", "version", "content_hash", "projection" ], "title": "SkillDraftAccepted", "type": "object" }, "SkillDraftBase": { "additionalProperties": false, "description": "The managed version the draft was opened against (the connector's\n``ManagedSkillRecord`` identity), captured when the draft opened.", "properties": { "content_hash": { "maxLength": 128, "minLength": 1, "title": "Content Hash", "type": "string" }, "projection": { "enum": [ "canonical", "linux", "macos", "windows" ], "title": "Projection", "type": "string" }, "skill_id": { "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "title": "Skill Id", "type": "string" }, "version": { "minimum": 1.0, "title": "Version", "type": "integer" } }, "required": [ "skill_id", "version", "content_hash", "projection" ], "title": "SkillDraftBase", "type": "object" }, "SkillDraftConflict": { "description": "The skill moved past the draft's base. ``kept_edit``: the edit is kept\nas ``conflict_version`` beside the head; otherwise nothing was kept and\nthere is no conflict version.", "properties": { "base_version": { "title": "Base Version", "type": "integer" }, "conflict_version": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Conflict Version" }, "head_version": { "title": "Head Version", "type": "integer" }, "kept_edit": { "title": "Kept Edit", "type": "boolean" }, "kind": { "const": "conflict", "title": "Kind", "type": "string" }, "skill_id": { "title": "Skill Id", "type": "string" } }, "required": [ "kind", "skill_id", "kept_edit", "base_version", "head_version" ], "title": "SkillDraftConflict", "type": "object" }, "SkillDraftPending": { "description": "Nothing was written: the draft stays private, and a later turn of the\nsame conversation may offer it again under ITS authority.", "properties": { "code": { "title": "Code", "type": "string" }, "kind": { "const": "pending", "title": "Kind", "type": "string" }, "message": { "title": "Message", "type": "string" }, "reason": { "enum": [ "unauthorized", "expired", "deletion_intent" ], "title": "Reason", "type": "string" } }, "required": [ "kind", "reason", "code", "message" ], "title": "SkillDraftPending", "type": "object" }, "SkillDraftPublicationReceipt": { "description": "The answer for one sealed draft (the connector's ``PublishReceipt``).\n\n``replayed``: the recorded answer of an earlier call for this same draft —\nno new version, assignment or audit entry was made.", "properties": { "draft_id": { "title": "Draft Id", "type": "string" }, "outcome": { "discriminator": { "mapping": { "accepted": "#/components/schemas/SkillDraftAccepted", "conflict": "#/components/schemas/SkillDraftConflict", "pending": "#/components/schemas/SkillDraftPending", "refused": "#/components/schemas/SkillDraftRefused" }, "propertyName": "kind" }, "oneOf": [ { "$ref": "#/components/schemas/SkillDraftAccepted" }, { "$ref": "#/components/schemas/SkillDraftConflict" }, { "$ref": "#/components/schemas/SkillDraftPending" }, { "$ref": "#/components/schemas/SkillDraftRefused" } ], "title": "Outcome" }, "replayed": { "default": false, "title": "Replayed", "type": "boolean" }, "snapshot_digest": { "title": "Snapshot Digest", "type": "string" } }, "required": [ "draft_id", "snapshot_digest", "outcome" ], "title": "SkillDraftPublicationReceipt", "type": "object" }, "SkillDraftPublishRequest": { "additionalProperties": false, "description": "A sealed private skill draft, offered for publication (TIDY-19569 R4d).\n\n``bundle`` is the WHOLE canonical bundle the gateway reconstructed from\nthe sealed rendered bytes and the draft's base — never a path. ``base`` is\nnull for a new skill created in the managed draft root. A whole-skill\ndeletion carries no bundle: it is an intent, and is never applied.", "properties": { "base": { "anyOf": [ { "$ref": "#/components/schemas/SkillDraftBase" }, { "type": "null" } ] }, "bundle": { "anyOf": [ { "$ref": "#/components/schemas/SkillBundle" }, { "type": "null" } ] }, "scope": { "$ref": "#/components/schemas/SkillDraftScope" }, "skill_key": { "pattern": "^[A-Za-z0-9_][A-Za-z0-9._-]{0,127}$", "title": "Skill Key", "type": "string" }, "snapshot_digest": { "pattern": "^[0-9a-f]{64}$", "title": "Snapshot Digest", "type": "string" }, "whole_skill_deletion": { "default": false, "title": "Whole Skill Deletion", "type": "boolean" } }, "required": [ "scope", "skill_key", "snapshot_digest" ], "title": "SkillDraftPublishRequest", "type": "object" }, "SkillDraftRefused": { "description": "Not publishable as offered. Never published; ``saved`` says what was kept.", "properties": { "code": { "title": "Code", "type": "string" }, "fields": { "items": { "$ref": "#/components/schemas/SkillValidationError" }, "title": "Fields", "type": "array" }, "kind": { "const": "refused", "title": "Kind", "type": "string" }, "message": { "title": "Message", "type": "string" }, "saved": { "$ref": "#/components/schemas/SkillDraftRefusedSave" } }, "required": [ "kind", "code", "message", "saved" ], "title": "SkillDraftRefused", "type": "object" }, "SkillDraftRefusedSave": { "description": "What a refusal left on the server: nothing, or an invalid draft record.", "properties": { "draft_record_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Draft Record Id" }, "kind": { "enum": [ "none", "stored_invalid" ], "title": "Kind", "type": "string" } }, "required": [ "kind" ], "title": "SkillDraftRefusedSave", "type": "object" }, "SkillDraftScope": { "additionalProperties": false, "description": "Whose private draft this is (TIDY-19569 R4d / TIDY-19557 F2 ``DraftScope``).\n\nBinding only, never authority: every field must equal what the presenting\nturn credential's own row records, or nothing is published.", "properties": { "audience_key": { "maxLength": 300, "minLength": 1, "title": "Audience Key", "type": "string" }, "conversation_id": { "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "title": "Conversation Id", "type": "string" }, "employee_id": { "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "title": "Employee Id", "type": "string" }, "runtime": { "maxLength": 64, "minLength": 1, "title": "Runtime", "type": "string" }, "tenant_id": { "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "title": "Tenant Id", "type": "string" } }, "required": [ "tenant_id", "employee_id", "conversation_id", "audience_key", "runtime" ], "title": "SkillDraftScope", "type": "object" }, "SkillEnvDeclaration": { "description": "One env name one carried skill declares, with that skill's own\nrequiredness (TIDY-19802). Names, ids and versions only — never a value.", "properties": { "env_key": { "title": "Env Key", "type": "string" }, "required": { "title": "Required", "type": "boolean" }, "skill": { "title": "Skill", "type": "string" }, "skill_id": { "title": "Skill Id", "type": "string" }, "version": { "title": "Version", "type": "integer" } }, "required": [ "env_key", "skill", "skill_id", "version", "required" ], "title": "SkillEnvDeclaration", "type": "object" }, "SkillExecuteAccepted": { "properties": { "invocation_id": { "title": "Invocation Id", "type": "string" }, "status": { "default": "queued", "title": "Status", "type": "string" }, "temporal_execution_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Temporal Execution Id" } }, "required": [ "invocation_id" ], "title": "SkillExecuteAccepted", "type": "object" }, "SkillExecuteAsyncRequest": { "description": "Body for ``POST /skills/{id}/execute-async`` (TIDY-11351 / S3).", "properties": { "agent_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Agent Id" }, "conversation_id": { "description": "Conversation to resume on completion.", "title": "Conversation Id", "type": "string" }, "depth": { "default": 0, "minimum": 0.0, "title": "Depth", "type": "integer" }, "inputs": { "additionalProperties": true, "title": "Inputs", "type": "object" }, "notify_policy": { "default": "on_complete", "title": "Notify Policy", "type": "string" }, "resume_instruction": { "maxLength": 4000, "minLength": 1, "title": "Resume Instruction", "type": "string" }, "trigger_source": { "default": "assistant_skill_background", "title": "Trigger Source", "type": "string" } }, "required": [ "conversation_id", "resume_instruction" ], "title": "SkillExecuteAsyncRequest", "type": "object" }, "SkillExecuteRequest": { "properties": { "inputs": { "additionalProperties": true, "title": "Inputs", "type": "object" }, "script_name": { "anyOf": [ { "maxLength": 128, "type": "string" }, { "type": "null" } ], "title": "Script Name" }, "trigger_source": { "default": "manual", "maxLength": 80, "title": "Trigger Source", "type": "string" } }, "title": "SkillExecuteRequest", "type": "object" }, "SkillFileValue": { "description": "A model provider's key for the named skills' turn ``.env`` only\n(TIDY-20203 F7). The harness reads this name for its own model login, so\nthe connector writes it into each skill's folder and never into the\nturn's process env. A secret like any credential: redacted, turn-scoped.", "properties": { "env_key": { "title": "Env Key", "type": "string" }, "id": { "title": "Id", "type": "string" }, "skills": { "items": { "type": "string" }, "title": "Skills", "type": "array" }, "value": { "title": "Value", "type": "string" } }, "required": [ "id", "env_key", "value", "skills" ], "title": "SkillFileValue", "type": "object" }, "SkillGive": { "additionalProperties": false, "description": "A skill a deploy gives the employee, at exactly this version — published\nby the deploy when it is newer, as a give publishes it.", "properties": { "runtime": { "anyOf": [ { "maxLength": 32, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Runtime" }, "skill_id": { "format": "uuid", "title": "Skill Id", "type": "string" }, "version": { "exclusiveMinimum": 0.0, "title": "Version", "type": "integer" } }, "required": [ "skill_id", "version" ], "title": "SkillGive", "type": "object" }, "SkillGiveGroup": { "additionalProperties": false, "description": "The skills one employee is given on one list — every harness\n(``runtime`` null) or that harness's own — with the access the person\napproved for them, once, over all of them.", "properties": { "assign_pending": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Assign Pending" }, "employee_account_id": { "format": "uuid", "title": "Employee Account Id", "type": "string" }, "gives": { "items": { "$ref": "#/components/schemas/SkillGiveItem" }, "maxItems": 96, "minItems": 1, "title": "Gives", "type": "array" }, "plugin_access": { "anyOf": [ { "items": { "$ref": "#/components/schemas/PluginAccessChoice" }, "maxItems": 16, "type": "array" }, { "type": "null" } ], "title": "Plugin Access" }, "requirements_hash": { "anyOf": [ { "maxLength": 64, "minLength": 64, "type": "string" }, { "type": "null" } ], "title": "Requirements Hash" }, "runtime": { "anyOf": [ { "maxLength": 32, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Runtime" }, "secret_files": { "anyOf": [ { "items": { "$ref": "#/components/schemas/SecretFileChoice" }, "maxItems": 16, "type": "array" }, { "type": "null" } ], "title": "Secret Files" } }, "required": [ "employee_account_id", "gives" ], "title": "SkillGiveGroup", "type": "object" }, "SkillGiveGroupPlan": { "properties": { "code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Code" }, "employee_account_id": { "title": "Employee Account Id", "type": "string" }, "gives": { "items": { "$ref": "#/components/schemas/SkillGivePlanItem" }, "title": "Gives", "type": "array" }, "message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Message" }, "plan": { "anyOf": [ { "$ref": "#/components/schemas/SkillPluginAccessPlan" }, { "type": "null" } ], "default": null }, "runtime": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Runtime" } }, "required": [ "employee_account_id", "gives" ], "title": "SkillGiveGroupPlan", "type": "object" }, "SkillGiveGroupResult": { "properties": { "already": { "items": { "type": "string" }, "title": "Already", "type": "array" }, "code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Code" }, "employee_account_id": { "title": "Employee Account Id", "type": "string" }, "given": { "items": { "type": "string" }, "title": "Given", "type": "array" }, "message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Message" }, "outcome": { "enum": [ "given", "refused" ], "title": "Outcome", "type": "string" }, "pending_access": { "items": { "type": "string" }, "title": "Pending Access", "type": "array" }, "runtime": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Runtime" } }, "required": [ "employee_account_id", "outcome" ], "title": "SkillGiveGroupResult", "type": "object" }, "SkillGiveItem": { "additionalProperties": false, "description": "One skill at the version the person saw published.", "properties": { "skill_id": { "format": "uuid", "title": "Skill Id", "type": "string" }, "version": { "exclusiveMinimum": 0.0, "title": "Version", "type": "integer" } }, "required": [ "skill_id", "version" ], "title": "SkillGiveItem", "type": "object" }, "SkillGivePlanItem": { "properties": { "code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Code" }, "message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Message" }, "skill_id": { "title": "Skill Id", "type": "string" }, "state": { "enum": [ "give", "already", "refused" ], "title": "State", "type": "string" }, "version": { "title": "Version", "type": "integer" } }, "required": [ "skill_id", "version", "state" ], "title": "SkillGivePlanItem", "type": "object" }, "SkillGivesPlan": { "properties": { "groups": { "items": { "$ref": "#/components/schemas/SkillGiveGroupPlan" }, "title": "Groups", "type": "array" } }, "required": [ "groups" ], "title": "SkillGivesPlan", "type": "object" }, "SkillGivesRequest": { "additionalProperties": false, "description": "A bulk give: skills × employees × lists, decided in one review.", "properties": { "groups": { "items": { "$ref": "#/components/schemas/SkillGiveGroup" }, "maxItems": 50, "minItems": 1, "title": "Groups", "type": "array" } }, "required": [ "groups" ], "title": "SkillGivesRequest", "type": "object" }, "SkillGivesResult": { "properties": { "groups": { "items": { "$ref": "#/components/schemas/SkillGiveGroupResult" }, "title": "Groups", "type": "array" } }, "required": [ "groups" ], "title": "SkillGivesResult", "type": "object" }, "SkillInstallAckEntry": { "description": "One published skill's install receipt (TIDY-17072 S4 / R9 / gate F10).\n\nIdempotent per (agent, slug, version, status). ``missing_keys`` names the\nrequired credential slots that blocked the install — names only.", "properties": { "missing_keys": { "items": { "type": "string" }, "maxItems": 32, "title": "Missing Keys", "type": "array" }, "missing_requirements": { "items": { "$ref": "#/components/schemas/SkillMissingRequirement" }, "maxItems": 8, "title": "Missing Requirements", "type": "array" }, "slug": { "maxLength": 64, "title": "Slug", "type": "string" }, "status": { "enum": [ "installed", "blocked", "removed" ], "title": "Status", "type": "string" }, "version": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Version" } }, "required": [ "slug", "status" ], "title": "SkillInstallAckEntry", "type": "object" }, "SkillMaterializedFile": { "description": "One canonical, bounded file relative to the existing skill directory.", "properties": { "content": { "maxLength": 262144, "title": "Content", "type": "string" }, "relative": { "maxLength": 256, "minLength": 1, "title": "Relative", "type": "string" } }, "required": [ "relative", "content" ], "title": "SkillMaterializedFile", "type": "object" }, "SkillMetadataResponse": { "properties": { "assistant_applicability": { "default": "assistant_and_ve", "enum": [ "assistant_and_ve", "ve_only" ], "title": "Assistant Applicability", "type": "string" }, "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "enabled": { "title": "Enabled", "type": "boolean" }, "execution_digest": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Execution Digest" }, "forked_from": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Forked From" }, "id": { "title": "Id", "type": "string" }, "is_default": { "title": "Is Default", "type": "boolean" }, "lifecycle": { "default": "active", "enum": [ "active", "candidate" ], "title": "Lifecycle", "type": "string" }, "name": { "title": "Name", "type": "string" }, "origin": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Origin" }, "owner_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Owner Id" }, "provenance": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "title": "Provenance" }, "published_version": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Published Version" }, "review_state": { "anyOf": [ { "enum": [ "draft", "reviewed", "validated" ], "type": "string" }, { "type": "null" } ], "default": null, "title": "Review State" }, "slug": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Slug" }, "source_conversation_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Source Conversation Id" }, "tenant_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Tenant Id" }, "updated_at": { "format": "date-time", "title": "Updated At", "type": "string" }, "validated_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Validated At" }, "validation_error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Validation Error" }, "version": { "title": "Version", "type": "integer" }, "visibility": { "enum": [ "private", "shared", "tenant", "global" ], "title": "Visibility", "type": "string" } }, "required": [ "id", "tenant_id", "owner_id", "name", "description", "version", "visibility", "enabled", "is_default", "validation_error", "created_at", "updated_at" ], "title": "SkillMetadataResponse", "type": "object" }, "SkillMissingRequirement": { "description": "A requirement the workshop does not meet (TIDY-20203 F4).", "properties": { "found": { "anyOf": [ { "maxLength": 64, "type": "string" }, { "type": "null" } ], "title": "Found" }, "min_version": { "anyOf": [ { "maxLength": 32, "type": "string" }, { "type": "null" } ], "title": "Min Version" }, "name": { "enum": [ "node", "python", "chrome" ], "title": "Name", "type": "string" }, "purpose": { "anyOf": [ { "maxLength": 200, "type": "string" }, { "type": "null" } ], "title": "Purpose" }, "required": { "default": true, "title": "Required", "type": "boolean" } }, "required": [ "name" ], "title": "SkillMissingRequirement", "type": "object" }, "SkillPackageRequest": { "description": "VE-assisted packaging of a local skill into the tenant registry (D4).", "properties": { "description": { "anyOf": [ { "maxLength": 2000, "type": "string" }, { "type": "null" } ], "title": "Description" }, "markdown": { "maxLength": 262144, "minLength": 1, "title": "Markdown", "type": "string" }, "name": { "maxLength": 128, "minLength": 1, "title": "Name", "type": "string" }, "scripts": { "items": { "$ref": "#/components/schemas/SkillAssetScript" }, "maxItems": 32, "title": "Scripts", "type": "array" }, "source": { "anyOf": [ { "maxLength": 1024, "type": "string" }, { "type": "null" } ], "title": "Source" }, "source_host": { "maxLength": 256, "minLength": 1, "title": "Source Host", "type": "string" } }, "required": [ "name", "markdown", "source_host" ], "title": "SkillPackageRequest", "type": "object" }, "SkillPluginAccessApprove": { "additionalProperties": false, "description": "Approve access a skill the employee already carries needs.", "properties": { "plugin_access": { "items": { "$ref": "#/components/schemas/PluginAccessChoice" }, "maxItems": 16, "title": "Plugin Access", "type": "array" }, "requirements_hash": { "maxLength": 64, "minLength": 64, "title": "Requirements Hash", "type": "string" }, "runtime": { "anyOf": [ { "maxLength": 32, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Runtime" }, "secret_files": { "items": { "$ref": "#/components/schemas/SecretFileChoice" }, "maxItems": 16, "title": "Secret Files", "type": "array" }, "version": { "exclusiveMinimum": 0.0, "title": "Version", "type": "integer" } }, "required": [ "version", "requirements_hash" ], "title": "SkillPluginAccessApprove", "type": "object" }, "SkillPluginAccessPlan": { "description": "The plan for an employee that exists.", "properties": { "agent_account_id": { "title": "Agent Account Id", "type": "string" }, "key_requirements": { "items": { "$ref": "#/components/schemas/KeyRequirement" }, "title": "Key Requirements", "type": "array" }, "requirements": { "items": { "$ref": "#/components/schemas/PluginAccessRequirement" }, "title": "Requirements", "type": "array" }, "requirements_hash": { "title": "Requirements Hash", "type": "string" }, "runtime": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Runtime" }, "skills": { "items": { "$ref": "#/components/schemas/PluginAccessSkillRef" }, "title": "Skills", "type": "array" }, "workshop_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Workshop Id" }, "workshops": { "items": { "$ref": "#/components/schemas/PluginAccessWorkshop" }, "title": "Workshops", "type": "array" } }, "required": [ "skills", "requirements_hash", "workshops", "requirements", "agent_account_id" ], "title": "SkillPluginAccessPlan", "type": "object" }, "SkillPluginAccessResult": { "properties": { "applied": { "items": { "$ref": "#/components/schemas/AppliedPluginAccess" }, "title": "Applied", "type": "array" } }, "required": [ "applied" ], "title": "SkillPluginAccessResult", "type": "object" }, "SkillProjectLinkCreate": { "properties": { "project_id": { "title": "Project Id", "type": "string" } }, "required": [ "project_id" ], "title": "SkillProjectLinkCreate", "type": "object" }, "SkillProjectLinkResponse": { "properties": { "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "id": { "title": "Id", "type": "string" }, "linked_by": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Linked By" }, "project_id": { "title": "Project Id", "type": "string" }, "project_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Project Name" }, "skill_id": { "title": "Skill Id", "type": "string" }, "tenant_id": { "title": "Tenant Id", "type": "string" } }, "required": [ "id", "tenant_id", "skill_id", "project_id", "created_at" ], "title": "SkillProjectLinkResponse", "type": "object" }, "SkillPublishRequest": { "description": "Publish promotion (TIDY-17072 D6b): pin ONE version as what VEs install.", "properties": { "version": { "exclusiveMinimum": 0.0, "title": "Version", "type": "integer" } }, "required": [ "version" ], "title": "SkillPublishRequest", "type": "object" }, "SkillRegistrationRequest": { "description": "A new skill found in an employee's MANAGED harness root (TIDY-19569 R3b).\n\nThe gateway mints ``registration_id`` once per skill directory and keeps it\nin its index before the first submit, so a retry — after a lost response,\nor racing itself — names the same registration. Who registered it, and from\nwhich installation and workshop, come from the runtime PAT and the lease,\nnever from this body.", "properties": { "bundle": { "$ref": "#/components/schemas/SkillBundle" }, "change_summary": { "anyOf": [ { "maxLength": 500, "type": "string" }, { "type": "null" } ], "title": "Change Summary" }, "runtime": { "maxLength": 64, "minLength": 1, "title": "Runtime", "type": "string" }, "source_path": { "maxLength": 256, "minLength": 1, "title": "Source Path", "type": "string" } }, "required": [ "runtime", "source_path", "bundle" ], "title": "SkillRegistrationRequest", "type": "object" }, "SkillRegistrationResponse": { "description": "The registered identity and where it resolves — the gateway's index entry.\n\n``version``/``content_hash`` are the REGISTERED version: what the directory\nheld when it was submitted, and the base its next local edit is pushed\nagainst. ``created`` is false for a retry of a registration that already\nexists — the same identity, read back, never a second skill.", "properties": { "assignment_id": { "title": "Assignment Id", "type": "string" }, "collection_id": { "title": "Collection Id", "type": "string" }, "content_hash": { "title": "Content Hash", "type": "string" }, "created": { "title": "Created", "type": "boolean" }, "employee_account_id": { "title": "Employee Account Id", "type": "string" }, "installation_id": { "title": "Installation Id", "type": "string" }, "name": { "title": "Name", "type": "string" }, "registered_at": { "format": "date-time", "title": "Registered At", "type": "string" }, "registration_id": { "format": "uuid", "title": "Registration Id", "type": "string" }, "runtime": { "title": "Runtime", "type": "string" }, "skill_id": { "title": "Skill Id", "type": "string" }, "slug": { "title": "Slug", "type": "string" }, "source_path": { "title": "Source Path", "type": "string" }, "version": { "title": "Version", "type": "integer" }, "workshop_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Workshop Id" } }, "required": [ "registration_id", "created", "skill_id", "name", "slug", "version", "content_hash", "runtime", "source_path", "collection_id", "assignment_id", "employee_account_id", "installation_id", "registered_at" ], "title": "SkillRegistrationResponse", "type": "object" }, "SkillRepoArchive": { "description": "The carried files, packed once and stored by their SHA-256.", "properties": { "file_count": { "title": "File Count", "type": "integer" }, "sha256": { "title": "Sha256", "type": "string" }, "size": { "title": "Size", "type": "integer" } }, "required": [ "sha256", "size", "file_count" ], "title": "SkillRepoArchive", "type": "object" }, "SkillRepoFile": { "properties": { "path": { "title": "Path", "type": "string" }, "size": { "title": "Size", "type": "integer" }, "status": { "enum": [ "included", "excluded", "binary", "link", "unsafe_path", "too_large", "secret" ], "title": "Status", "type": "string" } }, "required": [ "path", "size", "status" ], "title": "SkillRepoFile", "type": "object" }, "SkillRepoFolder": { "description": "One top-level folder (or ``.`` for the top-level files), summed.", "properties": { "bytes": { "title": "Bytes", "type": "integer" }, "carried_bytes": { "title": "Carried Bytes", "type": "integer" }, "carried_files": { "title": "Carried Files", "type": "integer" }, "files": { "title": "Files", "type": "integer" }, "path": { "title": "Path", "type": "string" } }, "required": [ "path", "files", "bytes", "carried_files", "carried_bytes" ], "title": "SkillRepoFolder", "type": "object" }, "SkillRepoImportRequest": { "description": "Add the repository at exactly the commit the preview showed.", "properties": { "commit": { "pattern": "^[0-9a-f]{40}$", "title": "Commit", "type": "string" }, "credentials": { "items": { "$ref": "#/components/schemas/SkillCredentialDeclaration" }, "maxItems": 32, "title": "Credentials", "type": "array" }, "env_file": { "default": false, "title": "Env File", "type": "boolean" }, "exclude": { "items": { "type": "string" }, "maxItems": 64, "title": "Exclude", "type": "array" }, "include": { "items": { "type": "string" }, "maxItems": 64, "title": "Include", "type": "array" }, "ref": { "anyOf": [ { "maxLength": 200, "type": "string" }, { "type": "null" } ], "title": "Ref" }, "requires": { "items": { "$ref": "#/components/schemas/SkillRequirementDeclaration" }, "maxItems": 8, "title": "Requires", "type": "array" }, "url": { "maxLength": 500, "minLength": 3, "title": "Url", "type": "string" } }, "required": [ "url", "commit" ], "title": "SkillRepoImportRequest", "type": "object" }, "SkillRepoKeysUpdate": { "description": "Change a repo skill's keys: a new published version on the same commit.", "properties": { "credentials": { "items": { "$ref": "#/components/schemas/SkillCredentialDeclaration" }, "maxItems": 32, "title": "Credentials", "type": "array" }, "env_file": { "default": false, "title": "Env File", "type": "boolean" }, "requires": { "anyOf": [ { "items": { "$ref": "#/components/schemas/SkillRequirementDeclaration" }, "maxItems": 8, "type": "array" }, { "type": "null" } ], "title": "Requires" } }, "title": "SkillRepoKeysUpdate", "type": "object" }, "SkillRepoPreview": { "properties": { "carried_bytes": { "title": "Carried Bytes", "type": "integer" }, "carried_files": { "title": "Carried Files", "type": "integer" }, "commit": { "title": "Commit", "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Description" }, "exclude": { "items": { "type": "string" }, "title": "Exclude", "type": "array" }, "existing_skill_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Existing Skill Id" }, "files": { "items": { "$ref": "#/components/schemas/SkillRepoFile" }, "title": "Files", "type": "array" }, "files_truncated": { "default": false, "title": "Files Truncated", "type": "boolean" }, "folders": { "items": { "$ref": "#/components/schemas/SkillRepoFolder" }, "title": "Folders", "type": "array" }, "include": { "items": { "type": "string" }, "title": "Include", "type": "array" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Name" }, "problems": { "items": { "$ref": "#/components/schemas/SkillValidationError" }, "title": "Problems", "type": "array" }, "ref": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Ref" }, "repo_url": { "title": "Repo Url", "type": "string" }, "requirements": { "items": { "$ref": "#/components/schemas/SkillRepoRequirement" }, "title": "Requirements", "type": "array" }, "suggested_credentials": { "items": { "$ref": "#/components/schemas/SkillRepoSuggestedKey" }, "title": "Suggested Credentials", "type": "array" }, "suggested_requires": { "items": { "$ref": "#/components/schemas/SkillRequirementDeclaration" }, "title": "Suggested Requires", "type": "array" }, "total_bytes": { "title": "Total Bytes", "type": "integer" }, "total_files": { "title": "Total Files", "type": "integer" } }, "required": [ "repo_url", "commit", "include", "exclude", "total_files", "total_bytes", "carried_files", "carried_bytes", "folders", "files" ], "title": "SkillRepoPreview", "type": "object" }, "SkillRepoPreviewRequest": { "description": "A repository to look at before adding it. Nothing is stored.", "properties": { "commit": { "anyOf": [ { "pattern": "^[0-9a-f]{40}$", "type": "string" }, { "type": "null" } ], "title": "Commit" }, "credentials": { "anyOf": [ { "items": { "$ref": "#/components/schemas/SkillCredentialDeclaration" }, "maxItems": 32, "type": "array" }, { "type": "null" } ], "title": "Credentials" }, "exclude": { "anyOf": [ { "items": { "type": "string" }, "maxItems": 64, "type": "array" }, { "type": "null" } ], "title": "Exclude" }, "include": { "items": { "type": "string" }, "maxItems": 64, "title": "Include", "type": "array" }, "ref": { "anyOf": [ { "maxLength": 200, "type": "string" }, { "type": "null" } ], "title": "Ref" }, "url": { "maxLength": 500, "minLength": 3, "title": "Url", "type": "string" } }, "required": [ "url" ], "title": "SkillRepoPreviewRequest", "type": "object" }, "SkillRepoRequirement": { "description": "Something the repository says it needs. Shown, not yet checked.", "properties": { "detail": { "title": "Detail", "type": "string" }, "kind": { "enum": [ "runtime", "tool", "packages", "key" ], "title": "Kind", "type": "string" }, "name": { "title": "Name", "type": "string" }, "source": { "title": "Source", "type": "string" }, "version": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Version" } }, "required": [ "kind", "name", "detail", "source" ], "title": "SkillRepoRequirement", "type": "object" }, "SkillRepoReview": { "description": "The code review a repo skill was added on (TIDY-20203 F6): an employee\nthat asks for a repository reviews it first, on the request its owner approved.", "properties": { "by_account_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "By Account Id" }, "by_name": { "default": "", "title": "By Name", "type": "string" }, "proposal_id": { "title": "Proposal Id", "type": "string" }, "report": { "title": "Report", "type": "string" } }, "required": [ "proposal_id", "report" ], "title": "SkillRepoReview", "type": "object" }, "SkillRepoSource": { "description": "Where a repo skill's version came from. Read-only: only an import sets it.", "properties": { "archive": { "$ref": "#/components/schemas/SkillRepoArchive" }, "commit": { "title": "Commit", "type": "string" }, "credentials": { "items": { "$ref": "#/components/schemas/SkillCredentialDeclaration" }, "title": "Credentials", "type": "array" }, "env_file": { "default": false, "title": "Env File", "type": "boolean" }, "exclude": { "items": { "type": "string" }, "title": "Exclude", "type": "array" }, "include": { "items": { "type": "string" }, "title": "Include", "type": "array" }, "kind": { "const": "git", "default": "git", "title": "Kind", "type": "string" }, "ref": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Ref" }, "repo_url": { "title": "Repo Url", "type": "string" }, "requires": { "items": { "$ref": "#/components/schemas/SkillRequirementDeclaration" }, "title": "Requires", "type": "array" }, "review": { "anyOf": [ { "$ref": "#/components/schemas/SkillRepoReview" }, { "type": "null" } ], "default": null } }, "required": [ "repo_url", "commit", "archive" ], "title": "SkillRepoSource", "type": "object" }, "SkillRepoSuggestedKey": { "description": "A key the repository's example dotenv file names (TIDY-20203 F3).", "properties": { "allowed": { "default": true, "title": "Allowed", "type": "boolean" }, "env_key": { "title": "Env Key", "type": "string" }, "purpose": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Purpose" }, "required": { "default": true, "title": "Required", "type": "boolean" }, "source": { "title": "Source", "type": "string" } }, "required": [ "env_key", "source" ], "title": "SkillRepoSuggestedKey", "type": "object" }, "SkillRepoUpdateApprove": { "description": "Approve a repo skill's update: exactly the commit the owner reviewed.", "properties": { "commit": { "pattern": "^[0-9a-f]{40}$", "title": "Commit", "type": "string" } }, "required": [ "commit" ], "title": "SkillRepoUpdateApprove", "type": "object" }, "SkillRepoUpstream": { "description": "What the branch a repo skill was added from says now (TIDY-20203 F5).\n\nNothing here reaches a workshop: an owner approves ``upstream_commit``\nfirst, which publishes a new version.", "properties": { "ahead_by": { "default": 0, "title": "Ahead By", "type": "integer" }, "behind_by": { "default": 0, "title": "Behind By", "type": "integer" }, "checked_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Checked At" }, "commits": { "items": { "$ref": "#/components/schemas/SkillRepoUpstreamCommit" }, "title": "Commits", "type": "array" }, "diverged": { "default": false, "title": "Diverged", "type": "boolean" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Error" }, "files": { "items": { "$ref": "#/components/schemas/SkillRepoUpstreamFile" }, "title": "Files", "type": "array" }, "files_truncated": { "default": false, "title": "Files Truncated", "type": "boolean" }, "pinned_commit": { "title": "Pinned Commit", "type": "string" }, "ref": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Ref" }, "status": { "enum": [ "up_to_date", "update_available", "unreachable", "not_tracked" ], "title": "Status", "type": "string" }, "tracked": { "default": true, "title": "Tracked", "type": "boolean" }, "upstream_commit": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Upstream Commit" } }, "required": [ "status", "pinned_commit" ], "title": "SkillRepoUpstream", "type": "object" }, "SkillRepoUpstreamCommit": { "description": "One commit on the branch past the reviewed one (TIDY-20203 F5).", "properties": { "author": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Author" }, "date": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Date" }, "message": { "default": "", "title": "Message", "type": "string" }, "sha": { "title": "Sha", "type": "string" } }, "required": [ "sha" ], "title": "SkillRepoUpstreamCommit", "type": "object" }, "SkillRepoUpstreamFile": { "description": "One file those commits change.", "properties": { "carried": { "title": "Carried", "type": "boolean" }, "change": { "title": "Change", "type": "string" }, "path": { "title": "Path", "type": "string" }, "previous_path": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Previous Path" } }, "required": [ "path", "change", "carried" ], "title": "SkillRepoUpstreamFile", "type": "object" }, "SkillRequirementDeclaration": { "description": "Something a workshop must have for a repo skill to work (TIDY-20203 F4).\n\nA missing ``required`` one holds the install, the way a missing key does;\na missing optional one installs it and says what will not work.", "properties": { "min_version": { "anyOf": [ { "pattern": "^\\d{1,4}(\\.\\d{1,6}){0,2}$", "type": "string" }, { "type": "null" } ], "title": "Min Version" }, "name": { "enum": [ "node", "python", "chrome" ], "title": "Name", "type": "string" }, "purpose": { "anyOf": [ { "maxLength": 200, "type": "string" }, { "type": "null" } ], "title": "Purpose" }, "required": { "default": true, "title": "Required", "type": "boolean" } }, "required": [ "name" ], "title": "SkillRequirementDeclaration", "type": "object" }, "SkillResponse": { "properties": { "asset_scripts": { "items": { "$ref": "#/components/schemas/SkillAssetScript" }, "title": "Asset Scripts", "type": "array" }, "assistant_applicability": { "default": "assistant_and_ve", "enum": [ "assistant_and_ve", "ve_only" ], "title": "Assistant Applicability", "type": "string" }, "bundle": { "anyOf": [ { "$ref": "#/components/schemas/SkillBundle" }, { "type": "null" } ], "default": null }, "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "credentials": { "items": { "$ref": "#/components/schemas/SkillCredentialDeclaration" }, "title": "Credentials", "type": "array" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "enabled": { "title": "Enabled", "type": "boolean" }, "execution_digest": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Execution Digest" }, "forked_from": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Forked From" }, "id": { "title": "Id", "type": "string" }, "is_default": { "title": "Is Default", "type": "boolean" }, "lifecycle": { "default": "active", "enum": [ "active", "candidate" ], "title": "Lifecycle", "type": "string" }, "markdown": { "title": "Markdown", "type": "string" }, "name": { "title": "Name", "type": "string" }, "origin": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Origin" }, "os_support": { "items": { "type": "string" }, "title": "Os Support", "type": "array" }, "owner_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Owner Id" }, "provenance": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "title": "Provenance" }, "published_version": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Published Version" }, "review_state": { "anyOf": [ { "enum": [ "draft", "reviewed", "validated" ], "type": "string" }, { "type": "null" } ], "default": null, "title": "Review State" }, "scripts": { "items": { "$ref": "#/components/schemas/SkillScriptResponse" }, "title": "Scripts", "type": "array" }, "slug": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Slug" }, "source": { "anyOf": [ { "$ref": "#/components/schemas/SkillRepoSource" }, { "type": "null" } ], "default": null }, "source_conversation_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Source Conversation Id" }, "tenant_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Tenant Id" }, "updated_at": { "format": "date-time", "title": "Updated At", "type": "string" }, "upstream": { "anyOf": [ { "$ref": "#/components/schemas/SkillRepoUpstream" }, { "type": "null" } ], "default": null }, "validated_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Validated At" }, "validation": { "items": { "$ref": "#/components/schemas/SkillValidationError" }, "title": "Validation", "type": "array" }, "validation_error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Validation Error" }, "version": { "title": "Version", "type": "integer" }, "visibility": { "enum": [ "private", "shared", "tenant", "global" ], "title": "Visibility", "type": "string" }, "workflow_ids": { "items": { "type": "string" }, "title": "Workflow Ids", "type": "array" } }, "required": [ "id", "tenant_id", "owner_id", "name", "description", "version", "visibility", "enabled", "is_default", "validation_error", "created_at", "updated_at", "markdown" ], "title": "SkillResponse", "type": "object" }, "SkillScriptEntry": { "description": "One script of a skill's published version, and where it runs.", "properties": { "label": { "title": "Label", "type": "string" }, "language": { "title": "Language", "type": "string" }, "runtime": { "enum": [ "machine", "backend" ], "title": "Runtime", "type": "string" }, "script": { "title": "Script", "type": "string" } }, "required": [ "script", "label", "runtime", "language" ], "title": "SkillScriptEntry", "type": "object" }, "SkillScriptFile": { "description": "One executable file of a skill asset (TIDY-17034).", "properties": { "language": { "default": "python", "enum": [ "python", "javascript", "typescript", "shell" ], "title": "Language", "type": "string" }, "name": { "maxLength": 128, "minLength": 1, "title": "Name", "type": "string" }, "source": { "default": "", "maxLength": 262144, "title": "Source", "type": "string" } }, "required": [ "name" ], "title": "SkillScriptFile", "type": "object" }, "SkillScriptInput": { "properties": { "language": { "default": "python", "enum": [ "python", "javascript", "typescript" ], "title": "Language", "type": "string" }, "name": { "maxLength": 128, "minLength": 1, "title": "Name", "type": "string" }, "source": { "default": "", "maxLength": 200000, "title": "Source", "type": "string" } }, "required": [ "name" ], "title": "SkillScriptInput", "type": "object" }, "SkillScriptList": { "properties": { "name": { "title": "Name", "type": "string" }, "published_version": { "title": "Published Version", "type": "integer" }, "scripts": { "items": { "$ref": "#/components/schemas/SkillScriptEntry" }, "title": "Scripts", "type": "array" }, "skill_id": { "title": "Skill Id", "type": "string" } }, "required": [ "skill_id", "name", "published_version", "scripts" ], "title": "SkillScriptList", "type": "object" }, "SkillScriptResponse": { "properties": { "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "id": { "title": "Id", "type": "string" }, "language": { "enum": [ "python", "javascript", "typescript" ], "title": "Language", "type": "string" }, "name": { "title": "Name", "type": "string" }, "skill_id": { "title": "Skill Id", "type": "string" }, "source": { "title": "Source", "type": "string" }, "updated_at": { "format": "date-time", "title": "Updated At", "type": "string" }, "version": { "title": "Version", "type": "integer" } }, "required": [ "id", "skill_id", "name", "language", "source", "version", "created_at", "updated_at" ], "title": "SkillScriptResponse", "type": "object" }, "SkillScriptRunClaim": { "description": "Everything the machine runs: the pinned version's files, the inputs,\nthe folders its requester may not see, and the requester's explicit lends.", "properties": { "env": { "items": { "$ref": "#/components/schemas/SkillScriptRunEnv" }, "title": "Env", "type": "array" }, "files": { "items": { "$ref": "#/components/schemas/SkillScriptRunFile" }, "title": "Files", "type": "array" }, "inputs": { "additionalProperties": true, "title": "SkillScriptRunInputs", "type": "object" }, "language": { "title": "Language", "type": "string" }, "requester_account_id": { "title": "Requester Account Id", "type": "string" }, "run_id": { "title": "Run Id", "type": "string" }, "script": { "title": "Script", "type": "string" }, "skill_id": { "title": "Skill Id", "type": "string" }, "slug": { "title": "Slug", "type": "string" }, "timeout_sec": { "title": "Timeout Sec", "type": "integer" }, "trigger_envelope": { "additionalProperties": true, "title": "SkillScriptRunTriggerEnvelope", "type": "object" }, "version": { "title": "Version", "type": "integer" }, "withheld_env": { "items": { "$ref": "#/components/schemas/SkillScriptRunWithheldEnv" }, "title": "Withheld Env", "type": "array" }, "withheld_paths": { "items": { "type": "string" }, "title": "Withheld Paths", "type": "array" } }, "required": [ "run_id", "skill_id", "slug", "version", "script", "language", "files", "inputs", "trigger_envelope", "timeout_sec", "requester_account_id", "withheld_paths", "env", "withheld_env" ], "title": "SkillScriptRunClaim", "type": "object" }, "SkillScriptRunClaimRequest": { "additionalProperties": false, "description": "The harness the employee runs now: lends scoped to it apply to the run.", "properties": { "runtime": { "maxLength": 64, "minLength": 1, "title": "Runtime", "type": "string" } }, "required": [ "runtime" ], "title": "SkillScriptRunClaimRequest", "type": "object" }, "SkillScriptRunEnv": { "properties": { "env_key": { "title": "Env Key", "type": "string" }, "value": { "title": "Value", "type": "string" } }, "required": [ "env_key", "value" ], "title": "SkillScriptRunEnv", "type": "object" }, "SkillScriptRunFile": { "properties": { "content": { "title": "Content", "type": "string" }, "relative": { "title": "Relative", "type": "string" } }, "required": [ "relative", "content" ], "title": "SkillScriptRunFile", "type": "object" }, "SkillScriptRunReport": { "additionalProperties": false, "description": "How the script ended. ``error`` when it could not run at all.", "properties": { "error": { "anyOf": [ { "maxLength": 2000, "type": "string" }, { "type": "null" } ], "title": "Error" }, "exit_code": { "anyOf": [ { "maximum": 255.0, "minimum": -255.0, "type": "integer" }, { "type": "null" } ], "title": "Exit Code" }, "stderr": { "default": "", "maxLength": 65536, "title": "Stderr", "type": "string" }, "stdout": { "default": "", "maxLength": 65536, "title": "Stdout", "type": "string" } }, "title": "SkillScriptRunReport", "type": "object" }, "SkillScriptRunReportAck": { "properties": { "settled": { "title": "Settled", "type": "boolean" } }, "required": [ "settled" ], "title": "SkillScriptRunReportAck", "type": "object" }, "SkillScriptRunWithheldEnv": { "properties": { "env_key": { "title": "Env Key", "type": "string" }, "reason": { "title": "Reason", "type": "string" } }, "required": [ "env_key", "reason" ], "title": "SkillScriptRunWithheldEnv", "type": "object" }, "SkillTags": { "properties": { "skill_id": { "title": "Skill Id", "type": "string" }, "tags": { "items": { "type": "string" }, "title": "Tags", "type": "array" } }, "required": [ "skill_id", "tags" ], "title": "SkillTags", "type": "object" }, "SkillTagsBatch": { "additionalProperties": false, "description": "Add and remove tags across a selection of skills, in one transaction.", "properties": { "add": { "items": { "type": "string" }, "maxItems": 20, "title": "Add", "type": "array" }, "remove": { "items": { "type": "string" }, "maxItems": 20, "title": "Remove", "type": "array" }, "skill_ids": { "items": { "format": "uuid", "type": "string" }, "maxItems": 200, "minItems": 1, "title": "Skill Ids", "type": "array" } }, "required": [ "skill_ids" ], "title": "SkillTagsBatch", "type": "object" }, "SkillTagsBatchResult": { "properties": { "skills": { "items": { "$ref": "#/components/schemas/SkillTags" }, "title": "Skills", "type": "array" } }, "required": [ "skills" ], "title": "SkillTagsBatchResult", "type": "object" }, "SkillTagsSet": { "additionalProperties": false, "description": "Exactly these workspace tags on the skill.", "properties": { "tags": { "items": { "type": "string" }, "maxItems": 20, "title": "Tags", "type": "array" } }, "required": [ "tags" ], "title": "SkillTagsSet", "type": "object" }, "SkillUpdate": { "properties": { "assistant_applicability": { "anyOf": [ { "enum": [ "assistant_and_ve", "ve_only" ], "type": "string" }, { "type": "null" } ], "title": "Assistant Applicability" }, "change_summary": { "anyOf": [ { "maxLength": 500, "type": "string" }, { "type": "null" } ], "title": "Change Summary" }, "description": { "anyOf": [ { "maxLength": 2000, "type": "string" }, { "type": "null" } ], "title": "Description" }, "enabled": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Enabled" }, "expected_version": { "anyOf": [ { "minimum": 1.0, "type": "integer" }, { "type": "null" } ], "title": "Expected Version" }, "is_default": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is Default" }, "lifecycle": { "anyOf": [ { "const": "active", "type": "string" }, { "type": "null" } ], "title": "Lifecycle" }, "markdown": { "anyOf": [ { "maxLength": 200000, "type": "string" }, { "type": "null" } ], "title": "Markdown" }, "name": { "anyOf": [ { "maxLength": 128, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Name" }, "scripts": { "anyOf": [ { "items": { "$ref": "#/components/schemas/SkillScriptInput" }, "type": "array" }, { "type": "null" } ], "title": "Scripts" }, "visibility": { "anyOf": [ { "enum": [ "private", "shared", "tenant", "global" ], "type": "string" }, { "type": "null" } ], "title": "Visibility" }, "workflow_ids": { "anyOf": [ { "items": { "type": "string" }, "maxItems": 16, "type": "array" }, { "type": "null" } ], "title": "Workflow Ids" } }, "title": "SkillUpdate", "type": "object" }, "SkillValidationError": { "description": "One bundle validation violation (TIDY-17069 R3).", "properties": { "detail": { "title": "Detail", "type": "string" }, "file": { "title": "File", "type": "string" }, "kind": { "title": "Kind", "type": "string" } }, "required": [ "kind", "file", "detail" ], "title": "SkillValidationError", "type": "object" }, "SkillValidationRequest": { "description": "A whole skill to check before it is saved or published (TIDY-19569 F5).\n\nExactly one of ``bundle`` (the whole skill) or ``markdown`` (a whole\nSKILL.md, for a skill that is nothing else).", "properties": { "bundle": { "anyOf": [ { "$ref": "#/components/schemas/SkillBundle" }, { "type": "null" } ] }, "markdown": { "anyOf": [ { "maxLength": 262144, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Markdown" } }, "title": "SkillValidationRequest", "type": "object" }, "SkillValidationResponse": { "description": "What a save or a workshop publication would say of a bundle; nothing is written.\n\n``valid`` is true only with no ``validation`` errors. ``name`` and ``slug``\nare what a clean frontmatter declares (None when it does not parse).", "properties": { "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Name" }, "slug": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Slug" }, "valid": { "title": "Valid", "type": "boolean" }, "validation": { "items": { "$ref": "#/components/schemas/SkillValidationError" }, "title": "Validation", "type": "array" } }, "required": [ "valid" ], "title": "SkillValidationResponse", "type": "object" }, "SkillVersionCreate": { "description": "One atomic new version of the WHOLE bundle (TIDY-17069).\n\n``bundle`` is the shape going forward. The legacy ``{markdown, scripts}``\npair is still accepted — the server wraps it into a bundle — so existing\nSkillEditorTab saves keep working unchanged. One or the other: a bundle\nbeside non-empty legacy content is refused.", "properties": { "authored_kind": { "default": "user", "enum": [ "user", "assistant" ], "title": "Authored Kind", "type": "string" }, "bundle": { "anyOf": [ { "$ref": "#/components/schemas/SkillBundle" }, { "type": "null" } ] }, "change_summary": { "anyOf": [ { "maxLength": 500, "type": "string" }, { "type": "null" } ], "title": "Change Summary" }, "expected_version": { "anyOf": [ { "minimum": 1.0, "type": "integer" }, { "type": "null" } ], "title": "Expected Version" }, "markdown": { "default": "", "maxLength": 1048576, "title": "Markdown", "type": "string" }, "resolves_conflict_versions": { "items": { "minimum": 1.0, "type": "integer" }, "maxItems": 16, "title": "Resolves Conflict Versions", "type": "array" }, "scripts": { "items": { "$ref": "#/components/schemas/SkillAssetScript" }, "maxItems": 256, "title": "Scripts", "type": "array" } }, "title": "SkillVersionCreate", "type": "object" }, "SkillVersionResponse": { "properties": { "authored_kind": { "default": "user", "enum": [ "user", "assistant", "ve" ], "title": "Authored Kind", "type": "string" }, "base_version": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Base Version" }, "bundle": { "anyOf": [ { "$ref": "#/components/schemas/SkillBundle" }, { "type": "null" } ], "default": null }, "change_summary": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Change Summary" }, "changed_by": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Changed By" }, "conflict_head_version": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Conflict Head Version" }, "conflict_status": { "anyOf": [ { "enum": [ "open", "resolved" ], "type": "string" }, { "type": "null" } ], "default": null, "title": "Conflict Status" }, "content_hash": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Content Hash" }, "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "id": { "title": "Id", "type": "string" }, "markdown": { "title": "Markdown", "type": "string" }, "resolved_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Resolved At" }, "resolved_by": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Resolved By" }, "resolved_version": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Resolved Version" }, "scripts": { "items": { "$ref": "#/components/schemas/SkillAssetScript" }, "title": "Scripts", "type": "array" }, "skill_id": { "title": "Skill Id", "type": "string" }, "source": { "anyOf": [ { "$ref": "#/components/schemas/SkillRepoSource" }, { "type": "null" } ], "default": null }, "source_host": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Source Host" }, "validation": { "items": { "$ref": "#/components/schemas/SkillValidationError" }, "title": "Validation", "type": "array" }, "version": { "title": "Version", "type": "integer" } }, "required": [ "id", "skill_id", "version", "markdown", "description", "changed_by", "change_summary", "created_at" ], "title": "SkillVersionResponse", "type": "object" }, "SlideCellSummary": { "properties": { "block_types": { "items": { "type": "string" }, "title": "Block Types", "type": "array" }, "cell_path": { "title": "Cell Path", "type": "integer" }, "style_token": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Style Token" } }, "required": [ "cell_path" ], "title": "SlideCellSummary", "type": "object" }, "SlideDeckReadResponse": { "properties": { "design_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Design Id" }, "note_id": { "title": "Note Id", "type": "string" }, "slide_count": { "title": "Slide Count", "type": "integer" }, "slides": { "items": { "$ref": "#/components/schemas/SlideSummary" }, "title": "Slides", "type": "array" } }, "required": [ "note_id", "slide_count" ], "title": "SlideDeckReadResponse", "type": "object" }, "SlideDeleteRequest": { "properties": { "slide_index": { "title": "Slide Index", "type": "integer" } }, "required": [ "slide_index" ], "title": "SlideDeleteRequest", "type": "object" }, "SlideImage": { "description": "One rendered slide within a manifest.", "properties": { "height": { "default": 2160, "title": "Height", "type": "integer" }, "index": { "title": "Index", "type": "integer" }, "url": { "description": "Short-lived signed PNG URL.", "title": "Url", "type": "string" }, "width": { "default": 3840, "title": "Width", "type": "integer" } }, "required": [ "index", "url" ], "title": "SlideImage", "type": "object" }, "SlideMoveRequest": { "properties": { "from_index": { "title": "From Index", "type": "integer" }, "to_index": { "title": "To Index", "type": "integer" } }, "required": [ "from_index", "to_index" ], "title": "SlideMoveRequest", "type": "object" }, "SlideSummary": { "properties": { "cells": { "items": { "$ref": "#/components/schemas/SlideCellSummary" }, "title": "Cells", "type": "array" }, "design_layout_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Design Layout Id" }, "index": { "title": "Index", "type": "integer" }, "node_summary": { "items": { "type": "string" }, "title": "Node Summary", "type": "array" }, "outline": { "items": { "type": "string" }, "title": "Outline", "type": "array" }, "slide_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Slide Type" } }, "required": [ "index" ], "title": "SlideSummary", "type": "object" }, "SlideSurgeryOkResponse": { "properties": { "detail": { "additionalProperties": true, "title": "Detail", "type": "object" }, "note_id": { "title": "Note Id", "type": "string" }, "ok": { "default": true, "title": "Ok", "type": "boolean" } }, "required": [ "note_id" ], "title": "SlideSurgeryOkResponse", "type": "object" }, "SlideUpsertRequest": { "properties": { "mode": { "default": "insert", "enum": [ "insert", "replace" ], "title": "Mode", "type": "string" }, "slide_doc": { "additionalProperties": true, "description": "A single well-formed slideBlock ProseMirror-JSON node.", "title": "Slide Doc", "type": "object" }, "slide_index": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "0-based slide position. Required for replace; insert-at for insert.", "title": "Slide Index" } }, "required": [ "slide_doc" ], "title": "SlideUpsertRequest", "type": "object" }, "SlidesConvertNoteRequest": { "properties": { "noteId": { "title": "Noteid", "type": "string" } }, "required": [ "noteId" ], "title": "SlidesConvertNoteRequest", "type": "object" }, "SlidesConvertNoteResponse": { "properties": { "doc": { "$ref": "#/components/schemas/ProsemirrorDoc" }, "sourceNoteId": { "title": "Sourcenoteid", "type": "string" }, "sourceNoteTitle": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Sourcenotetitle" } }, "required": [ "doc", "sourceNoteId" ], "title": "SlidesConvertNoteResponse", "type": "object" }, "SlotResponse": { "description": "One bookable slot. start/end are canonical ISO UTC; timezone is the owner's.", "properties": { "end": { "format": "date-time", "title": "End", "type": "string" }, "start": { "format": "date-time", "title": "Start", "type": "string" }, "timezone": { "title": "Timezone", "type": "string" } }, "required": [ "start", "end", "timezone" ], "title": "SlotResponse", "type": "object" }, "SlotsResponse": { "properties": { "owner_timezone": { "title": "Owner Timezone", "type": "string" }, "service_duration_min": { "title": "Service Duration Min", "type": "integer" }, "slots": { "items": { "$ref": "#/components/schemas/SlotResponse" }, "title": "Slots", "type": "array" } }, "required": [ "owner_timezone", "service_duration_min", "slots" ], "title": "SlotsResponse", "type": "object" }, "SmartGroupListResponse": { "properties": { "groups": { "items": { "$ref": "#/components/schemas/SmartGroupSummary" }, "title": "Groups", "type": "array" } }, "required": [ "groups" ], "title": "SmartGroupListResponse", "type": "object" }, "SmartGroupMemberResponse": { "properties": { "addresses": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "default": [], "description": "Array of addresses [{street, city, state, zip, type}]", "title": "Addresses" }, "aliases": { "description": "Aliases (honorifics, nicknames, alternate spellings) recognized by the matcher.", "items": { "$ref": "#/components/schemas/ContactAliasResponse" }, "title": "Aliases", "type": "array" }, "approval_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Lifecycle state: 'pending_review' | 'approved' | 'rejected'.", "title": "Approval Status" }, "audit_recent": { "anyOf": [ { "items": { "$ref": "#/components/schemas/AuditLogSummary" }, "type": "array" }, { "type": "null" } ], "default": null, "description": "Last 10 audit_log entries for this contact, newest first.", "title": "Audit Recent" }, "audit_recent_error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Set when the audit_log sub-fetch failed; isolated from core response.", "title": "Audit Recent Error" }, "child_associations": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "default": [], "description": "List of child associations [{child_name, relationship}]", "examples": [ [ { "child_name": "Emma", "relationship": "teacher" } ] ], "title": "Child Associations" }, "confidence_score": { "anyOf": [ { "maximum": 1.0, "minimum": 0.0, "type": "number" }, { "type": "null" } ], "default": null, "description": "AI confidence score 0.0-1.0", "examples": [ 0.85 ], "title": "Confidence Score" }, "created_at": { "description": "ISO 8601 timestamp of contact creation", "format": "date-time", "title": "Created At", "type": "string" }, "display_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Generated display name", "examples": [ "Jane Marie Smith" ], "title": "Display Name" }, "email_addresses": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "default": [], "description": "Array of email addresses [{address, type, primary, label}]", "title": "Email Addresses" }, "facet_data": { "additionalProperties": true, "description": "Per-facet scoped custom fields for contact-inheriting facets ({ slug: { field_key: value } }).", "title": "Facet Data", "type": "object" }, "first_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "First name", "examples": [ "Jane" ], "title": "First Name" }, "graph_facts": { "anyOf": [ { "items": { "$ref": "#/components/schemas/GraphFact" }, "type": "array" }, { "type": "null" } ], "default": null, "description": "Recent KG facts about this entity (most recent 50). NULL when not pending or no entity.", "title": "Graph Facts" }, "graph_facts_error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Set when the KG sub-fetch failed; isolated from core response.", "title": "Graph Facts Error" }, "graph_sync_summary": { "anyOf": [ { "$ref": "#/components/schemas/GraphSyncSummary" }, { "type": "null" } ], "default": null, "description": "Most-recent merge's graph_sync summary; NULL when no recent merge." }, "id": { "description": "Unique contact identifier (UUID)", "examples": [ "a1b2c3d4-..." ], "title": "Id", "type": "string" }, "is_self": { "default": false, "description": "True when this contact IS the signed-in account in this tenant.", "title": "Is Self", "type": "boolean" }, "is_starred": { "default": false, "description": "VIP/starred status. VIP = is_starred=TRUE OR source_type=imported", "title": "Is Starred", "type": "boolean" }, "last_interaction_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Last Interaction At" }, "last_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Last name", "examples": [ "Smith" ], "title": "Last Name" }, "metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": {}, "description": "Extensible metadata", "title": "Metadata" }, "middle_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Middle name", "examples": [ "Marie" ], "title": "Middle Name" }, "name": { "description": "Contact name (legacy)", "examples": [ "Jane Smith" ], "title": "Name", "type": "string" }, "nickname": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Informal name", "examples": [ "Coach Mike" ], "title": "Nickname" }, "notes_history": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "default": [], "description": "DEPRECATED: Use /api/v1/notes endpoints. Always returns empty array.", "title": "Notes History" }, "organization": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "[DEPRECATED] Use 'organizations' field instead.", "examples": [ "Lincoln Elementary", "Youth Soccer League" ], "title": "Organization" }, "organizations": { "default": [], "description": "List of organizations this contact is affiliated with", "items": { "$ref": "#/components/schemas/OrganizationSummary" }, "title": "Organizations", "type": "array" }, "phone_numbers": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "default": [], "description": "Array of phone numbers [{number, type, primary, label}]", "title": "Phone Numbers" }, "photo_source": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Source of photo (manual|device_sync|google_people|generated)", "examples": [ "google_people" ], "title": "Photo Source" }, "photo_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "URL to contact's primary photo (priority: manual > device > google > generated)", "examples": [ "tenant-id/contacts/contact-id/photos/manual/2026-01-12.jpg" ], "title": "Photo Url" }, "potential_matches": { "anyOf": [ { "items": { "$ref": "#/components/schemas/PotentialMatch" }, "type": "array" }, { "type": "null" } ], "default": null, "description": "Existing contacts the matcher proposes as merge targets. NULL when not pending.", "title": "Potential Matches" }, "potential_matches_error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Set when the duplicate-detection sub-fetch failed; isolated from core response.", "title": "Potential Matches Error" }, "provenance": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "description": "Provenance metadata: who created this contact and how (D29).", "title": "Provenance" }, "relation_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": "acquaintance", "description": "Relationship classification (child|relation|acquaintance)", "examples": [ "child", "relation", "acquaintance" ], "title": "Relation Type" }, "requires_review": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "description": "Mirror of contacts.requires_review — server-asserted review flag.", "title": "Requires Review" }, "role": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Contact role (Teacher, Coach, Parent, etc.)", "examples": [ "Teacher", "Coach" ], "title": "Role" }, "source_email_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Email this contact was extracted from (extraction-source contacts only).", "title": "Source Email Id" }, "source_evidence": { "anyOf": [ { "items": { "$ref": "#/components/schemas/SourceEvidence" }, "type": "array" }, { "type": "null" } ], "default": null, "description": "Source records that produced this contact (email/note/calendar/extracted).", "title": "Source Evidence" }, "source_evidence_error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Set when the source-evidence sub-fetch failed; isolated from core response.", "title": "Source Evidence Error" }, "source_type": { "default": "manual", "description": "Where contact came from (extracted|manual|imported|booking)", "examples": [ "manual", "extracted" ], "pattern": "^(extracted|manual|imported|booking)$", "title": "Source Type", "type": "string" }, "source_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Supabase Storage URL to the original source document", "examples": [ "tenant-id/raw_emails/2025/12/18/email.eml" ], "title": "Source Url" }, "tags": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "default": null, "description": "Tag slugs applied to this contact", "title": "Tags" }, "tenant_id": { "description": "Associated tenant identifier (UUID)", "examples": [ "a1b2c3d4-..." ], "title": "Tenant Id", "type": "string" }, "total_interactions": { "default": 0, "title": "Total Interactions", "type": "integer" }, "updated_at": { "description": "ISO 8601 timestamp of last modification", "format": "date-time", "title": "Updated At", "type": "string" } }, "required": [ "id", "tenant_id", "name", "created_at", "updated_at" ], "title": "SmartGroupMemberResponse", "type": "object" }, "SmartGroupMembersResponse": { "properties": { "group": { "$ref": "#/components/schemas/SmartGroupSummary" }, "members": { "items": { "$ref": "#/components/schemas/SmartGroupMemberResponse" }, "title": "Members", "type": "array" } }, "required": [ "group", "members" ], "title": "SmartGroupMembersResponse", "type": "object" }, "SmartGroupRuleCondition": { "additionalProperties": false, "properties": { "field": { "title": "Field", "type": "string" }, "op": { "title": "Op", "type": "string" }, "value": { "title": "Value" } }, "required": [ "field", "op", "value" ], "title": "SmartGroupRuleCondition", "type": "object" }, "SmartGroupRuleDefinition": { "additionalProperties": false, "properties": { "all": { "items": { "$ref": "#/components/schemas/SmartGroupRuleCondition" }, "maxItems": 10, "minItems": 1, "title": "All", "type": "array" }, "version": { "const": 1, "default": 1, "title": "Version", "type": "integer" } }, "required": [ "all" ], "title": "SmartGroupRuleDefinition", "type": "object" }, "SmartGroupSummary": { "properties": { "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Description" }, "id": { "format": "uuid", "title": "Id", "type": "string" }, "last_computed_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Last Computed At" }, "member_count": { "default": 0, "title": "Member Count", "type": "integer" }, "name": { "title": "Name", "type": "string" }, "type": { "enum": [ "frequent", "stale", "follow_up", "custom" ], "title": "Type", "type": "string" } }, "required": [ "id", "type", "name" ], "title": "SmartGroupSummary", "type": "object" }, "SmsConsentGrant": { "description": "One TCPA consent grant and the number it covers (TIDY-18047).\n\n``phone_number`` is null only while a grant made before any number was on\nfile waits for the first number the user provides.", "properties": { "granted_at": { "title": "Granted At", "type": "string" }, "granted_via": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Granted Via" }, "phone_number": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Phone Number" }, "revoked_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Revoked At" }, "revoked_via": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Revoked Via" }, "terms_version": { "title": "Terms Version", "type": "string" } }, "required": [ "terms_version", "granted_at" ], "title": "SmsConsentGrant", "type": "object" }, "SmsProviderHealth": { "properties": { "balance": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Balance" }, "currency": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Currency" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Error" }, "ok": { "default": false, "title": "Ok", "type": "boolean" } }, "title": "SmsProviderHealth", "type": "object" }, "SmsProviderStatusResponse": { "properties": { "api_key_configured": { "default": false, "title": "Api Key Configured", "type": "boolean" }, "configured": { "default": false, "title": "Configured", "type": "boolean" }, "from_number": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "From Number" }, "health": { "$ref": "#/components/schemas/SmsProviderHealth", "default": { "balance": null, "currency": null, "error": null, "ok": false } }, "messaging_profile_configured": { "default": false, "title": "Messaging Profile Configured", "type": "boolean" }, "provider": { "default": "telnyx", "title": "Provider", "type": "string" }, "source": { "default": "environment", "title": "Source", "type": "string" }, "webhook_public_key_configured": { "default": false, "title": "Webhook Public Key Configured", "type": "boolean" } }, "title": "SmsProviderStatusResponse", "type": "object" }, "SmsTemplateListResponse": { "properties": { "templates": { "items": { "$ref": "#/components/schemas/SmsTemplateRow" }, "title": "Templates", "type": "array" } }, "required": [ "templates" ], "title": "SmsTemplateListResponse", "type": "object" }, "SmsTemplateRow": { "properties": { "available_variables": { "default": [], "items": { "type": "string" }, "title": "Available Variables", "type": "array" }, "body_template": { "title": "Body Template", "type": "string" }, "category": { "title": "Category", "type": "string" }, "created_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Created At" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Description" }, "id": { "title": "Id", "type": "string" }, "is_active": { "default": true, "title": "Is Active", "type": "boolean" }, "is_system": { "default": false, "title": "Is System", "type": "boolean" }, "max_length": { "default": 160, "title": "Max Length", "type": "integer" }, "name": { "title": "Name", "type": "string" }, "slug": { "title": "Slug", "type": "string" }, "tenant_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Tenant Id" }, "updated_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Updated At" } }, "required": [ "id", "name", "slug", "category", "body_template" ], "title": "SmsTemplateRow", "type": "object" }, "SmsTemplateSaveRequest": { "additionalProperties": false, "properties": { "body_template": { "title": "Body Template", "type": "string" }, "category": { "title": "Category", "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "is_active": { "default": true, "title": "Is Active", "type": "boolean" }, "max_length": { "default": 160, "title": "Max Length", "type": "integer" }, "name": { "title": "Name", "type": "string" }, "slug": { "title": "Slug", "type": "string" } }, "required": [ "name", "slug", "category", "body_template" ], "title": "SmsTemplateSaveRequest", "type": "object" }, "SmsTemplateToggleRequest": { "additionalProperties": false, "properties": { "is_active": { "title": "Is Active", "type": "boolean" } }, "required": [ "is_active" ], "title": "SmsTemplateToggleRequest", "type": "object" }, "SmsTestSendRequest": { "properties": { "message": { "maxLength": 1600, "minLength": 1, "title": "Message", "type": "string" }, "tenant_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Tenant the test send is recorded against. Defaults to the caller's tenant; required for a tenant-less operator.", "title": "Tenant Id" }, "to_phone": { "description": "Recipient phone number (E.164)", "title": "To Phone", "type": "string" } }, "required": [ "to_phone", "message" ], "title": "SmsTestSendRequest", "type": "object" }, "SmsTestSendResponse": { "properties": { "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Error" }, "message_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Message Id" }, "segments": { "default": 1, "title": "Segments", "type": "integer" }, "status": { "title": "Status", "type": "string" }, "success": { "title": "Success", "type": "boolean" } }, "required": [ "success", "status" ], "title": "SmsTestSendResponse", "type": "object" }, "SnapshotRequest": { "properties": { "estimated_bytes": { "maximum": 1073741824.0, "minimum": 0.0, "title": "Estimated Bytes", "type": "integer" } }, "required": [ "estimated_bytes" ], "title": "SnapshotRequest", "type": "object" }, "SnapshotResponse": { "properties": { "folder_path": { "title": "Folder Path", "type": "string" }, "quota_bytes": { "title": "Quota Bytes", "type": "integer" }, "snapshot_id": { "format": "uuid", "title": "Snapshot Id", "type": "string" }, "used_bytes": { "title": "Used Bytes", "type": "integer" } }, "required": [ "snapshot_id", "folder_path", "used_bytes", "quota_bytes" ], "title": "SnapshotResponse", "type": "object" }, "SnapshotStorage": { "properties": { "quota_bytes": { "title": "Quota Bytes", "type": "integer" }, "used_bytes": { "title": "Used Bytes", "type": "integer" } }, "required": [ "used_bytes", "quota_bytes" ], "title": "SnapshotStorage", "type": "object" }, "SnapshotUploadResponse": { "properties": { "file_id": { "format": "uuid", "title": "File Id", "type": "string" } }, "required": [ "file_id" ], "title": "SnapshotUploadResponse", "type": "object" }, "SnoozeResponse": { "description": "Response for snooze email endpoint.\n\nAttributes:\n id: Email UUID that was snoozed\n success: Whether the snooze was applied\n message: Human-readable result message\n wake_at: When the email will reappear\n\nExample:\n {\"id\": \"uuid-here\", \"success\": true, \"message\": \"Snoozed until tomorrow\", \"wake_at\": \"2026-01-20T09:00:00Z\"}\n\nRelated: KCC-3348 S5.4 Snooze & Mute", "properties": { "id": { "description": "Email UUID", "format": "uuid", "title": "Id", "type": "string" }, "message": { "description": "Result message", "title": "Message", "type": "string" }, "success": { "description": "Whether snooze was applied", "title": "Success", "type": "boolean" }, "wake_at": { "description": "When email will reappear", "format": "date-time", "title": "Wake At", "type": "string" } }, "required": [ "id", "success", "message", "wake_at" ], "title": "SnoozeResponse", "type": "object" }, "SortClause": { "description": "Single Database facet sort clause (QuerySpec V1 SortClause).", "properties": { "direction": { "default": "asc", "enum": [ "asc", "desc" ], "title": "Direction", "type": "string" }, "field": { "minLength": 1, "title": "Field", "type": "string" }, "nulls": { "anyOf": [ { "enum": [ "first", "last" ], "type": "string" }, { "type": "null" } ], "description": "Explicit null placement (TIDY-14224); executor type default when absent.", "title": "Nulls" } }, "required": [ "field" ], "title": "SortClause", "type": "object" }, "SourceControlProviderListResponse": { "properties": { "providers": { "items": { "$ref": "#/components/schemas/SourceControlProviderResponse" }, "title": "Providers", "type": "array" } }, "required": [ "providers" ], "title": "SourceControlProviderListResponse", "type": "object" }, "SourceControlProviderResponse": { "description": "One catalog entry plus this tenant's live connection state.", "properties": { "account_label": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Account Label" }, "auth_kinds": { "items": { "type": "string" }, "title": "Auth Kinds", "type": "array" }, "capabilities": { "$ref": "#/components/schemas/ProviderCapabilitiesModel" }, "docs_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Docs Url" }, "id": { "title": "Id", "type": "string" }, "label": { "title": "Label", "type": "string" }, "novice_blurb": { "title": "Novice Blurb", "type": "string" }, "repository_selection": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Repository Selection" }, "self_hosted": { "title": "Self Hosted", "type": "boolean" }, "status": { "description": "not_configured | not_connected | working | needs_reauth | disconnected | pending. 'not_configured' means this deployment cannot talk to the provider at all; 'not_connected' means this tenant has not.", "title": "Status", "type": "string" }, "status_detail": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Status Detail" } }, "required": [ "id", "label", "novice_blurb", "self_hosted", "auth_kinds", "capabilities", "status" ], "title": "SourceControlProviderResponse", "type": "object" }, "SourceControlRepository": { "description": "One repository, provider-neutral.", "properties": { "archived": { "default": false, "title": "Archived", "type": "boolean" }, "clone_url": { "title": "Clone Url", "type": "string" }, "default_branch": { "title": "Default Branch", "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Description" }, "external_id": { "title": "External Id", "type": "string" }, "full_name": { "title": "Full Name", "type": "string" }, "name": { "title": "Name", "type": "string" }, "owner": { "title": "Owner", "type": "string" }, "private": { "title": "Private", "type": "boolean" }, "provider_id": { "title": "Provider Id", "type": "string" }, "web_url": { "title": "Web Url", "type": "string" } }, "required": [ "provider_id", "external_id", "full_name", "name", "owner", "private", "default_branch", "clone_url", "web_url" ], "title": "SourceControlRepository", "type": "object" }, "SourceControlRepositoryListResponse": { "properties": { "repositories": { "items": { "$ref": "#/components/schemas/SourceControlRepository" }, "title": "Repositories", "type": "array" } }, "required": [ "repositories" ], "title": "SourceControlRepositoryListResponse", "type": "object" }, "SourceDetailResponse": { "description": "Detailed source information for a primitive.", "properties": { "email_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Email Id" }, "email_received_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Email Received At" }, "email_sender": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Email Sender" }, "email_subject": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Email Subject" }, "email_summary": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Email Summary" }, "file_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "File Name" }, "file_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "File Type" }, "trace_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Trace Id" }, "type": { "title": "Type", "type": "string" } }, "required": [ "type" ], "title": "SourceDetailResponse", "type": "object" }, "SourceEvidence": { "description": "One source record that produced a contact (TIDY-8725).\n\nMultiple sources are possible (email + extraction + future note/calendar\nreferences). The ``type`` discriminates the rendering path on the\nfrontend, while ``id`` + ``jump_url`` carry the linkback so the user can\nopen the originating record in the working panel.", "properties": { "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Identifier of the source record (email id, note id, ...).", "title": "Id" }, "jump_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Working-panel URL for jumping to the source. NULL = no linkback.", "title": "Jump Url" }, "occurred_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "description": "Timestamp the source record was received / extracted.", "title": "Occurred At" }, "sender": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "From-address or author when applicable.", "title": "Sender" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Subject / title shown in the row header.", "title": "Title" }, "type": { "description": "Source primitive type.", "enum": [ "email", "note", "calendar", "extracted" ], "title": "Type", "type": "string" } }, "required": [ "type" ], "title": "SourceEvidence", "type": "object" }, "SourceInfo": { "description": "Source information for a primitive.", "properties": { "sender": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Sender" }, "subject": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Subject" }, "trace_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Trace Id" }, "type": { "title": "Type", "type": "string" } }, "required": [ "type" ], "title": "SourceInfo", "type": "object" }, "SourceTypeBreakdown": { "properties": { "calls": { "default": 0, "title": "Calls", "type": "integer" }, "cost_usd": { "default": 0.0, "title": "Cost Usd", "type": "number" }, "source_type": { "title": "Source Type", "type": "string" }, "total_tokens": { "default": 0, "title": "Total Tokens", "type": "integer" } }, "required": [ "source_type" ], "title": "SourceTypeBreakdown", "type": "object" }, "SourceUrlIngest": { "description": "A commit or pull-request named by its web URL (TIDY-15590).\n\nThe paste-to-attach transport: the server recognises the URL, derives the\nnatural key, and upserts the matching commit / PR record — the client\nnever parses a provider URL. Non-commit/PR URLs are a 422.", "properties": { "links": { "default": [], "items": { "$ref": "#/components/schemas/EvidenceLinkIn" }, "title": "Links", "type": "array" }, "url": { "maxLength": 2000, "minLength": 1, "title": "Url", "type": "string" } }, "required": [ "url" ], "title": "SourceUrlIngest", "type": "object" }, "SpeakerUpdate": { "properties": { "account_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Account Id" }, "contact_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Contact Id" }, "display_name": { "anyOf": [ { "maxLength": 200, "type": "string" }, { "type": "null" } ], "title": "Display Name" }, "speaker_label": { "maxLength": 200, "minLength": 1, "title": "Speaker Label", "type": "string" } }, "required": [ "speaker_label" ], "title": "SpeakerUpdate", "type": "object" }, "SpendBreakdown": { "properties": { "cost_usd": { "title": "Cost Usd", "type": "number" }, "key": { "title": "Key", "type": "string" }, "measured": { "title": "Measured", "type": "boolean" }, "tokens": { "title": "Tokens", "type": "integer" } }, "required": [ "key", "tokens", "cost_usd", "measured" ], "title": "SpendBreakdown", "type": "object" }, "SpendCapCreate": { "properties": { "alert_thresholds": { "items": { "anyOf": [ { "type": "number" }, { "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$", "type": "string" } ] }, "title": "Alert Thresholds", "type": "array" }, "monthly_cap_usd": { "anyOf": [ { "exclusiveMinimum": 0.0, "type": "number" }, { "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$", "type": "string" } ], "title": "Monthly Cap Usd" } }, "required": [ "monthly_cap_usd" ], "title": "SpendCapCreate", "type": "object" }, "SpendCapResponse": { "properties": { "alert_thresholds": { "items": { "anyOf": [ { "type": "number" }, { "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$", "type": "string" } ] }, "title": "Alert Thresholds", "type": "array" }, "budget_state": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Budget State" }, "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "crossed_thresholds": { "items": { "anyOf": [ { "type": "number" }, { "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$", "type": "string" } ] }, "title": "Crossed Thresholds", "type": "array" }, "current_spend_usd": { "anyOf": [ { "type": "number" }, { "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$", "type": "string" } ], "title": "Current Spend Usd" }, "cycle_start": { "format": "date-time", "title": "Cycle Start", "type": "string" }, "monthly_cap_usd": { "anyOf": [ { "type": "number" }, { "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$", "type": "string" } ], "title": "Monthly Cap Usd" }, "overridden_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Overridden At" }, "overridden_by": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Overridden By" }, "soft_ratio": { "anyOf": [ { "type": "number" }, { "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$", "type": "string" }, { "type": "null" } ], "default": null, "title": "Soft Ratio" }, "state_since": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "State Since" }, "tenant_id": { "format": "uuid", "title": "Tenant Id", "type": "string" }, "updated_at": { "format": "date-time", "title": "Updated At", "type": "string" }, "warn_ratio": { "anyOf": [ { "type": "number" }, { "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$", "type": "string" }, { "type": "null" } ], "default": null, "title": "Warn Ratio" } }, "required": [ "tenant_id", "monthly_cap_usd", "alert_thresholds", "current_spend_usd", "cycle_start", "crossed_thresholds", "overridden_at", "overridden_by", "created_at", "updated_at" ], "title": "SpendCapResponse", "type": "object" }, "SpendDelta": { "properties": { "invested": { "title": "Invested", "type": "number" }, "saved": { "title": "Saved", "type": "number" } }, "required": [ "saved", "invested" ], "title": "SpendDelta", "type": "object" }, "SpendWindow": { "properties": { "cost_usd": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Cost Usd" }, "funding": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Funding" }, "funding_split": { "items": { "$ref": "#/components/schemas/SpendBreakdown" }, "title": "Funding Split", "type": "array" }, "label": { "default": "Spend on work you can see", "title": "Label", "type": "string" }, "lanes": { "items": { "$ref": "#/components/schemas/SpendBreakdown" }, "title": "Lanes", "type": "array" }, "scope": { "title": "Scope", "type": "string" }, "scope_key": { "title": "Scope Key", "type": "string" }, "stalled": { "default": false, "title": "Stalled", "type": "boolean" }, "stalled_since": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Stalled Since" }, "tokens": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Tokens" }, "window": { "title": "Window", "type": "string" } }, "required": [ "scope", "scope_key", "window", "cost_usd", "tokens", "funding", "lanes", "funding_split" ], "title": "SpendWindow", "type": "object" }, "SplitCount": { "description": "Count of emails in a split category.", "properties": { "total": { "default": 0, "description": "Total emails in this split", "title": "Total", "type": "integer" }, "unread": { "default": 0, "description": "Unread emails in this split", "title": "Unread", "type": "integer" } }, "title": "SplitCount", "type": "object" }, "StaleScanResult": { "properties": { "enqueued": { "title": "Enqueued", "type": "integer" }, "stale_found": { "title": "Stale Found", "type": "integer" } }, "required": [ "stale_found", "enqueued" ], "title": "StaleScanResult", "type": "object" }, "StandingAuthorisation": { "properties": { "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "employee_account_id": { "title": "Employee Account Id", "type": "string" }, "exercise_count": { "title": "Exercise Count", "type": "integer" }, "expires_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Expires At" }, "id": { "title": "Id", "type": "string" }, "kind": { "title": "Kind", "type": "string" }, "last_exercised_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Last Exercised At" }, "limits": { "additionalProperties": true, "title": "Limits", "type": "object" }, "message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "On a renewal, what the person renewing must know now: that it cannot reach the machine until the workshop updates (TIDY-20019).", "title": "Message" }, "owner_account_id": { "title": "Owner Account Id", "type": "string" }, "revoked_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Revoked At" }, "scope": { "additionalProperties": true, "title": "Scope", "type": "object" }, "source_id": { "title": "Source Id", "type": "string" }, "source_table": { "title": "Source Table", "type": "string" }, "tenant_id": { "title": "Tenant Id", "type": "string" }, "updated_at": { "format": "date-time", "title": "Updated At", "type": "string" } }, "required": [ "id", "tenant_id", "employee_account_id", "owner_account_id", "kind", "source_table", "source_id", "scope", "limits", "exercise_count", "created_at", "updated_at" ], "title": "StandingAuthorisation", "type": "object" }, "StandingAuthorisationsResponse": { "properties": { "authorisations": { "items": { "$ref": "#/components/schemas/StandingAuthorisation" }, "title": "Authorisations", "type": "array" } }, "required": [ "authorisations" ], "title": "StandingAuthorisationsResponse", "type": "object" }, "StartHuddleRequest": { "description": "Huddle start options (TIDY-11947 / S3, D1).\n\n``plane_choice='meet'`` is the explicit \"Huddle in Meet\" secondary\naffordance; ``scheduled_at`` (future) makes this a scheduled,\ncalendar-anchored Meet huddle; ``invite_external`` signals intended\nparticipants without Tidy access (D1 rule 1).", "properties": { "conversation_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "description": "The conversation the caller has open when they start the call. A call with a virtual employee continues it: the call's note, every spoken turn and the recap land in that conversation. It must be one of the caller's conversations with that employee in this DM, or the start is refused (409 ve_huddle_conversation_unavailable). Absent, the call opens a new conversation. Other calls do not read it.", "title": "Conversation Id" }, "invite_external": { "default": false, "title": "Invite External", "type": "boolean" }, "plane_choice": { "default": "auto", "enum": [ "auto", "meet" ], "title": "Plane Choice", "type": "string" }, "scheduled_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Scheduled At" } }, "title": "StartHuddleRequest", "type": "object" }, "StartTimerRequest": { "description": "Request payload for starting a timer.", "properties": { "target_id": { "description": "Target object ID", "format": "uuid", "title": "Target Id", "type": "string" }, "target_type": { "$ref": "#/components/schemas/TimerTargetType", "description": "Timer target type" } }, "required": [ "target_type", "target_id" ], "title": "StartTimerRequest", "type": "object" }, "StateVectorEntry": { "properties": { "note_id": { "title": "Note Id", "type": "string" }, "state_vector": { "title": "State Vector", "type": "string" } }, "required": [ "note_id", "state_vector" ], "title": "StateVectorEntry", "type": "object" }, "StorageOnlyUploadResponse": { "description": "Response for /admin/coaching-knowledge/upload (storage-only).", "properties": { "fileName": { "title": "Filename", "type": "string" }, "module": { "title": "Module", "type": "string" }, "size": { "title": "Size", "type": "integer" }, "storagePath": { "title": "Storagepath", "type": "string" }, "success": { "title": "Success", "type": "boolean" } }, "required": [ "success", "storagePath", "fileName", "module", "size" ], "title": "StorageOnlyUploadResponse", "type": "object" }, "StorageSignBatchItem": { "description": "One item in a batch sign request.", "properties": { "bucket": { "description": "Bucket name. Must be in the allow-list.", "examples": [ "pipeline-artifacts" ], "title": "Bucket", "type": "string" }, "path": { "description": "Object path within the bucket (no leading slash).", "examples": [ "00000000-0000-0000-0000-000000000001/contacts/abc/photo.jpg" ], "title": "Path", "type": "string" } }, "required": [ "bucket", "path" ], "title": "StorageSignBatchItem", "type": "object" }, "StorageSignBatchRequest": { "description": "Request body for POST /api/v1/storage/sign-batch.", "properties": { "expires_in_seconds": { "default": 3600, "description": "Signed URL TTL applied to every item. Max 86400 (1 day).", "maximum": 86400.0, "minimum": 1.0, "title": "Expires In Seconds", "type": "integer" }, "items": { "description": "List of bucket+path pairs to sign. Empty list rejected. Max 100 items per batch.", "items": { "$ref": "#/components/schemas/StorageSignBatchItem" }, "title": "Items", "type": "array" } }, "required": [ "items" ], "title": "StorageSignBatchRequest", "type": "object" }, "StorageSignBatchResponse": { "description": "Response body for POST /api/v1/storage/sign-batch.", "properties": { "items": { "items": { "$ref": "#/components/schemas/StorageSignBatchResponseItem" }, "title": "Items", "type": "array" } }, "required": [ "items" ], "title": "StorageSignBatchResponse", "type": "object" }, "StorageSignBatchResponseItem": { "description": "One item in a batch sign response.", "properties": { "bucket": { "title": "Bucket", "type": "string" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Short error code when signing failed for this item; null on success. Known codes: object_not_found, signing_request_failed, signing_failed, not_visible (the caller may not see the row that owns this object — a user-files asset, a photo, or the note behind a drawing/collage snapshot).", "title": "Error" }, "expires_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO 8601 UTC expiry timestamp; null when signing failed.", "title": "Expires At" }, "path": { "title": "Path", "type": "string" }, "signed_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Download URL, or null if signing failed. Scoped files return a relative /api/v1/storage URL requiring current authentication on every request; ordinary objects return a signed URL.", "title": "Signed Url" } }, "required": [ "bucket", "path" ], "title": "StorageSignBatchResponseItem", "type": "object" }, "StorageSignRequest": { "description": "Request body for POST /api/v1/storage/sign.", "properties": { "bucket": { "description": "Bucket name. Must be in the allow-list.", "examples": [ "pipeline-artifacts" ], "title": "Bucket", "type": "string" }, "expires_in_seconds": { "default": 3600, "description": "Signed URL TTL. Max 86400 (1 day).", "maximum": 86400.0, "minimum": 1.0, "title": "Expires In Seconds", "type": "integer" }, "path": { "description": "Object path within the bucket (no leading slash).", "examples": [ "00000000-0000-0000-0000-000000000001/contacts/abc/photo.jpg" ], "title": "Path", "type": "string" } }, "required": [ "bucket", "path" ], "title": "StorageSignRequest", "type": "object" }, "StorageSignResponse": { "description": "Response body for POST /api/v1/storage/sign.", "properties": { "expires_at": { "description": "ISO 8601 UTC timestamp when the signed URL expires.", "examples": [ "2026-04-26T14:30:00.000Z" ], "title": "Expires At", "type": "string" }, "signed_url": { "description": "Download URL. Scoped files return a relative /api/v1/storage URL that requires current authentication on every request; ordinary objects return a signed URL.", "title": "Signed Url", "type": "string" } }, "required": [ "signed_url", "expires_at" ], "title": "StorageSignResponse", "type": "object" }, "StreakResponse": { "properties": { "active": { "title": "Active", "type": "boolean" }, "best_count": { "title": "Best Count", "type": "integer" }, "current_count": { "title": "Current Count", "type": "integer" }, "icon": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Icon" }, "include_weekends": { "title": "Include Weekends", "type": "boolean" }, "label": { "title": "Label", "type": "string" }, "last_achieved": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Achieved" }, "paused": { "title": "Paused", "type": "boolean" }, "streak_start_date": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Streak Start Date" }, "type": { "title": "Type", "type": "string" } }, "required": [ "type", "label", "current_count", "best_count", "active", "include_weekends", "paused" ], "title": "StreakResponse", "type": "object" }, "StreaksListResponse": { "properties": { "streaks": { "items": { "$ref": "#/components/schemas/StreakResponse" }, "title": "Streaks", "type": "array" } }, "required": [ "streaks" ], "title": "StreaksListResponse", "type": "object" }, "StreamingLookupResponse": { "properties": { "configured": { "default": true, "title": "Configured", "type": "boolean" }, "message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Message" }, "results": { "default": [], "items": { "$ref": "#/components/schemas/StreamingLookupResult" }, "title": "Results", "type": "array" } }, "title": "StreamingLookupResponse", "type": "object" }, "StreamingLookupResult": { "description": "One matched title with its watch-provider availability.", "properties": { "media_type": { "title": "Media Type", "type": "string" }, "overview": { "default": "", "title": "Overview", "type": "string" }, "providers": { "$ref": "#/components/schemas/WatchProviders", "default": { "buy": [], "rent": [], "stream": [] } }, "title": { "title": "Title", "type": "string" }, "tmdb_id": { "title": "Tmdb Id", "type": "integer" }, "year": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Year" } }, "required": [ "tmdb_id", "title", "media_type" ], "title": "StreamingLookupResult", "type": "object" }, "StripeFieldDriftItem": { "properties": { "field": { "title": "Field", "type": "string" }, "stripe": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Stripe" }, "tidy": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Tidy" } }, "required": [ "field" ], "title": "StripeFieldDriftItem", "type": "object" }, "StripeReconciliationResponse": { "properties": { "checked_at": { "format": "date-time", "title": "Checked At", "type": "string" }, "drift": { "items": { "$ref": "#/components/schemas/StripeTenantDriftItem" }, "title": "Drift", "type": "array" }, "endpoints": { "items": { "$ref": "#/components/schemas/StripeWebhookEndpointCheckItem" }, "title": "Endpoints", "type": "array" }, "tenants_checked": { "title": "Tenants Checked", "type": "integer" } }, "required": [ "checked_at", "tenants_checked", "drift", "endpoints" ], "title": "StripeReconciliationResponse", "type": "object" }, "StripeTenantDriftItem": { "properties": { "billing_exempt": { "title": "Billing Exempt", "type": "boolean" }, "detail": { "default": "", "title": "Detail", "type": "string" }, "env": { "title": "Env", "type": "string" }, "fields": { "default": [], "items": { "$ref": "#/components/schemas/StripeFieldDriftItem" }, "title": "Fields", "type": "array" }, "problem": { "title": "Problem", "type": "string" }, "stripe_customer_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Stripe Customer Id" }, "stripe_subscription_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Stripe Subscription Id" }, "tenant_id": { "title": "Tenant Id", "type": "string" }, "tenant_name": { "title": "Tenant Name", "type": "string" }, "tenant_status": { "title": "Tenant Status", "type": "string" } }, "required": [ "tenant_id", "tenant_name", "tenant_status", "env", "billing_exempt", "problem" ], "title": "StripeTenantDriftItem", "type": "object" }, "StripeWebhookEndpointCheckItem": { "properties": { "enabled": { "title": "Enabled", "type": "boolean" }, "endpoint_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Endpoint Id" }, "envs": { "items": { "type": "string" }, "title": "Envs", "type": "array" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Error" }, "expected_url": { "title": "Expected Url", "type": "string" }, "missing_event_types": { "default": [], "items": { "type": "string" }, "title": "Missing Event Types", "type": "array" } }, "required": [ "envs", "expected_url", "enabled" ], "title": "StripeWebhookEndpointCheckItem", "type": "object" }, "StrongMatchCandidate": { "properties": { "display_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Display Name" }, "id": { "title": "Id", "type": "string" }, "match_score": { "title": "Match Score", "type": "number" }, "preview": { "$ref": "#/components/schemas/MatchCandidatePreview" }, "visibility": { "title": "Visibility", "type": "string" } }, "required": [ "id", "visibility", "match_score", "preview" ], "title": "StrongMatchCandidate", "type": "object" }, "StrongMatchResponse": { "properties": { "candidates": { "items": { "$ref": "#/components/schemas/StrongMatchCandidate" }, "title": "Candidates", "type": "array" } }, "required": [ "candidates" ], "title": "StrongMatchResponse", "type": "object" }, "StuckEmailOut": { "properties": { "from_address": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "From Address" }, "id": { "title": "Id", "type": "string" }, "pipeline_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Pipeline Status" }, "screening_status": { "title": "Screening Status", "type": "string" }, "sender_decision": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Sender Decision" }, "subject": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Subject" } }, "required": [ "id", "screening_status" ], "title": "StuckEmailOut", "type": "object" }, "StuckWorkItem": { "description": "An item stuck on an employee's plate (TIDY-20074 F13): assigned to it,\nin a Waiting or Being-worked state its \"Wakes for\" leaves out, so nothing\nwill ever wake anyone for it (TIDY-20074 F16: Parked and Done never are).", "properties": { "alerted": { "description": "Its employee manager has been alerted.", "title": "Alerted", "type": "boolean" }, "item_ref": { "title": "Item Ref", "type": "string" }, "short_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Short Id" }, "since": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "When it was first seen stuck; null until the heartbeat has looked.", "title": "Since" }, "status": { "title": "Status", "type": "string" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Title" }, "tried": { "description": "Its one try is spent: the employee whose write left it stuck was told in its tool result, or the employee was woken once with the note.", "title": "Tried", "type": "boolean" }, "woken_for_by": { "description": "Who around the employee (its manager, peers and direct reports) wakes for this state — whom to hand it to.", "items": { "type": "string" }, "title": "Woken For By", "type": "array" } }, "required": [ "item_ref", "status", "since", "tried", "alerted", "woken_for_by" ], "title": "StuckWorkItem", "type": "object" }, "StuckWorkManager": { "description": "The employee's manager on the team Org chart, when it is an employee:\nalerted to its stuck work once its one try is spent (TIDY-20074 F13).", "properties": { "account_id": { "title": "Account Id", "type": "string" }, "name": { "title": "Name", "type": "string" } }, "required": [ "account_id", "name" ], "title": "StuckWorkManager", "type": "object" }, "StuckWorkNote": { "description": "TIDY-20074 F13: an employee's task write left this item stuck — the note\nits tool result carries in the same turn. That is its one try.", "properties": { "employee": { "description": "Who it is assigned to.", "title": "Employee", "type": "string" }, "employee_account_id": { "title": "Employee Account Id", "type": "string" }, "first_try": { "description": "False when this stuck spell's one try was already spent.", "title": "First Try", "type": "boolean" }, "item_ref": { "title": "Item Ref", "type": "string" }, "manager": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The employee manager alerted if it is still stuck after this.", "title": "Manager" }, "status": { "title": "Status", "type": "string" }, "status_labels": { "additionalProperties": { "type": "string" }, "description": "TIDY-20074 F16: the word the workspace shows for `status` and each state in `wakes_for` (the task status field's labels).", "title": "Status Labels", "type": "object" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Title" }, "wakes_for": { "description": "The states that wake the employee it is assigned to.", "items": { "type": "string" }, "title": "Wakes For", "type": "array" }, "woken_for_by": { "description": "Who around that employee wakes for this state — whom to hand it to.", "items": { "type": "string" }, "title": "Woken For By", "type": "array" }, "yours": { "description": "It is assigned to the employee that wrote.", "title": "Yours", "type": "boolean" } }, "required": [ "item_ref", "status", "employee", "employee_account_id", "yours", "wakes_for", "woken_for_by", "manager", "first_try" ], "title": "StuckWorkNote", "type": "object" }, "StudyProgressListResponse": { "description": "Every card of one deck the caller has studied.", "properties": { "progress": { "items": { "$ref": "#/components/schemas/StudyProgressResponse" }, "title": "Progress", "type": "array" }, "record_id": { "title": "Record Id", "type": "string" }, "total": { "title": "Total", "type": "integer" } }, "required": [ "record_id", "progress", "total" ], "title": "StudyProgressListResponse", "type": "object" }, "StudyProgressResponse": { "description": "One card's study state for the calling member.", "properties": { "card_id": { "title": "Card Id", "type": "string" }, "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "due_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Due At" }, "ease": { "title": "Ease", "type": "number" }, "id": { "title": "Id", "type": "string" }, "interval_days": { "title": "Interval Days", "type": "integer" }, "lapse_count": { "title": "Lapse Count", "type": "integer" }, "last_result": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Last Result" }, "last_reviewed_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Last Reviewed At" }, "record_id": { "title": "Record Id", "type": "string" }, "review_count": { "title": "Review Count", "type": "integer" }, "updated_at": { "format": "date-time", "title": "Updated At", "type": "string" } }, "required": [ "id", "record_id", "card_id", "ease", "interval_days", "review_count", "lapse_count", "created_at", "updated_at" ], "title": "StudyProgressResponse", "type": "object" }, "StudyReviewRequest": { "description": "One graded card review.", "properties": { "card_id": { "description": "The card's id within the deck's properties", "title": "Card Id", "type": "string" }, "due_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "When this card is next due (ISO 8601 UTC); unchanged when omitted", "title": "Due At" }, "ease": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Scheduler-computed ease factor; unchanged when omitted", "title": "Ease" }, "interval_days": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Scheduler-computed interval in days; unchanged when omitted", "title": "Interval Days" }, "result": { "description": "How the card was graded", "enum": [ "again", "hard", "good", "easy" ], "title": "Result", "type": "string" }, "reviewed_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "When the card was graded (ISO 8601 UTC). Defaults to now; a review that waited in the offline queue carries the instant it was graded.", "title": "Reviewed At" } }, "required": [ "card_id", "result" ], "title": "StudyReviewRequest", "type": "object" }, "StudySessionRequest": { "description": "One COMPLETED study or quiz session (R17: study-session completion).\n\nSent once, when the queue empties. Fire-and-forget from the client's point\nof view — a failure here loses a data point, never a review.", "properties": { "again_count": { "default": 0, "title": "Again Count", "type": "integer" }, "cards_reviewed": { "default": 0, "title": "Cards Reviewed", "type": "integer" }, "cards_total": { "default": 0, "title": "Cards Total", "type": "integer" }, "client_session_id": { "description": "Client-generated session id; a replay collapses to one row", "title": "Client Session Id", "type": "string" }, "correct_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Quiz only — questions answered correctly", "title": "Correct Count" }, "easy_count": { "default": 0, "title": "Easy Count", "type": "integer" }, "good_count": { "default": 0, "title": "Good Count", "type": "integer" }, "hard_count": { "default": 0, "title": "Hard Count", "type": "integer" }, "session_kind": { "default": "study", "enum": [ "study", "quiz" ], "title": "Session Kind", "type": "string" }, "started_at": { "description": "When the session began (ISO 8601 UTC)", "title": "Started At", "type": "string" } }, "required": [ "client_session_id", "started_at" ], "title": "StudySessionRequest", "type": "object" }, "StudySessionResponse": { "properties": { "duplicate": { "title": "Duplicate", "type": "boolean" }, "id": { "title": "Id", "type": "string" }, "record_id": { "title": "Record Id", "type": "string" } }, "required": [ "id", "record_id", "duplicate" ], "title": "StudySessionResponse", "type": "object" }, "StylePresetModel": { "properties": { "id": { "title": "Id", "type": "string" }, "label": { "title": "Label", "type": "string" } }, "required": [ "id", "label" ], "title": "StylePresetModel", "type": "object" }, "SubagentActivityDetail": { "description": "Per-run drill-down for a sub-agent on the Activity surface (TIDY-13686).\n\nHarvest by default; progress timeline always; the (compacted) transcript\nonly when explicitly requested. Owner-scoped read model.", "properties": { "harvest": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "title": "Harvest" }, "progress": { "items": { "$ref": "#/components/schemas/SubagentProgressEntry" }, "title": "Progress", "type": "array" }, "run_id": { "title": "Run Id", "type": "string" }, "status": { "title": "Status", "type": "string" }, "subagent_type": { "title": "Subagent Type", "type": "string" }, "transcript": { "anyOf": [ {}, { "type": "null" } ], "default": null, "title": "Transcript" }, "truncated": { "default": false, "title": "Truncated", "type": "boolean" } }, "required": [ "run_id", "subagent_type", "status" ], "title": "SubagentActivityDetail", "type": "object" }, "SubagentProgressEntry": { "properties": { "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "message": { "title": "Message", "type": "string" } }, "required": [ "message", "created_at" ], "title": "SubagentProgressEntry", "type": "object" }, "SubmitSignatureRequest": { "properties": { "consent_accepted": { "description": "ESIGN/UETA consent checkbox", "title": "Consent Accepted", "type": "boolean" }, "drawn_signature": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Drawn-signature image data URL", "title": "Drawn Signature" }, "typed_name": { "anyOf": [ { "maxLength": 200, "type": "string" }, { "type": "null" } ], "title": "Typed Name" } }, "required": [ "consent_accepted" ], "title": "SubmitSignatureRequest", "type": "object" }, "SubmitSignatureResult": { "properties": { "signed_pdf_file_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Signed Pdf File Id" }, "status": { "title": "Status", "type": "string" } }, "required": [ "status" ], "title": "SubmitSignatureResult", "type": "object" }, "SubscriptionResponse": { "properties": { "billing_interval": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Billing Interval" }, "cancel_at_period_end": { "default": false, "title": "Cancel At Period End", "type": "boolean" }, "checkout_discount": { "anyOf": [ { "$ref": "#/components/schemas/BillingDiscount" }, { "type": "null" } ] }, "current_period_end": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Current Period End" }, "current_period_start": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Current Period Start" }, "discounts": { "default": [], "items": { "$ref": "#/components/schemas/BillingDiscount" }, "title": "Discounts", "type": "array" }, "payment_method": { "anyOf": [ { "$ref": "#/components/schemas/PaymentMethod" }, { "type": "null" } ] }, "plan_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Plan Id" }, "plan_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Plan Name" }, "price_cents": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Price Cents" }, "scheduled_billing_interval": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Scheduled Billing Interval" }, "scheduled_change_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Scheduled Change At" }, "scheduled_plan_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Scheduled Plan Id" }, "seat_items": { "default": [], "items": { "$ref": "#/components/schemas/SubscriptionSeatItem" }, "title": "Seat Items", "type": "array" }, "seats": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Seats" }, "status": { "title": "Status", "type": "string" }, "subscription_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Subscription Id" }, "trial_end": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Trial End" } }, "required": [ "status" ], "title": "SubscriptionResponse", "type": "object" }, "SubscriptionSeatItem": { "description": "One seat tier on the Stripe subscription.", "properties": { "is_plan": { "title": "Is Plan", "type": "boolean" }, "quantity": { "title": "Quantity", "type": "integer" }, "tier": { "title": "Tier", "type": "string" }, "unit_amount_cents": { "description": "One seat of this tier, per billing interval.", "title": "Unit Amount Cents", "type": "integer" } }, "required": [ "tier", "quantity", "unit_amount_cents", "is_plan" ], "title": "SubscriptionSeatItem", "type": "object" }, "SuggestEmbedRequest": { "properties": { "limit": { "default": 5, "maximum": 10.0, "minimum": 1.0, "title": "Limit", "type": "integer" }, "query": { "maxLength": 500, "minLength": 1, "title": "Query", "type": "string" }, "room_id": { "minLength": 1, "title": "Room Id", "type": "string" } }, "required": [ "room_id", "query" ], "title": "SuggestEmbedRequest", "type": "object" }, "SuggestEmbedResponse": { "properties": { "items": { "items": { "$ref": "#/components/schemas/SuggestedEmbed" }, "title": "Items", "type": "array" } }, "required": [ "items" ], "title": "SuggestEmbedResponse", "type": "object" }, "SuggestRequest": { "description": "Input for ``POST /api/v1/extension/suggest``.", "properties": { "og_metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "Open Graph metadata parsed by the popup.", "title": "Og Metadata" }, "plain_text_snippet": { "default": "", "description": "Readability-extracted page text. Capped at 8 KB.", "maxLength": 8192, "title": "Plain Text Snippet", "type": "string" }, "schema_org": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "schema.org JSON-LD parsed by the popup.", "title": "Schema Org" }, "title": { "maxLength": 500, "minLength": 1, "title": "Title", "type": "string" }, "trace_id": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "title": "Trace Id" }, "url": { "maxLength": 2048, "minLength": 1, "title": "Url", "type": "string" } }, "required": [ "url", "title" ], "title": "SuggestRequest", "type": "object" }, "SuggestResponse": { "properties": { "cache_hit": { "title": "Cache Hit", "type": "boolean" }, "entities": { "items": { "$ref": "#/components/schemas/SuggestedEntity" }, "title": "Entities", "type": "array" }, "facets": { "items": { "$ref": "#/components/schemas/SuggestedFacet" }, "title": "Facets", "type": "array" }, "model_tier": { "title": "Model Tier", "type": "string" }, "tags": { "items": { "$ref": "#/components/schemas/SuggestedTag" }, "title": "Tags", "type": "array" }, "trace_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Trace Id" } }, "required": [ "facets", "tags", "entities", "cache_hit", "model_tier" ], "title": "SuggestResponse", "type": "object" }, "SuggestSubjectResponse": { "properties": { "email_id": { "format": "uuid", "title": "Email Id", "type": "string" }, "original_subject": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Original Subject" }, "suggested_subject": { "title": "Suggested Subject", "type": "string" } }, "required": [ "email_id", "suggested_subject", "original_subject" ], "title": "SuggestSubjectResponse", "type": "object" }, "SuggestedEmbed": { "properties": { "embed_facet_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Embed Facet Id" }, "embed_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Embed Type" }, "event_id": { "title": "Event Id", "type": "string" }, "room_id": { "title": "Room Id", "type": "string" }, "score": { "title": "Score", "type": "number" }, "snippet": { "title": "Snippet", "type": "string" } }, "required": [ "event_id", "room_id", "snippet", "score" ], "title": "SuggestedEmbed", "type": "object" }, "SuggestedEntity": { "properties": { "display_name": { "default": "", "title": "Display Name", "type": "string" }, "id": { "title": "Id", "type": "string" }, "score": { "maximum": 1.0, "minimum": 0.0, "title": "Score", "type": "number" }, "type": { "enum": [ "contact", "project" ], "title": "Type", "type": "string" }, "why": { "default": "", "maxLength": 200, "title": "Why", "type": "string" } }, "required": [ "type", "id", "score" ], "title": "SuggestedEntity", "type": "object" }, "SuggestedFacet": { "properties": { "score": { "maximum": 1.0, "minimum": 0.0, "title": "Score", "type": "number" }, "slug": { "title": "Slug", "type": "string" }, "why": { "default": "", "maxLength": 200, "title": "Why", "type": "string" } }, "required": [ "slug", "score" ], "title": "SuggestedFacet", "type": "object" }, "SuggestedTag": { "properties": { "name": { "default": "", "title": "Name", "type": "string" }, "score": { "maximum": 1.0, "minimum": 0.0, "title": "Score", "type": "number" }, "slug": { "title": "Slug", "type": "string" } }, "required": [ "slug", "score" ], "title": "SuggestedTag", "type": "object" }, "SuggestionDismissalCreate": { "description": "Input for POST /organizations/{id}/contact-suggestions/dismissals.", "properties": { "match_key": { "description": "Opaque suggestion identity computed by the client — contact: or sender:", "maxLength": 400, "minLength": 1, "title": "Match Key", "type": "string" } }, "required": [ "match_key" ], "title": "SuggestionDismissalCreate", "type": "object" }, "SuggestionDismissalResponse": { "description": "One dismissal row (member-private).", "properties": { "created_at": { "description": "Dismissal timestamp", "format": "date-time", "title": "Created At", "type": "string" }, "id": { "description": "Dismissal row id (UUID)", "title": "Id", "type": "string" }, "match_key": { "description": "Opaque suggestion identity", "title": "Match Key", "type": "string" }, "organization_id": { "description": "Organization the dismissed suggestion belongs to", "examples": [ "O-550e8400-e29b-41d4-a716-446655440000" ], "pattern": "^O-[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "title": "OrganizationId", "type": "string", "x-tidy-typed-id-prefix": "O", "x-tidy-typed-id-table": "organizations" } }, "required": [ "id", "organization_id", "match_key", "created_at" ], "title": "SuggestionDismissalResponse", "type": "object" }, "SuggestionLinkProbe": { "description": "Input for POST /organizations/{id}/contact-suggestions/linked.", "properties": { "addresses": { "description": "Candidate email addresses; compared case-insensitively", "items": { "type": "string" }, "maxItems": 500, "title": "Addresses", "type": "array" }, "contact_ids": { "description": "Candidate contact ids (typed 'C-' or bare UUID)", "items": { "type": "string" }, "maxItems": 500, "title": "Contact Ids", "type": "array" } }, "title": "SuggestionLinkProbe", "type": "object" }, "SuggestionLinkProbeResponse": { "description": "The submitted candidates that are already linked to the organization.\n\nStrictly a subset of the request: the response never names a contact, an\nid, or an address the caller did not already send.", "properties": { "linked_addresses": { "description": "Submitted addresses (lowercased) carried by a contact that already has a membership row", "items": { "type": "string" }, "title": "Linked Addresses", "type": "array" }, "linked_contact_ids": { "description": "Submitted contact ids that already have a membership row", "items": { "type": "string" }, "title": "Linked Contact Ids", "type": "array" } }, "required": [ "linked_contact_ids", "linked_addresses" ], "title": "SuggestionLinkProbeResponse", "type": "object" }, "SuggestionResponse": { "properties": { "created_at": { "title": "Created At", "type": "string" }, "evidence": { "additionalProperties": true, "title": "Evidence", "type": "object" }, "freshness": { "title": "Freshness", "type": "string" }, "id": { "title": "Id", "type": "string" }, "match_key": { "title": "Match Key", "type": "string" }, "proposed_rule": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Proposed Rule" }, "status": { "title": "Status", "type": "string" }, "suggestion_type": { "title": "Suggestion Type", "type": "string" } }, "required": [ "id", "suggestion_type", "match_key", "proposed_rule", "evidence", "status", "freshness", "created_at" ], "title": "SuggestionResponse", "type": "object" }, "SummarizeRequest": { "properties": { "range": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": "last_visit", "title": "Range" }, "since_ts": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Since Ts" }, "until_ts": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Until Ts" } }, "title": "SummarizeRequest", "type": "object" }, "SummarizeTextRequest": { "description": "Request to summarize text via AI.", "properties": { "text": { "description": "Text to summarize", "maxLength": 50000, "minLength": 1, "title": "Text", "type": "string" } }, "required": [ "text" ], "title": "SummarizeTextRequest", "type": "object" }, "SummarizeTextResponse": { "description": "Response from AI text summarization.", "properties": { "summary": { "title": "Summary", "type": "string" } }, "required": [ "summary" ], "title": "SummarizeTextResponse", "type": "object" }, "SupportOverrideCreate": { "description": "Input model for creating support overrides.\n\nUsed in:\n - POST /api/v1/support-overrides (tenant owner grants access)", "example": { "duration_minutes": 60, "reason": "Need help troubleshooting email sync issues", "scope": [ "view_data", "manage_connections" ] }, "properties": { "duration_minutes": { "default": 60, "description": "Duration in minutes (15-480)", "maximum": 480.0, "minimum": 15.0, "title": "Duration Minutes", "type": "integer" }, "reason": { "description": "Reason for granting support access", "maxLength": 500, "minLength": 10, "title": "Reason", "type": "string" }, "scope": { "default": [ "view_data" ], "description": "Actions to allow", "items": { "$ref": "#/components/schemas/OverrideScope" }, "title": "Scope", "type": "array" }, "support_account_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Specific admin to grant access to (optional, defaults to any admin)", "title": "Support Account Id" } }, "required": [ "reason" ], "title": "SupportOverrideCreate", "type": "object" }, "SupportOverrideResponse": { "description": "Complete support override object returned by API endpoints.\n\nUsed in:\n - GET /api/v1/support-overrides (list, for tenant owner)\n - GET /api/v1/support-overrides/{id} (detail)\n - POST /api/v1/support-overrides (created response, 201)", "properties": { "access_count": { "default": 0, "description": "Number of times support accessed", "title": "Access Count", "type": "integer" }, "created_at": { "description": "ISO 8601 creation timestamp", "format": "date-time", "title": "Created At", "type": "string" }, "duration_minutes": { "default": 60, "description": "Duration in minutes", "title": "Duration Minutes", "type": "integer" }, "expires_at": { "description": "When access expires", "format": "date-time", "title": "Expires At", "type": "string" }, "granted_at": { "description": "When access was granted", "format": "date-time", "title": "Granted At", "type": "string" }, "granting_account_id": { "description": "Account that granted access (UUID)", "title": "Granting Account Id", "type": "string" }, "id": { "description": "Unique override identifier (UUID)", "title": "Id", "type": "string" }, "last_access_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "description": "Last access timestamp", "title": "Last Access At" }, "reason": { "description": "User-provided reason for granting access", "title": "Reason", "type": "string" }, "revoked_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "description": "When access was revoked", "title": "Revoked At" }, "revoked_by": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Who revoked access (UUID)", "title": "Revoked By" }, "scope": { "default": [ "view_data" ], "description": "Allowed actions", "items": { "$ref": "#/components/schemas/OverrideScope" }, "title": "Scope", "type": "array" }, "status": { "$ref": "#/components/schemas/OverrideStatus", "default": "active", "description": "Override status" }, "support_account_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Specific admin with access (UUID), or NULL for any admin", "title": "Support Account Id" }, "tenant_id": { "description": "Associated tenant identifier (UUID)", "title": "Tenant Id", "type": "string" }, "updated_at": { "description": "ISO 8601 last modification timestamp", "format": "date-time", "title": "Updated At", "type": "string" } }, "required": [ "id", "tenant_id", "granting_account_id", "reason", "granted_at", "expires_at", "created_at", "updated_at" ], "title": "SupportOverrideResponse", "type": "object" }, "SupportOverridesListResponse": { "description": "Response for support overrides list.", "properties": { "overrides": { "items": { "$ref": "#/components/schemas/SupportOverrideResponse" }, "title": "Overrides", "type": "array" }, "total": { "title": "Total", "type": "integer" } }, "required": [ "overrides", "total" ], "title": "SupportOverridesListResponse", "type": "object" }, "SuppressRequest": { "properties": { "kind": { "enum": [ "less_like_this", "dont_do_again" ], "title": "Kind", "type": "string" }, "run_id": { "format": "uuid", "title": "Run Id", "type": "string" } }, "required": [ "run_id", "kind" ], "title": "SuppressRequest", "type": "object" }, "SuppressionCheckResponse": { "properties": { "consent_state": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "The visible lead's consent_state (subscribed | unsubscribed | never_subscribed); null when no lead the caller can see carries this address.", "title": "Consent State" }, "email": { "description": "The checked address, normalized.", "title": "Email", "type": "string" }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Why the address is suppressed (unsubscribe | bounce | complaint | manual | forget_me), when it is.", "title": "Reason" }, "suppressed": { "title": "Suppressed", "type": "boolean" } }, "required": [ "email", "suppressed" ], "title": "SuppressionCheckResponse", "type": "object" }, "SuppressionCreateRequest": { "description": "Mute a scope outright, with no proposal in hand.\n\nThe scope is always EXPLICIT: muting ``dave@acme.com`` never mutes\n``acme.com``, and muting ``acme.com`` never mutes anything else.", "properties": { "expires_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "Optional lapse time — the mute stops applying on its own after it.", "title": "Expires At" }, "reason": { "anyOf": [ { "maxLength": 500, "type": "string" }, { "type": "null" } ], "title": "Reason" }, "scope_kind": { "description": "Explicit scope — muting an address never mutes its domain.", "enum": [ "address", "domain", "pattern" ], "title": "Scope Kind", "type": "string" }, "scope_value": { "description": "Address, domain, or a glob over the normalized address (e.g. '*@*.acme.com').", "maxLength": 320, "title": "Scope Value", "type": "string" } }, "required": [ "scope_kind", "scope_value" ], "title": "SuppressionCreateRequest", "type": "object" }, "SuppressionEntry": { "properties": { "attenuation_factor": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "title": "Attenuation Factor" }, "category": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Category" }, "category_label": { "title": "Category Label", "type": "string" }, "created_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Created At" }, "id": { "format": "uuid", "title": "Id", "type": "string" }, "kind": { "title": "Kind", "type": "string" }, "own": { "default": true, "title": "Own", "type": "boolean" }, "renewed_consent_rationale": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Renewed Consent Rationale" }, "renewed_consent_requested": { "default": false, "title": "Renewed Consent Requested", "type": "boolean" } }, "required": [ "id", "kind", "category_label" ], "title": "SuppressionEntry", "type": "object" }, "SuppressionListResponse": { "properties": { "suppressions": { "items": { "$ref": "#/components/schemas/SuppressionRecordModel" }, "title": "Suppressions", "type": "array" }, "total": { "title": "Total", "type": "integer" } }, "required": [ "suppressions", "total" ], "title": "SuppressionListResponse", "type": "object" }, "SuppressionOut": { "properties": { "account_id": { "format": "uuid", "title": "Account Id", "type": "string" }, "reason": { "title": "Reason", "type": "string" } }, "required": [ "account_id", "reason" ], "title": "SuppressionOut", "type": "object" }, "SuppressionRecordModel": { "description": "One member-owned mute. Bounded scope fields only — never message content.", "properties": { "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "expires_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Expires At" }, "is_active": { "title": "Is Active", "type": "boolean" }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Reason" }, "reversed_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Reversed At" }, "scope_kind": { "title": "Scope Kind", "type": "string" }, "scope_value": { "title": "Scope Value", "type": "string" }, "source_proposal_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Source Proposal Id" }, "suppression_id": { "title": "Suppression Id", "type": "string" }, "updated_at": { "format": "date-time", "title": "Updated At", "type": "string" } }, "required": [ "suppression_id", "scope_kind", "scope_value", "reason", "source_proposal_id", "is_active", "expires_at", "reversed_at", "created_at", "updated_at" ], "title": "SuppressionRecordModel", "type": "object" }, "SuppressionReleaseResponse": { "properties": { "released": { "title": "Released", "type": "boolean" }, "scope_kind": { "title": "Scope Kind", "type": "string" }, "scope_value": { "title": "Scope Value", "type": "string" }, "suppression_id": { "title": "Suppression Id", "type": "string" } }, "required": [ "suppression_id", "scope_kind", "scope_value", "released" ], "title": "SuppressionReleaseResponse", "type": "object" }, "SuppressionRevokeResponse": { "properties": { "revoked": { "title": "Revoked", "type": "boolean" } }, "required": [ "revoked" ], "title": "SuppressionRevokeResponse", "type": "object" }, "SwitchEnablement": { "properties": { "denominator": { "title": "Denominator", "type": "integer" }, "denominator_kind": { "enum": [ "cohort", "active_tenants" ], "title": "Denominator Kind", "type": "string" }, "enabled_count": { "title": "Enabled Count", "type": "integer" } }, "required": [ "denominator_kind", "denominator", "enabled_count" ], "title": "SwitchEnablement", "type": "object" }, "SyncBatchRequest": { "description": "Batch payload from the local-first connector.", "properties": { "envelope_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Envelope Id" }, "operations": { "items": { "$ref": "#/components/schemas/SyncOperation" }, "maxItems": 1000, "minItems": 1, "title": "Operations", "type": "array" } }, "required": [ "operations" ], "title": "SyncBatchRequest", "type": "object" }, "SyncBatchResponse": { "description": "Batch processing summary + per-op results.", "properties": { "ignored": { "title": "Ignored", "type": "integer" }, "processed": { "title": "Processed", "type": "integer" }, "results": { "items": { "$ref": "#/components/schemas/SyncOpResult" }, "title": "Results", "type": "array" }, "total": { "title": "Total", "type": "integer" } }, "required": [ "total", "processed", "ignored" ], "title": "SyncBatchResponse", "type": "object" }, "SyncCredential": { "properties": { "expires_at": { "description": "When PowerSync stops accepting it", "format": "date-time", "title": "Expires At", "type": "string" }, "token": { "description": "PowerSync bearer (aud urn:tidy:powersync); every REST route refuses it", "title": "Token", "type": "string" } }, "required": [ "token", "expires_at" ], "title": "SyncCredential", "type": "object" }, "SyncOpResult": { "description": "Per-operation outcome (TIDY-11627 / F1-S3).\n\n`status` is the HTTP-equivalent status for the op: 2xx = applied (or\nintentionally ignored), 4xx/5xx = failed. The connector (F1-S2) classifies\neach: success commits, retryable (401/429/5xx) re-attempts, permanent 4xx /\nbounded-409 dead-letters. The server NEVER converts a failure to a silent\n200 — every non-success op carries its real status here.", "properties": { "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error" }, "index": { "title": "Index", "type": "integer" }, "outcome": { "anyOf": [ { "enum": [ "refused", "uncertain" ], "type": "string" }, { "type": "null" } ], "description": "Failed-op write certainty: refused proves no write; uncertain may have written. Missing is not proof of refusal.", "title": "Outcome" }, "refusal_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Refusal Id" }, "status": { "title": "Status", "type": "integer" } }, "required": [ "index", "status" ], "title": "SyncOpResult", "type": "object" }, "SyncOperation": { "description": "Single PowerSync CRUD operation.", "properties": { "id": { "title": "Id", "type": "string" }, "op": { "title": "Op", "type": "string" }, "opData": { "additionalProperties": true, "title": "Opdata", "type": "object" }, "origin_envelope_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Origin Envelope Id" }, "origin_index": { "anyOf": [ { "minimum": 0.0, "type": "integer" }, { "type": "null" } ], "title": "Origin Index" }, "table": { "title": "Table", "type": "string" } }, "required": [ "table", "id", "op" ], "title": "SyncOperation", "type": "object" }, "SyncPhaseStatus": { "description": "Status of a single sync phase.", "properties": { "completed": { "default": 0, "title": "Completed", "type": "integer" }, "status": { "title": "Status", "type": "string" }, "total": { "default": 0, "title": "Total", "type": "integer" } }, "required": [ "status" ], "title": "SyncPhaseStatus", "type": "object" }, "SyncRefusalListResponse": { "properties": { "refusals": { "items": { "$ref": "#/components/schemas/SyncRefusalResponse" }, "title": "Refusals", "type": "array" } }, "title": "SyncRefusalListResponse", "type": "object" }, "SyncRefusalResponse": { "description": "One refused upload op, as recorded for the member who made it (TIDY-19351).\n\nSafe identifiers and the server's sentence only — never the op's payload or\nthe rejected value; the refusing device keeps the edit itself.", "properties": { "attempts": { "title": "Attempts", "type": "integer" }, "constraint_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Constraint Name" }, "envelope_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "default": null, "title": "Envelope Id" }, "error_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Error Code" }, "first_seen_at": { "format": "date-time", "title": "First Seen At", "type": "string" }, "id": { "format": "uuid", "title": "Id", "type": "string" }, "last_seen_at": { "format": "date-time", "title": "Last Seen At", "type": "string" }, "op_index": { "title": "Op Index", "type": "integer" }, "op_table": { "title": "Op Table", "type": "string" }, "op_type": { "title": "Op Type", "type": "string" }, "reason": { "title": "Reason", "type": "string" }, "row_id": { "title": "Row Id", "type": "string" }, "status_code": { "title": "Status Code", "type": "integer" } }, "required": [ "id", "op_index", "op_table", "op_type", "row_id", "status_code", "reason", "attempts", "first_seen_at", "last_seen_at" ], "title": "SyncRefusalResponse", "type": "object" }, "SyncRequest": { "description": "Trigger a sync for a provider connection.", "properties": { "sync_type": { "default": "all", "description": "What to sync: all, email, calendar", "title": "Sync Type", "type": "string" } }, "title": "SyncRequest", "type": "object" }, "SyncResponse": { "description": "Sync result summary.", "properties": { "connection_id": { "title": "Connection Id", "type": "string" }, "message": { "title": "Message", "type": "string" }, "success": { "title": "Success", "type": "boolean" }, "sync_type": { "title": "Sync Type", "type": "string" } }, "required": [ "connection_id", "sync_type", "success", "message" ], "title": "SyncResponse", "type": "object" }, "SyncSourceStatus": { "description": "Status for a single sync source.", "properties": { "contacts_synced": { "default": 0, "title": "Contacts Synced", "type": "integer" }, "enabled": { "default": false, "title": "Enabled", "type": "boolean" }, "last_sync_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Sync At" } }, "title": "SyncSourceStatus", "type": "object" }, "SynthesizeCardResponse": { "description": "Response from card synthesis.", "properties": { "card": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "Updated card with synthesized sections", "title": "Card" }, "cardId": { "description": "ID of the card", "title": "Cardid", "type": "string" }, "message": { "description": "Human-readable status message", "title": "Message", "type": "string" }, "status": { "description": "Processing status after synthesis trigger", "title": "Status", "type": "string" }, "success": { "description": "Whether synthesis was triggered", "title": "Success", "type": "boolean" } }, "required": [ "success", "cardId", "status", "message" ], "title": "SynthesizeCardResponse", "type": "object" }, "SystemEventCatalogEntry": { "description": "One entry of the system-event trigger catalog (TIDY-14802 / S13, R8/D7).\n\nThe sentence builder's \"When something happens in Tidy…\" category is\nsourced from this endpoint so the curated set lives in ONE place (the\nbackend constant) — never hardcoded twice. Entries with ``enabled=false``\nare deliberately WITHHELD events rendered disabled with their rationale\n(the D7 discoverability surface).", "properties": { "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Description" }, "disabled_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Disabled Reason" }, "enabled": { "title": "Enabled", "type": "boolean" }, "event_type": { "title": "Event Type", "type": "string" }, "label": { "title": "Label", "type": "string" } }, "required": [ "event_type", "label", "enabled" ], "title": "SystemEventCatalogEntry", "type": "object" }, "SystemEventTrigger": { "additionalProperties": false, "properties": { "event_type": { "minLength": 1, "title": "Event Type", "type": "string" }, "kind": { "const": "system_event", "title": "Kind", "type": "string" } }, "required": [ "kind", "event_type" ], "title": "SystemEventTrigger", "type": "object" }, "SystemSkillDownloadTicketResponse": { "properties": { "download_command": { "description": "The shell command that installs the skill; replace .", "title": "Download Command", "type": "string" }, "download_expires_at": { "title": "Download Expires At", "type": "string" }, "download_token": { "description": "Send it in the X-Tidy-Download-Token header, never in the URL.", "title": "Download Token", "type": "string" }, "download_url": { "title": "Download Url", "type": "string" }, "message": { "title": "Message", "type": "string" }, "published_version": { "title": "Published Version", "type": "integer" }, "slug": { "title": "Slug", "type": "string" } }, "required": [ "slug", "published_version", "download_url", "download_token", "download_expires_at", "download_command", "message" ], "title": "SystemSkillDownloadTicketResponse", "type": "object" }, "SystemSkillFile": { "properties": { "chars": { "title": "Chars", "type": "integer" }, "content": { "title": "Content", "type": "string" }, "path": { "description": "Where the file goes inside the skill's folder.", "title": "Path", "type": "string" }, "sha256": { "description": "SHA-256 of the file's UTF-8 bytes, hex.", "title": "Sha256", "type": "string" } }, "required": [ "path", "chars", "sha256", "content" ], "title": "SystemSkillFile", "type": "object" }, "SystemSkillResponse": { "properties": { "description": { "title": "Description", "type": "string" }, "files": { "description": "SKILL.md first, then the rest sorted.", "items": { "$ref": "#/components/schemas/SystemSkillFile" }, "title": "Files", "type": "array" }, "installed_by_workshop": { "description": "The caller is a workshop employee, whose workshop installs and updates its skills: no download address is handed out.", "title": "Installed By Workshop", "type": "boolean" }, "name": { "title": "Name", "type": "string" }, "published_version": { "description": "The published version every file comes from.", "title": "Published Version", "type": "integer" }, "slug": { "title": "Slug", "type": "string" } }, "required": [ "slug", "name", "description", "published_version", "files", "installed_by_workshop" ], "title": "SystemSkillResponse", "type": "object" }, "SystemSkillSummary": { "properties": { "description": { "title": "Description", "type": "string" }, "name": { "title": "Name", "type": "string" }, "published_version": { "description": "The published version every file comes from.", "title": "Published Version", "type": "integer" }, "slug": { "title": "Slug", "type": "string" } }, "required": [ "slug", "name", "description", "published_version" ], "title": "SystemSkillSummary", "type": "object" }, "TabOkResponse": { "properties": { "ok": { "default": true, "title": "Ok", "type": "boolean" } }, "title": "TabOkResponse", "type": "object" }, "TabResponse": { "properties": { "id": { "title": "Id", "type": "string" }, "kind": { "title": "Kind", "type": "string" }, "note_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Note Id" }, "position": { "title": "Position", "type": "integer" }, "room_id": { "title": "Room Id", "type": "string" }, "title": { "title": "Title", "type": "string" } }, "required": [ "id", "room_id", "note_id", "kind", "title", "position" ], "title": "TabResponse", "type": "object" }, "TableSummary": { "description": "A workbook table and its CURRENT rectangle — the extent a chart over it\nwould draw today, which grows as rows are appended inside the table.", "properties": { "name": { "title": "Name", "type": "string" }, "range": { "title": "Range", "type": "string" }, "sheet": { "title": "Sheet", "type": "string" } }, "required": [ "name", "sheet", "range" ], "title": "TableSummary", "type": "object" }, "TagAssignmentCreateRequest": { "description": "POST /api/v1/tag-assignments request body.", "properties": { "primitive_id": { "format": "uuid", "title": "Primitive Id", "type": "string" }, "primitive_type": { "enum": [ "note", "journal", "activity", "photo", "calendar_event", "contact", "file", "organization", "record" ], "title": "Primitive Type", "type": "string" }, "tag_slug": { "maxLength": 64, "minLength": 1, "pattern": "^[a-z0-9][a-z0-9-]*(/[a-z0-9][a-z0-9-]*)*$", "title": "Tag Slug", "type": "string" } }, "required": [ "primitive_type", "primitive_id", "tag_slug" ], "title": "TagAssignmentCreateRequest", "type": "object" }, "TagAssignmentCreateResponse": { "description": "POST /api/v1/tag-assignments response.", "properties": { "changed": { "title": "Changed", "type": "boolean" }, "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "id": { "title": "Id", "type": "string" }, "primitive_id": { "title": "Primitive Id", "type": "string" }, "primitive_type": { "enum": [ "note", "journal", "activity", "photo", "calendar_event", "contact", "file", "organization", "record" ], "title": "Primitive Type", "type": "string" }, "provenance_status": { "title": "Provenance Status", "type": "string" }, "tag_slug": { "title": "Tag Slug", "type": "string" }, "trigger_style": { "title": "Trigger Style", "type": "string" }, "updated_at": { "format": "date-time", "title": "Updated At", "type": "string" } }, "required": [ "id", "primitive_type", "primitive_id", "tag_slug", "provenance_status", "trigger_style", "created_at", "updated_at", "changed" ], "title": "TagAssignmentCreateResponse", "type": "object" }, "TagAssignmentListResponse": { "description": "GET /api/v1/tags/{slug}/assignments envelope.", "properties": { "assignments": { "items": { "$ref": "#/components/schemas/TagAssignmentResponse" }, "title": "Assignments", "type": "array" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Next Cursor" }, "total": { "title": "Total", "type": "integer" } }, "required": [ "assignments", "total" ], "title": "TagAssignmentListResponse", "type": "object" }, "TagAssignmentResponse": { "description": "One row of the GET /api/v1/tags/{slug}/assignments response.\n\nFields:\n id: tag_assignments.id\n primitive_type: one of {note, journal, email, contact,\n calendar_event, activity, project}\n primitive_id: foreign key into the corresponding primitive table\n tag_slug: lowercase, dash-separated slug\n source_block_id: UUID of the block where the mention was found,\n or ``None`` for legacy_container rows that predate block-level\n provenance.\n source_block_excerpt: ~200-char snippet centered on the mention.\n trigger_style: 'hash' for v1 mentions; 'none' for legacy backfilled\n rows.\n provenance_status: 'precise' (block-level) or 'legacy_container'\n (no block context).\n primitive_title: resolved from the source primitive table — falls\n back to a sensible default ('Untitled', '(no subject)', etc.)\n when the source row has no display field.\n primitive_subtitle: secondary line useful for the timeline UI —\n e.g. note_type ('standalone_page', 'journal_page', 'drawing'),\n 'event' for calendar_events, 'task'/'activity' for activities.\n primitive_date: For ``primitive_type='journal'`` only — the\n ``feed_target_date`` of the source journal page (YYYY-MM-DD).\n Lets clients build navigation URLs like\n ``/notes?date=2026-04-26`` without a separate UUID→date lookup.\n ``None`` for every other primitive type.\n updated_at: when the assignment row was last updated.", "properties": { "id": { "title": "Id", "type": "string" }, "primitive_date": { "anyOf": [ { "format": "date", "type": "string" }, { "type": "null" } ], "default": null, "title": "Primitive Date" }, "primitive_id": { "title": "Primitive Id", "type": "string" }, "primitive_subtitle": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Primitive Subtitle" }, "primitive_title": { "title": "Primitive Title", "type": "string" }, "primitive_type": { "title": "Primitive Type", "type": "string" }, "provenance_status": { "title": "Provenance Status", "type": "string" }, "source_block_excerpt": { "title": "Source Block Excerpt", "type": "string" }, "source_block_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Source Block Id" }, "tag_slug": { "title": "Tag Slug", "type": "string" }, "trigger_style": { "title": "Trigger Style", "type": "string" }, "updated_at": { "format": "date-time", "title": "Updated At", "type": "string" } }, "required": [ "id", "primitive_type", "primitive_id", "tag_slug", "source_block_excerpt", "trigger_style", "provenance_status", "primitive_title", "updated_at" ], "title": "TagAssignmentResponse", "type": "object" }, "TagCreate": { "properties": { "color": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Color" }, "description": { "anyOf": [ { "maxLength": 2000, "type": "string" }, { "type": "null" } ], "title": "Description" }, "icon": { "anyOf": [ { "maxLength": 512, "type": "string" }, { "type": "null" } ], "title": "Icon" }, "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Client-provided UUID", "title": "Id" }, "name": { "maxLength": 255, "minLength": 1, "title": "Name", "type": "string" }, "note_page_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Note Page Id" }, "view_config": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "View Config" } }, "required": [ "name" ], "title": "TagCreate", "type": "object" }, "TagListItem": { "description": "A single tag definition row as returned by ``GET /api/v1/tags/``.\n\nThe shape mirrors the SQL projection in :func:`list_tags`. ``view_config``\nis the raw JSON-encoded string as stored in the ``jsonb`` column (asyncpg\nhas no global JSONB codec, so callers parse it client-side).", "properties": { "color": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Color" }, "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Description" }, "icon": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Icon" }, "id": { "format": "uuid", "title": "Id", "type": "string" }, "is_system": { "title": "Is System", "type": "boolean" }, "name": { "title": "Name", "type": "string" }, "note_page_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "default": null, "title": "Note Page Id" }, "slug": { "title": "Slug", "type": "string" }, "tenant_id": { "format": "uuid", "title": "Tenant Id", "type": "string" }, "updated_at": { "format": "date-time", "title": "Updated At", "type": "string" }, "usage_count": { "title": "Usage Count", "type": "integer" }, "view_config": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "View Config" } }, "required": [ "id", "tenant_id", "name", "slug", "is_system", "created_at", "updated_at", "usage_count" ], "title": "TagListItem", "type": "object" }, "TagRename": { "properties": { "name": { "maxLength": 255, "minLength": 1, "title": "Name", "type": "string" } }, "required": [ "name" ], "title": "TagRename", "type": "object" }, "TagSettingsPatch": { "properties": { "ai_may_mint_tags": { "title": "Ai May Mint Tags", "type": "boolean" } }, "required": [ "ai_may_mint_tags" ], "title": "TagSettingsPatch", "type": "object" }, "TagSettingsResponse": { "properties": { "ai_may_mint_tags": { "default": false, "title": "Ai May Mint Tags", "type": "boolean" } }, "title": "TagSettingsResponse", "type": "object" }, "TagUpdate": { "properties": { "color": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Color" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "icon": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Icon" }, "name": { "anyOf": [ { "maxLength": 255, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Name" }, "note_page_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Note Page Id" }, "view_config": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "View Config" } }, "title": "TagUpdate", "type": "object" }, "TargetShipping": { "description": "Stage 3 — delivery-ledger state for ONE target env (qa / dev1 / dev2).", "properties": { "accepted_schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Accepted Schema" }, "contract_drift": { "default": false, "title": "Contract Drift", "type": "boolean" }, "delivered": { "default": 0, "title": "Delivered", "type": "integer" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Error" }, "failed": { "default": 0, "title": "Failed", "type": "integer" }, "failed_last_error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Failed Last Error" }, "last_delivered_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Last Delivered At" }, "pending": { "default": 0, "title": "Pending", "type": "integer" } }, "title": "TargetShipping", "type": "object" }, "TaskAttachmentUploadRegisterRequest": { "description": "Request payload for POST /tasks/{id}/attachments/upload.\n\nFollows the presigned-URL pattern: the client first obtains a presigned\nupload URL from /api/v1/files/upload-url (or similar), uploads bytes\ndirectly to storage, then calls this endpoint with the resulting\nstorage_path + file metadata to register the attachment.", "properties": { "attachment_type": { "default": "document", "enum": [ "document", "snippet", "link", "email", "image" ], "title": "Attachment Type", "type": "string" }, "content": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Inline content for 'snippet' attachments", "title": "Content" }, "content_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Content Type" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "email_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Source email UUID for 'email' attachments", "title": "Email Id" }, "file_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "File Name" }, "file_size": { "anyOf": [ { "minimum": 0.0, "type": "integer" }, { "type": "null" } ], "title": "File Size" }, "storage_path": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Object storage path returned from presigned upload", "title": "Storage Path" }, "title": { "maxLength": 500, "minLength": 1, "title": "Title", "type": "string" }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "External URL for 'link' attachments", "title": "Url" } }, "required": [ "title" ], "title": "TaskAttachmentUploadRegisterRequest", "type": "object" }, "TaskBatchCreateRequest": { "additionalProperties": false, "properties": { "default_project_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "`P-` applied to rows that carry no project_id.", "title": "Default Project Id" }, "rows": { "items": { "$ref": "#/components/schemas/TaskBatchRow" }, "maxItems": 50, "minItems": 1, "title": "Rows", "type": "array" } }, "required": [ "rows" ], "title": "TaskBatchCreateRequest", "type": "object" }, "TaskBatchCreateResponse": { "properties": { "results": { "items": { "$ref": "#/components/schemas/TaskBatchResult" }, "title": "Results", "type": "array" } }, "required": [ "results" ], "title": "TaskBatchCreateResponse", "type": "object" }, "TaskBatchResult": { "properties": { "action": { "enum": [ "created", "updated", "unchanged", "rejected" ], "title": "Action", "type": "string" }, "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Typed activity id (`A-`); null when rejected.", "title": "Id" }, "issues": { "items": { "additionalProperties": true, "type": "object" }, "title": "Issues", "type": "array" }, "source_ref": { "title": "Source Ref", "type": "string" } }, "required": [ "source_ref", "action" ], "title": "TaskBatchResult", "type": "object" }, "TaskBatchRow": { "additionalProperties": false, "description": "One task to create or update, identified by ``source_ref``.", "properties": { "assignee": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Assignee" }, "category": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Category" }, "due_date": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Date-only YYYY-MM-DD.", "title": "Due Date" }, "due_datetime": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO 8601 UTC datetime (YYYY-MM-DDTHH:MM:SS.sssZ).", "title": "Due Datetime" }, "execution": { "anyOf": [ { "$ref": "#/components/schemas/TaskExecution" }, { "type": "null" } ] }, "parent_activity_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "`A-` parent — alternative to parent_source_ref.", "title": "Parent Activity Id" }, "parent_source_ref": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Parent identified by its source_ref. Resolves within the same call (order-independent) or against previously imported rows.", "title": "Parent Source Ref" }, "plain_text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Plain Text" }, "priority": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Priority" }, "project_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "`P-` — overrides `default_project_id`.", "title": "Project Id" }, "source_ref": { "description": "Caller-stable identity for this task (e.g. `yt:TIDY-16234`). Re-posting the same source_ref updates the same row.", "maxLength": 200, "minLength": 1, "title": "Source Ref", "type": "string" }, "start_date": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Date-only YYYY-MM-DD.", "title": "Start Date" }, "status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Status" }, "tags": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Tags" }, "title": { "anyOf": [ { "maxLength": 500, "type": "string" }, { "type": "null" } ], "title": "Title" }, "type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Work-item classification validated against the tenant's task facet.", "title": "Type" } }, "required": [ "source_ref" ], "title": "TaskBatchRow", "type": "object" }, "TaskCommentSummary": { "description": "One comment on the compact task read (TIDY-14992 / D18).\n\nDefault by-id task reads carry unresolved comments only; resolved rows\n(with their audit pair) appear when the caller passes include_resolved.", "properties": { "anchor_text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Anchor Text" }, "author_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Author Id" }, "author_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Author Name" }, "created_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Created At" }, "id": { "title": "Id", "type": "string" }, "plain_text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Plain Text" }, "reopened_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Reopened At" }, "reopened_by": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Reopened By" }, "resolved_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Resolved At" }, "resolved_by": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Resolved By" }, "status": { "default": "open", "title": "Status", "type": "string" }, "thread_root_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Thread Root Id" }, "updated_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Updated At" } }, "required": [ "id" ], "title": "TaskCommentSummary", "type": "object" }, "TaskCreateCompat": { "properties": { "assigned_by": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Assigned By" }, "assignee": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Tenant-scoped assignee reference.", "title": "Assignee" }, "assignee_principal_key": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Assignment intent: account UUID or assistant for the built-in employee.", "title": "Assignee Principal Key" }, "category": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Category" }, "confidence_score": { "anyOf": [ { "maximum": 1.0, "minimum": 0.0, "type": "number" }, { "type": "null" } ], "title": "Confidence Score" }, "custom_properties": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Custom Properties" }, "due_date": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Due Date" }, "due_datetime": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Due Datetime" }, "end": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "End" }, "estimated_duration_minutes": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Estimated Duration Minutes" }, "facet_data": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Facet Data" }, "facets": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Facets" }, "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Id" }, "is_recurring": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is Recurring" }, "owner": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Owner" }, "parent_activity_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Parent Activity Id" }, "plain_text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Plain Text" }, "priority": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Priority" }, "project_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Project Id" }, "recurrence_day_of_month": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Recurrence Day Of Month" }, "recurrence_days_of_week": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Recurrence Days Of Week" }, "recurrence_end_date": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Recurrence End Date" }, "recurrence_interval": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Recurrence Interval" }, "recurrence_pattern": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Recurrence Pattern" }, "snoozed_until": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Snoozed Until" }, "source_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Source Id" }, "source_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": "manual", "title": "Source Type" }, "start": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Start" }, "start_date": { "anyOf": [ { "format": "date", "type": "string" }, { "type": "null" } ], "title": "Start Date" }, "status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Status" }, "tags": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Tags" }, "title": { "maxLength": 500, "minLength": 1, "title": "Title", "type": "string" }, "type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Type" }, "visibility": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": "private", "title": "Visibility" } }, "required": [ "title" ], "title": "TaskCreateCompat", "type": "object" }, "TaskDependenciesResponse": { "description": "Response for GET /api/v1/tasks/{task_id}/dependencies.", "properties": { "blocked_by_this": { "description": "Tasks that are blocked by this task", "items": { "$ref": "#/components/schemas/DependencyWithTask" }, "title": "Blocked By This", "type": "array" }, "depends_on": { "description": "Tasks that this task depends on (blockers)", "items": { "$ref": "#/components/schemas/DependencyWithTask" }, "title": "Depends On", "type": "array" } }, "title": "TaskDependenciesResponse", "type": "object" }, "TaskDependencyCreate": { "description": "Request body for POST /api/v1/tasks/{task_id}/dependencies.", "properties": { "dependency_type": { "default": "blocks", "description": "Relationship type (currently only 'blocks')", "pattern": "^(blocks)$", "title": "Dependency Type", "type": "string" }, "depends_on_task_id": { "description": "The task this task depends on — a typed id (`A-`) or a bare UUID.", "title": "Depends On Task Id", "type": "string" } }, "required": [ "depends_on_task_id" ], "title": "TaskDependencyCreate", "type": "object" }, "TaskDependencyResponse": { "description": "Single dependency record returned by the API.", "properties": { "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "dependency_type": { "title": "Dependency Type", "type": "string" }, "depends_on_task_id": { "title": "Depends On Task Id", "type": "string" }, "id": { "title": "Id", "type": "string" }, "task_id": { "title": "Task Id", "type": "string" }, "tenant_id": { "title": "Tenant Id", "type": "string" } }, "required": [ "id", "tenant_id", "task_id", "depends_on_task_id", "dependency_type", "created_at" ], "title": "TaskDependencyResponse", "type": "object" }, "TaskExecution": { "additionalProperties": false, "description": "Optional per-task overrides, independent of the task's container project.", "properties": { "harness": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Harness" }, "model": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Model" }, "project_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Project Id" }, "reasoning_level": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Reasoning Level" } }, "title": "TaskExecution", "type": "object" }, "TaskFromSourceRequest": { "description": "Request payload for POST /tasks/from-source.", "properties": { "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "due_date": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Due Date" }, "due_datetime": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Due Datetime" }, "priority": { "anyOf": [ { "enum": [ "critical", "high", "medium", "low" ], "type": "string" }, { "type": "null" } ], "title": "Priority" }, "project_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Project Id" }, "source_id": { "description": "UUID of the originating resource", "title": "Source Id", "type": "string" }, "source_type": { "description": "Type of the originating resource", "enum": [ "email", "note", "calendar_event", "document" ], "title": "Source Type", "type": "string" }, "title": { "maxLength": 500, "minLength": 1, "title": "Title", "type": "string" } }, "required": [ "source_type", "source_id", "title" ], "title": "TaskFromSourceRequest", "type": "object" }, "TaskHealthResponse": { "properties": { "aging_distribution": { "items": { "$ref": "#/components/schemas/AgingBucket" }, "title": "Aging Distribution", "type": "array" }, "avg_task_age_days": { "title": "Avg Task Age Days", "type": "number" }, "blocked_count": { "title": "Blocked Count", "type": "integer" }, "by_project": { "items": { "$ref": "#/components/schemas/ProjectHealth" }, "title": "By Project", "type": "array" }, "overdue_count": { "title": "Overdue Count", "type": "integer" }, "stale_count": { "title": "Stale Count", "type": "integer" } }, "required": [ "overdue_count", "stale_count", "blocked_count", "avg_task_age_days", "by_project", "aging_distribution" ], "title": "TaskHealthResponse", "type": "object" }, "TaskPeriodComparison": { "properties": { "completed_change_pct": { "title": "Completed Change Pct", "type": "number" }, "created_change_pct": { "title": "Created Change Pct", "type": "number" }, "prev_completed": { "title": "Prev Completed", "type": "integer" }, "prev_created": { "title": "Prev Created", "type": "integer" } }, "required": [ "prev_created", "prev_completed", "created_change_pct", "completed_change_pct" ], "title": "TaskPeriodComparison", "type": "object" }, "TaskReminderCreate": { "description": "Request payload for POST /tasks/{id}/reminders.", "properties": { "delivery_methods": { "default": "push", "description": "Comma-separated: push, sms, email", "title": "Delivery Methods", "type": "string" }, "reminder_date": { "format": "date-time", "title": "Reminder Date", "type": "string" }, "title": { "maxLength": 500, "minLength": 1, "title": "Title", "type": "string" } }, "required": [ "reminder_date", "title" ], "title": "TaskReminderCreate", "type": "object" }, "TaskReminderResponse": { "description": "A single task reminder.", "properties": { "activity_id": { "title": "Activity Id", "type": "string" }, "created_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Created At" }, "delivery_methods": { "title": "Delivery Methods", "type": "string" }, "id": { "title": "Id", "type": "string" }, "reminder_date": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Reminder Date" }, "status": { "title": "Status", "type": "string" }, "title": { "title": "Title", "type": "string" } }, "required": [ "id", "activity_id", "title", "status", "delivery_methods" ], "title": "TaskReminderResponse", "type": "object" }, "TaskRemindersListResponse": { "description": "Response for GET /tasks/{id}/reminders.", "properties": { "reminders": { "items": { "$ref": "#/components/schemas/TaskReminderResponse" }, "title": "Reminders", "type": "array" } }, "title": "TaskRemindersListResponse", "type": "object" }, "TaskScheduleRequest": { "description": "Request payload for POST /tasks/{id}/schedule.", "properties": { "end": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "End" }, "start": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Start" } }, "title": "TaskScheduleRequest", "type": "object" }, "TaskSnoozeRequest": { "description": "Request payload for POST /tasks/{id}/snooze.", "properties": { "duration_minutes": { "anyOf": [ { "maximum": 525600.0, "minimum": 1.0, "type": "integer" }, { "type": "null" } ], "description": "Snooze duration in minutes from now", "title": "Duration Minutes" }, "snoozed_until": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "Timestamp to snooze until (mutually exclusive with duration_minutes)", "title": "Snoozed Until" } }, "title": "TaskSnoozeRequest", "type": "object" }, "TaskSummary": { "description": "Lightweight task info included in dependency listings.", "properties": { "id": { "title": "Id", "type": "string" }, "status": { "title": "Status", "type": "string" }, "title": { "title": "Title", "type": "string" } }, "required": [ "id", "title", "status" ], "title": "TaskSummary", "type": "object" }, "TaskSummaryResponse": { "properties": { "avg_cycle_time_days": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Avg Cycle Time Days" }, "backlog_size": { "title": "Backlog Size", "type": "integer" }, "by_priority": { "additionalProperties": { "type": "integer" }, "title": "By Priority", "type": "object" }, "by_status": { "additionalProperties": { "type": "integer" }, "title": "By Status", "type": "object" }, "completion_rate_pct": { "title": "Completion Rate Pct", "type": "number" }, "period_comparison": { "$ref": "#/components/schemas/TaskPeriodComparison" }, "total_completed": { "title": "Total Completed", "type": "integer" }, "total_created": { "title": "Total Created", "type": "integer" }, "total_overdue": { "title": "Total Overdue", "type": "integer" } }, "required": [ "total_created", "total_completed", "total_overdue", "completion_rate_pct", "avg_cycle_time_days", "backlog_size", "by_status", "by_priority", "period_comparison" ], "title": "TaskSummaryResponse", "type": "object" }, "TaskUpdateCompat": { "properties": { "assigned_agent": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Assigned Agent" }, "assigned_by": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Assigned By" }, "assignee": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Tenant-scoped assignee reference; explicit null clears assignment.", "title": "Assignee" }, "assignee_principal_key": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Account UUID or assistant; explicit null clears the assignment.", "title": "Assignee Principal Key" }, "backlog_rank": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "The item's place in its assignee's manual work order (lower is earlier; null clears it).", "title": "Backlog Rank" }, "base_values": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "Internal-only autosave base values for field conflict detection", "title": "Base Values" }, "category": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Category" }, "confirm_unready": { "anyOf": [ { "maxLength": 500, "type": "string" }, { "type": "null" } ], "description": "An employee starting work that waits on something not done: why it starts anyway (a person asked, or what it waits for already exists). Accepted only after the refusal that names the prerequisites; audited.", "title": "Confirm Unready" }, "container_seq": { "anyOf": [ { "minimum": 0.0, "type": "integer" }, { "type": "null" } ], "title": "Container Seq" }, "custom_properties": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Custom Properties" }, "due_date": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Due Date" }, "due_datetime": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Due Datetime" }, "end": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "End" }, "estimated_duration_minutes": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Estimated Duration Minutes" }, "facet_data": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Facet Data" }, "facets": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Facets" }, "icon": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Icon" }, "is_recurring": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is Recurring" }, "owner": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Owner" }, "parent_activity_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Parent Activity Id" }, "pin": { "anyOf": [ { "enum": [ "next", "last", "none" ], "type": "string" }, { "type": "null" } ], "description": "Reorder this item in its assignee's backlog: 'next' works it first, 'last' sinks it, 'none' clears the pin.", "title": "Pin" }, "plain_text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Plain Text" }, "priority": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Priority" }, "project_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Project Id" }, "recurrence_day_of_month": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Recurrence Day Of Month" }, "recurrence_days_of_week": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Recurrence Days Of Week" }, "recurrence_end_date": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Recurrence End Date" }, "recurrence_interval": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Recurrence Interval" }, "recurrence_pattern": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Recurrence Pattern" }, "score": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Score" }, "score_override": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Manual score override. Set a number to pin the score against recalculation; send null to delete the override and revert to the computed score.", "title": "Score Override" }, "snoozed_until": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Snoozed Until" }, "source_context": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "Internal-only audit/source attribution metadata", "title": "Source Context" }, "start": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Start" }, "start_date": { "anyOf": [ { "format": "date", "type": "string" }, { "type": "null" } ], "title": "Start Date" }, "status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Status" }, "tags": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Tags" }, "title": { "anyOf": [ { "maxLength": 500, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Title" }, "tracked_time_seconds": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Tracked Time Seconds" }, "type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Type" }, "visibility": { "anyOf": [ { "enum": [ "private", "shared", "tenant" ], "type": "string" }, { "type": "null" } ], "title": "Visibility" } }, "title": "TaskUpdateCompat", "type": "object" }, "TaskVelocityPeriod": { "properties": { "avg_cycle_time_days": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Avg Cycle Time Days" }, "completed": { "title": "Completed", "type": "integer" }, "created": { "title": "Created", "type": "integer" }, "net_change": { "title": "Net Change", "type": "integer" }, "on_time_pct": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "On Time Pct" }, "period": { "title": "Period", "type": "string" } }, "required": [ "period", "created", "completed", "net_change", "avg_cycle_time_days", "on_time_pct" ], "title": "TaskVelocityPeriod", "type": "object" }, "TasksInboxBulkRequest": { "properties": { "ids": { "items": { "format": "uuid", "type": "string" }, "title": "Ids", "type": "array" } }, "required": [ "ids" ], "title": "TasksInboxBulkRequest", "type": "object" }, "TasksInboxBulkResponse": { "properties": { "errors": { "items": { "type": "string" }, "title": "Errors", "type": "array" }, "failed": { "title": "Failed", "type": "integer" }, "processed": { "title": "Processed", "type": "integer" } }, "required": [ "processed", "failed" ], "title": "TasksInboxBulkResponse", "type": "object" }, "TeachImportanceRequest": { "description": "Teach Tidy that an email is (or isn't) Important.", "properties": { "surface": { "default": "unknown", "description": "Which reader surface the teach came from", "enum": [ "viewer", "feed_card", "context_menu", "action_menu", "list", "unknown" ], "title": "Surface", "type": "string" }, "target": { "description": "'important' to teach, 'not_important' to un-teach", "enum": [ "important", "not_important" ], "title": "Target", "type": "string" } }, "required": [ "target" ], "title": "TeachImportanceRequest", "type": "object" }, "TeachImportanceResponse": { "description": "The synthesized correction + immediate reclassify outcome.", "properties": { "email_id": { "title": "Email Id", "type": "string" }, "exception_to_rule_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Exception To Rule Id" }, "is_exception": { "default": false, "title": "Is Exception", "type": "boolean" }, "learned_summary": { "title": "Learned Summary", "type": "string" }, "match_dimension": { "title": "Match Dimension", "type": "string" }, "match_value": { "title": "Match Value", "type": "string" }, "new_inbox_split": { "title": "New Inbox Split", "type": "string" }, "prior_inbox_split": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Prior Inbox Split" }, "resolved_suggestion_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Resolved Suggestion Id" }, "rule_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Rule Id" }, "success": { "default": true, "title": "Success", "type": "boolean" }, "target": { "enum": [ "important", "not_important" ], "title": "Target", "type": "string" } }, "required": [ "email_id", "target", "match_dimension", "match_value", "new_inbox_split", "learned_summary" ], "title": "TeachImportanceResponse", "type": "object" }, "TeachImportanceUndoResponse": { "description": "The reversal of the most recent teach for an email.", "properties": { "email_id": { "title": "Email Id", "type": "string" }, "restored_rule_ids": { "default": [], "items": { "type": "string" }, "title": "Restored Rule Ids", "type": "array" }, "reverted_inbox_split": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Reverted Inbox Split" }, "rule_deleted": { "default": false, "title": "Rule Deleted", "type": "boolean" }, "success": { "default": true, "title": "Success", "type": "boolean" }, "suggestion_reopened": { "default": false, "title": "Suggestion Reopened", "type": "boolean" } }, "required": [ "email_id" ], "title": "TeachImportanceUndoResponse", "type": "object" }, "TeachMuteRequest": { "description": "Create a durable mute rule from user-confirmed conditions.", "properties": { "any_of": { "description": "Alternatives of which at least one must also match (two or more)", "items": { "$ref": "#/components/schemas/MatchCondition" }, "title": "Any Of", "type": "array" }, "conditions": { "items": { "$ref": "#/components/schemas/MatchCondition" }, "title": "Conditions", "type": "array" }, "retro_apply": { "default": false, "description": "Also mark existing historical matches Done", "title": "Retro Apply", "type": "boolean" }, "surface": { "default": "context_menu", "description": "Which reader surface the teach came from", "enum": [ "viewer", "feed_card", "context_menu", "action_menu", "list", "unknown" ], "title": "Surface", "type": "string" } }, "required": [ "conditions" ], "title": "TeachMuteRequest", "type": "object" }, "TeachMuteResponse": { "description": "The created mute rule + immediate + retro outcome.", "properties": { "email_id": { "title": "Email Id", "type": "string" }, "learned_summary": { "title": "Learned Summary", "type": "string" }, "match_dimension": { "title": "Match Dimension", "type": "string" }, "match_value": { "title": "Match Value", "type": "string" }, "prior_inbox_split": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Prior Inbox Split" }, "retro_applied_count": { "default": 0, "title": "Retro Applied Count", "type": "integer" }, "rule_id": { "title": "Rule Id", "type": "string" }, "success": { "default": true, "title": "Success", "type": "boolean" } }, "required": [ "email_id", "rule_id", "match_dimension", "match_value", "learned_summary" ], "title": "TeachMuteResponse", "type": "object" }, "TeachMuteUndoResponse": { "description": "The reversal of the most recent teach-mute for an email.", "properties": { "email_id": { "title": "Email Id", "type": "string" }, "retro_restored_count": { "default": 0, "title": "Retro Restored Count", "type": "integer" }, "retro_reverted": { "default": true, "title": "Retro Reverted", "type": "boolean" }, "reverted_inbox_split": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Reverted Inbox Split" }, "rule_deleted": { "default": false, "title": "Rule Deleted", "type": "boolean" }, "success": { "default": true, "title": "Success", "type": "boolean" }, "suggestion_reopened": { "default": false, "title": "Suggestion Reopened", "type": "boolean" } }, "required": [ "email_id" ], "title": "TeachMuteUndoResponse", "type": "object" }, "TeamApprovalKind": { "properties": { "key": { "description": "The kind's stable key.", "title": "Key", "type": "string" }, "label": { "description": "What the toggle is called.", "title": "Label", "type": "string" } }, "required": [ "key", "label" ], "title": "TeamApprovalKind", "type": "object" }, "TeamApprovalListResponse": { "properties": { "approval_authority": { "description": "none | team | team_including_destructive — what your owner allowed: none while no kind is on for any report, team_including_destructive when destructive commands are on for the team.", "title": "Approval Authority", "type": "string" }, "requests": { "description": "Open requests you may answer, oldest first.", "items": { "$ref": "#/components/schemas/TeamApprovalRequest" }, "title": "Requests", "type": "array" }, "waiting_on_people": { "description": "Open requests on your team that a person answers, with why.", "items": { "$ref": "#/components/schemas/TeamApprovalRequest" }, "title": "Waiting On People", "type": "array" } }, "required": [ "approval_authority" ], "title": "TeamApprovalListResponse", "type": "object" }, "TeamApprovalReport": { "properties": { "account_id": { "title": "Account Id", "type": "string" }, "agent_member_id": { "title": "Agent Member Id", "type": "string" }, "display_name": { "title": "Display Name", "type": "string" }, "effective": { "additionalProperties": { "type": "boolean" }, "description": "What the manager decides for this report, by kind.", "title": "TeamApprovalReportEffective", "type": "object" }, "overrides": { "additionalProperties": { "type": "boolean" }, "description": "This report's own toggles, by kind; a kind left out follows the team.", "title": "TeamApprovalReportOverrides", "type": "object" }, "role": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Its role title.", "title": "Role" }, "unavailable": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Set when only the report's owner decides for it, whatever the toggles say, and why (an employee manager answers only within its owner's own authority).", "title": "Unavailable" } }, "required": [ "agent_member_id", "account_id", "display_name", "effective" ], "title": "TeamApprovalReport", "type": "object" }, "TeamApprovalRequest": { "properties": { "detail": { "additionalProperties": true, "description": "What a person is shown to decide: tool_name, display_command, tool_call, cwd, paths, reason, plan, and the policy rule that raised it.", "title": "Detail", "type": "object" }, "employee_account_id": { "title": "Employee Account Id", "type": "string" }, "employee_handle": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Employee Handle" }, "employee_name": { "title": "Employee Name", "type": "string" }, "id": { "description": "The request's id — pass it to the resolve route.", "title": "Id", "type": "string" }, "kind": { "description": "command_execution_approval | file_change_approval | file_read_approval | plan_approval, or (waiting on people) any other request kind", "title": "Kind", "type": "string" }, "opened_at": { "format": "date-time", "title": "Opened At", "type": "string" }, "parked": { "description": "The employee's turn stopped to wait for this answer.", "title": "Parked", "type": "boolean" }, "why": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Waiting-on-people rows only: why a person answers it.", "title": "Why" } }, "required": [ "id", "kind", "employee_account_id", "employee_name", "parked", "opened_at" ], "title": "TeamApprovalRequest", "type": "object" }, "TeamApprovalResolveBody": { "properties": { "decision": { "description": "approve runs the action once; decline refuses it and the employee carries on without it; cancel_turn stops the employee's turn.", "enum": [ "approve", "decline", "cancel_turn" ], "title": "Decision", "type": "string" } }, "required": [ "decision" ], "title": "TeamApprovalResolveBody", "type": "object" }, "TeamApprovalResolveResponse": { "properties": { "decision": { "title": "Decision", "type": "string" }, "id": { "title": "Id", "type": "string" }, "status": { "description": "resolved — the employee has the answer; resume_pending — its host is away and resumes with the answer when it returns.", "title": "Status", "type": "string" } }, "required": [ "id", "decision", "status" ], "title": "TeamApprovalResolveResponse", "type": "object" }, "TeamApprovalSettingsRequest": { "properties": { "reports": { "additionalProperties": { "additionalProperties": { "type": "boolean" }, "type": "object" }, "description": "Per-report overrides keyed by agent_member_id; a kind or a report left out follows the team.", "title": "TeamApprovalOverridesChange", "type": "object" }, "team": { "additionalProperties": { "type": "boolean" }, "description": "The team default, by kind; a kind left out is off.", "title": "TeamApprovalDefaultsChange", "type": "object" } }, "title": "TeamApprovalSettingsRequest", "type": "object" }, "TeamApprovalSettingsResponse": { "properties": { "can_edit": { "description": "True when the caller may change these: for an employee manager its owner or a workspace admin, for a person a workspace admin.", "title": "Can Edit", "type": "boolean" }, "kinds": { "description": "The kinds a manager can be given, in the order to show them.", "items": { "$ref": "#/components/schemas/TeamApprovalKind" }, "title": "Kinds", "type": "array" }, "manager_account_id": { "title": "Manager Account Id", "type": "string" }, "manager_kind": { "enum": [ "person", "employee" ], "title": "Manager Kind", "type": "string" }, "manager_name": { "title": "Manager Name", "type": "string" }, "reports": { "description": "Its direct reports on the team Org chart that are employees.", "items": { "$ref": "#/components/schemas/TeamApprovalReport" }, "title": "Reports", "type": "array" }, "team": { "additionalProperties": { "type": "boolean" }, "description": "The team default, by kind.", "title": "TeamApprovalDefaults", "type": "object" }, "unavailable": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Set when the manager decides nothing for now, and why.", "title": "Unavailable" } }, "required": [ "manager_account_id", "manager_kind", "manager_name", "kinds", "team", "can_edit" ], "title": "TeamApprovalSettingsResponse", "type": "object" }, "TeamConversation": { "properties": { "conversation_id": { "title": "Conversation Id", "type": "string" }, "conversation_ref": { "description": "`H-` — when `steerable`, steer with `message_employee(conversation_ref=...)`.", "title": "Conversation Ref", "type": "string" }, "employee": { "title": "Employee", "type": "string" }, "employee_display_name": { "title": "Employee Display Name", "type": "string" }, "items": { "items": { "$ref": "#/components/schemas/TeamConversationItem" }, "title": "Items", "type": "array" }, "last_activity_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Last Activity At" }, "relation": { "description": "The employee to you: `manager`, `direct_report`, `peer` (under the same manager), `self` (another of your own conversations), `hand_off` (it works a task you handed out, or one handed on under it) or `your_employee`.", "title": "Relation", "type": "string" }, "room_session": { "default": false, "description": "True when a room reads this conversation: a steer into it is read there too.", "title": "Room Session", "type": "boolean" }, "status": { "description": "Where its work stands, as `fetch(H-...)` reports it: `working`, `needs_attention` (waiting on someone), `waiting` (a message not started yet), `answered`, `failed`, `idle`.", "title": "Status", "type": "string" }, "steerable": { "default": false, "description": "May write into this conversation: the person the caller works for owns it or is currently a member of its room. False for a read-only share.", "title": "Steerable", "type": "boolean" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Title" }, "turn_started_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Turn Started At" } }, "required": [ "conversation_ref", "conversation_id", "employee", "employee_display_name", "relation", "status" ], "title": "TeamConversation", "type": "object" }, "TeamConversationItem": { "properties": { "item_ref": { "description": "The work the conversation is on, as a typed id.", "title": "Item Ref", "type": "string" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Its title, when you may see the task.", "title": "Title" } }, "required": [ "item_ref" ], "title": "TeamConversationItem", "type": "object" }, "TeamConversationsResponse": { "properties": { "conversations": { "description": "Their conversations that are going, newest activity first; never the conversation the call runs in.", "items": { "$ref": "#/components/schemas/TeamConversation" }, "title": "Conversations", "type": "array" }, "employees": { "description": "You, your manager, your direct reports and your peers under the same manager (or the employees you own).", "items": { "$ref": "#/components/schemas/TeamEmployee" }, "title": "Employees", "type": "array" } }, "title": "TeamConversationsResponse", "type": "object" }, "TeamEmployee": { "properties": { "conversation_count": { "title": "Conversation Count", "type": "integer" }, "employee": { "title": "Employee", "type": "string" }, "employee_account_id": { "title": "Employee Account Id", "type": "string" }, "employee_display_name": { "title": "Employee Display Name", "type": "string" }, "employee_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Employee Status" }, "relation": { "title": "Relation", "type": "string" } }, "required": [ "employee", "employee_display_name", "employee_account_id", "relation", "conversation_count" ], "title": "TeamEmployee", "type": "object" }, "TeamEmployeeDefinition": { "description": "One member of a team definition (TIDY-19500 F4): a whole employee, plus\nthe key its teammates' ``reports_to.draft_key`` names it by.", "properties": { "display_name": { "maxLength": 120, "minLength": 1, "title": "Display Name", "type": "string" }, "draft_key": { "maxLength": 64, "minLength": 1, "title": "Draft Key", "type": "string" }, "heartbeat_enabled": { "default": true, "title": "Heartbeat Enabled", "type": "boolean" }, "hire_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Hire Id" }, "manners_markdown": { "default": "# TIDY MANNERS\n\nYou are connected to Tidy as a virtual employee.\n\nWhen you are in a group chat, you can read the conversation for context, but you should not reply to every message. Speak up when someone addresses you by name, asks you a question, delegates a task to you, replies to your current work, or you need to report meaningful progress, a blocker, or completion. Answer once, in the thread you were reached in. Never reply only to agree, thank or acknowledge, and never repeat what someone else already said.\n\nDo not assume every group message is for you. If the conversation is between other people or other employees, follow along silently. If you are unsure whether you are being asked to act, ask one short clarifying question or wait.\n\nDo not take action on private data or delegated work unless Tidy grants you the needed tool access.\n\n## Work skill-first\n\nBefore starting any multi-step task, list your installed skills and read the one that matches the task: its SKILL.md first, then only the reference file it points you to for this task, not every file. It carries the commands, paths, credentials, and failure remedies you would otherwise rediscover by trial and error. Follow the matching skill's steps instead of probing with ad-hoc terminal commands. Improvise only when no installed skill matches the task.\n\n## Colleagues and your inbox\n\nYou may work alongside other virtual employees. To tell, ask, or update a colleague, call `message_employee` with their name, and pass the item's `item_ref` when the message is about one. On shared work, a comment on the task that @mentions their handle reaches them too. `send_to_assistant` reaches Tidy's built-in assistant, never a colleague, and its reply is not theirs.\n\nMessages colleagues send you and @mentions waiting on you are in your inbox. Check it with `agent_inbox` when you start work, and before you tell anyone whether a message arrived. Answer a comment mention with `comment_reply` in its thread; reply to a colleague with `message_employee`.\n\nTidy also keeps a home room for you, where it posts system alerts. It is not a chat and no one waits in it to talk; every mention and colleague message it alerts you to is also in `agent_inbox`.\n\n## Shared knowledge framing\n\nTidy's memory holds facts from ALL of the user's assistants and from their notes, email, calendar and contacts, and recalls the ones relevant to a message for you under \"Personal Context\". Present a shared fact that did not come from your own conversation with this user as Tidy's record (\"our records show the launch moved to March\"), NEVER as your own history with them (\"as we discussed\", \"you told me\"): that fabricates a history and breaks their trust.\n\n## Recording and correcting memory\n\nWrite to memory only deliberately, never every turn. The tidy-mcp skill says when to correct a fact in the user's shared memory, when to keep a note of your own, and how to check what you remember.", "maxLength": 20000, "title": "Manners Markdown", "type": "string" }, "mention_handle": { "anyOf": [ { "maxLength": 80, "minLength": 2, "type": "string" }, { "type": "null" } ], "title": "Mention Handle" }, "model_access": { "anyOf": [ { "$ref": "#/components/schemas/EmployeeModelAccess" }, { "type": "null" } ] }, "objectives": { "items": { "$ref": "#/components/schemas/EmployeeObjective" }, "maxItems": 10, "title": "Objectives", "type": "array" }, "reflection_cadence": { "anyOf": [ { "maxLength": 32, "pattern": "^P(?:\\d+D)?(?:T(?:\\d+H)?(?:\\d+M)?)?$", "type": "string" }, { "type": "null" } ], "default": "P7D", "title": "Reflection Cadence" }, "reports_to": { "anyOf": [ { "$ref": "#/components/schemas/EmployeeReportsTo" }, { "type": "null" } ] }, "role_title": { "maxLength": 160, "minLength": 1, "title": "Role Title", "type": "string" }, "scheduled_jobs": { "items": { "$ref": "#/components/schemas/EmployeeScheduledJob" }, "maxItems": 10, "title": "Scheduled Jobs", "type": "array" }, "skills": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Skills" }, "soul_markdown": { "maxLength": 20000, "minLength": 1, "title": "Soul Markdown", "type": "string" }, "template_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Template Id" }, "voice_id": { "anyOf": [ { "maxLength": 120, "type": "string" }, { "type": "null" } ], "title": "Voice Id" } }, "required": [ "display_name", "role_title", "soul_markdown", "draft_key" ], "title": "TeamEmployeeDefinition", "type": "object" }, "TeamMember": { "properties": { "account_id": { "title": "Account Id", "type": "string" }, "display_name": { "title": "Display Name", "type": "string" } }, "required": [ "account_id", "display_name" ], "title": "TeamMember", "type": "object" }, "TeammateResponse": { "description": "Someone above, below or beside the caller on the team Org chart (TIDY-19750).", "properties": { "account_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Their account (UUID) for an employee or member — what project_add_member takes", "title": "Account Id" }, "can_configure": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "description": "An employee only (TIDY-20154): whether you may set its work policy and standing instructions — as its direct manager or a workspace admin", "title": "Can Configure" }, "contact_id": { "description": "Their card on the Org chart", "examples": [ "C-550e8400-e29b-41d4-a716-446655440000" ], "pattern": "^C-[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "title": "ContactId", "type": "string", "x-tidy-typed-id-prefix": "C", "x-tidy-typed-id-table": "contacts" }, "display_name": { "description": "Their name as the chart shows it", "title": "Display Name", "type": "string" }, "employee_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "An employee's runtime status (active, offline, ...)", "title": "Employee Status" }, "in_project": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "description": "Whether they belong to the project asked about (project_id)", "title": "In Project" }, "in_room": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "description": "In a room turn: whether they are in the room the turn answers in", "title": "In Room" }, "kind": { "description": "A virtual employee, a workspace member, or a shared card with no account (it cannot be added to a project)", "enum": [ "employee", "member", "contact" ], "title": "Kind", "type": "string" }, "mention_handle": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "An employee's @handle, to @mention it in a room", "title": "Mention Handle" }, "relation": { "description": "Your manager, one of your direct reports, or a peer (someone else under your manager)", "enum": [ "manager", "direct_report", "peer" ], "title": "Relation", "type": "string" } }, "required": [ "relation", "contact_id", "display_name", "kind" ], "title": "TeammateResponse", "type": "object" }, "TemplateAutoCreatedItem": { "description": "One materialized embedded facet returned by /instantiate.\n\n``node_id`` / ``prompt_title`` are populated on form-template runs\n(TIDY-14395): ``node_id`` keys the child to its template\n``facetPlaceholder``; ``prompt_title=True`` flags a titleMode='prompt'\nchild created untitled so the opening client prompts for a name (D13).", "properties": { "facet_slug": { "title": "Facet Slug", "type": "string" }, "id": { "format": "uuid", "title": "Id", "type": "string" }, "node_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Node Id" }, "prompt_title": { "default": false, "title": "Prompt Title", "type": "boolean" }, "target_table": { "title": "Target Table", "type": "string" }, "title": { "title": "Title", "type": "string" } }, "required": [ "facet_slug", "id", "title", "target_table" ], "title": "TemplateAutoCreatedItem", "type": "object" }, "TemplateCreateRequest": { "description": "POST /api/v1/templates body.", "properties": { "body": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Base64-encoded Yjs state bytes (optional — empty allowed).", "title": "Body" }, "content_json": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "ProseMirror JSON document — the LLM/agent authoring path (TIDY-14399 / D2). Mutually exclusive with `body`; converted to Yjs state server-side after full validation (placeholders, bound-field keys, form-node vocabulary).", "title": "Content Json" }, "content_markdown": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The body as Markdown — the text-only authoring path (TIDY-18493). CommonMark plus GFM task lists (`- [ ]`), tables and strikethrough, `[[typed-id]]` wiki links and `![[typed-id]]` embeds, with `{{field.*}}` / `{{context.*}}` / `{{date.*}}` / `{{this.*}}` placeholders as plain text. Converted to ProseMirror server-side, then validated like `content_json`. Mutually exclusive with `body` and `content_json`.", "title": "Content Markdown" }, "facet_slug": { "maxLength": 128, "minLength": 1, "title": "Facet Slug", "type": "string" }, "layout_config": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Layout Config" }, "name": { "maxLength": 256, "minLength": 1, "title": "Name", "type": "string" }, "plain_text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Plain Text" }, "template_kind": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": "document", "description": "'document' (default), 'form' (TIDY-14393), or 'report' (TIDY-14583 — an export layout authored in the same editor). Form and report templates require a resolvable facet_slug.", "title": "Template Kind" }, "visibility": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": "private", "title": "Visibility" } }, "required": [ "facet_slug", "name" ], "title": "TemplateCreateRequest", "type": "object" }, "TemplateDetail": { "description": "Full template record including body, plain_text, layout, and versions.\n\nReturned by `GET /api/v1/templates/{id}`, `POST /api/v1/templates`,\n`POST /api/v1/templates/{id}/fork`.", "properties": { "body": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Base64-encoded Yjs state bytes (None if no body).", "title": "Body" }, "content_json": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "description": "ProseMirror JSON decode of the body for round-trip editing (TIDY-14399). None when the body is empty or does not decode.", "title": "Content Json" }, "content_markdown": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "The body rendered as Markdown in the dialect `content_markdown` takes, so a text-only client can check and re-send it (TIDY-18493). None when the body is empty or does not decode.", "title": "Content Markdown" }, "content_markdown_unsupported": { "description": "Body content `content_markdown` cannot express: node types and `mark:` marks. Re-sending that Markdown would drop them; send `content_json` to keep them.", "items": { "type": "string" }, "title": "Content Markdown Unsupported", "type": "array" }, "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "facet_slug": { "title": "Facet Slug", "type": "string" }, "forked_from_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "default": null, "title": "Forked From Id" }, "id": { "format": "uuid", "title": "Id", "type": "string" }, "is_system": { "title": "Is System", "type": "boolean" }, "layout_config": { "additionalProperties": true, "title": "Layout Config", "type": "object" }, "name": { "title": "Name", "type": "string" }, "owner_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Owner Id" }, "placeholders": { "description": "Every distinct `{{...}}` placeholder in the body, in order.", "items": { "type": "string" }, "title": "Placeholders", "type": "array" }, "plain_text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Plain Text" }, "template_kind": { "default": "document", "title": "Template Kind", "type": "string" }, "tenant_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Tenant Id" }, "updated_at": { "format": "date-time", "title": "Updated At", "type": "string" }, "versions": { "items": { "$ref": "#/components/schemas/TemplateVersionSummary" }, "title": "Versions", "type": "array" }, "visibility": { "title": "Visibility", "type": "string" } }, "required": [ "id", "tenant_id", "owner_id", "facet_slug", "name", "visibility", "is_system", "created_at", "updated_at" ], "title": "TemplateDetail", "type": "object" }, "TemplateEmbedSpec": { "description": "Spec describing one missing child facet to materialize on retry.", "properties": { "facet_slug": { "maxLength": 128, "minLength": 1, "title": "Facet Slug", "type": "string" }, "name": { "anyOf": [ { "maxLength": 256, "type": "string" }, { "type": "null" } ], "title": "Name" }, "properties": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Properties" } }, "required": [ "facet_slug" ], "title": "TemplateEmbedSpec", "type": "object" }, "TemplateForkRequest": { "description": "POST /api/v1/templates/{id}/fork body.", "properties": { "name": { "anyOf": [ { "maxLength": 256, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Name" } }, "title": "TemplateForkRequest", "type": "object" }, "TemplateGenerateRequest": { "properties": { "context": { "anyOf": [ { "maxLength": 4000, "type": "string" }, { "type": "null" } ], "title": "Context" }, "facet_slug": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Facet Slug" }, "name": { "anyOf": [ { "maxLength": 256, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Name" }, "persist": { "default": false, "description": "When true, save the generated template via TemplateWriter and return its `template_id`. Requires `name`.", "title": "Persist", "type": "boolean" }, "prompt": { "maxLength": 2000, "minLength": 1, "title": "Prompt", "type": "string" }, "visibility": { "default": "private", "title": "Visibility", "type": "string" } }, "required": [ "prompt" ], "title": "TemplateGenerateRequest", "type": "object" }, "TemplateGenerateResponse": { "properties": { "content": { "title": "Content", "type": "string" }, "layout": { "additionalProperties": true, "title": "Layout", "type": "object" }, "suggested_facets": { "items": { "type": "string" }, "title": "Suggested Facets", "type": "array" }, "template_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Template Id" } }, "required": [ "content", "layout", "suggested_facets" ], "title": "TemplateGenerateResponse", "type": "object" }, "TemplateInstantiateEmbedRequest": { "description": "`POST /api/v1/templates/{id}/instantiate-embed` body.\n\nTwo shapes (exactly one applies):\n\n* Legacy retry (TIDY-8978): ``parent_primitive_id`` + ``embed_spec`` —\n the AutoCreateBanner re-materializes a failed auto-create entry.\n* Form lazy reveal (TIDY-14395, consumed by S7): ``parent_record_id`` +\n ``embed_node_id`` (+ optional ``title`` for prompt-mode children) —\n idempotently births the pinned snapshot's placeholder under a form run.", "properties": { "embed_node_id": { "anyOf": [ { "maxLength": 128, "type": "string" }, { "type": "null" } ], "title": "Embed Node Id" }, "embed_spec": { "anyOf": [ { "$ref": "#/components/schemas/TemplateEmbedSpec" }, { "type": "null" } ] }, "parent_primitive_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Parent Primitive Id" }, "parent_record_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Parent Record Id" }, "title": { "anyOf": [ { "maxLength": 500, "type": "string" }, { "type": "null" } ], "title": "Title" } }, "title": "TemplateInstantiateEmbedRequest", "type": "object" }, "TemplateInstantiateEmbedResponse": { "description": "Result of `POST /api/v1/templates/{id}/instantiate-embed`.\n\n``node_id`` / ``already_existed`` / ``prompt_title`` are populated on the\nform lazy-reveal shape: ``already_existed=True`` means the idempotency\nledger returned the child that was already born for this\n``(parent, node)`` pair.", "properties": { "already_existed": { "default": false, "title": "Already Existed", "type": "boolean" }, "facet_slug": { "title": "Facet Slug", "type": "string" }, "id": { "format": "uuid", "title": "Id", "type": "string" }, "node_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Node Id" }, "prompt_title": { "default": false, "title": "Prompt Title", "type": "boolean" }, "target_table": { "title": "Target Table", "type": "string" }, "title": { "title": "Title", "type": "string" } }, "required": [ "id", "facet_slug", "title", "target_table" ], "title": "TemplateInstantiateEmbedResponse", "type": "object" }, "TemplateInstantiateRequest": { "description": "`POST /api/v1/templates/{id}/instantiate` body.", "properties": { "strict_variables": { "default": false, "description": "When true, a template variable that cannot be resolved fails the instantiation with 422 template_placeholders_unresolved instead of storing the raw `{{...}}` marker in the created primitive.", "title": "Strict Variables", "type": "boolean" }, "target": { "$ref": "#/components/schemas/TemplateInstantiateTarget" }, "variables": { "additionalProperties": true, "title": "Variables", "type": "object" } }, "required": [ "target" ], "title": "TemplateInstantiateRequest", "type": "object" }, "TemplateInstantiateResponse": { "description": "Result of `POST /api/v1/templates/{id}/instantiate`.", "properties": { "auto_created": { "items": { "$ref": "#/components/schemas/TemplateAutoCreatedItem" }, "title": "Auto Created", "type": "array" }, "body_html": { "default": "", "title": "Body Html", "type": "string" }, "body_yjs": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Base64-encoded Yjs state of the rendered body (None — body is delivered via plain_text + body_html).", "title": "Body Yjs" }, "primitive_id": { "format": "uuid", "title": "Primitive Id", "type": "string" }, "warnings": { "items": { "type": "string" }, "title": "Warnings", "type": "array" } }, "required": [ "primitive_id" ], "title": "TemplateInstantiateResponse", "type": "object" }, "TemplateInstantiateTarget": { "description": "Target descriptor for `POST /api/v1/templates/{id}/instantiate`.\n\n`primitive` names the entity type to create (`note`, `task`,\n`activity`, `record`, `page`). `parent_id` optionally anchors the new\nprimitive under another row (e.g. project_id when creating a task\nunder a project).", "properties": { "custom_properties": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Custom Properties" }, "facet_slug": { "anyOf": [ { "maxLength": 128, "minLength": 1, "type": "string" }, { "type": "null" } ], "description": "Facet the created primitive carries, when it differs from the template's own facet. Must be a facet that can use the template (its own facet, an ancestor's, or a descendant's); otherwise 422 facet_mismatch.", "title": "Facet Slug" }, "parent_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Parent Id" }, "primitive": { "maxLength": 64, "minLength": 1, "title": "Primitive", "type": "string" } }, "required": [ "primitive" ], "title": "TemplateInstantiateTarget", "type": "object" }, "TemplatePatchRequest": { "properties": { "default_pinned_embeds": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "title": "Default Pinned Embeds" }, "default_topic": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Default Topic" }, "default_visibility": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Default Visibility" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "name": { "anyOf": [ { "maxLength": 120, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Name" }, "preload": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "title": "Preload" }, "project_config": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Project Config" }, "spawn_project": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Spawn Project" }, "tabs": { "anyOf": [ { "items": { "$ref": "#/components/schemas/ChannelTemplateTab" }, "type": "array" }, { "type": "null" } ], "title": "Tabs" } }, "title": "TemplatePatchRequest", "type": "object" }, "TemplateRequest": { "properties": { "default_pinned_embeds": { "items": { "additionalProperties": true, "type": "object" }, "title": "Default Pinned Embeds", "type": "array" }, "default_topic": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Default Topic" }, "default_visibility": { "default": "private", "title": "Default Visibility", "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "name": { "maxLength": 120, "minLength": 1, "title": "Name", "type": "string" }, "preload": { "items": { "additionalProperties": true, "type": "object" }, "title": "Preload", "type": "array" }, "project_config": { "additionalProperties": true, "title": "Project Config", "type": "object" }, "spawn_project": { "default": false, "title": "Spawn Project", "type": "boolean" }, "tabs": { "items": { "$ref": "#/components/schemas/ChannelTemplateTab" }, "title": "Tabs", "type": "array" } }, "required": [ "name" ], "title": "TemplateRequest", "type": "object" }, "TemplateResponse": { "properties": { "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "created_by_account_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Created By Account Id" }, "default_pinned_embeds": { "items": { "additionalProperties": true, "type": "object" }, "title": "Default Pinned Embeds", "type": "array" }, "default_topic": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Default Topic" }, "default_visibility": { "title": "Default Visibility", "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "id": { "format": "uuid", "title": "Id", "type": "string" }, "is_system": { "title": "Is System", "type": "boolean" }, "name": { "title": "Name", "type": "string" }, "preload": { "items": { "additionalProperties": true, "type": "object" }, "title": "Preload", "type": "array" }, "project_config": { "additionalProperties": true, "title": "Project Config", "type": "object" }, "spawn_project": { "title": "Spawn Project", "type": "boolean" }, "tabs": { "items": { "additionalProperties": true, "type": "object" }, "title": "Tabs", "type": "array" }, "tenant_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Tenant Id" }, "updated_at": { "format": "date-time", "title": "Updated At", "type": "string" } }, "required": [ "id", "tenant_id", "name", "description", "default_topic", "default_visibility", "default_pinned_embeds", "tabs", "spawn_project", "project_config", "preload", "is_system", "created_by_account_id", "created_at", "updated_at" ], "title": "TemplateResponse", "type": "object" }, "TemplateRewriteRequest": { "description": "`POST /api/v1/templates/{id}/rewrite` body.\n\nThe user's existing draft content is restructured by the LLM into the\nsections defined by the target template. ``current_content`` is the\nplain-text or markdown rendering of what's currently in the editor.\nThe handler loads the template's ``plain_text`` (S2 stores the\nsearchable rendering) as the structural reference.", "properties": { "current_content": { "maxLength": 20000, "minLength": 1, "title": "Current Content", "type": "string" } }, "required": [ "current_content" ], "title": "TemplateRewriteRequest", "type": "object" }, "TemplateRewriteResponse": { "description": "Result of `POST /api/v1/templates/{id}/rewrite`.\n\n``prosemirror_doc`` is a ProseMirror document JSON that the editor\ncan set via ``editor.commands.setContent(doc)``. It is wrapped under\na ``doc`` node so the editor receives a complete document; callers\nthat want raw fragments should ``content`` from inside the doc.", "properties": { "elapsed_ms": { "title": "Elapsed Ms", "type": "integer" }, "model": { "title": "Model", "type": "string" }, "prosemirror_doc": { "additionalProperties": true, "title": "Prosemirror Doc", "type": "object" }, "template_id": { "format": "uuid", "title": "Template Id", "type": "string" } }, "required": [ "template_id", "prosemirror_doc", "model", "elapsed_ms" ], "title": "TemplateRewriteResponse", "type": "object" }, "TemplateSummary": { "description": "Lightweight list-view template record (no body bytes).\n\nReturned by `GET /api/v1/templates`.", "properties": { "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "facet_slug": { "title": "Facet Slug", "type": "string" }, "forked_from_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "default": null, "title": "Forked From Id" }, "id": { "format": "uuid", "title": "Id", "type": "string" }, "is_system": { "title": "Is System", "type": "boolean" }, "name": { "title": "Name", "type": "string" }, "owner_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Owner Id" }, "template_kind": { "default": "document", "title": "Template Kind", "type": "string" }, "tenant_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Tenant Id" }, "updated_at": { "format": "date-time", "title": "Updated At", "type": "string" }, "visibility": { "title": "Visibility", "type": "string" } }, "required": [ "id", "tenant_id", "owner_id", "facet_slug", "name", "visibility", "is_system", "created_at", "updated_at" ], "title": "TemplateSummary", "type": "object" }, "TemplateUpdateBlobRequest": { "description": "POST /api/v1/templates/{id}/updates body.\n\nExactly one of ``update_blob`` (client Yjs state), ``content_json``\n(ProseMirror JSON, converted server-side — TIDY-14399) or\n``content_markdown`` (Markdown, converted server-side — TIDY-18493) is\nrequired.", "properties": { "content_json": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "ProseMirror JSON document — the LLM/agent authoring path. Mutually exclusive with `update_blob`.", "title": "Content Json" }, "content_markdown": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The body as Markdown (TIDY-18493), converted and validated like `content_markdown` on create. Mutually exclusive with `update_blob` and `content_json`.", "title": "Content Markdown" }, "plain_text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Plain Text" }, "update_blob": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Base64-encoded Yjs state bytes.", "title": "Update Blob" } }, "title": "TemplateUpdateBlobRequest", "type": "object" }, "TemplateUpdateRequest": { "description": "PATCH /api/v1/templates/{id} body — partial update of metadata.\n\nBody content (yjs_state) is sent via POST /api/v1/templates/{id}/updates.", "properties": { "layout_config": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Layout Config" }, "name": { "anyOf": [ { "maxLength": 256, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Name" }, "visibility": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Visibility" } }, "title": "TemplateUpdateRequest", "type": "object" }, "TemplateVersionCreateRequest": { "description": "POST /api/v1/templates/{id}/versions body.", "properties": { "label": { "anyOf": [ { "maxLength": 256, "type": "string" }, { "type": "null" } ], "title": "Label" } }, "title": "TemplateVersionCreateRequest", "type": "object" }, "TemplateVersionDetail": { "description": "One version snapshot WITH its content (TIDY-14394 P4).\n\nThe form viewer renders the immutable snapshot a record run is pinned to\n(`_form_template_version_id`); `body` is the version's yjs_state as\nbase64 — the same encoding `TemplateDetail.body` uses.", "properties": { "body": { "title": "Body", "type": "string" }, "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "created_by": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Created By" }, "id": { "format": "uuid", "title": "Id", "type": "string" }, "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Label" }, "plain_text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Plain Text" }, "template_id": { "format": "uuid", "title": "Template Id", "type": "string" } }, "required": [ "id", "template_id", "label", "created_by", "created_at", "body" ], "title": "TemplateVersionDetail", "type": "object" }, "TemplateVersionSummary": { "description": "Single entry in a template's version-history list.", "properties": { "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "created_by": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Created By" }, "id": { "format": "uuid", "title": "Id", "type": "string" }, "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Label" }, "template_id": { "format": "uuid", "title": "Template Id", "type": "string" } }, "required": [ "id", "template_id", "label", "created_by", "created_at" ], "title": "TemplateVersionSummary", "type": "object" }, "TenantAssociation": { "description": "User's association with a tenant.", "properties": { "account_type": { "default": "personal", "description": "Tenant account type (personal, household, business)", "title": "Account Type", "type": "string" }, "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "is_active": { "description": "Whether this is the currently active tenant", "title": "Is Active", "type": "boolean" }, "last_active_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Last Active At" }, "role": { "title": "Role", "type": "string" }, "status": { "title": "Status", "type": "string" }, "tenant_id": { "title": "Tenant Id", "type": "string" }, "tenant_name": { "title": "Tenant Name", "type": "string" } }, "required": [ "tenant_id", "tenant_name", "role", "status", "is_active", "created_at" ], "title": "TenantAssociation", "type": "object" }, "TenantAssociationsResponse": { "description": "Response for tenant associations list.", "properties": { "active_tenant_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Active Tenant Id" }, "associations": { "items": { "$ref": "#/components/schemas/TenantAssociation" }, "title": "Associations", "type": "array" } }, "required": [ "associations" ], "title": "TenantAssociationsResponse", "type": "object" }, "TenantAuditItem": { "properties": { "action": { "title": "Action", "type": "string" }, "actor_account_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "default": null, "title": "Actor Account Id" }, "actor_kind": { "enum": [ "human", "agent", "service", "automation" ], "title": "Actor Kind", "type": "string" }, "event_type": { "title": "Event Type", "type": "string" }, "id": { "title": "Id", "type": "string" }, "outcome": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Outcome" }, "resource_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Resource Id" }, "resource_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Resource Type" }, "run_ref": { "anyOf": [ { "$ref": "#/components/schemas/RunRef" }, { "type": "null" } ], "default": null }, "seq": { "title": "Seq", "type": "integer" }, "source": { "enum": [ "audit", "agent_run", "subagent", "workflow" ], "title": "Source", "type": "string" }, "ts": { "format": "date-time", "title": "Ts", "type": "string" } }, "required": [ "id", "seq", "ts", "source", "actor_kind", "action", "event_type" ], "title": "TenantAuditItem", "type": "object" }, "TenantAuditResponse": { "properties": { "items": { "items": { "$ref": "#/components/schemas/TenantAuditItem" }, "title": "Items", "type": "array" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Next Cursor" } }, "required": [ "items" ], "title": "TenantAuditResponse", "type": "object" }, "TenantAuditRunDetail": { "properties": { "actor_account_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "default": null, "title": "Actor Account Id" }, "completed_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Completed At" }, "content": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "title": "Content" }, "content_visible": { "default": false, "title": "Content Visible", "type": "boolean" }, "kind": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Kind" }, "outcome": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Outcome" }, "run_id": { "title": "Run Id", "type": "string" }, "source": { "enum": [ "audit", "agent_run", "subagent", "workflow" ], "title": "Source", "type": "string" }, "started_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Started At" }, "status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Status" } }, "required": [ "source", "run_id" ], "title": "TenantAuditRunDetail", "type": "object" }, "TenantCreate": { "description": "Input model for creating new tenants.\n\nUsed in:\n - POST /api/v1/tenants (admin-only endpoint)\n - Auto-provisioning on Supabase Auth signup (internal)\n\nAttributes:\n display_name: Human-readable name for the new tenant (required)\n - Minimum 1 character, maximum 255 characters\n - Validated: no leading/trailing whitespace\n - Cannot be empty after trimming\n\nExample (Admin Manual Creation):\n POST /api/v1/tenants\n {\n \"display_name\": \"The Martinez Family\"\n }\n\nExample (Auto-Provisioning - Internal):\n {\n \"display_name\": \"Parent Account\"\n }\n\nResponse:\n 201 Created with full TenantResponse body (includes auto-generated tenant_id)\n\nRelated: FR-004, FR-010, KCC-1148", "example": { "account_type": "household", "display_name": "The Smith Family" }, "properties": { "account_type": { "default": "personal", "description": "Tenant profile type for account switching", "enum": [ "personal", "household", "business" ], "examples": [ "personal", "household", "business" ], "title": "Account Type", "type": "string" }, "display_name": { "description": "Human-readable tenant name (1-255 characters, no leading/trailing whitespace)", "examples": [ "The Smith Family", "Acme School District", "Parent Account" ], "maxLength": 255, "minLength": 1, "title": "Display Name", "type": "string" } }, "required": [ "display_name" ], "title": "TenantCreate", "type": "object" }, "TenantDashboardResponse": { "description": "Tenant-scoped dashboard statistics.", "properties": { "avg_pipeline_duration_minutes": { "default": 0.0, "title": "Avg Pipeline Duration Minutes", "type": "number" }, "contacts_low_confidence": { "default": 0, "title": "Contacts Low Confidence", "type": "integer" }, "events_approved": { "default": 0, "title": "Events Approved", "type": "integer" }, "events_pending_review": { "default": 0, "title": "Events Pending Review", "type": "integer" }, "events_rejected": { "default": 0, "title": "Events Rejected", "type": "integer" }, "failed_pipelines_today": { "default": 0, "title": "Failed Pipelines Today", "type": "integer" }, "news_summaries_by_type": { "additionalProperties": { "type": "integer" }, "default": {}, "title": "News Summaries By Type", "type": "object" }, "notes_approved": { "default": 0, "title": "Notes Approved", "type": "integer" }, "notes_pending_review": { "default": 0, "title": "Notes Pending Review", "type": "integer" }, "notes_rejected": { "default": 0, "title": "Notes Rejected", "type": "integer" }, "organizations_approved": { "default": 0, "title": "Organizations Approved", "type": "integer" }, "organizations_pending_review": { "default": 0, "title": "Organizations Pending Review", "type": "integer" }, "organizations_rejected": { "default": 0, "title": "Organizations Rejected", "type": "integer" }, "owner_email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Owner Email" }, "pipeline_runs_today": { "default": 0, "title": "Pipeline Runs Today", "type": "integer" }, "pipeline_success_rate": { "default": 0.0, "title": "Pipeline Success Rate", "type": "number" }, "pipelines_last_hour": { "default": 0, "title": "Pipelines Last Hour", "type": "integer" }, "sms_delivered": { "default": 0, "title": "Sms Delivered", "type": "integer" }, "sms_delivery_rate": { "default": 0.0, "title": "Sms Delivery Rate", "type": "number" }, "sms_failed": { "default": 0, "title": "Sms Failed", "type": "integer" }, "sms_total_cost_cents": { "default": 0, "title": "Sms Total Cost Cents", "type": "integer" }, "sms_total_messages": { "default": 0, "title": "Sms Total Messages", "type": "integer" }, "sms_total_segments": { "default": 0, "title": "Sms Total Segments", "type": "integer" }, "tasks_approved": { "default": 0, "title": "Tasks Approved", "type": "integer" }, "tasks_pending_review": { "default": 0, "title": "Tasks Pending Review", "type": "integer" }, "tasks_rejected": { "default": 0, "title": "Tasks Rejected", "type": "integer" }, "tenant_id": { "title": "Tenant Id", "type": "string" }, "tenant_name": { "title": "Tenant Name", "type": "string" }, "total_api_calls_30d": { "default": 0, "title": "Total Api Calls 30D", "type": "integer" }, "total_contacts": { "default": 0, "title": "Total Contacts", "type": "integer" }, "total_cost_cents_30d": { "default": 0, "title": "Total Cost Cents 30D", "type": "integer" }, "total_emails_processed": { "default": 0, "title": "Total Emails Processed", "type": "integer" }, "total_events": { "default": 0, "title": "Total Events", "type": "integer" }, "total_news_summaries": { "default": 0, "title": "Total News Summaries", "type": "integer" }, "total_news_updates": { "default": 0, "title": "Total News Updates", "type": "integer" }, "total_notes": { "default": 0, "title": "Total Notes", "type": "integer" }, "total_organizations": { "default": 0, "title": "Total Organizations", "type": "integer" }, "total_reminders": { "default": 0, "title": "Total Reminders", "type": "integer" }, "total_tasks": { "default": 0, "title": "Total Tasks", "type": "integer" }, "total_tokens_30d": { "default": 0, "title": "Total Tokens 30D", "type": "integer" } }, "required": [ "tenant_id", "tenant_name" ], "title": "TenantDashboardResponse", "type": "object" }, "TenantDefaultEmployeeResponse": { "properties": { "employee_ref": { "$ref": "#/components/schemas/DefaultEmployeeRef" }, "label": { "title": "Label", "type": "string" }, "matrix_user_id": { "title": "Matrix User Id", "type": "string" }, "source": { "title": "Source", "type": "string" } }, "required": [ "employee_ref", "matrix_user_id", "label", "source" ], "title": "TenantDefaultEmployeeResponse", "type": "object" }, "TenantExportFilters": { "properties": { "actor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Actor" }, "event_type": { "items": { "type": "string" }, "title": "Event Type", "type": "array" }, "source": { "items": { "type": "string" }, "title": "Source", "type": "array" } }, "title": "TenantExportFilters", "type": "object" }, "TenantExportJobResponse": { "properties": { "job_id": { "format": "uuid", "title": "Job Id", "type": "string" }, "location": { "title": "Location", "type": "string" }, "status": { "title": "Status", "type": "string" } }, "required": [ "job_id", "status", "location" ], "title": "TenantExportJobResponse", "type": "object" }, "TenantExportRequest": { "properties": { "date_from": { "format": "date", "title": "Date From", "type": "string" }, "date_to": { "format": "date", "title": "Date To", "type": "string" }, "filters": { "$ref": "#/components/schemas/TenantExportFilters" }, "format": { "default": "jsonl", "enum": [ "jsonl", "csv" ], "title": "Format", "type": "string" } }, "required": [ "date_from", "date_to" ], "title": "TenantExportRequest", "type": "object" }, "TenantExportStatusResponse": { "properties": { "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Error" }, "job_id": { "format": "uuid", "title": "Job Id", "type": "string" }, "row_count": { "default": 0, "title": "Row Count", "type": "integer" }, "status": { "title": "Status", "type": "string" } }, "required": [ "job_id", "status" ], "title": "TenantExportStatusResponse", "type": "object" }, "TenantFeatureSettingsResponse": { "properties": { "admin_names": { "items": { "type": "string" }, "title": "Admin Names", "type": "array" }, "advanced_noise_enabled": { "default": false, "title": "Advanced Noise Enabled", "type": "boolean" }, "ai_local_only_enabled": { "default": false, "title": "Ai Local Only Enabled", "type": "boolean" }, "choices": { "items": { "$ref": "#/components/schemas/ChoiceSettingEntry" }, "title": "Choices", "type": "array" }, "collab_nav_enabled": { "default": false, "title": "Collab Nav Enabled", "type": "boolean" }, "flags": { "items": { "$ref": "#/components/schemas/FeatureFlagEntry" }, "title": "Flags", "type": "array" }, "hosted_employees_may_use_tenant_keys": { "default": false, "title": "Hosted Employees May Use Tenant Keys", "type": "boolean" }, "huddle_composite_eval_enabled": { "default": false, "title": "Huddle Composite Eval Enabled", "type": "boolean" }, "native_email_collaboration_enabled": { "default": false, "title": "Native Email Collaboration Enabled", "type": "boolean" }, "record_action_menu_vertical": { "default": false, "title": "Record Action Menu Vertical", "type": "boolean" }, "settings": { "items": { "$ref": "#/components/schemas/ValueSettingEntry" }, "title": "Settings", "type": "array" }, "tenant_id": { "title": "Tenant Id", "type": "string" }, "updated_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Updated At" }, "updated_by": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Updated By" }, "updated_by_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Updated By Name" }, "ve_activity_feed_enabled": { "default": false, "title": "Ve Activity Feed Enabled", "type": "boolean" }, "ve_autonomy_heartbeat_enabled": { "default": false, "title": "Ve Autonomy Heartbeat Enabled", "type": "boolean" }, "ve_backlog_injection_enabled": { "default": false, "title": "Ve Backlog Injection Enabled", "type": "boolean" }, "ve_goal_facets_enabled": { "default": false, "title": "Ve Goal Facets Enabled", "type": "boolean" }, "ve_home_base_enabled": { "default": false, "title": "Ve Home Base Enabled", "type": "boolean" }, "ve_meeting_wake_enabled": { "default": false, "title": "Ve Meeting Wake Enabled", "type": "boolean" }, "ve_reflection_wake_enabled": { "default": false, "title": "Ve Reflection Wake Enabled", "type": "boolean" }, "ve_resolution_enabled": { "default": false, "title": "Ve Resolution Enabled", "type": "boolean" }, "ve_scheduled_jobs_enabled": { "default": false, "title": "Ve Scheduled Jobs Enabled", "type": "boolean" }, "ve_session_links_enabled": { "default": false, "title": "Ve Session Links Enabled", "type": "boolean" }, "ve_settle_resume_enabled": { "default": false, "title": "Ve Settle Resume Enabled", "type": "boolean" }, "version": { "default": 0, "title": "Version", "type": "integer" }, "voice_identity_enabled": { "default": false, "title": "Voice Identity Enabled", "type": "boolean" }, "workforce_path_policy": { "default": "both", "enum": [ "both", "hosted_only", "workshop_only" ], "title": "Workforce Path Policy", "type": "string" } }, "required": [ "tenant_id" ], "title": "TenantFeatureSettingsResponse", "type": "object" }, "TenantInvitationResponse": { "description": "Pending tenant invitation item returned by the tenant invitations list.", "properties": { "code": { "description": "7-character invitation code", "title": "Code", "type": "string" }, "created_at": { "description": "Invitation creation timestamp", "format": "date-time", "title": "Created At", "type": "string" }, "email": { "description": "Email address invited to the tenant", "title": "Email", "type": "string" }, "expires_at": { "description": "Invitation expiry timestamp", "format": "date-time", "title": "Expires At", "type": "string" }, "id": { "description": "UUID of the invitation row", "title": "Id", "type": "string" }, "invited_by": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Account ID that created the invitation", "title": "Invited By" }, "role": { "description": "Role assigned on accept", "enum": [ "Member", "Viewer" ], "title": "Role", "type": "string" } }, "required": [ "id", "code", "email", "role", "created_at", "expires_at" ], "title": "TenantInvitationResponse", "type": "object" }, "TenantKindBreakdown": { "properties": { "by_kind": { "default": [], "items": { "$ref": "#/components/schemas/KindBreakdown" }, "title": "By Kind", "type": "array" }, "tenant_id": { "title": "Tenant Id", "type": "string" } }, "required": [ "tenant_id" ], "title": "TenantKindBreakdown", "type": "object" }, "TenantListResponse": { "description": "Response model for tenant list.", "properties": { "tenants": { "items": { "$ref": "#/components/schemas/TenantSummary" }, "title": "Tenants", "type": "array" }, "total": { "title": "Total", "type": "integer" } }, "required": [ "tenants", "total" ], "title": "TenantListResponse", "type": "object" }, "TenantMailboxResponse": { "description": "Response model for tenant mailbox info.", "properties": { "domain": { "description": "Email domain", "title": "Domain", "type": "string" }, "email_address": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Tenant's KCC email address", "title": "Email Address" }, "local_part": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Local part of email address", "title": "Local Part" } }, "required": [ "domain" ], "title": "TenantMailboxResponse", "type": "object" }, "TenantMembership": { "description": "A single tenant membership row for the caller.\n\nMirrors exactly the columns ``hooks.server.ts`` read from PostgREST\n(``person_account_memberships``) to resolve the request's tenant:\n``tenant_id`` + the two ordering signals ``is_primary`` /\n``last_active_at``. The frontend hook applies its own preferred-tenant\nselection over this ordered list.", "properties": { "is_primary": { "default": false, "title": "Is Primary", "type": "boolean" }, "last_active_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Last Active At" }, "tenant_id": { "format": "uuid", "title": "Tenant Id", "type": "string" } }, "required": [ "tenant_id" ], "title": "TenantMembership", "type": "object" }, "TenantMembershipsResponse": { "description": "Response body for ``GET /me/tenant-memberships``.\n\nOrdered ``is_primary DESC, last_active_at DESC NULLS LAST`` — the same\norder the retired PostgREST hot-path query used, so the frontend's\npreferred-tenant pick is byte-for-byte unchanged.", "properties": { "memberships": { "items": { "$ref": "#/components/schemas/TenantMembership" }, "title": "Memberships", "type": "array" } }, "required": [ "memberships" ], "title": "TenantMembershipsResponse", "type": "object" }, "TenantPATPublic": { "properties": { "account_email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Account Email" }, "account_id": { "title": "Account Id", "type": "string" }, "agent_label": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Agent Label" }, "client_kind": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Client Kind" }, "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "expires_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Expires At" }, "id": { "title": "Id", "type": "string" }, "last_used_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Last Used At" }, "name": { "title": "Name", "type": "string" }, "prefix": { "title": "Prefix", "type": "string" }, "scopes": { "items": { "type": "string" }, "title": "Scopes", "type": "array" }, "tenant_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Tenant Id" } }, "required": [ "id", "name", "prefix", "scopes", "created_at", "account_id" ], "title": "TenantPATPublic", "type": "object" }, "TenantProvisionRequest": { "description": "Request model for tenant provisioning on sign-up.", "properties": { "attribution": { "anyOf": [ { "$ref": "#/components/schemas/SignupAttribution" }, { "type": "null" } ], "description": "Campaign attribution context carried from the marketing site (tidy_aid cookie + UTM params). When present, provisioning writes a 'signup' attribution event linking the anonymous trail to the new tenant (TIDY-12082 / F9-S1)." }, "avatar_url": { "anyOf": [ { "maxLength": 2048, "type": "string" }, { "type": "null" } ], "description": "OAuth avatar URL to store on account profile", "title": "Avatar Url" }, "display_name": { "anyOf": [ { "maxLength": 255, "minLength": 1, "type": "string" }, { "type": "null" } ], "description": "Tenant display name (defaults to user's name from OAuth)", "title": "Display Name" }, "invite_code": { "anyOf": [ { "maxLength": 64, "type": "string" }, { "type": "null" } ], "description": "Invite code — required when invite_only_mode is ON. Redeemed atomically inside the provision transaction (TIDY-12617).", "title": "Invite Code" }, "workspace_invitation_code": { "anyOf": [ { "maxLength": 16, "type": "string" }, { "type": "null" } ], "description": "A workspace invitation's 7-character code. When present, the verified caller joins the inviting workspace instead of creating one; the private-beta invite gate does not apply (TIDY-19981).", "title": "Workspace Invitation Code" } }, "title": "TenantProvisionRequest", "type": "object" }, "TenantProvisionResponse": { "description": "Response model for tenant provisioning.", "properties": { "created_at": { "description": "Creation timestamp", "format": "date-time", "title": "Created At", "type": "string" }, "display_name": { "description": "Tenant display name", "title": "Display Name", "type": "string" }, "mailbox_email": { "description": "Unique inbox email address", "title": "Mailbox Email", "type": "string" }, "role": { "description": "User's role in tenant (Owner)", "title": "Role", "type": "string" }, "tenant_id": { "description": "Tenant UUID", "title": "Tenant Id", "type": "string" } }, "required": [ "tenant_id", "display_name", "mailbox_email", "role", "created_at" ], "title": "TenantProvisionResponse", "type": "object" }, "TenantResponse": { "description": "Complete tenant object returned by API endpoints.\n\nUsed in:\n - GET /api/v1/tenants (list response items)\n - GET /api/v1/tenants/{id} (single tenant detail)\n - POST /api/v1/tenants (created tenant response, 201)\n - PATCH /api/v1/tenants/{id} (updated tenant response)\n\nAttributes:\n tenant_id: Unique UUID v4 identifier (external, system-generated)\n display_name: Human-readable tenant name (1-255 characters)\n status: Tenant lifecycle state (active|suspended|deleted|orphaned)\n role: User's role in this tenant (owner|member|viewer)\n - Populated only when user context available (authenticated requests)\n - Omitted in admin-only list endpoints\n member_count: Number of associated user accounts (Optional)\n - Populated in GET detail endpoints\n - Omitted in list endpoints for performance\n account_type: Tenant account type (personal|household|business)\n created_at: ISO 8601 timestamp of tenant creation\n updated_at: ISO 8601 timestamp of last modification\n\nExample (Full Detail):\n {\n \"tenant_id\": \"a1b2c3d4-e5f6-4789-abcd-ef1234567890\",\n \"display_name\": \"The Smith Family\",\n \"status\": \"active\",\n \"role\": \"owner\",\n \"member_count\": 3,\n \"account_type\": \"household\",\n \"created_at\": \"2025-11-08T14:30:22.123Z\",\n \"updated_at\": \"2025-11-08T15:45:00.456Z\"\n }\n\nExample (List Item - Minimal):\n {\n \"tenant_id\": \"a1b2c3d4-e5f6-4789-abcd-ef1234567890\",\n \"display_name\": \"The Smith Family\",\n \"status\": \"active\",\n \"role\": \"owner\",\n \"created_at\": \"2025-11-08T14:30:22.123Z\",\n \"updated_at\": \"2025-11-08T15:45:00.456Z\"\n }\n\nRelated: FR-001, FR-003, FR-004, KCC-1147", "examples": [ { "account_type": "household", "created_at": "2025-11-08T14:30:22.123Z", "display_name": "The Smith Family", "member_count": 3, "role": "owner", "status": "active", "tenant_id": "a1b2c3d4-e5f6-4789-abcd-ef1234567890", "updated_at": "2025-11-08T15:45:00.456Z" } ], "properties": { "account_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Tenant account type (personal, household, or business)", "examples": [ "personal", "household", "business" ], "title": "Account Type" }, "created_at": { "description": "ISO 8601 timestamp of tenant creation", "examples": [ "2025-11-08T14:30:22.123Z" ], "format": "date-time", "title": "Created At", "type": "string" }, "display_name": { "description": "Human-readable tenant name (e.g., 'The Smith Family')", "examples": [ "The Smith Family", "Acme School District" ], "maxLength": 255, "minLength": 1, "title": "Display Name", "type": "string" }, "marketing_consent_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "description": "When marketing communications were opted in. Null means not consented (TIDY-18851).", "title": "Marketing Consent At" }, "member_count": { "anyOf": [ { "minimum": 0, "type": "integer" }, { "type": "null" } ], "default": null, "description": "Number of user accounts associated with this tenant. None in list endpoints.", "examples": [ 1, 3, 5 ], "title": "Member Count" }, "role": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Current user's role in this tenant (owner|member|viewer). None if not associated.", "examples": [ "owner", "member", "viewer" ], "title": "Role" }, "status": { "default": "active", "description": "Tenant lifecycle state (active|suspended|deleted|orphaned)", "examples": [ "active", "suspended" ], "pattern": "^(active|suspended|deleted|orphaned)$", "title": "Status", "type": "string" }, "tenant_id": { "description": "Unique tenant identifier (UUID v4 format, globally unique)", "examples": [ "a1b2c3d4-e5f6-4789-abcd-ef1234567890" ], "maxLength": 36, "minLength": 36, "title": "Tenant Id", "type": "string" }, "updated_at": { "description": "ISO 8601 timestamp of last modification", "examples": [ "2025-11-08T15:45:00.456Z" ], "format": "date-time", "title": "Updated At", "type": "string" } }, "required": [ "tenant_id", "display_name", "created_at", "updated_at" ], "title": "TenantResponse", "type": "object" }, "TenantSpend": { "properties": { "budget_state": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Budget State" }, "cost_usd": { "title": "Cost Usd", "type": "number" }, "monthly_cap_usd": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "title": "Monthly Cap Usd" }, "ratio": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "title": "Ratio" }, "state_since": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "State Since" }, "tenant_id": { "format": "uuid", "title": "Tenant Id", "type": "string" } }, "required": [ "tenant_id", "cost_usd" ], "title": "TenantSpend", "type": "object" }, "TenantSummary": { "description": "Summary of a tenant for admin listing.", "properties": { "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "email_source_count": { "default": 0, "title": "Email Source Count", "type": "integer" }, "id": { "title": "Id", "type": "string" }, "last_active_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Last Active At" }, "member_count": { "default": 0, "title": "Member Count", "type": "integer" }, "name": { "title": "Name", "type": "string" }, "owner_email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Owner Email" }, "plan_tier": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Plan Tier" }, "status": { "title": "Status", "type": "string" } }, "required": [ "id", "name", "status", "created_at" ], "title": "TenantSummary", "type": "object" }, "TenantSwitchRequest": { "description": "Request to switch active tenant.", "properties": { "tenant_id": { "description": "ID of tenant to switch to", "title": "Tenant Id", "type": "string" } }, "required": [ "tenant_id" ], "title": "TenantSwitchRequest", "type": "object" }, "TenantSwitchResponse": { "description": "Response for tenant switch.", "properties": { "message": { "title": "Message", "type": "string" }, "role": { "title": "Role", "type": "string" }, "success": { "title": "Success", "type": "boolean" }, "tenant_id": { "title": "Tenant Id", "type": "string" }, "tenant_name": { "title": "Tenant Name", "type": "string" } }, "required": [ "success", "tenant_id", "tenant_name", "role", "message" ], "title": "TenantSwitchResponse", "type": "object" }, "TenantUpdate": { "description": "Input model for updating existing tenants.\n\nUsed in:\n - PATCH /api/v1/tenants/{id} (admin-only endpoint)\n\nAll fields are optional - only provided fields are updated.\n\nAttributes:\n display_name: New human-readable name (optional, 1-255 characters)\n status: New lifecycle state (optional, valid: active|suspended|deleted)\n\nExample (Update Name Only):\n PATCH /api/v1/tenants/a1b2c3d4-e5f6-4789-abcd-ef1234567890\n {\n \"display_name\": \"The Smith Family (Updated)\"\n }\n\nExample (Update Status Only):\n PATCH /api/v1/tenants/a1b2c3d4-e5f6-4789-abcd-ef1234567890\n {\n \"status\": \"suspended\"\n }\n\nExample (Update Both):\n PATCH /api/v1/tenants/a1b2c3d4-e5f6-4789-abcd-ef1234567890\n {\n \"display_name\": \"New Name\",\n \"status\": \"active\"\n }\n\nResponse:\n 200 OK with updated TenantResponse body\n\nRelated: FR-006, KCC-1149", "example": { "display_name": "The Smith Family (Updated)", "status": "active" }, "properties": { "account_type": { "anyOf": [ { "enum": [ "personal", "household", "business" ], "type": "string" }, { "type": "null" } ], "description": "Tenant account type (personal, household, or business)", "examples": [ "personal", "household", "business" ], "title": "Account Type" }, "display_name": { "anyOf": [ { "maxLength": 255, "minLength": 1, "type": "string" }, { "type": "null" } ], "description": "New human-readable tenant name (1-255 characters, optional)", "examples": [ "The Smith Family (Updated)" ], "title": "Display Name" }, "domain_auto_join_domain": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Email domain for auto-join (e.g. 'heirloomforge.com'). Required when enabling auto-join.", "examples": [ "heirloomforge.com" ], "title": "Domain Auto Join Domain" }, "domain_auto_join_enabled": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Enable domain-based auto-join for this tenant (Owner-only, business accounts)", "title": "Domain Auto Join Enabled" }, "marketing_consent": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Set marketing communications opt-in. true stamps tenants.marketing_consent_at = NOW(); false clears it. Omit to leave unchanged (TIDY-18851).", "title": "Marketing Consent" }, "onboarding_step": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Current onboarding step (e.g., 'team', 'complete')", "examples": [ "tenant", "team", "plan", "complete" ], "title": "Onboarding Step" }, "status": { "anyOf": [ { "pattern": "^(active|suspended|deleted|orphaned)?$", "type": "string" }, { "type": "null" } ], "description": "New tenant status (active|suspended|deleted, optional)", "examples": [ "active", "suspended" ], "title": "Status" } }, "title": "TenantUpdate", "type": "object" }, "TenantUsageResponse": { "description": "Per-tenant usage statistics.", "properties": { "by_feature": { "additionalProperties": { "additionalProperties": { "type": "integer" }, "type": "object" }, "default": {}, "title": "By Feature", "type": "object" }, "by_model": { "additionalProperties": { "additionalProperties": { "type": "integer" }, "type": "object" }, "default": {}, "title": "By Model", "type": "object" }, "daily_usage": { "default": [], "items": { "additionalProperties": true, "type": "object" }, "title": "Daily Usage", "type": "array" }, "failed_pipelines": { "default": 0, "title": "Failed Pipelines", "type": "integer" }, "last_login_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Last Login At" }, "last_pipeline_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Last Pipeline At" }, "owner_email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Owner Email" }, "sms_delivered": { "default": 0, "title": "Sms Delivered", "type": "integer" }, "sms_delivery_rate": { "default": 0.0, "title": "Sms Delivery Rate", "type": "number" }, "sms_failed": { "default": 0, "title": "Sms Failed", "type": "integer" }, "sms_total_cost_cents": { "default": 0, "title": "Sms Total Cost Cents", "type": "integer" }, "sms_total_messages": { "default": 0, "title": "Sms Total Messages", "type": "integer" }, "sms_total_segments": { "default": 0, "title": "Sms Total Segments", "type": "integer" }, "successful_pipelines": { "default": 0, "title": "Successful Pipelines", "type": "integer" }, "tenant_id": { "title": "Tenant Id", "type": "string" }, "tenant_name": { "title": "Tenant Name", "type": "string" }, "total_calls": { "default": 0, "title": "Total Calls", "type": "integer" }, "total_contacts": { "default": 0, "title": "Total Contacts", "type": "integer" }, "total_cost_cents": { "default": 0, "title": "Total Cost Cents", "type": "integer" }, "total_emails": { "default": 0, "title": "Total Emails", "type": "integer" }, "total_events": { "default": 0, "title": "Total Events", "type": "integer" }, "total_notes": { "default": 0, "title": "Total Notes", "type": "integer" }, "total_pipeline_runs": { "default": 0, "title": "Total Pipeline Runs", "type": "integer" }, "total_tasks": { "default": 0, "title": "Total Tasks", "type": "integer" }, "total_tokens": { "default": 0, "title": "Total Tokens", "type": "integer" }, "vector_chunks": { "default": 0, "title": "Vector Chunks", "type": "integer" } }, "required": [ "tenant_id", "tenant_name" ], "title": "TenantUsageResponse", "type": "object" }, "TenantUsageRow": { "properties": { "audio_minutes": { "title": "Audio Minutes", "type": "number" }, "estimated_cost_usd": { "title": "Estimated Cost Usd", "type": "number" }, "job_count": { "title": "Job Count", "type": "integer" }, "tenant_id": { "format": "uuid", "title": "Tenant Id", "type": "string" }, "tenant_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Tenant Name" } }, "required": [ "tenant_id", "tenant_name", "job_count", "audio_minutes", "estimated_cost_usd" ], "title": "TenantUsageRow", "type": "object" }, "TenantVeWorkPolicyRequest": { "properties": { "work_policy": { "anyOf": [ { "$ref": "#/components/schemas/VeWorkPolicy" }, { "type": "null" } ], "description": "The workspace default; null returns to the built-in default." } }, "required": [ "work_policy" ], "title": "TenantVeWorkPolicyRequest", "type": "object" }, "TenantVeWorkPolicyResponse": { "properties": { "available_states": { "description": "The states the settings offer: the workspace task facet's, in its order.", "items": { "type": "string" }, "title": "Available States", "type": "array" }, "effective_work_policy": { "$ref": "#/components/schemas/VeWorkPolicy" }, "wakes_for": { "description": "The states the default wakes an employee for (TIDY-20074).", "items": { "type": "string" }, "title": "Wakes For", "type": "array" }, "work_policy": { "anyOf": [ { "$ref": "#/components/schemas/VeWorkPolicy" }, { "type": "null" } ] } }, "required": [ "work_policy", "effective_work_policy", "wakes_for", "available_states" ], "title": "TenantVeWorkPolicyResponse", "type": "object" }, "TestFireRequest": { "properties": { "event_type": { "default": "nightly_batch_failure", "title": "Event Type", "type": "string" } }, "title": "TestFireRequest", "type": "object" }, "TestSendResponse": { "properties": { "campaign_id": { "title": "Campaign Id", "type": "string" }, "provider_message_id": { "default": "", "title": "Provider Message Id", "type": "string" }, "sent_to": { "title": "Sent To", "type": "string" }, "test_sent_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Test Sent At" } }, "required": [ "campaign_id", "sent_to" ], "title": "TestSendResponse", "type": "object" }, "TestimonialAccount": { "properties": { "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Email" }, "first_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "First Name" }, "last_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Last Name" } }, "title": "TestimonialAccount", "type": "object" }, "TestimonialCandidate": { "description": "An ``engagement_scores`` row with the nested ``accounts`` sub-object,\nbyte-compatible with the PostgREST ``engagement_scores`` select the page\nconsumed (``*, accounts!inner(email, first_name, last_name)``).", "properties": { "account_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "default": null, "title": "Account Id" }, "accounts": { "anyOf": [ { "$ref": "#/components/schemas/TestimonialAccount" }, { "type": "null" } ], "default": null }, "candidacy_threshold": { "default": 0, "title": "Candidacy Threshold", "type": "number" }, "created_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Created At" }, "has_calendar_connected": { "default": false, "title": "Has Calendar Connected", "type": "boolean" }, "has_contacts_authorized": { "default": false, "title": "Has Contacts Authorized", "type": "boolean" }, "has_daily_usage": { "default": false, "title": "Has Daily Usage", "type": "boolean" }, "has_imap_connected": { "default": false, "title": "Has Imap Connected", "type": "boolean" }, "has_location_authorized": { "default": false, "title": "Has Location Authorized", "type": "boolean" }, "has_positive_feedback": { "default": false, "title": "Has Positive Feedback", "type": "boolean" }, "has_used_journal": { "default": false, "title": "Has Used Journal", "type": "boolean" }, "has_used_sharing": { "default": false, "title": "Has Used Sharing", "type": "boolean" }, "id": { "format": "uuid", "title": "Id", "type": "string" }, "is_testimonial_candidate": { "default": false, "title": "Is Testimonial Candidate", "type": "boolean" }, "last_calculated_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Last Calculated At" }, "prompted_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Prompted At" }, "prompted_for_testimonial": { "default": false, "title": "Prompted For Testimonial", "type": "boolean" }, "tenant_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "default": null, "title": "Tenant Id" }, "testimonial_provided": { "default": false, "title": "Testimonial Provided", "type": "boolean" }, "testimonial_provided_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Testimonial Provided At" }, "total_score": { "default": 0, "title": "Total Score", "type": "number" }, "updated_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Updated At" }, "user_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "default": null, "title": "User Id" }, "weight_calendar": { "default": 0, "title": "Weight Calendar", "type": "number" }, "weight_contacts": { "default": 0, "title": "Weight Contacts", "type": "number" }, "weight_daily_usage": { "default": 0, "title": "Weight Daily Usage", "type": "number" }, "weight_imap": { "default": 0, "title": "Weight Imap", "type": "number" }, "weight_journal": { "default": 0, "title": "Weight Journal", "type": "number" }, "weight_location": { "default": 0, "title": "Weight Location", "type": "number" }, "weight_positive_feedback": { "default": 0, "title": "Weight Positive Feedback", "type": "number" }, "weight_sharing": { "default": 0, "title": "Weight Sharing", "type": "number" } }, "required": [ "id" ], "title": "TestimonialCandidate", "type": "object" }, "ThreadEmailItem": { "description": "Email item for thread timeline display with type discriminator.\n\nWraps EmailListItem fields with a 'type' discriminator for merged timeline.\n\nAttributes:\n type: Discriminator field, always 'email'\n (plus all EmailListItem fields)", "properties": { "attachments": { "description": "List of attachments", "items": { "$ref": "#/components/schemas/EmailAttachment" }, "title": "Attachments", "type": "array" }, "body_html": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "HTML body content", "title": "Body Html" }, "body_html_sanitized": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Pre-sanitized HTML from the server nh3 pipeline (TIDY-7319). Null when this row has not yet been sanitized at ingest.", "title": "Body Html Sanitized" }, "body_markdown": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Markdown body content", "title": "Body Markdown" }, "body_text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Plain text body content", "title": "Body Text" }, "cc_addresses": { "description": "CC addresses", "items": { "type": "string" }, "title": "Cc Addresses", "type": "array" }, "content_char_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Character count of message_content", "title": "Content Char Count" }, "display_mode": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Display mode: full or summary", "title": "Display Mode" }, "enrichment_overlays": { "anyOf": [ {}, { "type": "null" } ], "default": null, "description": "JSONB array of enrichment overlays", "title": "Enrichment Overlays" }, "from_address": { "description": "Sender email address", "title": "From Address", "type": "string" }, "from_contact_approval_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Approval status of resolved sender contact: 'approved', 'pending_review', or 'dismissed'", "title": "From Contact Approval Status" }, "from_contact_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "default": null, "description": "UUID of matching contact", "title": "From Contact Id" }, "from_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Sender display name", "title": "From Name" }, "from_photo_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Sender contact photo URL", "title": "From Photo Url" }, "has_attachments": { "default": false, "description": "Has attachments", "title": "Has Attachments", "type": "boolean" }, "id": { "description": "Email UUID (email_canonical.id)", "format": "uuid", "title": "Id", "type": "string" }, "is_archived": { "description": "Whether email is in archive", "title": "Is Archived", "type": "boolean" }, "is_from_user": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "description": "True if email was sent by the current user", "title": "Is From User" }, "is_read": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "description": "Whether email has been read", "title": "Is Read" }, "llm_confidence": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "description": "Confidence score", "title": "Llm Confidence" }, "message_content": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Net-new message content only", "title": "Message Content" }, "routing_decision": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Routing decision", "title": "Routing Decision" }, "sent_at": { "description": "Email sent timestamp", "format": "date-time", "title": "Sent At", "type": "string" }, "snippet": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Body preview (150 chars)", "title": "Snippet" }, "subject": { "description": "Email subject line", "title": "Subject", "type": "string" }, "tags": { "description": "Semantic tags extracted for cross-primitive linking", "items": { "type": "string" }, "title": "Tags", "type": "array" }, "thread_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "default": null, "description": "Conversation thread UUID", "title": "Thread Id" }, "to_addresses": { "description": "Recipients", "items": { "type": "string" }, "title": "To Addresses", "type": "array" }, "triage_category": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Triage category", "title": "Triage Category" }, "triage_label": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Triage label: to_respond, fyi, low_priority", "title": "Triage Label" }, "triage_summary": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "LLM summary", "title": "Triage Summary" }, "type": { "const": "email", "default": "email", "description": "Item type discriminator", "title": "Type", "type": "string" }, "user_labels": { "description": "User labels", "items": { "type": "string" }, "title": "User Labels", "type": "array" } }, "required": [ "id", "subject", "from_address", "sent_at", "is_archived" ], "title": "ThreadEmailItem", "type": "object" }, "ThreadMergeRequest": { "properties": { "thread_ids": { "items": { "format": "uuid", "type": "string" }, "minItems": 2, "title": "Thread Ids", "type": "array" } }, "required": [ "thread_ids" ], "title": "ThreadMergeRequest", "type": "object" }, "ThreadMergeResponse": { "properties": { "canonical_thread_id": { "format": "uuid", "title": "Canonical Thread Id", "type": "string" }, "merged_count": { "title": "Merged Count", "type": "integer" }, "total_emails": { "title": "Total Emails", "type": "integer" } }, "required": [ "canonical_thread_id", "merged_count", "total_emails" ], "title": "ThreadMergeResponse", "type": "object" }, "ThreadMuteRequest": { "description": "Request body for muting/unmuting a comment thread (TIDY-11596).\n\nA thread participant sets ``muted=true`` to stop reply notifications for that\nthread, or ``muted=false`` to resubscribe. Agents ignore mute (always\nsubscribed); this is the per-human, per-thread control.", "properties": { "muted": { "description": "True to mute reply notifications for this thread.", "title": "Muted", "type": "boolean" } }, "required": [ "muted" ], "title": "ThreadMuteRequest", "type": "object" }, "ThreadMuteResponse": { "properties": { "changed": { "description": "True if the mute state actually changed (idempotent no-op otherwise).", "title": "Changed", "type": "boolean" }, "muted": { "title": "Muted", "type": "boolean" }, "thread_root_id": { "format": "uuid", "title": "Thread Root Id", "type": "string" } }, "required": [ "thread_root_id", "muted", "changed" ], "title": "ThreadMuteResponse", "type": "object" }, "ThreadNote": { "description": "A private note attached to a specific email in a thread.\n\nNotes are anchored to both a thread_id (for grouping) and an email_id\n(for positioning in the conversation timeline).\n\nAttributes:\n type: Discriminator field, always 'note'\n id: Note UUID\n email_id: UUID of the email this note is attached to\n thread_id: UUID of the conversation thread\n content: Note text content\n created_at: When the note was created\n created_by: UUID of the user who created the note\n note_type: Source of note (user, system, recipe)\n\nExample:\n {\n \"type\": \"note\",\n \"id\": \"uuid-here\",\n \"email_id\": \"email-uuid\",\n \"thread_id\": \"thread-uuid\",\n \"content\": \"Remember to follow up on this\",\n \"created_at\": \"2026-01-14T10:30:00Z\",\n \"created_by\": \"user-uuid\",\n \"note_type\": \"user\"\n }", "properties": { "content": { "description": "Note text content", "title": "Content", "type": "string" }, "created_at": { "description": "When the note was created", "format": "date-time", "title": "Created At", "type": "string" }, "created_by": { "description": "UUID of user who created the note", "format": "uuid", "title": "Created By", "type": "string" }, "email_id": { "description": "UUID of email this note is attached to", "format": "uuid", "title": "Email Id", "type": "string" }, "id": { "description": "Note UUID", "format": "uuid", "title": "Id", "type": "string" }, "note_type": { "default": "user", "description": "Source: user, system, recipe", "title": "Note Type", "type": "string" }, "thread_id": { "description": "UUID of the conversation thread", "format": "uuid", "title": "Thread Id", "type": "string" }, "type": { "const": "note", "default": "note", "description": "Item type discriminator", "title": "Type", "type": "string" } }, "required": [ "id", "email_id", "thread_id", "content", "created_at", "created_by" ], "title": "ThreadNote", "type": "object" }, "ThreadReadRequest": { "properties": { "last_read_event_id": { "minLength": 1, "title": "Last Read Event Id", "type": "string" }, "native_receipt_sent": { "default": false, "title": "Native Receipt Sent", "type": "boolean" }, "operation_id": { "format": "uuid", "title": "Operation Id", "type": "string" } }, "required": [ "last_read_event_id", "operation_id" ], "title": "ThreadReadRequest", "type": "object" }, "ThreadReadResponse": { "properties": { "last_read_event_id": { "title": "Last Read Event Id", "type": "string" }, "receipt_source": { "enum": [ "matrix-threaded", "tidy-fallback" ], "title": "Receipt Source", "type": "string" }, "replayed": { "title": "Replayed", "type": "boolean" }, "room_id": { "title": "Room Id", "type": "string" }, "root_event_id": { "title": "Root Event Id", "type": "string" }, "unread_count": { "title": "Unread Count", "type": "integer" }, "updated_at": { "format": "date-time", "title": "Updated At", "type": "string" } }, "required": [ "room_id", "root_event_id", "last_read_event_id", "unread_count", "receipt_source", "replayed", "updated_at" ], "title": "ThreadReadResponse", "type": "object" }, "ThreadUnfollowResponse": { "properties": { "status": { "title": "Status", "type": "string" }, "thread_id": { "format": "uuid", "title": "Thread Id", "type": "string" } }, "required": [ "thread_id", "status" ], "title": "ThreadUnfollowResponse", "type": "object" }, "ThreadUnfollowStatusResponse": { "properties": { "is_unfollowed": { "title": "Is Unfollowed", "type": "boolean" }, "thread_id": { "format": "uuid", "title": "Thread Id", "type": "string" } }, "required": [ "thread_id", "is_unfollowed" ], "title": "ThreadUnfollowStatusResponse", "type": "object" }, "ThreadUnmergeResponse": { "properties": { "restored_threads": { "items": { "format": "uuid", "type": "string" }, "title": "Restored Threads", "type": "array" } }, "required": [ "restored_threads" ], "title": "ThreadUnmergeResponse", "type": "object" }, "ThreadWithNotesResponse": { "description": "Thread response with merged timeline of emails and notes.\n\nUsed in GET /api/v1/emails/thread/{thread_id} response.\nItems are sorted chronologically (sent_at for emails, created_at for notes).\n\nAttributes:\n thread_id: Thread UUID identifier\n items: Merged timeline of emails and notes\n total: Count of items (emails + notes)\n\nExample:\n {\n \"thread_id\": \"uuid-here\",\n \"items\": [\n {\"type\": \"email\", \"id\": \"...\", \"sent_at\": \"...\", ...},\n {\"type\": \"note\", \"id\": \"...\", \"email_id\": \"...\", \"created_at\": \"...\", ...},\n {\"type\": \"email\", \"id\": \"...\", \"sent_at\": \"...\", ...}\n ],\n \"total\": 3\n }", "properties": { "display_subject": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "User-renamed subject (TIDY-4096)", "title": "Display Subject" }, "items": { "description": "Merged timeline of emails and notes, chronologically sorted", "items": { "anyOf": [ { "$ref": "#/components/schemas/ThreadEmailItem" }, { "$ref": "#/components/schemas/ThreadNote" } ] }, "title": "Items", "type": "array" }, "message_count": { "default": 0, "description": "Number of emails in thread (excludes notes)", "title": "Message Count", "type": "integer" }, "participant_count": { "default": 0, "description": "Number of unique participants", "title": "Participant Count", "type": "integer" }, "subject": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Thread subject (from first email)", "title": "Subject" }, "suggested_subject": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "AI-suggested subject (TIDY-4100)", "title": "Suggested Subject" }, "thread_id": { "description": "Thread UUID identifier", "format": "uuid", "title": "Thread Id", "type": "string" }, "total": { "description": "Count of items (emails + notes)", "title": "Total", "type": "integer" } }, "required": [ "thread_id", "items", "total" ], "title": "ThreadWithNotesResponse", "type": "object" }, "ThresholdResultResponse": { "properties": { "comparator": { "title": "Comparator", "type": "string" }, "detail": { "title": "Detail", "type": "string" }, "name": { "title": "Name", "type": "string" }, "observed": { "anyOf": [ { "type": "number" }, { "type": "integer" }, { "type": "null" } ], "title": "Observed" }, "passed": { "title": "Passed", "type": "boolean" }, "required": { "anyOf": [ { "type": "number" }, { "type": "integer" } ], "title": "Required" } }, "required": [ "name", "passed", "observed", "required", "comparator", "detail" ], "title": "ThresholdResultResponse", "type": "object" }, "TidyInferenceLaneModelsResponse": { "properties": { "models": { "items": { "type": "string" }, "title": "Models", "type": "array" } }, "title": "TidyInferenceLaneModelsResponse", "type": "object" }, "TidyInferenceModelsResponse": { "properties": { "models": { "items": { "type": "string" }, "title": "Models", "type": "array" } }, "title": "TidyInferenceModelsResponse", "type": "object" }, "TierAccountCount": { "properties": { "account_count": { "title": "Account Count", "type": "integer" }, "tier_id": { "title": "Tier Id", "type": "string" } }, "required": [ "tier_id", "account_count" ], "title": "TierAccountCount", "type": "object" }, "TierAssignRequest": { "properties": { "tier_id": { "title": "Tier Id", "type": "string" } }, "required": [ "tier_id" ], "title": "TierAssignRequest", "type": "object" }, "TierAssignResponse": { "properties": { "takes_effect_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Takes Effect At" }, "tenant_id": { "title": "Tenant Id", "type": "string" }, "tier_id": { "title": "Tier Id", "type": "string" }, "via_stripe": { "default": false, "title": "Via Stripe", "type": "boolean" } }, "required": [ "tenant_id", "tier_id" ], "title": "TierAssignResponse", "type": "object" }, "TierBreakdown": { "description": "One row of the by-tier aggregation card.\n\n``tier`` is the canonical label (low/medium/high/critical) or ``None``\nfor legacy/non-tiered rows. The frontend renders ``None`` as\n\"Synchronous (no tier)\".", "properties": { "avg_cost_usd": { "default": 0.0, "title": "Avg Cost Usd", "type": "number" }, "count": { "default": 0, "title": "Count", "type": "integer" }, "tier": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Tier" }, "total_cost_usd": { "default": 0.0, "title": "Total Cost Usd", "type": "number" }, "total_tokens": { "default": 0, "title": "Total Tokens", "type": "integer" } }, "title": "TierBreakdown", "type": "object" }, "TimeAllocationPeriod": { "properties": { "email_hours_estimated": { "title": "Email Hours Estimated", "type": "number" }, "focus_hours": { "title": "Focus Hours", "type": "number" }, "meeting_hours": { "title": "Meeting Hours", "type": "number" }, "period": { "title": "Period", "type": "string" } }, "required": [ "period", "meeting_hours", "email_hours_estimated", "focus_hours" ], "title": "TimeAllocationPeriod", "type": "object" }, "TimeAllocationResponse": { "properties": { "by_period": { "items": { "$ref": "#/components/schemas/TimeAllocationPeriod" }, "title": "By Period", "type": "array" }, "email_hours_estimated": { "title": "Email Hours Estimated", "type": "number" }, "email_pct": { "title": "Email Pct", "type": "number" }, "focus_hours": { "title": "Focus Hours", "type": "number" }, "focus_pct": { "title": "Focus Pct", "type": "number" }, "meeting_hours": { "title": "Meeting Hours", "type": "number" }, "meeting_pct": { "title": "Meeting Pct", "type": "number" }, "total_working_hours": { "title": "Total Working Hours", "type": "number" } }, "required": [ "total_working_hours", "meeting_hours", "email_hours_estimated", "focus_hours", "meeting_pct", "email_pct", "focus_pct", "by_period" ], "title": "TimeAllocationResponse", "type": "object" }, "TimeBreakdownGroup": { "properties": { "facet_type": { "title": "Facet Type", "type": "string" }, "pct": { "title": "Pct", "type": "number" }, "sessions": { "title": "Sessions", "type": "integer" }, "tracked_hours": { "title": "Tracked Hours", "type": "number" }, "tracked_seconds": { "title": "Tracked Seconds", "type": "integer" } }, "required": [ "facet_type", "tracked_seconds", "tracked_hours", "sessions", "pct" ], "title": "TimeBreakdownGroup", "type": "object" }, "TimeByMode": { "properties": { "hours": { "title": "Hours", "type": "number" }, "mode": { "title": "Mode", "type": "string" }, "seconds": { "title": "Seconds", "type": "integer" }, "sessions": { "title": "Sessions", "type": "integer" } }, "required": [ "mode", "seconds", "hours", "sessions" ], "title": "TimeByMode", "type": "object" }, "TimeCoachingCard": { "properties": { "action": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "title": "Action" }, "dismissible": { "default": true, "title": "Dismissible", "type": "boolean" }, "impact": { "title": "Impact", "type": "string" }, "observation": { "title": "Observation", "type": "string" }, "rule_id": { "title": "Rule Id", "type": "string" }, "severity": { "title": "Severity", "type": "string" }, "technique": { "title": "Technique", "type": "string" } }, "required": [ "rule_id", "severity", "observation", "impact", "technique" ], "title": "TimeCoachingCard", "type": "object" }, "TimeCoachingResponse": { "properties": { "cards": { "items": { "$ref": "#/components/schemas/TimeCoachingCard" }, "title": "Cards", "type": "array" } }, "required": [ "cards" ], "title": "TimeCoachingResponse", "type": "object" }, "TimeCorrelationsResponse": { "properties": { "active_days": { "title": "Active Days", "type": "integer" }, "context_switches": { "title": "Context Switches", "type": "integer" }, "flow_seconds": { "title": "Flow Seconds", "type": "integer" }, "planned_pct": { "title": "Planned Pct", "type": "number" }, "planned_seconds": { "title": "Planned Seconds", "type": "integer" }, "switches_per_active_day": { "title": "Switches Per Active Day", "type": "number" }, "task_focus_pct": { "title": "Task Focus Pct", "type": "number" }, "task_seconds": { "title": "Task Seconds", "type": "integer" }, "total_seconds": { "title": "Total Seconds", "type": "integer" }, "total_sessions": { "title": "Total Sessions", "type": "integer" } }, "required": [ "total_sessions", "active_days", "context_switches", "switches_per_active_day", "task_focus_pct", "planned_pct", "planned_seconds", "flow_seconds", "task_seconds", "total_seconds" ], "title": "TimeCorrelationsResponse", "type": "object" }, "TimeHeatmapDay": { "properties": { "achieved": { "title": "Achieved", "type": "boolean" }, "date": { "title": "Date", "type": "string" }, "sessions": { "default": 0, "title": "Sessions", "type": "integer" }, "value": { "default": 0, "title": "Value", "type": "integer" } }, "required": [ "date", "achieved" ], "title": "TimeHeatmapDay", "type": "object" }, "TimeHeatmapResponse": { "properties": { "days": { "items": { "$ref": "#/components/schemas/TimeHeatmapDay" }, "title": "Days", "type": "array" }, "total_active_days": { "title": "Total Active Days", "type": "integer" }, "total_tracked_seconds": { "title": "Total Tracked Seconds", "type": "integer" }, "year": { "title": "Year", "type": "integer" } }, "required": [ "year", "days", "total_tracked_seconds", "total_active_days" ], "title": "TimeHeatmapResponse", "type": "object" }, "TimeLogCreateRequest": { "description": "Create a time-log row.\n\nAccepts an optional client-supplied `id` so PowerSync CRUD uploads that\nallocated the UUID locally persist under the same id. `target_typed_id`\ncarries the typed-id of the timed primitive (e.g. `A-`); it may be\nNULL until a naked timer is classified.", "properties": { "computed_value": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Computed Value" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "duration_seconds": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Duration Seconds" }, "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Client-provided id for PowerSync sync", "title": "Id" }, "idle_classification": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Idle Classification" }, "idle_seconds": { "default": 0, "title": "Idle Seconds", "type": "integer" }, "mode": { "default": "flow", "title": "Mode", "type": "string" }, "snapshot_rate": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Snapshot Rate" }, "source_facet_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Source Facet Type" }, "started_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Started At" }, "stopped_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Stopped At" }, "target_typed_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Target Typed Id" }, "value_currency": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Value Currency" }, "visibility": { "default": "private", "title": "Visibility", "type": "string" } }, "title": "TimeLogCreateRequest", "type": "object" }, "TimeLogResponse": { "description": "A single time-log ledger row returned by the API.", "properties": { "computed_value": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "title": "Computed Value" }, "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "deleted_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Deleted At" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Description" }, "duration_seconds": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Duration Seconds" }, "id": { "title": "Id", "type": "string" }, "idle_classification": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Idle Classification" }, "idle_seconds": { "default": 0, "title": "Idle Seconds", "type": "integer" }, "mode": { "default": "flow", "title": "Mode", "type": "string" }, "owner_id": { "title": "Owner Id", "type": "string" }, "snapshot_rate": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "title": "Snapshot Rate" }, "source_facet_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Source Facet Type" }, "started_at": { "format": "date-time", "title": "Started At", "type": "string" }, "stopped_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Stopped At" }, "target_typed_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Target Typed Id" }, "tenant_id": { "title": "Tenant Id", "type": "string" }, "updated_at": { "format": "date-time", "title": "Updated At", "type": "string" }, "value_currency": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Value Currency" }, "visibility": { "default": "private", "title": "Visibility", "type": "string" } }, "required": [ "id", "tenant_id", "owner_id", "started_at", "created_at", "updated_at" ], "title": "TimeLogResponse", "type": "object" }, "TimeLogUpdateRequest": { "description": "Partial update (stop / edit / reassign).\n\nEvery synced column is accepted so PowerSync PATCH round-trips succeed.", "properties": { "computed_value": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Computed Value" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "duration_seconds": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Duration Seconds" }, "idle_classification": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Idle Classification" }, "idle_seconds": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Idle Seconds" }, "mode": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Mode" }, "snapshot_rate": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Snapshot Rate" }, "source_facet_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Source Facet Type" }, "started_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Started At" }, "stopped_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Stopped At" }, "target_typed_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Target Typed Id" }, "value_currency": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Value Currency" }, "visibility": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Visibility" } }, "title": "TimeLogUpdateRequest", "type": "object" }, "TimeStreakResponse": { "properties": { "current_streak": { "title": "Current Streak", "type": "integer" }, "first_active_date": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "First Active Date" }, "freezes_available": { "title": "Freezes Available", "type": "integer" }, "freezes_used": { "title": "Freezes Used", "type": "integer" }, "is_active": { "title": "Is Active", "type": "boolean" }, "last_active_date": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Last Active Date" }, "record_streak": { "title": "Record Streak", "type": "integer" }, "total_active_days": { "title": "Total Active Days", "type": "integer" } }, "required": [ "current_streak", "record_streak", "freezes_used", "freezes_available", "total_active_days", "is_active" ], "title": "TimeStreakResponse", "type": "object" }, "TimeSummaryResponse": { "properties": { "active_days": { "title": "Active Days", "type": "integer" }, "avg_session_seconds": { "title": "Avg Session Seconds", "type": "number" }, "break_seconds": { "title": "Break Seconds", "type": "integer" }, "by_mode": { "items": { "$ref": "#/components/schemas/TimeByMode" }, "title": "By Mode", "type": "array" }, "focus_pct": { "title": "Focus Pct", "type": "number" }, "session_count": { "title": "Session Count", "type": "integer" }, "tracked_hours": { "title": "Tracked Hours", "type": "number" }, "tracked_seconds": { "title": "Tracked Seconds", "type": "integer" } }, "required": [ "tracked_seconds", "tracked_hours", "session_count", "avg_session_seconds", "active_days", "focus_pct", "break_seconds", "by_mode" ], "title": "TimeSummaryResponse", "type": "object" }, "TimeVolumePeriod": { "properties": { "period": { "title": "Period", "type": "string" }, "sessions": { "title": "Sessions", "type": "integer" }, "tracked_hours": { "title": "Tracked Hours", "type": "number" }, "tracked_seconds": { "title": "Tracked Seconds", "type": "integer" } }, "required": [ "period", "tracked_seconds", "tracked_hours", "sessions" ], "title": "TimeVolumePeriod", "type": "object" }, "TimelineCondenseBucket": { "properties": { "bucket_key": { "maxLength": 120, "minLength": 1, "title": "Bucket Key", "type": "string" }, "cards": { "items": { "$ref": "#/components/schemas/TimelineCondenseCard" }, "title": "Cards", "type": "array" } }, "required": [ "bucket_key" ], "title": "TimelineCondenseBucket", "type": "object" }, "TimelineCondenseCard": { "properties": { "id": { "maxLength": 200, "minLength": 1, "title": "Id", "type": "string" }, "text": { "default": "", "maxLength": 5000, "title": "Text", "type": "string" }, "title": { "default": "", "maxLength": 500, "title": "Title", "type": "string" } }, "required": [ "id" ], "title": "TimelineCondenseCard", "type": "object" }, "TimelineCondenseRequest": { "properties": { "buckets": { "items": { "$ref": "#/components/schemas/TimelineCondenseBucket" }, "minItems": 1, "title": "Buckets", "type": "array" }, "target_granularity": { "enum": [ "day", "week", "month", "year" ], "title": "Target Granularity", "type": "string" } }, "required": [ "buckets", "target_granularity" ], "title": "TimelineCondenseRequest", "type": "object" }, "TimelineCondenseResponse": { "properties": { "llm_usage": { "$ref": "#/components/schemas/TimelineCondenseUsage" }, "results": { "items": { "$ref": "#/components/schemas/TimelineCondensedBucket" }, "title": "Results", "type": "array" } }, "required": [ "results", "llm_usage" ], "title": "TimelineCondenseResponse", "type": "object" }, "TimelineCondenseUsage": { "properties": { "completion_tokens": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Completion Tokens" }, "model": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Model" }, "prompt_tokens": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Prompt Tokens" }, "request_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Request Id" }, "total_tokens": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Total Tokens" } }, "title": "TimelineCondenseUsage", "type": "object" }, "TimelineCondensedBucket": { "properties": { "bucket_key": { "maxLength": 120, "minLength": 1, "title": "Bucket Key", "type": "string" }, "condensed_text": { "maxLength": 2000, "minLength": 1, "title": "Condensed Text", "type": "string" } }, "required": [ "bucket_key", "condensed_text" ], "title": "TimelineCondensedBucket", "type": "object" }, "TimelinePeriod": { "properties": { "interaction_count": { "title": "Interaction Count", "type": "integer" }, "met": { "title": "Met", "type": "boolean" }, "period_end": { "title": "Period End", "type": "string" }, "period_start": { "title": "Period Start", "type": "string" } }, "required": [ "period_start", "period_end", "interaction_count", "met" ], "title": "TimelinePeriod", "type": "object" }, "TimelineResponse": { "properties": { "entries": { "items": { "additionalProperties": true, "type": "object" }, "title": "Entries", "type": "array" }, "limit": { "title": "Limit", "type": "integer" }, "offset": { "title": "Offset", "type": "integer" }, "session_id": { "format": "uuid", "title": "Session Id", "type": "string" } }, "required": [ "session_id", "entries", "limit", "offset" ], "title": "TimelineResponse", "type": "object" }, "TimerSessionResponse": { "description": "Timer session response payload (derived from a time_logs row).", "properties": { "elapsed_seconds": { "title": "Elapsed Seconds", "type": "integer" }, "id": { "title": "Id", "type": "string" }, "paused_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Paused At" }, "started_at": { "format": "date-time", "title": "Started At", "type": "string" }, "stopped_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Stopped At" }, "target_id": { "title": "Target Id", "type": "string" }, "target_type": { "title": "Target Type", "type": "string" } }, "required": [ "id", "target_type", "target_id", "started_at", "elapsed_seconds" ], "title": "TimerSessionResponse", "type": "object" }, "TimerTargetType": { "description": "Supported timer target object types.", "enum": [ "task", "calendar_event", "note", "project" ], "title": "TimerTargetType", "type": "string" }, "ToggleChecklistItemOp": { "additionalProperties": false, "properties": { "checked": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Checked" }, "index": { "anyOf": [ { "minimum": 0.0, "type": "integer" }, { "type": "null" } ], "title": "Index" }, "op": { "const": "toggle_checklist_item", "title": "Op", "type": "string" }, "text": { "anyOf": [ { "maxLength": 2000, "type": "string" }, { "type": "null" } ], "title": "Text" } }, "required": [ "op" ], "title": "ToggleChecklistItemOp", "type": "object" }, "TogglePromoCodeRequest": { "properties": { "active": { "title": "Active", "type": "boolean" } }, "required": [ "active" ], "title": "TogglePromoCodeRequest", "type": "object" }, "ToggleResponse": { "properties": { "enabled": { "title": "Enabled", "type": "boolean" }, "id": { "title": "Id", "type": "string" } }, "required": [ "id", "enabled" ], "title": "ToggleResponse", "type": "object" }, "TokenResponse": { "description": "OAuth 2.1 token endpoint response (RFC 6749 §5.1).\n\n`refresh_token` is absent for the client_credentials and\ntoken-exchange grants. `issued_token_type` is present only on the\nRFC 8693 token-exchange response (RFC 8693 §2.2.1).", "properties": { "access_token": { "title": "Access Token", "type": "string" }, "expires_in": { "title": "Expires In", "type": "integer" }, "issued_token_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Issued Token Type" }, "refresh_token": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Refresh Token" }, "scope": { "title": "Scope", "type": "string" }, "token_type": { "title": "Token Type", "type": "string" } }, "required": [ "access_token", "token_type", "expires_in", "scope" ], "title": "TokenResponse", "type": "object" }, "ToneLevel": { "description": "Tone levels for AI-generated drafts.", "enum": [ "casual", "standard", "formal" ], "title": "ToneLevel", "type": "string" }, "ToolPresence": { "additionalProperties": false, "properties": { "daemon_state": { "anyOf": [ { "enum": [ "responding", "refused", "unreachable" ], "type": "string" }, { "type": "null" } ], "title": "Daemon State" }, "daemon_version": { "anyOf": [ { "maxLength": 200, "type": "string" }, { "type": "null" } ], "title": "Daemon Version" }, "error": { "anyOf": [ { "maxLength": 300, "type": "string" }, { "type": "null" } ], "title": "Error" }, "present": { "title": "Present", "type": "boolean" }, "provenance": { "anyOf": [ { "enum": [ "workshop_runtime", "host" ], "type": "string" }, { "type": "null" } ], "title": "Provenance" }, "runtime_sha256": { "anyOf": [ { "pattern": "^[0-9a-f]{64}$", "type": "string" }, { "type": "null" } ], "title": "Runtime Sha256" }, "version": { "anyOf": [ { "maxLength": 200, "type": "string" }, { "type": "null" } ], "title": "Version" } }, "required": [ "present", "version" ], "title": "ToolPresence", "type": "object" }, "TopContact": { "properties": { "avg_response_time_seconds": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Avg Response Time Seconds" }, "contact_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Contact Id" }, "display_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Display Name" }, "email_address": { "title": "Email Address", "type": "string" }, "last_email_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Last Email At" }, "received_count": { "title": "Received Count", "type": "integer" }, "sent_count": { "title": "Sent Count", "type": "integer" }, "thread_count": { "title": "Thread Count", "type": "integer" }, "trend": { "title": "Trend", "type": "string" } }, "required": [ "email_address", "display_name", "contact_id", "received_count", "sent_count", "thread_count", "avg_response_time_seconds", "last_email_at", "trend" ], "title": "TopContact", "type": "object" }, "TopContactStat": { "properties": { "email_count": { "title": "Email Count", "type": "integer" }, "name": { "title": "Name", "type": "string" } }, "required": [ "name", "email_count" ], "title": "TopContactStat", "type": "object" }, "TopThread": { "properties": { "last_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last At" }, "message_count": { "title": "Message Count", "type": "integer" }, "subject": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Subject" }, "thread_id": { "format": "uuid", "title": "Thread Id", "type": "string" } }, "required": [ "thread_id", "subject", "message_count", "last_at" ], "title": "TopThread", "type": "object" }, "TopupRequest": { "properties": { "pack_id": { "title": "Pack Id", "type": "string" } }, "required": [ "pack_id" ], "title": "TopupRequest", "type": "object" }, "TopupResponse": { "properties": { "credits": { "title": "Credits", "type": "integer" }, "pack_id": { "title": "Pack Id", "type": "string" }, "session_id": { "title": "Session Id", "type": "string" }, "url": { "title": "Url", "type": "string" } }, "required": [ "url", "session_id", "pack_id", "credits" ], "title": "TopupResponse", "type": "object" }, "TouchResponse": { "properties": { "id": { "description": "Recorded attribution event id", "title": "Id", "type": "string" } }, "required": [ "id" ], "title": "TouchResponse", "type": "object" }, "TownBulletinEvent": { "description": "A calendar event harvested from email in the trailing window as of the\nday. ``harvested_at`` is when the provenance edge was written; ``expires_at``\n= harvested_at + 30 days so the frontend can animate drop-offs in playback.", "properties": { "expires_at": { "format": "date-time", "title": "Expires At", "type": "string" }, "harvested_at": { "format": "date-time", "title": "Harvested At", "type": "string" }, "id": { "title": "Id", "type": "string" }, "start_time": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Start Time" }, "summary": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Summary" } }, "required": [ "id", "harvested_at", "expires_at" ], "title": "TownBulletinEvent", "type": "object" }, "TownPendingContact": { "description": "A contact still pending review as of the selected day — a \"resident\" the\nscene renders. ``source_email_id`` links back to the email that proposed it.", "properties": { "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "display_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Display Name" }, "id": { "title": "Id", "type": "string" }, "source_email_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Source Email Id" }, "source_from": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Source From" }, "source_subject": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Source Subject" } }, "required": [ "id", "created_at" ], "title": "TownPendingContact", "type": "object" }, "TrackViewResponse": { "properties": { "view_count": { "title": "View Count", "type": "integer" } }, "required": [ "view_count" ], "title": "TrackViewResponse", "type": "object" }, "TrackerStateResponse": { "description": "Server-backed tracker state for a journal date.", "properties": { "date": { "description": "Tracker date", "format": "date", "title": "Date", "type": "string" }, "facet_slug": { "description": "Facet slug", "examples": [ "journal" ], "title": "Facet Slug", "type": "string" }, "journal_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Journal page id for the requested date, when present", "title": "Journal Id" }, "proxy_block_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Calendar proxy block id for the journal date, when present", "title": "Proxy Block Id" }, "rendering_mode": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Facet rendering mode (tracker-bar, tracker-circle, etc.)", "title": "Rendering Mode" }, "schema": { "description": "Facet schema fields for the tracker", "items": { "additionalProperties": true, "type": "object" }, "title": "Schema", "type": "array" }, "values": { "additionalProperties": true, "description": "Persisted tracker values keyed by field id", "title": "TrackerStateValues", "type": "object" } }, "required": [ "date", "facet_slug" ], "title": "TrackerStateResponse", "type": "object" }, "TrackerUpdateRequest": { "description": "Persist a single tracker field value for a journal date.", "properties": { "facet_slug": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional facet slug override", "title": "Facet Slug" }, "habit_id": { "description": "Tracker field key to update", "title": "Habit Id", "type": "string" }, "stored_value": { "description": "Persisted tracker value (boolean for toggle, number for counter)", "title": "Stored Value" } }, "required": [ "habit_id", "stored_value" ], "title": "TrackerUpdateRequest", "type": "object" }, "TranscriptEpisode": { "description": "The env's episode this transcript belongs to (resolved via the ingest log\nby ``(rss_feed_url, guid)`` — NEVER by assuming the pipeline UUID == env id).", "properties": { "duration_s": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "title": "Duration S" }, "id": { "title": "Id", "type": "string" }, "show": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Show" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Title" }, "webpage_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Webpage Url" } }, "required": [ "id" ], "title": "TranscriptEpisode", "type": "object" }, "TranscriptNoteResponse": { "properties": { "note_id": { "title": "Note Id", "type": "string" } }, "required": [ "note_id" ], "title": "TranscriptNoteResponse", "type": "object" }, "TranscriptResponse": { "description": "Full speaker-attributed transcript for the env's CURRENT version of an\nepisode resolved via ``(rss_feed_url, guid)``.", "properties": { "episode": { "$ref": "#/components/schemas/TranscriptEpisode" }, "num_speakers": { "default": 0, "title": "Num Speakers", "type": "integer" }, "segments": { "default": [], "items": { "$ref": "#/components/schemas/TranscriptSegment" }, "title": "Segments", "type": "array" }, "version": { "$ref": "#/components/schemas/TranscriptVersion" } }, "required": [ "episode", "version" ], "title": "TranscriptResponse", "type": "object" }, "TranscriptSegment": { "description": "One speaker-attributed turn. ``speaker_name``/``name_confidence`` are null\nwhen the namer abstained — the viewer renders the diarization label only.", "properties": { "end": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "title": "End" }, "name_confidence": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "title": "Name Confidence" }, "speaker_label": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Speaker Label" }, "speaker_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Speaker Name" }, "start": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "title": "Start" }, "text": { "default": "", "title": "Text", "type": "string" } }, "title": "TranscriptSegment", "type": "object" }, "TranscriptVersion": { "description": "The CURRENT transcript version (``is_current``) + its model provenance.", "properties": { "created_at": { "anyOf": [ {}, { "type": "null" } ], "default": null, "title": "Created At" }, "id": { "title": "Id", "type": "string" }, "pipeline_version": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Pipeline Version" }, "pyannote_model_version": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Pyannote Model Version" }, "whisper_model_version": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Whisper Model Version" } }, "required": [ "id" ], "title": "TranscriptVersion", "type": "object" }, "TranscriptVersionItem": { "properties": { "created_at": { "title": "Created At", "type": "string" }, "is_current": { "title": "Is Current", "type": "boolean" }, "is_soft_deleted": { "title": "Is Soft Deleted", "type": "boolean" }, "pinned_cut_count": { "title": "Pinned Cut Count", "type": "integer" }, "pipeline_version": { "title": "Pipeline Version", "type": "string" }, "pyannote_model_version": { "title": "Pyannote Model Version", "type": "string" }, "version_id": { "title": "Version Id", "type": "string" }, "whisper_model_version": { "title": "Whisper Model Version", "type": "string" } }, "required": [ "version_id", "whisper_model_version", "pyannote_model_version", "pipeline_version", "is_current", "is_soft_deleted", "pinned_cut_count", "created_at" ], "title": "TranscriptVersionItem", "type": "object" }, "TransformRequest": { "properties": { "input": { "description": "The value to transform (text or JSON).", "title": "Input" }, "instructions": { "anyOf": [ { "maxLength": 8000, "type": "string" }, { "type": "null" } ], "description": "Optional shaping instructions.", "title": "Instructions" }, "output_schema": { "additionalProperties": true, "description": "JSON Schema object describing the output. Per-property `ai_instructions` annotations shape each field's extraction.", "title": "Output Schema", "type": "object" }, "tier": { "default": "low", "description": "Model tier: low | medium | high (cheap by default).", "enum": [ "low", "medium", "high" ], "title": "Tier", "type": "string" }, "workflow_execution_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Workflow execution id for cost attribution (set by the sandbox).", "title": "Workflow Execution Id" } }, "required": [ "input", "output_schema" ], "title": "TransformRequest", "type": "object" }, "TransformResponse": { "properties": { "model": { "title": "Model", "type": "string" }, "output": { "additionalProperties": true, "description": "Schema-valid transform output.", "title": "Output", "type": "object" }, "tier": { "title": "Tier", "type": "string" }, "tokens_in": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Tokens In" }, "tokens_out": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Tokens Out" } }, "required": [ "output", "tier", "model" ], "title": "TransformResponse", "type": "object" }, "TransitionRequest": { "properties": { "action": { "enum": [ "activate", "supersede", "retire", "quarantine", "rollback" ], "title": "Action", "type": "string" }, "evidence": { "additionalProperties": true, "title": "Evidence", "type": "object" }, "reason": { "minLength": 1, "title": "Reason", "type": "string" }, "rebind_rollout_ids": { "items": { "format": "uuid", "type": "string" }, "title": "Rebind Rollout Ids", "type": "array" } }, "required": [ "action", "reason" ], "title": "TransitionRequest", "type": "object" }, "TransitionResponse": { "properties": { "affected": { "additionalProperties": true, "title": "Affected", "type": "object" }, "lifecycle_event_id": { "format": "uuid", "title": "Lifecycle Event Id", "type": "string" }, "previous_state": { "title": "Previous State", "type": "string" }, "state": { "title": "State", "type": "string" }, "version_id": { "format": "uuid", "title": "Version Id", "type": "string" } }, "required": [ "version_id", "previous_state", "state", "affected", "lifecycle_event_id" ], "title": "TransitionResponse", "type": "object" }, "TriageDropEmailSnapshot": { "description": "Pre-drop state for one dropped message (the message-move half of undo).", "properties": { "email_id": { "title": "Email Id", "type": "string" }, "prior_category_forced": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Prior Category Forced" }, "prior_inbox_split": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Prior Inbox Split" }, "prior_screening_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Prior Screening Status" } }, "required": [ "email_id" ], "title": "TriageDropEmailSnapshot", "type": "object" }, "TriageDropRequest": { "description": "Teach the sender rule for a split and move the dropped message(s).", "properties": { "email_ids": { "items": { "type": "string" }, "maxItems": 200, "minItems": 1, "title": "Email Ids", "type": "array" }, "surface": { "default": "split_drop", "enum": [ "split_drop", "unknown" ], "title": "Surface", "type": "string" }, "target": { "enum": [ "important", "feed", "paper_trail", "screener" ], "title": "Target", "type": "string" } }, "required": [ "target", "email_ids" ], "title": "TriageDropRequest", "type": "object" }, "TriageDropResponse": { "description": "The teach outcome + the snapshot the client replays on undo.", "properties": { "moved": { "default": 0, "title": "Moved", "type": "integer" }, "senders": { "default": 0, "title": "Senders", "type": "integer" }, "snapshot": { "$ref": "#/components/schemas/TriageDropSnapshot" }, "success": { "default": true, "title": "Success", "type": "boolean" }, "target": { "enum": [ "important", "feed", "paper_trail", "screener" ], "title": "Target", "type": "string" } }, "required": [ "target", "snapshot" ], "title": "TriageDropResponse", "type": "object" }, "TriageDropSenderSnapshot": { "description": "Pre-drop state for one distinct sender (the sender-rule half of undo).", "properties": { "had_force_split_rule": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Had Force Split Rule" }, "had_forced_category_rule": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Had Forced Category Rule" }, "prior_auto_approved": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Prior Auto Approved" }, "prior_forced_category": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Prior Forced Category" }, "prior_sender_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Prior Sender Status" }, "sender_address": { "title": "Sender Address", "type": "string" } }, "required": [ "sender_address" ], "title": "TriageDropSenderSnapshot", "type": "object" }, "TriageDropSnapshot": { "description": "The full captured pre-drop state for one drop gesture.", "properties": { "emails": { "items": { "$ref": "#/components/schemas/TriageDropEmailSnapshot" }, "title": "Emails", "type": "array" }, "senders": { "items": { "$ref": "#/components/schemas/TriageDropSenderSnapshot" }, "title": "Senders", "type": "array" }, "target": { "enum": [ "important", "feed", "paper_trail", "screener" ], "title": "Target", "type": "string" } }, "required": [ "target" ], "title": "TriageDropSnapshot", "type": "object" }, "TriageDropUndoRequest": { "description": "Restore the exact pre-drop state captured in a prior drop's snapshot.", "properties": { "snapshot": { "$ref": "#/components/schemas/TriageDropSnapshot" } }, "required": [ "snapshot" ], "title": "TriageDropUndoRequest", "type": "object" }, "TriageDropUndoResponse": { "description": "The reversal outcome.", "properties": { "restored_emails": { "default": 0, "title": "Restored Emails", "type": "integer" }, "restored_senders": { "default": 0, "title": "Restored Senders", "type": "integer" }, "reverted": { "default": true, "title": "Reverted", "type": "boolean" }, "success": { "default": true, "title": "Success", "type": "boolean" } }, "title": "TriageDropUndoResponse", "type": "object" }, "TrialActivationStep": { "properties": { "done": { "title": "Done", "type": "boolean" }, "key": { "title": "Key", "type": "string" }, "label": { "title": "Label", "type": "string" }, "required": { "title": "Required", "type": "boolean" } }, "required": [ "key", "label", "done", "required" ], "title": "TrialActivationStep", "type": "object" }, "TrialActivationView": { "description": "What a person sees about their trial's AI: what is done, what is left.", "properties": { "activated": { "title": "Activated", "type": "boolean" }, "starter_credits": { "title": "Starter Credits", "type": "number" }, "starter_remaining": { "title": "Starter Remaining", "type": "number" }, "steps": { "items": { "$ref": "#/components/schemas/TrialActivationStep" }, "title": "Steps", "type": "array" }, "steps_done": { "title": "Steps Done", "type": "integer" }, "steps_needed": { "title": "Steps Needed", "type": "integer" } }, "required": [ "activated", "steps", "steps_needed", "steps_done", "starter_credits", "starter_remaining" ], "title": "TrialActivationView", "type": "object" }, "TrialEndRequest": { "properties": { "trial_end": { "format": "date-time", "title": "Trial End", "type": "string" } }, "required": [ "trial_end" ], "title": "TrialEndRequest", "type": "object" }, "TrialEndResponse": { "properties": { "subscription_status": { "title": "Subscription Status", "type": "string" }, "tenant_id": { "title": "Tenant Id", "type": "string" }, "trial_end": { "format": "date-time", "title": "Trial End", "type": "string" } }, "required": [ "tenant_id", "trial_end", "subscription_status" ], "title": "TrialEndResponse", "type": "object" }, "TriggerEnvelope": { "description": "Trigger context for a workflow execution (TIDY-10489 / D7).\n\nOptional body on ``POST /workflows/{id}/execute``. When present, the\nenvelope is persisted onto the ``workflow_execution_logs`` row and forwarded\ninto the Temporal run so the script understands its own call-in. Facet\nactions populate this; manual triggers from the UI omit it.", "properties": { "call_in_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Invocation correlation id. A UUID is used as-is; any other non-empty string (e.g. an LLM tool-call id from the assistant's tidy_execute_workflow tool) is mapped to a deterministic UUIDv5 so the same call-in always yields the same stored id.", "title": "Call In Id" }, "origin_account_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Account that triggered the run from the surface.", "title": "Origin Account Id" }, "origin_room_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Matrix room_id when origin_surface='chat'.", "title": "Origin Room Id" }, "origin_surface": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "User surface the run originated from: chat|web|sms|mcp|scheduled|manual.", "title": "Origin Surface" }, "resolved_params": { "additionalProperties": true, "description": "Resolved parameter bundle", "title": "Resolved Params", "type": "object" }, "subjects": { "description": "Subject row UUIDs", "items": { "type": "string" }, "title": "Subjects", "type": "array" }, "trigger_source": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "e.g. 'facet_action' | 'manual'", "title": "Trigger Source" } }, "title": "TriggerEnvelope", "type": "object" }, "TtfcSummary": { "description": "Time-to-first-completed-conversation — the epic's KPI.", "properties": { "p50_minutes": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "title": "P50 Minutes" }, "p90_minutes": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "title": "P90 Minutes" }, "tenants_with_first": { "default": 0, "title": "Tenants With First", "type": "integer" }, "tenants_with_none": { "default": 0, "title": "Tenants With None", "type": "integer" } }, "title": "TtfcSummary", "type": "object" }, "TurnUsageCoverage": { "description": "How many of the turns in scope reported all, part or none of their usage (TIDY-19934).", "properties": { "complete": { "default": 0, "title": "Complete", "type": "integer" }, "partial": { "default": 0, "title": "Partial", "type": "integer" }, "unavailable": { "default": 0, "title": "Unavailable", "type": "integer" }, "undeclared": { "default": 0, "title": "Undeclared", "type": "integer" } }, "title": "TurnUsageCoverage", "type": "object" }, "URLObject": { "description": "Related URL reference object.\n\nAttributes:\n url: External URL\n title: Display title for the URL (optional, auto-generated from domain if missing)\n domain: Optional domain extracted from URL\n type: Optional type of link (e.g., \"link\")\n\nExample:\n {\n \"url\": \"https://school.edu/calendar\",\n \"title\": \"School calendar\"\n }", "properties": { "domain": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Domain extracted from URL", "title": "Domain" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Display title for the URL", "examples": [ "School calendar" ], "title": "Title" }, "type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Type of link", "title": "Type" }, "url": { "description": "External URL", "examples": [ "https://school.edu/calendar" ], "title": "Url", "type": "string" } }, "required": [ "url" ], "title": "URLObject", "type": "object" }, "UnaddressableMember": { "description": "A group member that could not be resolved to an address — flagged at\nexpand/send time, never silently dropped (R21/R22).", "properties": { "id": { "format": "uuid", "title": "Id", "type": "string" }, "kind": { "enum": [ "contact", "organization" ], "title": "Kind", "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name" }, "reason": { "title": "Reason", "type": "string" } }, "required": [ "kind", "id", "reason" ], "title": "UnaddressableMember", "type": "object" }, "UnblockResponse": { "properties": { "emails_restored": { "default": 0, "title": "Emails Restored", "type": "integer" }, "status": { "default": "unblocked", "title": "Status", "type": "string" } }, "title": "UnblockResponse", "type": "object" }, "UnblockSenderRequest": { "properties": { "scope": { "default": "address", "description": "Unblock scope: 'address' or 'domain'", "title": "Scope", "type": "string" } }, "title": "UnblockSenderRequest", "type": "object" }, "UnblockSenderResponse": { "properties": { "defense_rule_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Defense Rule Id" }, "email_id": { "format": "uuid", "title": "Email Id", "type": "string" }, "emails_restored": { "default": 0, "title": "Emails Restored", "type": "integer" }, "sender_email": { "title": "Sender Email", "type": "string" }, "success": { "default": true, "title": "Success", "type": "boolean" }, "unblock_scope": { "title": "Unblock Scope", "type": "string" } }, "required": [ "email_id", "sender_email", "unblock_scope" ], "title": "UnblockSenderResponse", "type": "object" }, "UncertainResolveRequest": { "properties": { "action": { "description": "'retry' (deliberate, logged — MAY duplicate the email) or 'skip' (counted as cancelled).", "title": "Action", "type": "string" } }, "required": [ "action" ], "title": "UncertainResolveRequest", "type": "object" }, "UncertainResolveResponse": { "properties": { "action": { "title": "Action", "type": "string" }, "campaign_id": { "title": "Campaign Id", "type": "string" }, "new_state": { "title": "New State", "type": "string" }, "recipient_id": { "title": "Recipient Id", "type": "string" } }, "required": [ "campaign_id", "recipient_id", "action", "new_state" ], "title": "UncertainResolveResponse", "type": "object" }, "UnderHeadingPlacement": { "additionalProperties": false, "description": "At the END of the named heading's section.", "properties": { "heading": { "description": "The heading's own text, matched trimmed and case-insensitively. The node lands before the next heading of the same or a higher level, or at the end of the body.", "maxLength": 2000, "minLength": 1, "title": "Heading", "type": "string" }, "mode": { "const": "under_heading", "title": "Mode", "type": "string" } }, "required": [ "mode", "heading" ], "title": "UnderHeadingPlacement", "type": "object" }, "UndoOutputResult": { "properties": { "output_index": { "title": "Output Index", "type": "integer" }, "resolution": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Resolution" }, "status": { "title": "Status", "type": "string" } }, "required": [ "output_index", "status" ], "title": "UndoOutputResult", "type": "object" }, "UndoRequest": { "properties": { "output_index": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Output Index" }, "resolution": { "anyOf": [ { "const": "force_restore", "type": "string" }, { "type": "null" } ], "title": "Resolution" }, "run_id": { "format": "uuid", "title": "Run Id", "type": "string" } }, "required": [ "run_id" ], "title": "UndoRequest", "type": "object" }, "UndoResponse": { "properties": { "cancelled_scheduled_action_ids": { "items": { "type": "string" }, "title": "Cancelled Scheduled Action Ids", "type": "array" }, "irreversible": { "items": { "$ref": "#/components/schemas/IrreversibleOutput" }, "title": "Irreversible", "type": "array" }, "results": { "items": { "$ref": "#/components/schemas/UndoOutputResult" }, "title": "Results", "type": "array" }, "rollback_run_id": { "format": "uuid", "title": "Rollback Run Id", "type": "string" }, "run_id": { "format": "uuid", "title": "Run Id", "type": "string" }, "run_status": { "title": "Run Status", "type": "string" } }, "required": [ "run_id", "run_status", "rollback_run_id", "results", "irreversible", "cancelled_scheduled_action_ids" ], "title": "UndoResponse", "type": "object" }, "UndoSendResponse": { "description": "Response for undo operation.", "properties": { "id": { "description": "Draft UUID", "format": "uuid", "title": "Id", "type": "string" }, "message": { "description": "Result message", "title": "Message", "type": "string" }, "success": { "description": "Whether undo succeeded", "title": "Success", "type": "boolean" } }, "required": [ "id", "success", "message" ], "title": "UndoSendResponse", "type": "object" }, "UndoSpamResponse": { "properties": { "email_id": { "format": "uuid", "title": "Email Id", "type": "string" }, "undone": { "title": "Undone", "type": "boolean" } }, "required": [ "undone", "email_id" ], "title": "UndoSpamResponse", "type": "object" }, "UnenforcedIsolation": { "additionalProperties": false, "properties": { "reason": { "maxLength": 500, "minLength": 1, "title": "Reason", "type": "string" }, "status": { "const": "unenforced", "title": "Status", "type": "string" } }, "required": [ "status", "reason" ], "title": "UnenforcedIsolation", "type": "object" }, "UnfurlAcceptedResponse": { "description": "Returned synchronously when the background task has been scheduled.\n\nThe actual unfurl work runs out-of-band; clients should not block on\nthis response for preview content. They will see the rendered cards\narrive via the room's regular Matrix sync stream.", "properties": { "status": { "const": "accepted", "default": "accepted", "title": "Status", "type": "string" }, "url_count": { "description": "Number of URLs accepted for unfurl.", "title": "Url Count", "type": "integer" } }, "required": [ "url_count" ], "title": "UnfurlAcceptedResponse", "type": "object" }, "UnfurlEnqueueRequest": { "description": "Payload sent by the composer after a message lands.\n\n``urls`` is the de-duped list extracted from the just-sent message body.\nThe caller caps at 10 client-side; the endpoint rejects any longer list\nwith 400. URLs must be ``http`` or ``https`` (``HttpUrl`` validates).\n\nThe composer also sends the ``body`` + ``formatted_body`` it just\nposted so the background task can build the m.replace ``m.new_content``\nwithout re-querying Tuwunel. Both default to empty so we degrade\ngracefully if the client doesn't have them in scope (the m.replace\nwill still be valid; just unstyled).", "properties": { "body": { "default": "", "description": "The original plain-text body, used to build m.new_content.body.", "maxLength": 20000, "title": "Body", "type": "string" }, "formatted_body": { "default": "", "description": "The original org.matrix.custom.html formatted_body, used to build m.new_content.formatted_body.", "maxLength": 80000, "title": "Formatted Body", "type": "string" }, "urls": { "description": "URLs to fetch previews for. http/https only, max 10.", "items": { "format": "uri", "maxLength": 2083, "minLength": 1, "type": "string" }, "maxItems": 10, "minItems": 1, "title": "Urls", "type": "array" } }, "required": [ "urls" ], "title": "UnfurlEnqueueRequest", "type": "object" }, "UnifiedCalendarEvent": { "description": "Complete unified calendar event object (response).", "properties": { "all_day": { "default": false, "description": "Whether this is an all-day event", "title": "All Day", "type": "boolean" }, "collection_id": { "description": "Calendar collection UUID", "title": "Collection Id", "type": "string" }, "confidence": { "anyOf": [ { "maximum": 1.0, "minimum": 0.0, "type": "number" }, { "type": "null" } ], "default": null, "description": "AI extraction confidence (0.0-1.0)", "title": "Confidence" }, "conflict_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Conflict type: time_overlap, double_booking, travel_impossible", "title": "Conflict Type" }, "conflict_with": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "default": null, "description": "Conflicting event UUIDs", "title": "Conflict With" }, "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "dav_etag": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Entity tag for sync", "title": "Dav Etag" }, "description": { "anyOf": [ { "maxLength": 10000, "type": "string" }, { "type": "null" } ], "default": null, "description": "Event description", "title": "Description" }, "dtend": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "description": "End time (ISO 8601 with timezone)", "title": "Dtend" }, "dtstart": { "description": "Start time (ISO 8601 with timezone)", "format": "date-time", "title": "Dtstart", "type": "string" }, "event_status": { "default": "approved", "description": "Lifecycle status: pending, approved, rejected, cancelled", "title": "Event Status", "type": "string" }, "event_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Event type/category", "examples": [ "meeting", "school", "sports", "birthday" ], "title": "Event Type" }, "exdate": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "default": null, "description": "Exception dates (ISO 8601 date strings)", "title": "Exdate" }, "external_event_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Linked external_calendar_events UUID", "title": "External Event Id" }, "external_provider_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Provider's event ID (Google, Zoho)", "title": "External Provider Id" }, "first_instance": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "First Instance" }, "has_local_changes": { "default": false, "description": "Computed flag: TRUE if event has local edits that differ from synced source", "title": "Has Local Changes", "type": "boolean" }, "id": { "description": "Event UUID", "title": "Id", "type": "string" }, "is_recurring_instance": { "default": false, "description": "True if this is an expanded instance of a recurring event", "title": "Is Recurring Instance", "type": "boolean" }, "last_instance": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Last Instance" }, "last_sync_etag": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "ETag from last successful sync - used for conflict detection", "title": "Last Sync Etag" }, "local_modifications": { "additionalProperties": true, "description": "Tracks original values for fields edited locally. Structure: {field: {original: value, modified_at: timestamp}}", "title": "Local Modifications", "type": "object" }, "location": { "anyOf": [ { "maxLength": 500, "type": "string" }, { "type": "null" } ], "default": null, "description": "Event location", "title": "Location" }, "notes_history": { "description": "DEPRECATED: Notes are now stored in unified notes table (KCC-3305). Use /api/v1/notes endpoints with event_id anchor. Always returns empty array.", "items": { "additionalProperties": true, "type": "object" }, "title": "Notes History", "type": "array" }, "recipe_data": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "description": "Recipe engine output: prep checklists, reminders, travel recommendations", "title": "Recipe Data" }, "rejection_notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Reason for rejection", "title": "Rejection Notes" }, "review_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Why review is needed: low_confidence, conflict, duplicate_suspect", "title": "Review Reason" }, "reviewed_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Reviewed At" }, "reviewed_by": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Reviewer account UUID", "title": "Reviewed By" }, "rrule": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "RFC 5545 recurrence rule", "examples": [ "FREQ=WEEKLY;BYDAY=MO,WE,FR", "FREQ=MONTHLY;BYMONTHDAY=15" ], "title": "Rrule" }, "source_type": { "description": "Origin: manual, email, calendar_sync, agent", "title": "Source Type", "type": "string" }, "status": { "default": "CONFIRMED", "description": "iCalendar status", "title": "Status", "type": "string" }, "summary": { "description": "Event title (iCalendar SUMMARY)", "maxLength": 500, "minLength": 1, "title": "Summary", "type": "string" }, "tags": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "default": null, "description": "User and auto-generated tags", "title": "Tags" }, "tenant_id": { "description": "Tenant UUID", "title": "Tenant Id", "type": "string" }, "timezone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "IANA timezone for the event", "title": "Timezone" }, "travel_mode": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Travel Mode" }, "travel_time_minutes": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Travel Time Minutes" }, "uid": { "description": "Unique iCalendar UID", "title": "Uid", "type": "string" }, "updated_at": { "format": "date-time", "title": "Updated At", "type": "string" }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Event URL", "title": "Url" }, "weather_data": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "title": "Weather Data" } }, "required": [ "summary", "dtstart", "id", "tenant_id", "collection_id", "uid", "source_type", "created_at", "updated_at" ], "title": "UnifiedCalendarEvent", "type": "object" }, "UnifiedCalendarEventCreate": { "description": "Input model for creating unified calendar events.", "properties": { "all_day": { "default": false, "description": "Whether this is an all-day event", "title": "All Day", "type": "boolean" }, "collection_id": { "description": "Target calendar collection UUID", "title": "Collection Id", "type": "string" }, "description": { "anyOf": [ { "maxLength": 10000, "type": "string" }, { "type": "null" } ], "description": "Event description", "title": "Description" }, "dtend": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "End time (ISO 8601 with timezone)", "title": "Dtend" }, "dtstart": { "description": "Start time (ISO 8601 with timezone)", "format": "date-time", "title": "Dtstart", "type": "string" }, "event_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Event type/category", "examples": [ "meeting", "school", "sports", "birthday" ], "title": "Event Type" }, "exdate": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "description": "Exception dates (ISO 8601 date strings)", "title": "Exdate" }, "location": { "anyOf": [ { "maxLength": 500, "type": "string" }, { "type": "null" } ], "description": "Event location", "title": "Location" }, "rrule": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 5545 recurrence rule", "examples": [ "FREQ=WEEKLY;BYDAY=MO,WE,FR", "FREQ=MONTHLY;BYMONTHDAY=15" ], "title": "Rrule" }, "status": { "default": "CONFIRMED", "description": "iCalendar status", "title": "Status", "type": "string" }, "summary": { "description": "Event title (iCalendar SUMMARY)", "maxLength": 500, "minLength": 1, "title": "Summary", "type": "string" }, "tags": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "description": "User and auto-generated tags", "title": "Tags" }, "timezone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "IANA timezone for the event", "title": "Timezone" }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Event URL", "title": "Url" } }, "required": [ "summary", "dtstart", "collection_id" ], "title": "UnifiedCalendarEventCreate", "type": "object" }, "UnifiedCalendarEventUpdate": { "description": "Input model for updating unified calendar events (partial update).", "properties": { "all_day": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "All Day" }, "description": { "anyOf": [ { "maxLength": 10000, "type": "string" }, { "type": "null" } ], "title": "Description" }, "dtend": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Dtend" }, "dtstart": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Dtstart" }, "event_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Event Type" }, "exdate": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Exdate" }, "location": { "anyOf": [ { "maxLength": 500, "type": "string" }, { "type": "null" } ], "title": "Location" }, "rrule": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Rrule" }, "summary": { "anyOf": [ { "maxLength": 500, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Summary" }, "tags": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Tags" }, "timezone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Timezone" }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Url" } }, "title": "UnifiedCalendarEventUpdate", "type": "object" }, "UnifiedOAuthCallbackRequest": { "description": "Request for unified OAuth callback.", "properties": { "code": { "description": "Authorization code from provider", "title": "Code", "type": "string" }, "state": { "description": "OAuth state parameter", "title": "State", "type": "string" } }, "required": [ "code", "state" ], "title": "UnifiedOAuthCallbackRequest", "type": "object" }, "UnifiedOAuthCallbackResponse": { "description": "Response from unified OAuth callback.", "properties": { "connection_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Connection Id" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error" }, "flow_type": { "description": "The OAuth flow; email for a provider connection", "title": "Flow Type", "type": "string" }, "return_to": { "description": "Page to redirect the user back to", "title": "Return To", "type": "string" }, "success": { "title": "Success", "type": "boolean" } }, "required": [ "success", "return_to", "flow_type" ], "title": "UnifiedOAuthCallbackResponse", "type": "object" }, "UnifiedSearchFilters": { "description": "Filter echo used by the UI to show \"interpreted\" query state.", "properties": { "search_text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Search Text" } }, "title": "UnifiedSearchFilters", "type": "object" }, "UnifiedSearchRequest": { "description": "Request body for `POST /api/v1/search/unified`.", "properties": { "context": { "default": "all", "enum": [ "all", "calendar", "tasks", "contacts", "email", "notes", "feed", "project" ], "title": "Context", "type": "string" }, "delegated_by": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "description": "Optional delegator account for virtual-employee/OBO searches. The API resolves active read grants before using it.", "title": "Delegated By" }, "include_archived": { "default": false, "title": "Include Archived", "type": "boolean" }, "limit": { "default": 20, "maximum": 100.0, "minimum": 1.0, "title": "Limit", "type": "integer" }, "mode": { "default": "search", "enum": [ "search", "recent" ], "title": "Mode", "type": "string" }, "query": { "maxLength": 1000, "minLength": 0, "title": "Query", "type": "string" }, "source_kind_filter": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Source Kind Filter" }, "surface": { "default": "search", "enum": [ "search", "command_palette" ], "title": "Surface", "type": "string" }, "tenant_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Tenant Id" } }, "required": [ "query" ], "title": "UnifiedSearchRequest", "type": "object" }, "UnifiedSearchResponse": { "description": "Response envelope for `POST /api/v1/search/unified`.", "properties": { "filters": { "$ref": "#/components/schemas/UnifiedSearchFilters" }, "interpretation": { "title": "Interpretation", "type": "string" }, "metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "title": "Metadata" }, "path": { "enum": [ "filter_fast", "semantic", "hybrid", "recent" ], "title": "Path", "type": "string" }, "processing_time_ms": { "title": "Processing Time Ms", "type": "integer" }, "results": { "items": { "$ref": "#/components/schemas/UnifiedSearchResult" }, "title": "Results", "type": "array" }, "strategy": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "title": "Strategy" }, "total_count": { "title": "Total Count", "type": "integer" } }, "required": [ "path", "interpretation", "filters", "results", "total_count", "processing_time_ms" ], "title": "UnifiedSearchResponse", "type": "object" }, "UnifiedSearchResult": { "description": "One merged search hit.", "properties": { "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Description" }, "id": { "title": "Id", "type": "string" }, "match_ranges": { "items": { "maxItems": 2, "minItems": 2, "prefixItems": [ { "type": "integer" }, { "type": "integer" } ], "type": "array" }, "title": "Match Ranges", "type": "array" }, "metadata": { "additionalProperties": true, "title": "Metadata", "type": "object" }, "snippet": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Snippet" }, "title": { "title": "Title", "type": "string" }, "type": { "enum": [ "calendar_event", "task", "activity", "contact", "organization", "email", "note", "journal", "drawing", "project", "conversation", "comment", "scm_object" ], "title": "Type", "type": "string" } }, "required": [ "id", "type", "title" ], "title": "UnifiedSearchResult", "type": "object" }, "UninstallLedgerResponse": { "description": "The delete/keep/archive preview a user confirms against (D28).", "properties": { "archive": { "items": { "$ref": "#/components/schemas/LedgerEntryResponse" }, "title": "Archive", "type": "array" }, "cascade_available": { "default": false, "title": "Cascade Available", "type": "boolean" }, "delete": { "items": { "$ref": "#/components/schemas/LedgerEntryResponse" }, "title": "Delete", "type": "array" }, "install_id": { "format": "uuid", "title": "Install Id", "type": "string" }, "keep_edited": { "items": { "$ref": "#/components/schemas/LedgerEntryResponse" }, "title": "Keep Edited", "type": "array" } }, "required": [ "install_id" ], "title": "UninstallLedgerResponse", "type": "object" }, "UninstallResultResponse": { "properties": { "counts": { "additionalProperties": { "type": "integer" }, "title": "Counts", "type": "object" }, "install_id": { "format": "uuid", "title": "Install Id", "type": "string" }, "status": { "title": "Status", "type": "string" } }, "required": [ "install_id", "status", "counts" ], "title": "UninstallResultResponse", "type": "object" }, "UnitPreviewItem": { "description": "One item the adoption would create (or skip because it is already there).", "properties": { "action": { "title": "Action", "type": "string" }, "conflict": { "default": false, "title": "Conflict", "type": "boolean" }, "kind": { "title": "Kind", "type": "string" }, "label": { "title": "Label", "type": "string" }, "ref": { "title": "Ref", "type": "string" } }, "required": [ "kind", "ref", "label", "action" ], "title": "UnitPreviewItem", "type": "object" }, "UnitSupersededItem": { "description": "A template-owned item the unit no longer declares.\n\n``user_modified`` items are ALWAYS kept — the disposition the user confirms\ncan only archive one that is still exactly as the pack created it.", "properties": { "item_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Item Id" }, "kind": { "title": "Kind", "type": "string" }, "ref": { "title": "Ref", "type": "string" }, "user_modified": { "default": true, "title": "User Modified", "type": "boolean" } }, "required": [ "kind", "ref" ], "title": "UnitSupersededItem", "type": "object" }, "UnlinkedWork": { "properties": { "activity_id": { "title": "Activity Id", "type": "string" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Title" } }, "required": [ "activity_id" ], "title": "UnlinkedWork", "type": "object" }, "UnlinkedWorkItem": { "description": "Project work item carrying no requirement links (gap query).", "properties": { "activity_id": { "title": "Activity Id", "type": "string" }, "facets": { "default": [], "items": { "type": "string" }, "title": "Facets", "type": "array" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Title" } }, "required": [ "activity_id" ], "title": "UnlinkedWorkItem", "type": "object" }, "UnpricedModel": { "properties": { "model_name": { "title": "Model Name", "type": "string" }, "recent_calls": { "title": "Recent Calls", "type": "integer" } }, "required": [ "model_name", "recent_calls" ], "title": "UnpricedModel", "type": "object" }, "UnreadCountResponse": { "description": "Response model for unread notification count.", "properties": { "unread_count": { "title": "Unread Count", "type": "integer" } }, "required": [ "unread_count" ], "title": "UnreadCountResponse", "type": "object" }, "UnsettledConversation": { "properties": { "id": { "title": "Id", "type": "string" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Title" } }, "required": [ "id" ], "title": "UnsettledConversation", "type": "object" }, "UnsubscribeHeaders": { "properties": { "list_unsubscribe": { "title": "List Unsubscribe", "type": "string" }, "list_unsubscribe_post": { "title": "List Unsubscribe Post", "type": "string" } }, "required": [ "list_unsubscribe", "list_unsubscribe_post" ], "title": "UnsubscribeHeaders", "type": "object" }, "UnsubscribeLinkRequest": { "properties": { "contact_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The lead this address belongs to, when known — recorded on the token so the unsubscribe click lands on the lead's timeline.", "title": "Contact Id" }, "email": { "description": "The recipient the 1:1 send goes to.", "title": "Email", "type": "string" }, "from_identity": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The send's From identity ('Name '); adds the mailto fallback to the List-Unsubscribe header when given.", "title": "From Identity" } }, "required": [ "email" ], "title": "UnsubscribeLinkRequest", "type": "object" }, "UnsubscribeLinkResponse": { "properties": { "email": { "title": "Email", "type": "string" }, "headers": { "$ref": "#/components/schemas/UnsubscribeHeaders" }, "url": { "description": "The tokened public unsubscribe URL (RFC 8058).", "title": "Url", "type": "string" } }, "required": [ "email", "url", "headers" ], "title": "UnsubscribeLinkResponse", "type": "object" }, "UpdateAdminChatSettingsRequest": { "properties": { "custom_emoji_enabled": { "title": "Custom Emoji Enabled", "type": "boolean" }, "edit_window_minutes": { "anyOf": [ { "maximum": 525600.0, "minimum": 0.0, "type": "integer" }, { "type": "null" } ], "title": "Edit Window Minutes" }, "huddle_media_plane": { "default": "auto", "enum": [ "auto", "meet_first", "livekit_only" ], "title": "Huddle Media Plane", "type": "string" }, "pin_permission": { "enum": [ "anyone", "members", "admins" ], "title": "Pin Permission", "type": "string" }, "schedule_max_days": { "maximum": 365.0, "minimum": 1.0, "title": "Schedule Max Days", "type": "integer" } }, "required": [ "pin_permission", "schedule_max_days", "custom_emoji_enabled" ], "title": "UpdateAdminChatSettingsRequest", "type": "object" }, "UpdateBundleRequest": { "description": "Rename / set instructions / rebind the output type / save or discard.\n\nEvery field is optional and only the ones PRESENT in the request body are\nwritten, so a client that knows about one field cannot blank the others.\n\n``status`` moves a bundle OUT of active — ``saved`` (name it and keep it,\nR8) or ``archived``. It cannot move a bundle back TO active: activation\ncarries the one-active-per-owner invariant and has to report what it put\naway, so it lives at ``POST /bundles/{id}/reopen`` instead. One activation\npath means the invariant cannot be sidestepped by a PATCH.\n\n``only_if_status`` makes the write conditional (TIDY-19719 F13): a phone\ncapture that completes archives the bundle it started with\n``{status: archived, only_if_status: active}``, so a bundle the user saved\nmeanwhile is never put away by a capture, and a replay is a no-op.", "properties": { "facet_slug": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Facet Slug" }, "instructions": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Instructions" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name" }, "only_if_status": { "anyOf": [ { "enum": [ "active", "saved", "archived" ], "type": "string" }, { "type": "null" } ], "description": "Apply the change only while the bundle holds this status. Otherwise nothing is written and the current bundle comes back unchanged; the caller reads its status.", "title": "Only If Status" }, "status": { "anyOf": [ { "enum": [ "saved", "archived" ], "type": "string" }, { "type": "null" } ], "title": "Status" } }, "title": "UpdateBundleRequest", "type": "object" }, "UpdateCompactionConfigRequest": { "additionalProperties": false, "properties": { "compact_after_pairs": { "title": "Compact After Pairs", "type": "integer" }, "conversation_type": { "title": "Conversation Type", "type": "string" }, "keep_intact_pairs": { "title": "Keep Intact Pairs", "type": "integer" }, "meta_compact_after_summaries": { "title": "Meta Compact After Summaries", "type": "integer" }, "token_threshold": { "title": "Token Threshold", "type": "integer" } }, "required": [ "conversation_type", "token_threshold", "keep_intact_pairs", "compact_after_pairs", "meta_compact_after_summaries" ], "title": "UpdateCompactionConfigRequest", "type": "object" }, "UpdateContentRequest": { "description": "Request to update document extracted content.", "properties": { "extracted_content": { "description": "Updated markdown content", "title": "Extracted Content", "type": "string" } }, "required": [ "extracted_content" ], "title": "UpdateContentRequest", "type": "object" }, "UpdateDocumentRequest": { "description": "Request to update document metadata.", "properties": { "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Document description", "title": "Description" }, "tags": { "default": [], "description": "Document tags", "items": { "type": "string" }, "title": "Tags", "type": "array" } }, "title": "UpdateDocumentRequest", "type": "object" }, "UpdateDraftRequest": { "additionalProperties": false, "description": "Request body for updating an email draft (auto-save).", "properties": { "bcc_recipients": { "anyOf": [ { "items": { "$ref": "#/components/schemas/EmailRecipient" }, "type": "array" }, { "type": "null" } ], "description": "BCC recipients", "title": "Bcc Recipients" }, "body_html": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "HTML body content", "title": "Body Html" }, "body_markdown": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The body as Markdown; raw HTML in it stays text. The server renders it into body_prosemirror, body_html and body_text, so send it instead of those three. A reply's or forward's quoted original is kept below it.", "title": "Body Markdown" }, "body_prosemirror": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "Authoritative ProseMirror doc for the compose body (TIDY-8977 S10). When supplied, the send pipeline renders this via EmailRenderer to produce email-safe HTML at send time; body_html is ignored. Sending an empty/null value DOES NOT clear the column — only an explicit non-null value updates it (auto-save semantics).", "title": "Body Prosemirror" }, "body_text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Plain text body content", "title": "Body Text" }, "cc_recipients": { "anyOf": [ { "items": { "$ref": "#/components/schemas/EmailRecipient" }, "type": "array" }, { "type": "null" } ], "description": "CC recipients", "title": "Cc Recipients" }, "subject": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Email subject", "title": "Subject" }, "to_recipients": { "anyOf": [ { "items": { "$ref": "#/components/schemas/EmailRecipient" }, "type": "array" }, { "type": "null" } ], "description": "To recipients", "title": "To Recipients" } }, "title": "UpdateDraftRequest", "type": "object" }, "UpdateElementOp": { "additionalProperties": false, "description": "Partial property update on ONE element — position, size, style, text.\n\nA move IS this op (``patch={\"x\": …, \"y\": …}``); a separate ``move_element``\nwould be a second spelling of one capability.", "properties": { "id": { "maxLength": 200, "minLength": 1, "title": "Id", "type": "string" }, "op": { "const": "update_element", "title": "Op", "type": "string" }, "patch": { "additionalProperties": true, "minProperties": 1, "title": "Patch", "type": "object" } }, "required": [ "id", "op", "patch" ], "title": "UpdateElementOp", "type": "object" }, "UpdateHuddleParticipantRequest": { "properties": { "audio": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Audio" }, "client_kind": { "anyOf": [ { "pattern": "^(web|android|ios)$", "type": "string" }, { "type": "null" } ], "title": "Client Kind" }, "sharing_screen": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Sharing Screen" }, "video": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Video" } }, "title": "UpdateHuddleParticipantRequest", "type": "object" }, "UpdateHuddleTitleRequest": { "description": "Rename a huddle, or hand the name back to derivation.\n\nSending ``title`` claims the name: source becomes ``user`` and the override\nis set, so later notes events skip derivation. Sending\n``title_override=false`` (with no title) deliberately clears the claim and\nre-derives from the LATEST notes — \"undo my rename\" restores the name the\nnotes imply now, not the one from before the rename.", "properties": { "title": { "anyOf": [ { "maxLength": 200, "type": "string" }, { "type": "null" } ], "title": "Title" }, "title_override": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Title Override" } }, "title": "UpdateHuddleTitleRequest", "type": "object" }, "UpdateItemRequest": { "properties": { "excluded": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Deselect (or re-select) this source. A deselected item stays in the tray but contributes nothing to the size indicator or to generation, and the deselection survives re-resolution.", "title": "Excluded" }, "instruction_reviewed": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Confirm (or withdraw confirmation of) this instruction's text. Withdrawing blocks generation until it is confirmed again.", "title": "Instruction Reviewed" }, "instruction_text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Correct the instruction this item carries (TIDY-17832). Valid only on an instruction item. Editing the text CLEARS the review stamp unless instruction_reviewed is sent in the same request — a machine transcript the member has changed is, by definition, not yet the text they confirmed. It never touches the recording or its extraction artifact.", "title": "Instruction Text" }, "position": { "anyOf": [ { "minimum": 0.0, "type": "integer" }, { "type": "null" } ], "title": "Position" }, "scope_note": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Scope Note" } }, "title": "UpdateItemRequest", "type": "object" }, "UpdateMemberRoleResponse": { "properties": { "changed": { "title": "Changed", "type": "boolean" }, "ok": { "title": "Ok", "type": "boolean" }, "role": { "title": "Role", "type": "string" } }, "required": [ "ok", "changed", "role" ], "title": "UpdateMemberRoleResponse", "type": "object" }, "UpdateOAuthAppRequest": { "properties": { "homepage_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Homepage Url" }, "logo_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Logo Url" }, "name": { "anyOf": [ { "maxLength": 120, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Name" }, "redirect_uris": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Redirect Uris" } }, "title": "UpdateOAuthAppRequest", "type": "object" }, "UpdateOAuthAppScopesResponse": { "properties": { "changed": { "title": "Changed", "type": "boolean" }, "ok": { "title": "Ok", "type": "boolean" }, "review_status": { "title": "Review Status", "type": "string" } }, "required": [ "ok", "changed", "review_status" ], "title": "UpdateOAuthAppScopesResponse", "type": "object" }, "UpdatePresentationDesignRequest": { "description": "Body for PATCH /api/v1/presentation-designs/{id}. All fields optional.", "properties": { "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "design": { "anyOf": [ { "$ref": "#/components/schemas/DesignPayload" }, { "type": "null" } ] }, "name": { "anyOf": [ { "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Name" }, "visibility": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Visibility" } }, "title": "UpdatePresentationDesignRequest", "type": "object" }, "UpdatePublicationRequest": { "description": "Tenant-configurable protection + follow-up knobs (D13). Only supplied\nfields change; the Turnstile secret is write-only.", "properties": { "cors_origins": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Cors Origins" }, "honeypot": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Honeypot" }, "honeypot_field": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Honeypot Field" }, "payload_cap_bytes": { "anyOf": [ { "maximum": 1048576.0, "minimum": 1024.0, "type": "integer" }, { "type": "null" } ], "title": "Payload Cap Bytes" }, "per_ip_per_minute": { "anyOf": [ { "maximum": 10000.0, "minimum": 1.0, "type": "integer" }, { "type": "null" } ], "title": "Per Ip Per Minute" }, "per_token_per_minute": { "anyOf": [ { "maximum": 10000.0, "minimum": 1.0, "type": "integer" }, { "type": "null" } ], "title": "Per Token Per Minute" }, "redirect_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Redirect Url" }, "thanks_message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Thanks Message" }, "turnstile": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Turnstile" }, "turnstile_secret": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Turnstile Secret" }, "turnstile_site_key": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Turnstile Site Key" } }, "title": "UpdatePublicationRequest", "type": "object" }, "UpdateRequireCapabilityApprovalResponse": { "properties": { "ok": { "title": "Ok", "type": "boolean" }, "require_capability_approval": { "title": "Require Capability Approval", "type": "boolean" } }, "required": [ "ok", "require_capability_approval" ], "title": "UpdateRequireCapabilityApprovalResponse", "type": "object" }, "UpdateSARequest": { "properties": { "description": { "anyOf": [ { "maxLength": 500, "type": "string" }, { "type": "null" } ], "title": "Description" }, "name": { "anyOf": [ { "maxLength": 120, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Name" } }, "title": "UpdateSARequest", "type": "object" }, "UpdateSavedRequest": { "properties": { "note": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Note" } }, "title": "UpdateSavedRequest", "type": "object" }, "UpdateSavedViewRequest": { "properties": { "config": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Config" }, "entity_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Entity Type" }, "is_default": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is Default" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name" }, "navigation_key": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Navigation Key" }, "position": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Position" }, "view_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "View Type" } }, "title": "UpdateSavedViewRequest", "type": "object" }, "UpdateScheduledMessageRequest": { "properties": { "payload": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Payload" }, "scheduled_for": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Scheduled For" } }, "title": "UpdateScheduledMessageRequest", "type": "object" }, "UpdateScopesRequest": { "properties": { "allowed_scopes": { "items": { "type": "string" }, "title": "Allowed Scopes", "type": "array" } }, "required": [ "allowed_scopes" ], "title": "UpdateScopesRequest", "type": "object" }, "UpdateSectionItem": { "description": "A single section update.", "properties": { "content": { "description": "New text content for the section", "minLength": 1, "title": "Content", "type": "string" }, "section_index": { "description": "Index of section to update (0-based)", "minimum": 0.0, "title": "Section Index", "type": "integer" } }, "required": [ "section_index", "content" ], "title": "UpdateSectionItem", "type": "object" }, "UpdateSectionsRequest": { "description": "Request body for updating card sections.", "properties": { "sections": { "description": "List of sections to update", "items": { "$ref": "#/components/schemas/UpdateSectionItem" }, "minItems": 1, "title": "Sections", "type": "array" } }, "required": [ "sections" ], "title": "UpdateSectionsRequest", "type": "object" }, "UpdateSectionsResponse": { "description": "Response from updating sections.", "properties": { "card": { "additionalProperties": true, "description": "Updated card with all sections", "title": "Card", "type": "object" }, "success": { "description": "Whether update succeeded", "title": "Success", "type": "boolean" } }, "required": [ "success", "card" ], "title": "UpdateSectionsResponse", "type": "object" }, "UpdateSettingRequest": { "properties": { "key": { "title": "Key", "type": "string" }, "value": { "title": "Value" } }, "required": [ "key", "value" ], "title": "UpdateSettingRequest", "type": "object" }, "UpdateSmartGroupRequest": { "properties": { "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name" }, "rule_definition": { "anyOf": [ { "$ref": "#/components/schemas/SmartGroupRuleDefinition" }, { "type": "null" } ] } }, "title": "UpdateSmartGroupRequest", "type": "object" }, "UpdateTaskRequest": { "properties": { "error": { "anyOf": [ { "maxLength": 4000, "type": "string" }, { "type": "null" } ], "title": "Error" }, "note": { "anyOf": [ { "maxLength": 4000, "type": "string" }, { "type": "null" } ], "title": "Note" }, "status": { "description": "todo|in_progress|blocked|failed|done", "title": "Status", "type": "string" } }, "required": [ "status" ], "title": "UpdateTaskRequest", "type": "object" }, "UpdateTenantFeatureSettingsRequest": { "description": "Omitted means \"leave as-is\", for every flag.\n\nA client that does not know about a flag cannot clear it, and the panel\nsends only the flag it is flipping plus the version it read.\n``native_email_collaboration_enabled`` was required until TIDY-17353 and is\nnow optional like the rest — a relaxation, so every request that was valid\nbefore still is.", "properties": { "advanced_noise_enabled": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Advanced Noise Enabled" }, "ai_local_only_enabled": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Ai Local Only Enabled" }, "collab_nav_enabled": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Collab Nav Enabled" }, "hosted_employees_may_use_tenant_keys": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Hosted Employees May Use Tenant Keys" }, "huddle_composite_eval_enabled": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Huddle Composite Eval Enabled" }, "native_email_collaboration_enabled": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Native Email Collaboration Enabled" }, "record_action_menu_vertical": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Record Action Menu Vertical" }, "ve_activity_feed_enabled": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Ve Activity Feed Enabled" }, "ve_autonomy_heartbeat_enabled": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Ve Autonomy Heartbeat Enabled" }, "ve_backlog_injection_enabled": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Ve Backlog Injection Enabled" }, "ve_goal_facets_enabled": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Ve Goal Facets Enabled" }, "ve_home_base_enabled": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Ve Home Base Enabled" }, "ve_meeting_wake_enabled": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Ve Meeting Wake Enabled" }, "ve_reflection_wake_enabled": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Ve Reflection Wake Enabled" }, "ve_resolution_enabled": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Ve Resolution Enabled" }, "ve_scheduled_jobs_enabled": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Ve Scheduled Jobs Enabled" }, "ve_session_links_enabled": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Ve Session Links Enabled" }, "ve_settle_resume_enabled": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Ve Settle Resume Enabled" }, "version": { "minimum": 0.0, "title": "Version", "type": "integer" }, "voice_identity_enabled": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Voice Identity Enabled" }, "workforce_path_policy": { "anyOf": [ { "enum": [ "both", "hosted_only", "workshop_only" ], "type": "string" }, { "type": "null" } ], "title": "Workforce Path Policy" } }, "required": [ "version" ], "title": "UpdateTenantFeatureSettingsRequest", "type": "object" }, "UpdateWidePreferencesRequest": { "description": "Partial update payload — only fields carrying a value are persisted.\n\nTwo contract notes, both from TIDY-18062:\n\n* ``sms_consent_timestamp`` is a ``datetime``, matching the narrow\n ``SMSSettingsUpdate`` it now subsumes. It used to be a bare ``str``, which\n was not a cosmetic difference: the handler passed it straight to asyncpg for\n a ``timestamptz`` column, so every consent write — including the\n ``datetime.now().isoformat()`` fallback, also a ``str`` — died with\n ``asyncpg.DataError`` (HTTP 500). ISO 8601 strings are still accepted on the\n wire; pydantic parses them, and a malformed one is now a 400\n validation_failed instead of a 500.\n* A body with no value in it is a 400, not a silent no-op 200 (Dave's call on\n TIDY-18062, reversing TIDY-18057's shipped behaviour). It is refused before\n any write, and the narrow door applies the same rule.", "properties": { "auto_expiry_enabled": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Auto Expiry Enabled" }, "digest_frequency": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Digest Frequency" }, "digest_time": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Digest Time" }, "phone_number": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Phone Number" }, "push_enabled": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Push Enabled" }, "quiet_hours_end": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Quiet Hours End" }, "quiet_hours_start": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Quiet Hours Start" }, "receive_billing": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Receive Billing" }, "receive_event_digests": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Receive Event Digests" }, "receive_event_reminders": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Receive Event Reminders" }, "receive_insights": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Receive Insights" }, "receive_marketing": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Receive Marketing" }, "receive_task_reminders": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Receive Task Reminders" }, "sms_consent_given": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Sms Consent Given" }, "sms_consent_timestamp": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Sms Consent Timestamp" }, "sms_enabled": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Sms Enabled" } }, "title": "UpdateWidePreferencesRequest", "type": "object" }, "UpdateWorkspaceGuestPolicyRequest": { "properties": { "allow_cross_workspace_channels": { "title": "Allow Cross Workspace Channels", "type": "boolean" }, "allow_external_guests": { "title": "Allow External Guests", "type": "boolean" }, "default_expiration_days": { "maximum": 365.0, "minimum": 1.0, "title": "Default Expiration Days", "type": "integer" }, "federation_allowed_servers": { "items": { "type": "string" }, "title": "Federation Allowed Servers", "type": "array" }, "require_admin_approval": { "title": "Require Admin Approval", "type": "boolean" } }, "required": [ "allow_external_guests", "require_admin_approval", "default_expiration_days", "allow_cross_workspace_channels" ], "title": "UpdateWorkspaceGuestPolicyRequest", "type": "object" }, "UpdateWorkstationRequest": { "properties": { "color": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Color" }, "create_config": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Create Config" }, "icon": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Icon" }, "name": { "anyOf": [ { "maxLength": 200, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Name" }, "nav_config": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Nav Config" }, "position": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Position" }, "visibility": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Visibility" } }, "title": "UpdateWorkstationRequest", "type": "object" }, "UploadEntry": { "properties": { "note_id": { "title": "Note Id", "type": "string" }, "yjs_update": { "title": "Yjs Update", "type": "string" } }, "required": [ "note_id", "yjs_update" ], "title": "UploadEntry", "type": "object" }, "UploadedAttachment": { "description": "Response model for uploaded attachment.", "properties": { "content_type": { "description": "MIME type of the file", "title": "Content Type", "type": "string" }, "filename": { "description": "Original filename", "title": "Filename", "type": "string" }, "size_bytes": { "description": "File size in bytes", "title": "Size Bytes", "type": "integer" }, "storage_path": { "description": "Object storage key path", "title": "Storage Path", "type": "string" }, "thumbnail_path": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Thumbnail path for images", "title": "Thumbnail Path" } }, "required": [ "storage_path", "filename", "content_type", "size_bytes" ], "title": "UploadedAttachment", "type": "object" }, "UrlPreview": { "description": "Structured link preview metadata.\n\nUsed by the frontend to render link cards (title, image, favicon) when\na user pastes or attaches a URL to a note/task/message. Sourced from:\n\n * OpenGraph / Twitter Card / scraping for generic HTML pages\n * oEmbed for YouTube + Vimeo (richer video metadata)\n * URL-pattern heuristics for Google Drive / Docs / Sheets / Slides\n (auth-gated pages whose HTML is a login form)\n\nPorts the previous SvelteKit BFF implementation at\n``apps/web/src/routes/api/v1/url-preview/+server.ts`` verbatim.", "properties": { "author_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Author Url" }, "description": { "title": "Description", "type": "string" }, "duration_seconds": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Duration Seconds" }, "favicon_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Favicon Url" }, "image_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Image Url" }, "kind": { "default": "link", "enum": [ "link", "video" ], "title": "Kind", "type": "string" }, "provider": { "title": "Provider", "type": "string" }, "published_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Published At" }, "site_name": { "title": "Site Name", "type": "string" }, "title": { "title": "Title", "type": "string" }, "url": { "title": "Url", "type": "string" }, "video_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Video Id" } }, "required": [ "url", "title", "description", "site_name", "provider" ], "title": "UrlPreview", "type": "object" }, "UsablePlugin": { "description": "One plugin the member may use, as an assistant reads it.", "properties": { "actions": { "items": { "$ref": "#/components/schemas/AgentPluginAction" }, "title": "Actions", "type": "array" }, "beyond_actions": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Beyond Actions" }, "category": { "title": "Category", "type": "string" }, "category_label": { "title": "Category Label", "type": "string" }, "connect_link": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Connect Link" }, "connection_method": { "enum": [ "oauth", "api_key", "mcp", "app_install", "native_box_login", "webhook", "outgoing_webhook" ], "title": "Connection Method", "type": "string" }, "display_name": { "title": "Display Name", "type": "string" }, "events": { "items": { "$ref": "#/components/schemas/AgentPluginEvent" }, "title": "Events", "type": "array" }, "id": { "title": "Id", "type": "string" }, "kind": { "title": "Kind", "type": "string" }, "label": { "title": "Label", "type": "string" }, "last_error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Last Error" }, "lent_to": { "items": { "$ref": "#/components/schemas/UsablePluginLend" }, "title": "Lent To", "type": "array" }, "link": { "title": "Link", "type": "string" }, "owned_by_you": { "title": "Owned By You", "type": "boolean" }, "provider_name": { "title": "Provider Name", "type": "string" }, "settings": { "$ref": "#/components/schemas/UsablePluginSettings" }, "status": { "enum": [ "working", "needs_reauth", "disconnected", "pending" ], "title": "Status", "type": "string" }, "typed_id": { "title": "Typed Id", "type": "string" }, "used_by": { "items": { "type": "string" }, "title": "Used By", "type": "array" }, "user_step": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "User Step" }, "visibility": { "enum": [ "private", "shared" ], "title": "Visibility", "type": "string" } }, "required": [ "id", "typed_id", "kind", "display_name", "label", "category", "category_label", "provider_name", "connection_method", "status", "used_by", "visibility", "owned_by_you", "lent_to", "settings", "actions", "events", "link" ], "title": "UsablePlugin", "type": "object" }, "UsablePluginLend": { "description": "An employee ticked in the plugin's Access section.", "properties": { "employee_account_id": { "title": "Employee Account Id", "type": "string" }, "name": { "title": "Name", "type": "string" } }, "required": [ "employee_account_id", "name" ], "title": "UsablePluginLend", "type": "object" }, "UsablePluginSettings": { "description": "The non-secret half of a connection. A destination shows its host only:\nits full URL can itself be a secret (a Slack hook's path).", "properties": { "auth_scheme": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Auth Scheme" }, "base_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Base Url" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Description" }, "destination_host": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Destination Host" }, "events_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Events Url" }, "mcp_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Mcp Url" }, "scheme_config": { "additionalProperties": { "type": "string" }, "title": "Usable Plugin Scheme Config", "type": "object" } }, "title": "UsablePluginSettings", "type": "object" }, "UsablePluginsResponse": { "description": "``member``: the member's own and shared plugins. ``employee``: the\nplugins the acting employee was lent — the manifest its workshop reads.", "properties": { "acting_as": { "enum": [ "member", "employee" ], "title": "Acting As", "type": "string" }, "lent": { "items": { "$ref": "#/components/schemas/AgentPluginManifest" }, "title": "Lent", "type": "array" }, "plugins": { "items": { "$ref": "#/components/schemas/UsablePlugin" }, "title": "Plugins", "type": "array" } }, "required": [ "acting_as" ], "title": "UsablePluginsResponse", "type": "object" }, "UsageContext": { "additionalProperties": false, "properties": { "maxTokens": { "minimum": 0, "title": "Maxtokens", "type": "integer" }, "percentage": { "maximum": 100, "minimum": 0, "title": "Percentage", "type": "number" }, "totalTokens": { "minimum": 0, "title": "Totaltokens", "type": "integer" } }, "required": [ "percentage", "totalTokens", "maxTokens" ], "title": "UsageContext", "type": "object" }, "UsageContext-Input": { "additionalProperties": false, "properties": { "maxTokens": { "minimum": 0.0, "title": "Maxtokens", "type": "integer" }, "percentage": { "maximum": 100.0, "minimum": 0.0, "title": "Percentage", "type": "number" }, "totalTokens": { "minimum": 0.0, "title": "Totaltokens", "type": "integer" } }, "required": [ "percentage", "totalTokens", "maxTokens" ], "title": "UsageContext", "type": "object" }, "UsageContext-Output": {}, "UsageCoverage": { "additionalProperties": false, "properties": { "dateBasis": { "enum": [ "harness", "local_day", "observation_day" ], "title": "Datebasis", "type": "string" }, "from": { "format": "date", "title": "From", "type": "string" }, "scope": { "enum": [ "account", "device", "session" ], "title": "Scope", "type": "string" }, "to": { "format": "date", "title": "To", "type": "string" } }, "required": [ "from", "to", "scope", "dateBasis" ], "title": "UsageCoverage", "type": "object" }, "UsageCoverage-Input": { "additionalProperties": false, "properties": { "dateBasis": { "enum": [ "harness", "local_day", "observation_day" ], "title": "Datebasis", "type": "string" }, "from": { "format": "date", "title": "From", "type": "string" }, "scope": { "enum": [ "account", "device", "session" ], "title": "Scope", "type": "string" }, "to": { "format": "date", "title": "To", "type": "string" } }, "required": [ "from", "to", "scope", "dateBasis" ], "title": "UsageCoverage", "type": "object" }, "UsageCoverage-Output": {}, "UsageCredits": { "additionalProperties": false, "properties": { "balance": { "anyOf": [ { "minimum": 0, "type": "number" }, { "type": "null" } ], "default": null, "title": "Balance" }, "hasCredits": { "title": "Hascredits", "type": "boolean" }, "unlimited": { "title": "Unlimited", "type": "boolean" } }, "required": [ "hasCredits", "unlimited" ], "title": "UsageCredits", "type": "object" }, "UsageCredits-Input": { "additionalProperties": false, "properties": { "balance": { "anyOf": [ { "minimum": 0.0, "type": "number" }, { "type": "null" } ], "title": "Balance" }, "hasCredits": { "title": "Hascredits", "type": "boolean" }, "unlimited": { "title": "Unlimited", "type": "boolean" } }, "required": [ "hasCredits", "unlimited" ], "title": "UsageCredits", "type": "object" }, "UsageCredits-Output": {}, "UsageDayTotals": { "description": "One date × provider × model day, summed from the harness's dated facts.\n\nNever derived from `workforce_spend_daily` (A4-4): that table mixes\ncumulative session totals with daily increments, and a per-day figure from\nit double counts. `tokens_by_day` is the grain the \"Tokens by day\"\nsection renders.", "properties": { "cost_usd": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "title": "Cost Usd" }, "date": { "format": "date", "title": "Date", "type": "string" }, "fact_count": { "title": "Fact Count", "type": "integer" }, "input_tokens": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Input Tokens" }, "model": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Model" }, "output_tokens": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Output Tokens" }, "priced": { "title": "Priced", "type": "boolean" }, "provider": { "title": "Provider", "type": "string" }, "tokens": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Tokens" } }, "required": [ "date", "provider", "priced", "fact_count" ], "title": "UsageDayTotals", "type": "object" }, "UsageFact": { "additionalProperties": false, "properties": { "cacheRead": { "anyOf": [ { "minimum": 0.0, "type": "integer" }, { "type": "null" } ], "title": "Cacheread" }, "cacheWrite": { "anyOf": [ { "minimum": 0.0, "type": "integer" }, { "type": "null" } ], "title": "Cachewrite" }, "costUsd": { "anyOf": [ { "minimum": 0.0, "type": "number" }, { "type": "null" } ], "title": "Costusd" }, "date": { "format": "date", "title": "Date", "type": "string" }, "inputTokens": { "anyOf": [ { "minimum": 0.0, "type": "integer" }, { "type": "null" } ], "title": "Inputtokens" }, "model": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "title": "Model" }, "outputTokens": { "anyOf": [ { "minimum": 0.0, "type": "integer" }, { "type": "null" } ], "title": "Outputtokens" }, "priced": { "title": "Priced", "type": "boolean" }, "provider": { "maxLength": 255, "minLength": 1, "title": "Provider", "type": "string" }, "reasoningOutput": { "anyOf": [ { "minimum": 0.0, "type": "integer" }, { "type": "null" } ], "title": "Reasoningoutput" }, "totalTokens": { "anyOf": [ { "minimum": 0.0, "type": "integer" }, { "type": "null" } ], "title": "Totaltokens" } }, "required": [ "date", "provider", "model", "priced" ], "title": "UsageFact", "type": "object" }, "UsageInsightItem": { "description": "One item the scope's turns served, with what they spent on it (TIDY-19934).", "properties": { "activity_id": { "title": "Activity Id", "type": "string" }, "cost_usd": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "title": "Cost Usd" }, "partial_turns": { "default": 0, "title": "Partial Turns", "type": "integer" }, "short_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Short Id" }, "subagent_count": { "default": 0, "title": "Subagent Count", "type": "integer" }, "subagent_tokens": { "title": "Subagent Tokens", "type": "integer" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Title" }, "tokens": { "title": "Tokens", "type": "integer" }, "turn_count": { "title": "Turn Count", "type": "integer" }, "unreported_turns": { "default": 0, "title": "Unreported Turns", "type": "integer" } }, "required": [ "activity_id", "turn_count", "tokens", "subagent_tokens" ], "title": "UsageInsightItem", "type": "object" }, "UsageInsightRow": { "description": "One figure, with everything a member needs to trust or act on it.", "properties": { "cause": { "title": "Cause", "type": "string" }, "caveat": { "title": "Caveat", "type": "string" }, "figure": { "title": "Figure", "type": "string" }, "group": { "enum": [ "where_it_went", "worth_attention" ], "title": "Group", "type": "string" }, "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Id" }, "key": { "title": "Key", "type": "string" }, "measured_turns": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Measured Turns" }, "remedy": { "title": "Remedy", "type": "string" }, "source": { "title": "Source", "type": "string" }, "unit": { "enum": [ "percent", "multiple", "usd", "usd_vs_weekly", "minutes", "share" ], "title": "Unit", "type": "string" }, "value": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "title": "Value" } }, "required": [ "key", "group", "figure", "unit", "cause", "remedy", "source", "caveat" ], "title": "UsageInsightRow", "type": "object" }, "UsageInsightsResponse": { "properties": { "caveat": { "title": "Caveat", "type": "string" }, "computed_at": { "title": "Computed At", "type": "string" }, "coverage_from": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Coverage From" }, "empty_reason": { "anyOf": [ { "enum": [ "insufficient_turns", "no_supported_metrics" ], "type": "string" }, { "type": "null" } ], "default": null, "title": "Empty Reason" }, "items": { "items": { "$ref": "#/components/schemas/UsageInsightItem" }, "title": "Items", "type": "array" }, "rows": { "items": { "$ref": "#/components/schemas/UsageInsightRow" }, "title": "Rows", "type": "array" }, "scope": { "enum": [ "employee", "workshop" ], "title": "Scope", "type": "string" }, "scope_key": { "title": "Scope Key", "type": "string" }, "slice": { "$ref": "#/components/schemas/UsageSliceInfo" }, "turn_count": { "title": "Turn Count", "type": "integer" }, "usage_coverage": { "anyOf": [ { "$ref": "#/components/schemas/TurnUsageCoverage" }, { "type": "null" } ], "default": null } }, "required": [ "scope", "scope_key", "slice", "turn_count", "computed_at", "caveat" ], "title": "UsageInsightsResponse", "type": "object" }, "UsageLane": { "description": "One provider × model lane over the slice.\n\n`cost_usd` is null whenever `priced` is false — a local lane reports its\ntokens and says it is unpriced, and never reports `$0.00`.", "properties": { "cost_usd": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "title": "Cost Usd" }, "days": { "title": "Days", "type": "integer" }, "input_tokens": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Input Tokens" }, "model": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Model" }, "output_tokens": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Output Tokens" }, "priced": { "title": "Priced", "type": "boolean" }, "provider": { "title": "Provider", "type": "string" }, "tokens": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Tokens" } }, "required": [ "provider", "priced", "days" ], "title": "UsageLane", "type": "object" }, "UsageLimitsResponse": { "properties": { "rows": { "items": { "$ref": "#/components/schemas/UsageLimitsRow" }, "title": "Rows", "type": "array" }, "scope": { "enum": [ "employee", "workshop" ], "title": "Scope", "type": "string" }, "scope_key": { "title": "Scope Key", "type": "string" }, "slice": { "$ref": "#/components/schemas/UsageSliceInfo" } }, "required": [ "scope", "scope_key", "slice" ], "title": "UsageLimitsResponse", "type": "object" }, "UsageLimitsRow": { "description": "One employee × harness reading. Absent entirely when nothing was observed.", "properties": { "context": { "anyOf": [ { "$ref": "#/components/schemas/UsageContext" }, { "type": "null" } ], "default": null }, "coverage": { "anyOf": [ { "$ref": "#/components/schemas/UsageCoverage" }, { "type": "null" } ], "default": null }, "employee_account_id": { "title": "Employee Account Id", "type": "string" }, "employee_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Employee Name" }, "is_default": { "default": false, "title": "Is Default", "type": "boolean" }, "lanes": { "items": { "$ref": "#/components/schemas/UsageLane" }, "title": "Lanes", "type": "array" }, "last_attempt_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Last Attempt At" }, "last_success_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Last Success At" }, "observed_at": { "format": "date-time", "title": "Observed At", "type": "string" }, "part_unavailable": { "additionalProperties": { "$ref": "#/components/schemas/UsageUnavailable" }, "propertyNames": { "enum": [ "windows", "usageFacts", "context", "plan" ] }, "title": "Part Unavailable", "type": "object" }, "plan": { "anyOf": [ { "$ref": "#/components/schemas/UsagePlan" }, { "type": "null" } ], "default": null }, "pool_key": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Pool Key" }, "profile_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Profile Id" }, "runtime": { "title": "Runtime", "type": "string" }, "source": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Source" }, "tokens_by_day": { "items": { "$ref": "#/components/schemas/UsageDayTotals" }, "title": "Tokens By Day", "type": "array" }, "totals": { "anyOf": [ { "$ref": "#/components/schemas/UsageTotals" }, { "type": "null" } ], "default": null }, "windows": { "items": { "$ref": "#/components/schemas/UsageWindow" }, "title": "Windows", "type": "array" } }, "required": [ "employee_account_id", "runtime", "observed_at" ], "title": "UsageLimitsRow", "type": "object" }, "UsageObservation": { "additionalProperties": false, "properties": { "observedAt": { "format": "date-time", "title": "Observedat", "type": "string" } }, "required": [ "observedAt" ], "title": "UsageObservation", "type": "object" }, "UsagePlan": { "additionalProperties": false, "properties": { "credits": { "anyOf": [ { "$ref": "#/components/schemas/UsageCredits" }, { "type": "null" } ], "default": null }, "subscriptionType": { "anyOf": [ { "maxLength": 80, "type": "string" }, { "type": "null" } ], "default": null, "title": "Subscriptiontype" } }, "title": "UsagePlan", "type": "object" }, "UsagePlan-Input": { "additionalProperties": false, "properties": { "credits": { "anyOf": [ { "$ref": "#/components/schemas/UsageCredits-Input" }, { "type": "null" } ] }, "subscriptionType": { "anyOf": [ { "maxLength": 80, "type": "string" }, { "type": "null" } ], "title": "Subscriptiontype" } }, "title": "UsagePlan", "type": "object" }, "UsagePlan-Output": {}, "UsageSliceInfo": { "description": "WHICH stretch of calendar this reading covers, and in whose calendar.", "properties": { "from": { "anyOf": [ { "format": "date", "type": "string" }, { "type": "null" } ], "default": null, "title": "From" }, "key": { "title": "Key", "type": "string" }, "label": { "title": "Label", "type": "string" }, "timezone": { "title": "Timezone", "type": "string" }, "to": { "anyOf": [ { "format": "date", "type": "string" }, { "type": "null" } ], "default": null, "title": "To" } }, "required": [ "key", "label", "timezone" ], "title": "UsageSliceInfo", "type": "object" }, "UsageSpend": { "additionalProperties": false, "properties": { "costUsd": { "anyOf": [ { "minimum": 0.0, "type": "number" }, { "type": "null" } ], "title": "Costusd" }, "coverage": { "enum": [ "account", "device", "session" ], "title": "Coverage", "type": "string" }, "priced": { "title": "Priced", "type": "boolean" } }, "required": [ "priced", "coverage" ], "title": "UsageSpend", "type": "object" }, "UsageTotals": { "description": "The slice's sum. Same pricing rule as a lane.", "properties": { "cache_read": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Cache Read" }, "cache_write": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Cache Write" }, "cost_usd": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "title": "Cost Usd" }, "fact_count": { "title": "Fact Count", "type": "integer" }, "input_tokens": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Input Tokens" }, "output_tokens": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Output Tokens" }, "priced": { "title": "Priced", "type": "boolean" }, "reasoning_output": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Reasoning Output" }, "tokens": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Tokens" } }, "required": [ "priced", "fact_count" ], "title": "UsageTotals", "type": "object" }, "UsageUnavailable": { "additionalProperties": false, "properties": { "message": { "anyOf": [ { "maxLength": 500, "type": "string" }, { "type": "null" } ], "default": null, "title": "Message" }, "parts": { "anyOf": [ { "items": { "enum": [ "windows", "usageFacts", "context", "plan" ], "type": "string" }, "type": "array" }, { "type": "null" } ], "default": null, "title": "Parts" }, "reason": { "enum": [ "unsupported", "probeFailed" ], "title": "Reason", "type": "string" } }, "required": [ "reason" ], "title": "UsageUnavailable", "type": "object" }, "UsageUnavailable-Input": { "additionalProperties": false, "properties": { "message": { "anyOf": [ { "maxLength": 500, "type": "string" }, { "type": "null" } ], "title": "Message" }, "parts": { "anyOf": [ { "items": { "enum": [ "windows", "usageFacts", "context", "plan" ], "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Parts" }, "reason": { "enum": [ "unsupported", "probeFailed" ], "title": "Reason", "type": "string" } }, "required": [ "reason" ], "title": "UsageUnavailable", "type": "object" }, "UsageUnavailable-Output": {}, "UsageVerdict": { "description": "One live standing instruction.", "properties": { "decided_at": { "title": "Decided At", "type": "string" }, "id": { "title": "Id", "type": "string" }, "source_surface": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Source Surface" }, "target_id": { "title": "Target Id", "type": "string" }, "target_type": { "title": "Target Type", "type": "string" }, "verdict": { "title": "Verdict", "type": "string" } }, "required": [ "id", "verdict", "target_type", "target_id", "decided_at" ], "title": "UsageVerdict", "type": "object" }, "UsageVerdictClearRequest": { "description": "Retire the caller's standing instruction about one target.", "properties": { "target_id": { "maxLength": 64, "minLength": 1, "title": "Target Id", "type": "string" }, "target_type": { "maxLength": 64, "minLength": 1, "title": "Target Type", "type": "string" } }, "required": [ "target_type", "target_id" ], "title": "UsageVerdictClearRequest", "type": "object" }, "UsageVerdictList": { "properties": { "verdicts": { "items": { "$ref": "#/components/schemas/UsageVerdict" }, "title": "Verdicts", "type": "array" } }, "required": [ "verdicts" ], "title": "UsageVerdictList", "type": "object" }, "UsageVerdictRequest": { "description": "One standing instruction about one target.", "properties": { "source_surface": { "anyOf": [ { "maxLength": 64, "type": "string" }, { "type": "null" } ], "title": "Source Surface" }, "target_id": { "maxLength": 64, "minLength": 1, "title": "Target Id", "type": "string" }, "target_type": { "maxLength": 64, "minLength": 1, "title": "Target Type", "type": "string" }, "verdict": { "maxLength": 16, "minLength": 1, "title": "Verdict", "type": "string" } }, "required": [ "target_type", "target_id", "verdict" ], "title": "UsageVerdictRequest", "type": "object" }, "UsageVerdictResult": { "description": "The stored instruction. ``changed`` is false when it was already this.", "properties": { "changed": { "title": "Changed", "type": "boolean" }, "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Id" }, "target_id": { "title": "Target Id", "type": "string" }, "target_type": { "title": "Target Type", "type": "string" }, "verdict": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Verdict" } }, "required": [ "target_type", "target_id", "changed" ], "title": "UsageVerdictResult", "type": "object" }, "UsageWindow": { "additionalProperties": false, "properties": { "id": { "maxLength": 255, "minLength": 1, "title": "Id", "type": "string" }, "kind": { "enum": [ "session", "weekly", "monthly", "other" ], "title": "Kind", "type": "string" }, "label": { "maxLength": 255, "minLength": 1, "title": "Label", "type": "string" }, "model": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "default": null, "title": "Model" }, "reachedType": { "anyOf": [ { "maxLength": 100, "type": "string" }, { "type": "null" } ], "default": null, "title": "Reachedtype" }, "resetsAt": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Resetsat" }, "usedPercent": { "maximum": 100, "minimum": 0, "title": "Usedpercent", "type": "number" }, "windowDurationMins": { "anyOf": [ { "minimum": 0, "type": "number" }, { "type": "null" } ], "default": null, "title": "Windowdurationmins" } }, "required": [ "id", "kind", "label", "usedPercent" ], "title": "UsageWindow", "type": "object" }, "UsageWindow-Input": { "additionalProperties": false, "properties": { "id": { "maxLength": 255, "minLength": 1, "title": "Id", "type": "string" }, "kind": { "enum": [ "session", "weekly", "monthly", "other" ], "title": "Kind", "type": "string" }, "label": { "maxLength": 255, "minLength": 1, "title": "Label", "type": "string" }, "model": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "title": "Model" }, "reachedType": { "anyOf": [ { "maxLength": 100, "type": "string" }, { "type": "null" } ], "title": "Reachedtype" }, "resetsAt": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Resetsat" }, "usedPercent": { "maximum": 100.0, "minimum": 0.0, "title": "Usedpercent", "type": "number" }, "windowDurationMins": { "anyOf": [ { "minimum": 0.0, "type": "number" }, { "type": "null" } ], "title": "Windowdurationmins" } }, "required": [ "id", "kind", "label", "usedPercent" ], "title": "UsageWindow", "type": "object" }, "UsageWindow-Output": {}, "UserCapRequest": { "properties": { "hard_cap_credits": { "anyOf": [ { "minimum": 0.0, "type": "number" }, { "type": "null" } ], "title": "Hard Cap Credits" }, "user_id": { "title": "User Id", "type": "string" } }, "required": [ "user_id" ], "title": "UserCapRequest", "type": "object" }, "UserCapResponse": { "properties": { "hard_cap_credits": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "title": "Hard Cap Credits" }, "user_id": { "title": "User Id", "type": "string" } }, "required": [ "user_id" ], "title": "UserCapResponse", "type": "object" }, "UserCreditRollup": { "properties": { "consumed": { "title": "Consumed", "type": "number" }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Email" }, "user_id": { "title": "User Id", "type": "string" } }, "required": [ "user_id", "consumed" ], "title": "UserCreditRollup", "type": "object" }, "UserNotificationListResponse": { "description": "Response model for paginated notification list.", "properties": { "items": { "items": { "$ref": "#/components/schemas/UserNotificationResponse" }, "title": "Items", "type": "array" }, "total": { "title": "Total", "type": "integer" }, "unread_count": { "title": "Unread Count", "type": "integer" } }, "required": [ "items", "unread_count", "total" ], "title": "UserNotificationListResponse", "type": "object" }, "UserNotificationPreferencesResponse": { "description": "User notification preferences object.\n\nUsed in GET /api/v1/news-updates/preferences.\n\nAttributes:\n enabled_channels: Array of enabled channels (in_app, email, sms, whatsapp, push)\n update_frequency: Frequency for individual updates (immediate, daily, weekly, off)\n summary_frequency: Frequency for summaries (daily, weekly, monthly, off)\n quiet_hours_start: Quiet hours start time (HH:MM:SS format)\n quiet_hours_end: Quiet hours end time (HH:MM:SS format)\n excluded_categories: Array of excluded categories\n\nExample:\n {\n \"enabled_channels\": [\"in_app\", \"email\"],\n \"update_frequency\": \"daily\",\n \"summary_frequency\": \"weekly\",\n \"quiet_hours_start\": \"22:00:00\",\n \"quiet_hours_end\": \"07:00:00\",\n \"excluded_categories\": []\n }", "properties": { "enabled_channels": { "description": "Array of enabled channels", "items": { "type": "string" }, "title": "Enabled Channels", "type": "array" }, "excluded_categories": { "description": "Array of excluded categories", "items": { "type": "string" }, "title": "Excluded Categories", "type": "array" }, "quiet_hours_end": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Quiet hours end (HH:MM:SS)", "title": "Quiet Hours End" }, "quiet_hours_start": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Quiet hours start (HH:MM:SS)", "title": "Quiet Hours Start" }, "summary_frequency": { "description": "Frequency for summaries", "title": "Summary Frequency", "type": "string" }, "update_frequency": { "description": "Frequency for individual updates", "title": "Update Frequency", "type": "string" } }, "required": [ "enabled_channels", "update_frequency", "summary_frequency" ], "title": "UserNotificationPreferencesResponse", "type": "object" }, "UserNotificationPreferencesUpdate": { "description": "Input for updating notification preferences.\n\nUsed in PUT /api/v1/news-updates/preferences.\n\nAttributes:\n enabled_channels: Array of enabled channels\n update_frequency: Frequency for individual updates\n summary_frequency: Frequency for summaries\n quiet_hours_start: Quiet hours start time\n quiet_hours_end: Quiet hours end time\n excluded_categories: Array of excluded categories\n\nExample:\n {\n \"enabled_channels\": [\"in_app\", \"email\", \"sms\"],\n \"update_frequency\": \"daily\",\n \"summary_frequency\": \"weekly\",\n \"quiet_hours_start\": \"22:00:00\",\n \"quiet_hours_end\": \"07:00:00\",\n \"excluded_categories\": [\"sports\"]\n }", "properties": { "enabled_channels": { "description": "Array of enabled channels", "items": { "type": "string" }, "title": "Enabled Channels", "type": "array" }, "excluded_categories": { "description": "Array of excluded categories", "items": { "type": "string" }, "title": "Excluded Categories", "type": "array" }, "quiet_hours_end": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Quiet hours end (HH:MM:SS)", "title": "Quiet Hours End" }, "quiet_hours_start": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Quiet hours start (HH:MM:SS)", "title": "Quiet Hours Start" }, "summary_frequency": { "description": "Frequency for summaries", "title": "Summary Frequency", "type": "string" }, "update_frequency": { "description": "Frequency for individual updates", "title": "Update Frequency", "type": "string" } }, "required": [ "enabled_channels", "update_frequency", "summary_frequency" ], "title": "UserNotificationPreferencesUpdate", "type": "object" }, "UserNotificationResponse": { "description": "Response model for a single notification.", "properties": { "account_id": { "format": "uuid", "title": "Account Id", "type": "string" }, "body": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Body" }, "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "id": { "format": "uuid", "title": "Id", "type": "string" }, "link": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Link" }, "metadata": { "additionalProperties": true, "title": "Metadata", "type": "object" }, "read_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Read At" }, "tenant_id": { "format": "uuid", "title": "Tenant Id", "type": "string" }, "title": { "title": "Title", "type": "string" }, "type": { "title": "Type", "type": "string" } }, "required": [ "id", "tenant_id", "account_id", "type", "title", "created_at" ], "title": "UserNotificationResponse", "type": "object" }, "UserPreferencesPatch": { "description": "Partial update body. Only set fields are written.", "properties": { "base_values": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Base Values" }, "calendar_default_collection_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Calendar Default Collection Id" }, "calendar_default_timed_item_duration_minutes": { "anyOf": [ { "maximum": 480.0, "minimum": 5.0, "type": "integer" }, { "type": "null" } ], "title": "Calendar Default Timed Item Duration Minutes" }, "calendar_imminent_delete_approval": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Calendar Imminent Delete Approval" }, "calendar_new_event_template_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Calendar New Event Template Id" }, "calendar_proposal_include_availability": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Calendar Proposal Include Availability" }, "calendar_working_hours": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Calendar Working Hours" }, "default_assistant_matrix_id": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "title": "Default Assistant Matrix Id" }, "default_employee_ref": { "anyOf": [ { "$ref": "#/components/schemas/DefaultEmployeeRef" }, { "type": "null" } ] }, "defense_replay_skin": { "anyOf": [ { "enum": [ "medieval", "schematic" ], "type": "string" }, { "type": "null" } ], "title": "Defense Replay Skin" }, "email_default_render_mode": { "anyOf": [ { "enum": [ "html", "markdown" ], "type": "string" }, { "type": "null" } ], "title": "Email Default Render Mode" }, "email_draft_instructions": { "anyOf": [ { "maxLength": 2000, "type": "string" }, { "type": "null" } ], "title": "Email Draft Instructions" }, "employee_call_effort": { "anyOf": [ { "enum": [ "low", "off" ], "type": "string" }, { "type": "null" } ], "title": "Employee Call Effort" }, "feed_settings": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Feed Settings" }, "file_upload_journal_link_enabled": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "File Upload Journal Link Enabled" }, "huddle_journal_embeds_enabled": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Huddle Journal Embeds Enabled" }, "import_google_other_contacts": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Import Google Other Contacts" }, "inbox_highlights_enabled": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Inbox Highlights Enabled" }, "inbox_highlights_instruction": { "anyOf": [ { "maxLength": 256, "type": "string" }, { "type": "null" } ], "title": "Inbox Highlights Instruction" }, "journal_daily_default_banner_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Journal Daily Default Banner Url" }, "journal_daily_default_icon": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Journal Daily Default Icon" }, "journal_daily_template_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Journal Daily Template Id" }, "journal_monthly_default_banner_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Journal Monthly Default Banner Url" }, "journal_monthly_default_icon": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Journal Monthly Default Icon" }, "journal_monthly_template_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Journal Monthly Template Id" }, "journal_weekly_default_banner_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Journal Weekly Default Banner Url" }, "journal_weekly_default_icon": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Journal Weekly Default Icon" }, "journal_weekly_template_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Journal Weekly Template Id" }, "keyboard_footer_hints_enabled": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Keyboard Footer Hints Enabled" }, "known_dock_types": { "anyOf": [ { "items": { "type": "string" }, "maxItems": 128, "type": "array" }, { "type": "null" } ], "description": "Dock types this client can render. Whole-list saves preserve existing docks outside this set. Omission declares the legacy set before plugin/browser; send all supported types to remove them normally. Not a stored preference.", "title": "Known Dock Types" }, "photo_settings": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Photo Settings" }, "projection_llm_free_enabled": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Projection Llm Free Enabled" }, "right_panel_docks": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Right Panel Docks" }, "shorten_long_voice_replies": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Shorten Long Voice Replies" }, "show_pending_contacts_inline": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Show Pending Contacts Inline" }, "show_pending_tasks_inline": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Show Pending Tasks Inline" }, "source_context": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Source Context" }, "spellcheck_enabled": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Spellcheck Enabled" }, "switcher_layout": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Switcher Layout" }, "task_new_task_template_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Task New Task Template Id" }, "theme_accent": { "anyOf": [ { "maxLength": 64, "type": "string" }, { "type": "null" } ], "title": "Theme Accent" }, "theme_advanced_overrides": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Theme Advanced Overrides" }, "theme_mode_override": { "anyOf": [ { "maxLength": 16, "type": "string" }, { "type": "null" } ], "title": "Theme Mode Override" }, "theme_name": { "anyOf": [ { "maxLength": 64, "type": "string" }, { "type": "null" } ], "title": "Theme Name" }, "time_automation_level": { "anyOf": [ { "enum": [ "passive", "assisted", "directive" ], "type": "string" }, { "type": "null" } ], "title": "Time Automation Level" }, "time_tracking_enabled": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Time Tracking Enabled" }, "usage_learning_enabled": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Usage Learning Enabled" }, "use_company_logo_avatars": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Use Company Logo Avatars" } }, "title": "UserPreferencesPatch", "type": "object" }, "UserPreferencesResponse": { "properties": { "calendar_default_collection_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "default": null, "title": "Calendar Default Collection Id" }, "calendar_default_timed_item_duration_minutes": { "default": 30, "title": "Calendar Default Timed Item Duration Minutes", "type": "integer" }, "calendar_imminent_delete_approval": { "default": true, "title": "Calendar Imminent Delete Approval", "type": "boolean" }, "calendar_new_event_template_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "default": null, "title": "Calendar New Event Template Id" }, "calendar_proposal_include_availability": { "default": false, "title": "Calendar Proposal Include Availability", "type": "boolean" }, "calendar_working_hours": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "title": "Calendar Working Hours" }, "calendar_write_target_collection_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "default": null, "title": "Calendar Write Target Collection Id" }, "default_assistant_matrix_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Default Assistant Matrix Id" }, "default_employee_ref": { "anyOf": [ { "$ref": "#/components/schemas/DefaultEmployeeRef" }, { "type": "null" } ], "default": null }, "defense_replay_skin": { "default": "schematic", "enum": [ "medieval", "schematic" ], "title": "Defense Replay Skin", "type": "string" }, "email_default_render_mode": { "default": "html", "enum": [ "html", "markdown" ], "title": "Email Default Render Mode", "type": "string" }, "email_draft_instructions": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Email Draft Instructions" }, "employee_call_effort": { "anyOf": [ { "enum": [ "low", "off" ], "type": "string" }, { "type": "null" } ], "default": null, "title": "Employee Call Effort" }, "feed_settings": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "title": "Feed Settings" }, "file_upload_journal_link_enabled": { "default": true, "title": "File Upload Journal Link Enabled", "type": "boolean" }, "huddle_journal_embeds_enabled": { "default": true, "title": "Huddle Journal Embeds Enabled", "type": "boolean" }, "import_google_other_contacts": { "title": "Import Google Other Contacts", "type": "boolean" }, "inbox_highlights_enabled": { "default": true, "title": "Inbox Highlights Enabled", "type": "boolean" }, "inbox_highlights_instruction": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Inbox Highlights Instruction" }, "journal_daily_default_banner_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Journal Daily Default Banner Url" }, "journal_daily_default_icon": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Journal Daily Default Icon" }, "journal_daily_template_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "default": null, "title": "Journal Daily Template Id" }, "journal_monthly_default_banner_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Journal Monthly Default Banner Url" }, "journal_monthly_default_icon": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Journal Monthly Default Icon" }, "journal_monthly_template_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "default": null, "title": "Journal Monthly Template Id" }, "journal_weekly_default_banner_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Journal Weekly Default Banner Url" }, "journal_weekly_default_icon": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Journal Weekly Default Icon" }, "journal_weekly_template_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "default": null, "title": "Journal Weekly Template Id" }, "keyboard_footer_hints_enabled": { "default": true, "title": "Keyboard Footer Hints Enabled", "type": "boolean" }, "photo_settings": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "title": "Photo Settings" }, "projection_llm_free_enabled": { "default": false, "title": "Projection Llm Free Enabled", "type": "boolean" }, "right_panel_docks": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "title": "Right Panel Docks" }, "shorten_long_voice_replies": { "default": false, "title": "Shorten Long Voice Replies", "type": "boolean" }, "show_pending_contacts_inline": { "title": "Show Pending Contacts Inline", "type": "boolean" }, "show_pending_tasks_inline": { "title": "Show Pending Tasks Inline", "type": "boolean" }, "spellcheck_enabled": { "default": true, "title": "Spellcheck Enabled", "type": "boolean" }, "switcher_layout": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "title": "Switcher Layout" }, "task_new_task_template_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "default": null, "title": "Task New Task Template Id" }, "theme_accent": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Theme Accent" }, "theme_advanced_overrides": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "title": "Theme Advanced Overrides" }, "theme_mode_override": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Theme Mode Override" }, "theme_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Theme Name" }, "time_automation_level": { "anyOf": [ { "enum": [ "passive", "assisted", "directive" ], "type": "string" }, { "type": "null" } ], "default": null, "title": "Time Automation Level" }, "time_tracking_enabled": { "default": true, "title": "Time Tracking Enabled", "type": "boolean" }, "usage_learning_enabled": { "default": true, "title": "Usage Learning Enabled", "type": "boolean" }, "use_company_logo_avatars": { "default": true, "title": "Use Company Logo Avatars", "type": "boolean" } }, "required": [ "show_pending_contacts_inline", "show_pending_tasks_inline", "import_google_other_contacts" ], "title": "UserPreferencesResponse", "type": "object" }, "UserProfileCreate": { "additionalProperties": false, "description": "Request model for creating user profile with initial data.", "properties": { "address": { "anyOf": [ { "$ref": "#/components/schemas/AddressData" }, { "type": "null" } ], "deprecated": true, "description": "Retired: set Home location through PUT /profiles/me/location instead.", "x-retired": true }, "avatar_url": { "anyOf": [ { "maxLength": 2048, "type": "string" }, { "type": "null" } ], "title": "Avatar Url" }, "base_values": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Base Values" }, "date_of_birth": { "anyOf": [ { "format": "date", "type": "string" }, { "type": "null" } ], "title": "Date Of Birth" }, "first_name": { "anyOf": [ { "maxLength": 255, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "First Name" }, "full_name": { "anyOf": [ { "maxLength": 255, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Full Name" }, "last_name": { "anyOf": [ { "maxLength": 255, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Last Name" }, "phone_number": { "anyOf": [ { "maxLength": 50, "type": "string" }, { "type": "null" } ], "title": "Phone Number" }, "source_context": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Source Context" } }, "title": "UserProfileCreate", "type": "object" }, "UserProfileResponse": { "description": "Response model for user profile with family members.", "properties": { "account_id": { "description": "User account UUID", "format": "uuid", "title": "Account Id", "type": "string" }, "address": { "anyOf": [ { "$ref": "#/components/schemas/AddressData" }, { "type": "null" } ], "default": null, "deprecated": true, "description": "Retired postal address; use Home location." }, "avatar_schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Self vector-avatar schema JSON (TIDY-13113)", "title": "Avatar Schema" }, "avatar_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "OAuth profile avatar URL", "title": "Avatar Url" }, "created_at": { "description": "Creation timestamp", "format": "date-time", "title": "Created At", "type": "string" }, "date_of_birth": { "anyOf": [ { "format": "date", "type": "string" }, { "type": "null" } ], "default": null, "description": "Date of birth", "title": "Date Of Birth" }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Email address from OAuth (read-only)", "title": "Email" }, "family_members": { "description": "Family members (spouse, children)", "items": { "$ref": "#/components/schemas/FamilyMemberResponse" }, "title": "Family Members", "type": "array" }, "first_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "User's first name", "title": "First Name" }, "full_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "User's full name (backward compatibility)", "title": "Full Name" }, "last_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "User's last name", "title": "Last Name" }, "mailbox_email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Unique inbox email (e.g., smith@mail.tidy.engineering)", "title": "Mailbox Email" }, "phone_number": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Primary phone number (backward compatibility)", "title": "Phone Number" }, "phone_numbers": { "description": "All account phone numbers", "items": { "$ref": "#/components/schemas/ProfilePhoneNumberResponse" }, "title": "Phone Numbers", "type": "array" }, "tenant_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "default": null, "description": "Tenant UUID", "title": "Tenant Id" }, "updated_at": { "description": "Last update timestamp", "format": "date-time", "title": "Updated At", "type": "string" } }, "required": [ "account_id", "created_at", "updated_at" ], "title": "UserProfileResponse", "type": "object" }, "UserProfileUpdate": { "additionalProperties": false, "description": "Request model for updating user profile (all fields optional).", "properties": { "address": { "anyOf": [ { "$ref": "#/components/schemas/AddressData" }, { "type": "null" } ], "deprecated": true, "description": "Retired: set Home location through PUT /profiles/me/location instead.", "x-retired": true }, "avatar_url": { "anyOf": [ { "maxLength": 2048, "type": "string" }, { "type": "null" } ], "title": "Avatar Url" }, "base_values": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Base Values" }, "date_of_birth": { "anyOf": [ { "format": "date", "type": "string" }, { "type": "null" } ], "title": "Date Of Birth" }, "first_name": { "anyOf": [ { "maxLength": 255, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "First Name" }, "full_name": { "anyOf": [ { "maxLength": 255, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Full Name" }, "last_name": { "anyOf": [ { "maxLength": 255, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Last Name" }, "phone_number": { "anyOf": [ { "maxLength": 50, "type": "string" }, { "type": "null" } ], "title": "Phone Number" }, "source_context": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Source Context" } }, "title": "UserProfileUpdate", "type": "object" }, "UserReminderPreferencesResponse": { "description": "Response model for user reminder preferences", "properties": { "account_id": { "description": "Account ID", "format": "uuid", "title": "Account Id", "type": "string" }, "created_at": { "description": "Preferences creation timestamp", "format": "date-time", "title": "Created At", "type": "string" }, "default_delivery_methods": { "default": "push", "description": "Default delivery methods (comma-separated)", "title": "Default Delivery Methods", "type": "string" }, "default_metadata": { "additionalProperties": true, "description": "Default metadata (email, phone, etc.)", "title": "Default Metadata", "type": "object" }, "id": { "description": "Unique preferences ID", "format": "uuid", "title": "Id", "type": "string" }, "quiet_hours_end": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Quiet hours end time (HH:MM)", "title": "Quiet Hours End" }, "quiet_hours_start": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Quiet hours start time (HH:MM)", "title": "Quiet Hours Start" }, "timezone": { "default": "America/New_York", "description": "User timezone", "title": "Timezone", "type": "string" }, "updated_at": { "description": "Preferences last update timestamp", "format": "date-time", "title": "Updated At", "type": "string" } }, "required": [ "id", "account_id", "created_at", "updated_at" ], "title": "UserReminderPreferencesResponse", "type": "object" }, "UserReminderPreferencesUpdate": { "description": "Request model for updating user reminder preferences", "properties": { "default_delivery_methods": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Default delivery methods (comma-separated)", "title": "Default Delivery Methods" }, "default_metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "Default metadata (email, phone, etc.)", "title": "Default Metadata" }, "quiet_hours_end": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Quiet hours end time (HH:MM)", "title": "Quiet Hours End" }, "quiet_hours_start": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Quiet hours start time (HH:MM)", "title": "Quiet Hours Start" }, "timezone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "User timezone (IANA identifier, e.g., 'America/New_York')", "title": "Timezone" } }, "title": "UserReminderPreferencesUpdate", "type": "object" }, "UserUsage": { "properties": { "account_id": { "title": "Account Id", "type": "string" }, "credits_used": { "title": "Credits Used", "type": "number" }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Email" } }, "required": [ "account_id", "credits_used" ], "title": "UserUsage", "type": "object" }, "ValidateInviteRequest": { "properties": { "code": { "title": "Code", "type": "string" }, "email": { "title": "Email", "type": "string" } }, "required": [ "code", "email" ], "title": "ValidateInviteRequest", "type": "object" }, "ValidateRecipientsRequest": { "description": "Body for the send-time expansion preview (TIDY-14747).", "properties": { "bcc_recipients": { "items": { "$ref": "#/components/schemas/RecipientInput" }, "title": "Bcc Recipients", "type": "array" }, "cc_recipients": { "items": { "$ref": "#/components/schemas/RecipientInput" }, "title": "Cc Recipients", "type": "array" }, "to_recipients": { "items": { "$ref": "#/components/schemas/RecipientInput" }, "title": "To Recipients", "type": "array" } }, "title": "ValidateRecipientsRequest", "type": "object" }, "ValidationError": { "properties": { "ctx": { "title": "Context", "type": "object" }, "input": { "title": "Input" }, "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "title": "Location", "type": "array" }, "msg": { "title": "Message", "type": "string" }, "type": { "title": "Error Type", "type": "string" } }, "required": [ "loc", "msg", "type" ], "title": "ValidationError", "type": "object" }, "ValidationErrorDetail": { "properties": { "code": { "title": "Code", "type": "string" }, "message": { "title": "Message", "type": "string" }, "ref": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Ref" } }, "required": [ "code", "message" ], "title": "ValidationErrorDetail", "type": "object" }, "ValidationRunIngest": { "properties": { "kind": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Kind" }, "links": { "default": [], "items": { "$ref": "#/components/schemas/EvidenceLinkIn" }, "title": "Links", "type": "array" }, "provider": { "default": "local", "title": "Provider", "type": "string" }, "ran_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Ran At" }, "repository": { "minLength": 1, "title": "Repository", "type": "string" }, "result": { "default": "pass", "enum": [ "pass", "fail", "error", "skipped" ], "title": "Result", "type": "string" }, "run_identifier": { "minLength": 1, "title": "Run Identifier", "type": "string" }, "source_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Source Url" }, "summary": { "additionalProperties": true, "default": {}, "title": "Summary", "type": "object" } }, "required": [ "repository", "run_identifier" ], "title": "ValidationRunIngest", "type": "object" }, "ValueSettingEntry": { "properties": { "description": { "title": "Description", "type": "string" }, "key": { "title": "Key", "type": "string" }, "kind": { "enum": [ "integer", "boolean" ], "title": "Kind", "type": "string" }, "label": { "title": "Label", "type": "string" }, "lifecycle": { "default": "ga", "title": "Lifecycle", "type": "string" }, "maximum": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Maximum" }, "minimum": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Minimum" }, "value": { "anyOf": [ { "type": "integer" }, { "type": "boolean" } ], "title": "Value" } }, "required": [ "key", "label", "description", "kind", "value" ], "title": "ValueSettingEntry", "type": "object" }, "VeApprovalParkAlertRequest": { "description": "One parked approval an accountable human should learn about.", "properties": { "account_id": { "description": "The conversation owner. The FLOOR under the TIDY-17352 routing ladder — used when no work-item owner and no approvers list resolve.", "title": "Account Id", "type": "string" }, "agent_member_id": { "description": "agent_members.id — WHOSE home room the alert lands in.", "title": "Agent Member Id", "type": "string" }, "conversation_id": { "title": "Conversation Id", "type": "string" }, "deep_link": { "description": "tidy://session/{account}/{conversation}", "title": "Deep Link", "type": "string" }, "kind": { "description": "The conversation-request kind that parked.", "title": "Kind", "type": "string" }, "reason": { "description": "The command or question — why it stopped.", "title": "Reason", "type": "string" }, "request_id": { "description": "The parked request; also the Matrix transaction id.", "title": "Request Id", "type": "string" }, "session_title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Session Title" }, "tenant_id": { "title": "Tenant Id", "type": "string" } }, "required": [ "tenant_id", "account_id", "agent_member_id", "conversation_id", "request_id", "kind", "reason", "deep_link" ], "title": "VeApprovalParkAlertRequest", "type": "object" }, "VeApprovalParkAlertResponse": { "properties": { "outcome": { "description": "delivered | dispatch_failed — reports the OWNER rail, the one whose failure means a human was never told. The home-room record's own outcome is logged, not returned: a VE with no home room is not a reason to re-alert an owner who already has the notification.", "title": "Outcome", "type": "string" } }, "required": [ "outcome" ], "title": "VeApprovalParkAlertResponse", "type": "object" }, "VeApprovalRelayControlRequest": { "description": "One share holder's answer, relayed to the employee's connector (TIDY-19433).", "properties": { "agent_member_id": { "description": "agent_members.id — WHOSE home room the control is posted in.", "title": "Agent Member Id", "type": "string" }, "content": { "additionalProperties": true, "description": "The Matrix event content: a `com.tidy.harness_control` resolve_request envelope carrying `relay` (the conversation's room and the resolver).", "title": "Content", "type": "object" }, "conversation_id": { "title": "Conversation Id", "type": "string" }, "defer_delivery": { "default": false, "description": "Bind to the committed answer without posting it; an offline host resumes from the durable request later. Authorization and audit committed with the decision.", "title": "Defer Delivery", "type": "boolean" }, "request_id": { "title": "Request Id", "type": "string" }, "resolver_account_id": { "description": "The delegate who answered, authenticated by assistant-service.", "title": "Resolver Account Id", "type": "string" }, "tenant_id": { "title": "Tenant Id", "type": "string" } }, "required": [ "tenant_id", "agent_member_id", "conversation_id", "request_id", "resolver_account_id", "content" ], "title": "VeApprovalRelayControlRequest", "type": "object" }, "VeApprovalRelayControlResponse": { "properties": { "outcome": { "description": "delivered | authorized | not_ve | unreachable | dispatch_failed", "title": "Outcome", "type": "string" } }, "required": [ "outcome" ], "title": "VeApprovalRelayControlResponse", "type": "object" }, "VeAutonomyStatusRequest": { "description": "One autonomy status transition decided by the error classifier.", "properties": { "agent_account_id": { "title": "Agent Account Id", "type": "string" }, "reason": { "anyOf": [ { "maxLength": 500, "type": "string" }, { "type": "null" } ], "title": "Reason" }, "status": { "description": "The operational status to move to. `active` is the recovery direction and is honoured only FROM degraded/needs_reauth.", "enum": [ "active", "degraded", "needs_reauth" ], "title": "Status", "type": "string" }, "tenant_id": { "title": "Tenant Id", "type": "string" } }, "required": [ "tenant_id", "agent_account_id", "status" ], "title": "VeAutonomyStatusRequest", "type": "object" }, "VeAutonomyStatusResponse": { "properties": { "changed": { "description": "False when the row already read that way.", "title": "Changed", "type": "boolean" }, "status": { "description": "The VE's status after the transition.", "title": "Status", "type": "string" } }, "required": [ "status", "changed" ], "title": "VeAutonomyStatusResponse", "type": "object" }, "VeBacklogEntry": { "properties": { "item_ref": { "title": "Item Ref", "type": "string" }, "not_before": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "description": "When the item becomes work, if that is still ahead: its start date (from midnight in the owner's timezone), start time or snooze. The heartbeat does not take it before then (TIDY-20074).", "title": "Not Before" }, "pin": { "anyOf": [ { "enum": [ "next", "last" ], "type": "string" }, { "type": "null" } ], "default": null, "title": "Pin" }, "placed": { "description": "True when someone set its manual position.", "title": "Placed", "type": "boolean" }, "position": { "description": "1-based place in the work order.", "title": "Position", "type": "integer" }, "priority": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Priority" }, "project": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Project" }, "short_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Short Id" }, "status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Status" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Title" }, "worked": { "description": "False when the item's state is one the work policy ignores.", "title": "Worked", "type": "boolean" } }, "required": [ "item_ref", "position", "worked", "placed" ], "title": "VeBacklogEntry", "type": "object" }, "VeBacklogOrderReceipt": { "description": "A write-only credential gets its own placements, never queue data.", "properties": { "placements": { "items": { "$ref": "#/components/schemas/VeBacklogPlacement" }, "title": "Placements", "type": "array" }, "readback_refusal": { "title": "Readback Refusal", "type": "string" } }, "required": [ "placements", "readback_refusal" ], "title": "VeBacklogOrderReceipt", "type": "object" }, "VeBacklogOrderRequest": { "properties": { "item_ids": { "description": "Items of this employee's backlog, in the order they should be worked (`A-<uuid>` or bare uuid). They move to the head of the manual order in exactly this order; the rest keep theirs after them. Their do-next/do-last pins are cleared — a placement is the answer.", "items": { "type": "string" }, "maxItems": 200, "minItems": 1, "title": "Item Ids", "type": "array" } }, "required": [ "item_ids" ], "title": "VeBacklogOrderRequest", "type": "object" }, "VeBacklogPlacement": { "properties": { "backlog_rank": { "title": "Backlog Rank", "type": "number" }, "item_ref": { "title": "Item Ref", "type": "string" } }, "required": [ "item_ref", "backlog_rank" ], "title": "VeBacklogPlacement", "type": "object" }, "VeBacklogResponse": { "properties": { "can_set_standing_instructions": { "default": false, "description": "Whether you may set its standing instructions: a workspace Owner/Admin, its owner, or its direct manager on the team Org chart.", "title": "Can Set Standing Instructions", "type": "boolean" }, "can_set_work_policy": { "default": false, "description": "Whether you may set its work policy: a workspace Owner/Admin, or its direct manager on the team Org chart.", "title": "Can Set Work Policy", "type": "boolean" }, "employee": { "title": "Employee", "type": "string" }, "employee_name": { "title": "Employee Name", "type": "string" }, "items": { "items": { "$ref": "#/components/schemas/VeBacklogEntry" }, "title": "Items", "type": "array" }, "manual_order_leads": { "description": "True when the manual order is the policy's first key — a reorder then decides what is worked next. Otherwise placements only break ties of the keys ahead of it.", "title": "Manual Order Leads", "type": "boolean" }, "policy_source": { "enum": [ "employee", "workspace", "default" ], "title": "Policy Source", "type": "string" }, "standing_instructions": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "What the employee does on every wake, as its card holds it (TIDY-20154). Null when it has none.", "title": "Standing Instructions" }, "standing_instructions_changed": { "anyOf": [ { "$ref": "#/components/schemas/ConfigurationChange" }, { "type": "null" } ], "default": null }, "standing_instructions_sha256": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "sha256 of the instructions, to pass as based_on_sha256 when you replace them.", "title": "Standing Instructions Sha256" }, "state_groups": { "additionalProperties": { "type": "string" }, "description": "TIDY-20074 F16: the group of every state this response names — open (Waiting), active (Being worked), parked (never woken by default, never stuck) or done — as the workspace sets it on its task status field.", "title": "State Groups", "type": "object" }, "state_labels": { "additionalProperties": { "type": "string" }, "description": "TIDY-20074 F16: the word the workspace shows for each of those states.", "title": "State Labels", "type": "object" }, "stuck_work": { "description": "Its stuck work: items assigned to it in a Waiting or Being-worked state its Wakes for leaves out.", "items": { "$ref": "#/components/schemas/StuckWorkItem" }, "title": "Stuck Work", "type": "array" }, "stuck_work_manager": { "anyOf": [ { "$ref": "#/components/schemas/StuckWorkManager" }, { "type": "null" } ], "description": "Who is alerted to its stuck work; null when its manager is not an employee." }, "total": { "title": "Total", "type": "integer" }, "wakes_for": { "description": "The states that wake it on its own (TIDY-20074) — its work policy as one list. What wakes it, not what it may work.", "items": { "type": "string" }, "title": "Wakes For", "type": "array" }, "work_policy": { "$ref": "#/components/schemas/VeWorkPolicy" }, "work_policy_changed": { "anyOf": [ { "$ref": "#/components/schemas/ConfigurationChange" }, { "type": "null" } ], "default": null, "description": "Who last set this employee's own policy (TIDY-20154)." } }, "required": [ "employee", "employee_name", "work_policy", "wakes_for", "stuck_work", "stuck_work_manager", "policy_source", "manual_order_leads", "items", "total" ], "title": "VeBacklogResponse", "type": "object" }, "VeHeartbeatWakeRequest": { "description": "One claimed wake decision, ready for its side effect.", "properties": { "agent_account_id": { "description": "The VE's agent account id.", "title": "Agent Account Id", "type": "string" }, "body": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "TIDY-16407 (A3): the wake injection, rendered at fire time by assistant-service's `renderWakePayload`. Posted verbatim. Absent (flag off) falls back to the interim minimal payload.", "title": "Body" }, "context_compaction": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "TIDY-19935 (F11): ask the session's harness to compact before this wake's turn continues it — {runtime, ordinal, used, limit, threshold_percent}. Posted as the notification's `compact_first` only into the conversation it was measured on.", "title": "Context Compaction" }, "conversation_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The candidate's linked conversation; None mints one via the conversation-creation contract (anchor event + uuidv5 room::root).", "title": "Conversation Id" }, "decision_key": { "description": "The one-wake-per-stall identity.", "minLength": 8, "title": "Decision Key", "type": "string" }, "item_id": { "description": "The top wake candidate (activity id).", "title": "Item Id", "type": "string" }, "payload": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "The structured form of `body`, carried in the message metadata.", "title": "Payload" }, "resume_mode": { "anyOf": [ { "enum": [ "resume_native", "fresh_seeded" ], "type": "string" }, { "type": "null" } ], "description": "TIDY-16408 (A4): the settle-driven resume decision. `resume_native` posts into the existing conversation and stamps the contract into the wake envelope (the connector fails loud if the native conversation is gone); `fresh_seeded` archives the settled predecessor and mints a seeded successor. Absent = pre-story behavior (flag off).", "title": "Resume Mode" }, "seed": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "The fresh-seed carryover composed by assistant-service: {summary, summary_source, seeded_from_conversation_id, seed_text}.", "title": "Seed" }, "tenant_id": { "title": "Tenant Id", "type": "string" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The candidate's title, if any.", "title": "Title" } }, "required": [ "tenant_id", "agent_account_id", "item_id", "decision_key" ], "title": "VeHeartbeatWakeRequest", "type": "object" }, "VeHeartbeatWakeResponse": { "properties": { "already_minted": { "default": false, "title": "Already Minted", "type": "boolean" }, "context_compaction": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "description": "TIDY-19935: the compaction ask as posted; None when none was.", "title": "Context Compaction" }, "conversation_id": { "title": "Conversation Id", "type": "string" }, "matrix_event_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Matrix Event Id" }, "message_id": { "title": "Message Id", "type": "string" }, "resume_mode": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "The resume mode actually applied (None = legacy).", "title": "Resume Mode" } }, "required": [ "conversation_id", "message_id" ], "title": "VeHeartbeatWakeResponse", "type": "object" }, "VeMeetingWakeRequest": { "description": "One claimed meeting wake, composed and ready for its side effect.", "properties": { "agent_account_id": { "description": "The VE attendee's agent account id.", "title": "Agent Account Id", "type": "string" }, "body": { "description": "The composed wake body, posted verbatim.", "title": "Body", "type": "string" }, "decision_key": { "description": "The one-wake-per-occurrence-per-VE identity.", "minLength": 8, "title": "Decision Key", "type": "string" }, "event_id": { "description": "The calendar event this meeting is.", "title": "Event Id", "type": "string" }, "is_chair": { "default": false, "description": "True when this VE owns the agenda.", "title": "Is Chair", "type": "boolean" }, "occurrence_start": { "description": "ISO-8601 UTC start of THIS occurrence (recurring events).", "title": "Occurrence Start", "type": "string" }, "payload": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "The structured form of `body`, carried in the metadata.", "title": "Payload" }, "tenant_id": { "title": "Tenant Id", "type": "string" }, "title": { "description": "The meeting title, used for the conversation.", "title": "Title", "type": "string" } }, "required": [ "tenant_id", "agent_account_id", "event_id", "occurrence_start", "decision_key", "title", "body" ], "title": "VeMeetingWakeRequest", "type": "object" }, "VeMeetingWakeResponse": { "properties": { "already_minted": { "default": false, "title": "Already Minted", "type": "boolean" }, "conversation_id": { "title": "Conversation Id", "type": "string" }, "matrix_event_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Matrix Event Id" }, "message_id": { "title": "Message Id", "type": "string" } }, "required": [ "conversation_id", "message_id" ], "title": "VeMeetingWakeResponse", "type": "object" }, "VePromptSteerRequest": { "properties": { "tenant_id": { "title": "Tenant Id", "type": "string" } }, "required": [ "tenant_id" ], "title": "VePromptSteerRequest", "type": "object" }, "VePromptSteerResponse": { "properties": { "matrix_event_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Matrix Event Id" }, "outcome": { "description": "delivered | owed (could not post now; the prompt sweep delivers it) | undeliverable (the conversation can never take it; see reason) | nothing_owed", "title": "Outcome", "type": "string" }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Why it is owed or undeliverable: steer_unavailable, conversation_ended, conversation_not_found, conversation_unroutable or managed_chat_decrypt_disabled.", "title": "Reason" } }, "required": [ "outcome" ], "title": "VePromptSteerResponse", "type": "object" }, "VeQueueDepthResponse": { "properties": { "items": { "items": { "additionalProperties": true, "type": "object" }, "title": "Items", "type": "array" } }, "required": [ "items" ], "title": "VeQueueDepthResponse", "type": "object" }, "VeReflectionWakeRequest": { "properties": { "agent_account_id": { "title": "Agent Account Id", "type": "string" }, "body": { "description": "The rendered reflection brief.", "minLength": 1, "title": "Body", "type": "string" }, "decision_id": { "description": "The claimed agent_wake_decisions row.", "title": "Decision Id", "type": "string" }, "decision_key": { "minLength": 8, "title": "Decision Key", "type": "string" }, "payload": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "The structured form of the brief, for the archive.", "title": "Payload" }, "tenant_id": { "title": "Tenant Id", "type": "string" } }, "required": [ "tenant_id", "agent_account_id", "decision_key", "decision_id", "body" ], "title": "VeReflectionWakeRequest", "type": "object" }, "VeReflectionWakeResponse": { "properties": { "already_minted": { "default": false, "title": "Already Minted", "type": "boolean" }, "conversation_id": { "title": "Conversation Id", "type": "string" }, "matrix_event_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Matrix Event Id" }, "message_id": { "title": "Message Id", "type": "string" } }, "required": [ "conversation_id", "message_id" ], "title": "VeReflectionWakeResponse", "type": "object" }, "VeStuckWorkWakeRequest": { "description": "TIDY-20074 F13: one claimed wake of a manager employee for its team's\nstuck work.", "properties": { "agent_account_id": { "description": "The manager employee's account id.", "title": "Agent Account Id", "type": "string" }, "body": { "description": "The wake, rendered at fire time.", "minLength": 1, "title": "Body", "type": "string" }, "decision_key": { "description": "The claimed alert's identity.", "minLength": 8, "title": "Decision Key", "type": "string" }, "payload": { "additionalProperties": true, "description": "Its structured form; `team_stuck_work` names every item it lists.", "title": "Payload", "type": "object" }, "tenant_id": { "title": "Tenant Id", "type": "string" } }, "required": [ "tenant_id", "agent_account_id", "decision_key", "body", "payload" ], "title": "VeStuckWorkWakeRequest", "type": "object" }, "VeWorkPolicy": { "additionalProperties": false, "description": "The states that wake the employee on its own, and the order keys after\nthe pins.", "properties": { "ignore_statuses": { "description": "Status values that never wake the employee (an item in any of them stays on its board). Matched case-insensitively. TIDY-20074: the settings now say a policy as one list, work_statuses, and send this empty; a policy saved before that keeps its meaning (wakes_for).", "items": { "type": "string" }, "maxItems": 64, "title": "Ignore Statuses", "type": "array" }, "order": { "description": "How the next item is chosen, most significant first, after the do-next/do-last pins: manual (the order set by dragging), priority, project_priority, score (highest first), due (soonest first), age (oldest assignment first).", "items": { "enum": [ "manual", "priority", "project_priority", "score", "due", "age" ], "type": "string" }, "maxItems": 6, "title": "Order", "type": "array" }, "work_statuses": { "anyOf": [ { "items": { "type": "string" }, "maxItems": 64, "minItems": 1, "type": "array" }, { "type": "null" } ], "description": "\"Wakes for\" (TIDY-20074): the status values that wake the employee on its own. A wake filter, not a permission — once awake it can see and work anything. An item in any other state — one added to the workspace later too — or with no state does not wake it, nor does a state also in ignore_statuses. Null wakes it for every open or active state not ignored. Saving a policy without this key keeps the stored list; send null to clear it.", "title": "Work Statuses" } }, "required": [ "ignore_statuses", "order" ], "title": "VeWorkPolicy", "type": "object" }, "VerdictRequest": { "properties": { "authorized_by": { "title": "Authorized By", "type": "string" }, "cost_regression_approved": { "default": false, "description": "Explicit approval of a cost regression above the threshold.", "title": "Cost Regression Approved", "type": "boolean" }, "family": { "title": "Family", "type": "string" }, "from_version": { "title": "From Version", "type": "integer" }, "signature": { "title": "Signature", "type": "string" }, "to_version": { "title": "To Version", "type": "integer" } }, "required": [ "family", "from_version", "to_version", "authorized_by", "signature" ], "title": "VerdictRequest", "type": "object" }, "VerdictResponse": { "description": "A persisted verdict, as the promotion review reads it.", "properties": { "artifact": { "additionalProperties": true, "title": "Artifact", "type": "object" }, "artifact_hash": { "title": "Artifact Hash", "type": "string" }, "artifact_schema_version": { "title": "Artifact Schema Version", "type": "integer" }, "cohort_member_count": { "title": "Cohort Member Count", "type": "integer" }, "decision": { "title": "Decision", "type": "string" }, "failed_thresholds": { "items": { "type": "string" }, "title": "Failed Thresholds", "type": "array" }, "false_positive_rate": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "False Positive Rate" }, "id": { "format": "uuid", "title": "Id", "type": "string" }, "precision": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Precision" }, "reviewed_count": { "title": "Reviewed Count", "type": "integer" }, "signature_key_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Signature Key Id" }, "signed": { "title": "Signed", "type": "boolean" }, "tenant_id": { "format": "uuid", "title": "Tenant Id", "type": "string" }, "window_end": { "format": "date-time", "title": "Window End", "type": "string" }, "window_start": { "format": "date-time", "title": "Window Start", "type": "string" } }, "required": [ "id", "tenant_id", "decision", "window_start", "window_end", "reviewed_count", "cohort_member_count", "precision", "false_positive_rate", "failed_thresholds", "artifact_hash", "artifact_schema_version", "signed", "signature_key_id", "artifact" ], "title": "VerdictResponse", "type": "object" }, "VerificationResponse": { "properties": { "algorithm": { "anyOf": [ { "enum": [ "sha256", "sha1", "sha512" ], "type": "string" }, { "type": "null" } ], "default": null, "title": "Algorithm" }, "encoding": { "anyOf": [ { "enum": [ "hex", "base64" ], "type": "string" }, { "type": "null" } ], "default": null, "title": "Encoding" }, "has_secret": { "title": "Has Secret", "type": "boolean" }, "scheme": { "enum": [ "hmac", "bearer", "url_secret" ], "title": "Scheme", "type": "string" }, "secret_prefix": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Secret Prefix" }, "signature_header": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Signature Header" }, "signature_prefix": { "default": "", "title": "Signature Prefix", "type": "string" }, "timestamp_header": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Timestamp Header" }, "tolerance_seconds": { "default": 300, "title": "Tolerance Seconds", "type": "integer" } }, "required": [ "scheme", "has_secret" ], "title": "VerificationResponse", "type": "object" }, "VerificationSettings": { "additionalProperties": false, "description": "How deliveries prove themselves. ``secret`` is for an HMAC secret the\nSENDER issued (Stripe's ``whsec_…``); without one Tidy mints it.", "properties": { "algorithm": { "anyOf": [ { "enum": [ "sha256", "sha1", "sha512" ], "type": "string" }, { "type": "null" } ], "title": "Algorithm" }, "encoding": { "anyOf": [ { "enum": [ "hex", "base64" ], "type": "string" }, { "type": "null" } ], "title": "Encoding" }, "scheme": { "enum": [ "hmac", "bearer", "url_secret" ], "title": "Scheme", "type": "string" }, "secret": { "anyOf": [ { "maxLength": 512, "minLength": 8, "type": "string" }, { "type": "null" } ], "title": "Secret" }, "signature_header": { "anyOf": [ { "maxLength": 120, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Signature Header" }, "signature_prefix": { "default": "", "maxLength": 40, "title": "Signature Prefix", "type": "string" }, "timestamp_header": { "anyOf": [ { "maxLength": 120, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Timestamp Header" }, "tolerance_seconds": { "default": 300, "maximum": 86400.0, "minimum": 30.0, "title": "Tolerance Seconds", "type": "integer" } }, "required": [ "scheme" ], "title": "VerificationSettings", "type": "object" }, "VerifyOtpRequest": { "properties": { "email": { "format": "email", "title": "Email", "type": "string" }, "token": { "title": "Token", "type": "string" }, "type": { "default": "email", "title": "Type", "type": "string" } }, "required": [ "email", "token" ], "title": "VerifyOtpRequest", "type": "object" }, "VerifyOtpResponse": { "description": "Response shape for POST /api/v1/auth/verify-otp.\n\nUnder the gated identity model (TIDY-12626/TIDY-12650) a fresh identity\nthat verifies its email OTP has NO tenant yet — tenant birth is deferred\nto the invite-gated `/tenants/provision` boundary. So a Tidy session is\nminted ONLY when a tenant already exists (returning/verified user). For a\nfresh tenantless identity:\n\n * `verify_state` is the server-authoritative next step the verify page\n acts on — `needs_invite` (invite-only ON or indeterminable: the client\n routes to the signup invite step / oauth_invite contract) or\n `needs_provision` (invite-only OFF: the client proceeds to onboarding\n which self-provisions the tenant). A returning user with a tenant gets\n `active`.\n * The Tidy bearer fields are populated ONLY when a session was minted\n (tenant exists). For a tenantless identity they are null — the proxy\n returns the typed outcome instead of 403-ing (mirror of TIDY-12623).\n * `supabase_access_token` / `supabase_refresh_token` are populated ONLY on\n the tenantless path so the client can establish the browser Supabase\n session (via `supabase.auth.setSession`). That session is the HS256\n bootstrap credential `/tenants/provision` accepts — without it the\n tenantless user could neither mint a Tidy session nor authenticate the\n provision call. They are null on the with-tenant path.", "properties": { "expires_in": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Expires In" }, "refresh_token": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Refresh Token" }, "supabase_access_token": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Supabase Access Token" }, "supabase_refresh_token": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Supabase Refresh Token" }, "tidy_access_token": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Tidy Access Token" }, "verified": { "title": "Verified", "type": "boolean" }, "verify_state": { "default": "active", "title": "Verify State", "type": "string" } }, "required": [ "verified" ], "title": "VerifyOtpResponse", "type": "object" }, "VerifyRequest": { "properties": { "code": { "anyOf": [ { "pattern": "^\\d{6}$", "type": "string" }, { "type": "null" } ], "title": "Code" }, "factor": { "enum": [ "password", "provider", "email_otp", "totp", "passkey" ], "title": "Factor", "type": "string" }, "password": { "anyOf": [ { "maxLength": 1024, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Password" } }, "required": [ "factor" ], "title": "VerifyRequest", "type": "object" }, "VersionCreateRequest": { "description": "Either a full definition document, or clone-with-overrides (R29).", "properties": { "clone_from_version_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Clone From Version Id" }, "created_via": { "default": "operator", "title": "Created Via", "type": "string" }, "definition": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Definition" }, "overrides": { "additionalProperties": true, "title": "Overrides", "type": "object" } }, "title": "VersionCreateRequest", "type": "object" }, "VersionCreateResponse": { "properties": { "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "definition_hash": { "title": "Definition Hash", "type": "string" }, "definition_id": { "format": "uuid", "title": "Definition Id", "type": "string" }, "diff": { "items": { "additionalProperties": true, "type": "object" }, "title": "Diff", "type": "array" }, "id": { "format": "uuid", "title": "Id", "type": "string" }, "parent_version_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Parent Version Id" }, "state": { "title": "State", "type": "string" }, "version_number": { "title": "Version Number", "type": "integer" } }, "required": [ "id", "definition_id", "version_number", "parent_version_id", "state", "definition_hash", "diff", "created_at" ], "title": "VersionCreateResponse", "type": "object" }, "VersionList": { "properties": { "total": { "title": "Total", "type": "integer" }, "versions": { "items": { "$ref": "#/components/schemas/NoteVersion" }, "title": "Versions", "type": "array" } }, "required": [ "versions", "total" ], "title": "VersionList", "type": "object" }, "VersionResponse": { "properties": { "change_summary": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Change Summary" }, "changed_by": { "title": "Changed By", "type": "string" }, "code": { "title": "Code", "type": "string" }, "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "id": { "title": "Id", "type": "string" }, "script_id": { "title": "Script Id", "type": "string" }, "version": { "title": "Version", "type": "integer" } }, "required": [ "id", "script_id", "version", "code", "description", "changed_by", "change_summary", "created_at" ], "title": "VersionResponse", "type": "object" }, "VersionRow": { "properties": { "content_hash": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Content Hash" }, "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "id": { "title": "Id", "type": "string" }, "note_id": { "title": "Note Id", "type": "string" }, "primitive_type": { "title": "Primitive Type", "type": "string" }, "tenant_id": { "title": "Tenant Id", "type": "string" }, "trigger": { "title": "Trigger", "type": "string" }, "yjs_state_hex": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Yjs State Hex" } }, "required": [ "id", "note_id", "primitive_type", "tenant_id", "trigger", "created_at" ], "title": "VersionRow", "type": "object" }, "VersionSetEntry": { "properties": { "definition_id": { "format": "uuid", "title": "Definition Id", "type": "string" }, "version_id": { "format": "uuid", "title": "Version Id", "type": "string" } }, "required": [ "definition_id", "version_id" ], "title": "VersionSetEntry", "type": "object" }, "ViewBinding": { "description": "What a saved database view draws from its facet (TIDY-18514).\n\nA calendar, gantt, timeline, kanban or grouped list draws only what the\nfacet definition's ``view_mappings.<layout>`` names — nothing is guessed\nfrom the facet's fields (TIDY-19504). Table, card and gallery read the\nfacet's mapping when it has one; chart and hierarchy bind their fields in\nthe view's own ``layout_settings``.", "properties": { "facet": { "description": "The facet the view queries, whose definition it draws.", "title": "Facet", "type": "string" }, "layout": { "title": "Layout", "type": "string" }, "mapping": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "description": "The facet's view_mappings.<layout> the view draws, each slot {property: <field key>}; null when the layout reads no facet mapping or the facet's leaves a required slot unmet.", "title": "ViewBindingMapping" }, "missing_required": { "description": "Required slots the facet's mapping leaves unmapped or points at a field it does not have. Non-empty: the view draws nothing until the facet maps them.", "items": { "type": "string" }, "title": "Missing Required", "type": "array" } }, "required": [ "layout", "facet" ], "title": "ViewBinding", "type": "object" }, "ViewSlotCapability": { "description": "One field slot a layout binds — `field_kind` is the eligible field-type\nfamily, not a concrete facet field.", "properties": { "field_kind": { "title": "Field Kind", "type": "string" }, "key": { "title": "Key", "type": "string" } }, "required": [ "key", "field_kind" ], "title": "ViewSlotCapability", "type": "object" }, "ViewSourceOpen": { "properties": { "primitive_id": { "title": "Primitive Id", "type": "string" }, "primitive_type": { "title": "Primitive Type", "type": "string" } }, "required": [ "primitive_type", "primitive_id" ], "title": "ViewSourceOpen", "type": "object" }, "ViewSourceRow": { "properties": { "created_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Created At" }, "id": { "title": "Id", "type": "string" }, "open": { "anyOf": [ { "$ref": "#/components/schemas/ViewSourceOpen" }, { "type": "null" } ], "default": null, "description": "What opening the row opens, when it is not the row itself." }, "properties": { "additionalProperties": true, "title": "Properties", "type": "object" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Title" }, "updated_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Updated At" } }, "required": [ "id" ], "title": "ViewSourceRow", "type": "object" }, "ViewSourceRowsResponse": { "properties": { "has_more": { "title": "Has More", "type": "boolean" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Pass as `after` to read the rows that follow this page; null when none do.", "title": "Next Cursor" }, "rows": { "items": { "$ref": "#/components/schemas/ViewSourceRow" }, "title": "Rows", "type": "array" }, "total": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Total" }, "total_capped": { "default": false, "title": "Total Capped", "type": "boolean" } }, "required": [ "rows", "has_more" ], "title": "ViewSourceRowsResponse", "type": "object" }, "ViewTypeCapability": { "description": "A layout an agent may author, and what it needs from the facet.", "properties": { "always_available": { "title": "Always Available", "type": "boolean" }, "label": { "title": "Label", "type": "string" }, "layout": { "title": "Layout", "type": "string" }, "notes": { "default": "", "title": "Notes", "type": "string" }, "optional_slots": { "items": { "$ref": "#/components/schemas/ViewSlotCapability" }, "title": "Optional Slots", "type": "array" }, "required_slots": { "items": { "$ref": "#/components/schemas/ViewSlotCapability" }, "title": "Required Slots", "type": "array" } }, "required": [ "layout", "label", "always_available" ], "title": "ViewTypeCapability", "type": "object" }, "ViewUsageCoverage": { "description": "What the usage read looked at, so `in_use: false` can be trusted.", "properties": { "as_of": { "format": "date-time", "title": "As Of", "type": "string" }, "checked": { "items": { "type": "string" }, "title": "Checked", "type": "array" }, "complete": { "description": "True when every place in `checked` was read across the whole workspace.", "title": "Complete", "type": "boolean" }, "not_counted": { "items": { "type": "string" }, "title": "Not Counted", "type": "array" }, "scope": { "const": "workspace", "default": "workspace", "title": "Scope", "type": "string" } }, "required": [ "complete", "checked", "not_counted", "as_of" ], "title": "ViewUsageCoverage", "type": "object" }, "ViewUsagePlace": { "description": "One place, that you can open, that uses a saved view (TIDY-19705 F9).", "properties": { "block_ids": { "description": "For `embedded`: the body blocks that show the view.", "items": { "type": "string" }, "title": "Block Ids", "type": "array" }, "how": { "description": "`embedded`: its body shows the view. `referenced`: its configuration names the view (a chart, dashboard or form reading it). `pinned`: a saved-views nav pin. `built_in`: one of the workspace menu's own views.", "enum": [ "embedded", "referenced", "pinned", "built_in" ], "title": "How", "type": "string" }, "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Typed id of the place (`N-`, `J-`, `A-`, `P-`, `C-`, `O-`, `V-`, `R-`); a template, form, facet or workstation's own id; a pin's project (`P-`).", "title": "Id" }, "kind": { "enum": [ "note", "journal", "task", "project", "contact", "organization", "event", "template", "form", "record", "facet", "workstation", "nav_pin", "built_in" ], "title": "Kind", "type": "string" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Title" } }, "required": [ "kind", "how" ], "title": "ViewUsagePlace", "type": "object" }, "VisualizationExportRequest": { "description": "One image export. Exactly one of `record_id` / `inline` is required.", "properties": { "format": { "default": "png", "enum": [ "png", "svg" ], "title": "Format", "type": "string" }, "height": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Custom height in px (64–4096). Only meaningful alongside width; a height alone is rejected (422 invalid_dimensions).", "title": "Height" }, "inline": { "anyOf": [ { "$ref": "#/components/schemas/VisualizationInlineDefinition" }, { "type": "null" } ] }, "panel_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Panel Id" }, "record_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Record Id" }, "save": { "default": false, "title": "Save", "type": "boolean" }, "size_preset": { "anyOf": [ { "enum": [ "native", "og", "square" ], "type": "string" }, { "type": "null" } ], "description": "Named stage: native (1280×720 app proportions, the default), og (1200×630 social card), or square (1080×1080). Ignored when width is given.", "title": "Size Preset" }, "theme": { "default": "light", "enum": [ "light", "dark", "eink" ], "title": "Theme", "type": "string" }, "width": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Custom width in px (64–4096). A width ALONE is fine — the native aspect supplies the height, which is what a client that knows only its own width should send.", "title": "Width" } }, "title": "VisualizationExportRequest", "type": "object" }, "VisualizationInlineDefinition": { "description": "An unsaved chart/dashboard to render — the gen-UI/agent path, so an\nanswer that was never stored as a record can still be exported.", "properties": { "kind": { "enum": [ "chart", "dashboard" ], "title": "Kind", "type": "string" }, "properties": { "additionalProperties": true, "title": "VisualizationExportProperties", "type": "object" } }, "required": [ "kind" ], "title": "VisualizationInlineDefinition", "type": "object" }, "VisualizationIssue": { "properties": { "allowed": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "default": null, "title": "Allowed" }, "code": { "title": "Code", "type": "string" }, "message": { "title": "Message", "type": "string" }, "path": { "title": "Path", "type": "string" } }, "required": [ "path", "code", "message" ], "title": "VisualizationIssue", "type": "object" }, "VisualizationSuitability": { "description": "Whether the chart FORM suits the data (TIDY-17060 / R17).\n\nDeliberately separate from `issues`: an unsuitable chart is a legal spec,\nand the answer is a better form to use — never a rejection. Only reported\nfor `kind='chart'`, and only for what is knowable at validation time (a\nlive source's row count is not).", "properties": { "code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Code" }, "message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Message" }, "ok": { "title": "Ok", "type": "boolean" }, "suggested_kind": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Suggested Kind" } }, "required": [ "ok" ], "title": "VisualizationSuitability", "type": "object" }, "VisualizationValidateRequest": { "description": "A chart/dashboard properties payload to validate before writing.", "properties": { "consumer": { "default": "app", "enum": [ "app", "server_render" ], "title": "Consumer", "type": "string" }, "kind": { "enum": [ "chart", "dashboard" ], "title": "Kind", "type": "string" }, "properties": { "additionalProperties": true, "title": "VisualizationProperties", "type": "object" } }, "required": [ "kind" ], "title": "VisualizationValidateRequest", "type": "object" }, "VisualizationValidateResponse": { "properties": { "issues": { "items": { "$ref": "#/components/schemas/VisualizationIssue" }, "title": "Issues", "type": "array" }, "suitability": { "anyOf": [ { "$ref": "#/components/schemas/VisualizationSuitability" }, { "type": "null" } ], "default": null }, "valid": { "title": "Valid", "type": "boolean" } }, "required": [ "valid", "issues" ], "title": "VisualizationValidateResponse", "type": "object" }, "VoiceCaptureCreateResponse": { "properties": { "capture_id": { "title": "Capture Id", "type": "string" }, "status": { "title": "Status", "type": "string" } }, "required": [ "capture_id", "status" ], "title": "VoiceCaptureCreateResponse", "type": "object" }, "VoiceCaptureListResponse": { "properties": { "captures": { "items": { "$ref": "#/components/schemas/VoiceCaptureResponse" }, "title": "Captures", "type": "array" }, "count": { "title": "Count", "type": "integer" } }, "required": [ "captures", "count" ], "title": "VoiceCaptureListResponse", "type": "object" }, "VoiceCaptureResponse": { "properties": { "captured_at": { "format": "date-time", "title": "Captured At", "type": "string" }, "client_capture_id": { "title": "Client Capture Id", "type": "string" }, "embedded_facet_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Embedded Facet Id" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Error" }, "facet_slug": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Facet Slug" }, "id": { "title": "Id", "type": "string" }, "materialized_note_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Materialized Note Id" }, "status": { "title": "Status", "type": "string" } }, "required": [ "id", "client_capture_id", "status", "captured_at" ], "title": "VoiceCaptureResponse", "type": "object" }, "VoiceCatalogueResponse": { "properties": { "aliases": { "additionalProperties": { "additionalProperties": { "type": "string" }, "propertyNames": { "enum": [ "gemini-realtime", "openai-realtime", "self-hosted" ] }, "type": "object" }, "title": "Aliases", "type": "object" }, "defaults": { "additionalProperties": { "additionalProperties": { "type": "string" }, "propertyNames": { "enum": [ "male", "female", "neutral" ] }, "type": "object" }, "propertyNames": { "enum": [ "gemini-realtime", "openai-realtime", "self-hosted" ] }, "title": "Defaults", "type": "object" }, "engines": { "items": { "$ref": "#/components/schemas/EngineVoices" }, "title": "Engines", "type": "array" }, "speeds": { "items": { "type": "number" }, "title": "Speeds", "type": "array" } }, "required": [ "engines", "speeds", "aliases", "defaults" ], "title": "VoiceCatalogueResponse", "type": "object" }, "VoiceCostBreakdown": { "properties": { "llm_cost_cents": { "default": 0, "title": "Llm Cost Cents", "type": "integer" }, "stt_cost_cents": { "default": 0, "title": "Stt Cost Cents", "type": "integer" }, "total_cost_cents": { "default": 0, "title": "Total Cost Cents", "type": "integer" }, "tts_cost_cents": { "default": 0, "title": "Tts Cost Cents", "type": "integer" } }, "title": "VoiceCostBreakdown", "type": "object" }, "VoiceEndRequest": { "properties": { "session_id": { "format": "uuid", "title": "Session Id", "type": "string" } }, "required": [ "session_id" ], "title": "VoiceEndRequest", "type": "object" }, "VoiceEndResponse": { "properties": { "active_speech_seconds": { "title": "Active Speech Seconds", "type": "integer" }, "cost": { "anyOf": [ { "$ref": "#/components/schemas/VoiceCostBreakdown" }, { "type": "null" } ] }, "duration_seconds": { "title": "Duration Seconds", "type": "integer" }, "session_id": { "format": "uuid", "title": "Session Id", "type": "string" } }, "required": [ "session_id", "duration_seconds", "active_speech_seconds" ], "title": "VoiceEndResponse", "type": "object" }, "VoiceIdentityConsentRequest": { "properties": { "accepted_version": { "maxLength": 64, "minLength": 1, "title": "Accepted Version", "type": "string" }, "decision": { "default": "granted", "enum": [ "granted", "refused" ], "title": "Decision", "type": "string" }, "method": { "enum": [ "explicit_click", "spoken_confirmation" ], "title": "Method", "type": "string" } }, "required": [ "accepted_version", "method" ], "title": "VoiceIdentityConsentRequest", "type": "object" }, "VoiceIdentityConsentResponse": { "properties": { "accepted_version": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Accepted Version" }, "consent_method": { "anyOf": [ { "enum": [ "explicit_click", "spoken_confirmation" ], "type": "string" }, { "type": "null" } ], "default": null, "title": "Consent Method" }, "consented_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Consented At" }, "current_version": { "title": "Current Version", "type": "string" }, "disclosure": { "title": "Disclosure", "type": "string" }, "revoked_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Revoked At" }, "status": { "enum": [ "not_granted", "granted", "revoked", "refused" ], "title": "Status", "type": "string" }, "voice_identity_enabled": { "title": "Voice Identity Enabled", "type": "boolean" } }, "required": [ "disclosure", "current_version", "status", "voice_identity_enabled" ], "title": "VoiceIdentityConsentResponse", "type": "object" }, "VoiceIdentityCorrectionRequest": { "properties": { "huddle_id": { "format": "uuid", "title": "Huddle Id", "type": "string" }, "new_account_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "New Account Id" }, "operation_id": { "format": "uuid", "title": "Operation Id", "type": "string" }, "reason": { "maxLength": 500, "minLength": 1, "pattern": ".*\\S.*", "title": "Reason", "type": "string" }, "segment_id": { "format": "uuid", "title": "Segment Id", "type": "string" } }, "required": [ "huddle_id", "segment_id", "reason", "operation_id" ], "title": "VoiceIdentityCorrectionRequest", "type": "object" }, "VoiceIdentityCorrectionResponse": { "properties": { "audit_id": { "format": "uuid", "title": "Audit Id", "type": "string" }, "authority": { "enum": [ "huddle_member", "compliance_admin" ], "title": "Authority", "type": "string" }, "changed": { "title": "Changed", "type": "boolean" }, "huddle_id": { "format": "uuid", "title": "Huddle Id", "type": "string" }, "new_account_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "default": null, "title": "New Account Id" }, "previous_account_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "default": null, "title": "Previous Account Id" }, "previous_provenance": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Previous Provenance" }, "segment_id": { "format": "uuid", "title": "Segment Id", "type": "string" } }, "required": [ "huddle_id", "segment_id", "authority", "changed", "audit_id" ], "title": "VoiceIdentityCorrectionResponse", "type": "object" }, "VoiceIdentityEnrollRequest": { "properties": { "operation_id": { "format": "uuid", "title": "Operation Id", "type": "string" }, "track_id": { "maxLength": 255, "minLength": 1, "title": "Track Id", "type": "string" } }, "required": [ "track_id", "operation_id" ], "title": "VoiceIdentityEnrollRequest", "type": "object" }, "VoiceIdentityEnrollmentResponse": { "properties": { "completed_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Completed At" }, "failure_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Failure Reason" }, "huddle_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "default": null, "title": "Huddle Id" }, "job_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "default": null, "title": "Job Id" }, "operation_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "default": null, "title": "Operation Id" }, "status": { "enum": [ "not_enrolled", "pending", "complete", "failed" ], "title": "Status", "type": "string" }, "track_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Track Id" } }, "required": [ "status" ], "title": "VoiceIdentityEnrollmentResponse", "type": "object" }, "VoiceIdentityEnrollmentTrackResponse": { "properties": { "clear_speech_seconds": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "title": "Clear Speech Seconds" }, "duration_seconds": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "title": "Duration Seconds" }, "huddle_id": { "format": "uuid", "title": "Huddle Id", "type": "string" }, "quality": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "title": "Quality" }, "started_at": { "format": "date-time", "title": "Started At", "type": "string" }, "track_id": { "title": "Track Id", "type": "string" } }, "required": [ "track_id", "huddle_id", "started_at" ], "title": "VoiceIdentityEnrollmentTrackResponse", "type": "object" }, "VoiceIdentityEnrollmentTracksResponse": { "properties": { "tracks": { "items": { "$ref": "#/components/schemas/VoiceIdentityEnrollmentTrackResponse" }, "title": "Tracks", "type": "array" } }, "required": [ "tracks" ], "title": "VoiceIdentityEnrollmentTracksResponse", "type": "object" }, "VoiceIdentityRevocationRequest": { "properties": {}, "title": "VoiceIdentityRevocationRequest", "type": "object" }, "VoiceIdentityRevocationResponse": { "properties": { "jobs_deleted": { "title": "Jobs Deleted", "type": "integer" }, "objects_shredded": { "title": "Objects Shredded", "type": "integer" }, "samples_deleted": { "title": "Samples Deleted", "type": "integer" }, "status": { "const": "revoked", "default": "revoked", "title": "Status", "type": "string" }, "templates_deleted": { "title": "Templates Deleted", "type": "integer" } }, "required": [ "templates_deleted", "jobs_deleted", "samples_deleted", "objects_shredded" ], "title": "VoiceIdentityRevocationResponse", "type": "object" }, "VoiceMemberDescriptor": { "properties": { "display_name": { "title": "Display Name", "type": "string" }, "gender": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Gender" }, "kind": { "title": "Kind", "type": "string" }, "matrix_id": { "title": "Matrix Id", "type": "string" }, "speed": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Speed" }, "voice_engine": { "anyOf": [ { "enum": [ "gemini-realtime", "openai-realtime", "self-hosted" ], "type": "string" }, { "type": "null" } ], "title": "Voice Engine" }, "voice_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Voice Id" } }, "required": [ "matrix_id", "kind", "display_name" ], "title": "VoiceMemberDescriptor", "type": "object" }, "VoiceMembersResponse": { "properties": { "voices": { "items": { "$ref": "#/components/schemas/VoiceMemberDescriptor" }, "title": "Voices", "type": "array" } }, "required": [ "voices" ], "title": "VoiceMembersResponse", "type": "object" }, "VoicePreference": { "description": "A human member's persona voice preference.\n\nTIDY-20000: a voice is an engine, one of that engine's voices, and a speed.\n``voice_engine`` and ``speed`` are kept when a save leaves them out (older\nclients send only ``gender`` and ``voice_id``); a member with no engine is\nread aloud in Tidy's own voice. With a voice chosen, ``gender`` is the\nvoice's own.", "properties": { "gender": { "anyOf": [ { "enum": [ "male", "female", "neutral" ], "type": "string" }, { "type": "null" } ], "title": "Gender" }, "speed": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Speed" }, "voice_engine": { "anyOf": [ { "enum": [ "gemini-realtime", "openai-realtime", "self-hosted" ], "type": "string" }, { "type": "null" } ], "title": "Voice Engine" }, "voice_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Voice Id" } }, "title": "VoicePreference", "type": "object" }, "VoicePreferenceResponse": { "properties": { "available_voices": { "items": { "additionalProperties": true, "type": "object" }, "title": "Available Voices", "type": "array" }, "playback_quality": { "default": "standard", "enum": [ "standard", "high" ], "title": "Playback Quality", "type": "string" }, "playback_speed": { "default": 1.0, "title": "Playback Speed", "type": "number" }, "voice_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Voice Id" }, "voice_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Voice Name" }, "voice_speed": { "default": 1.0, "title": "Voice Speed", "type": "number" } }, "required": [ "available_voices" ], "title": "VoicePreferenceResponse", "type": "object" }, "VoicePreferenceUpdateRequest": { "description": "A partial update: every field left out (or null) keeps its stored value.", "properties": { "playback_quality": { "anyOf": [ { "enum": [ "standard", "high" ], "type": "string" }, { "type": "null" } ], "title": "Playback Quality" }, "playback_speed": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Playback Speed" }, "voice_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Voice Id" }, "voice_speed": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Voice Speed" } }, "title": "VoicePreferenceUpdateRequest", "type": "object" }, "VoiceSttResponse": { "properties": { "duration_seconds": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "title": "Duration Seconds" }, "language": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Language" }, "model": { "title": "Model", "type": "string" }, "provider": { "title": "Provider", "type": "string" }, "transcript": { "title": "Transcript", "type": "string" } }, "required": [ "transcript", "provider", "model" ], "title": "VoiceSttResponse", "type": "object" }, "VoiceTokenRequest": { "properties": { "context": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Context" }, "conversation_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Conversation Id" } }, "title": "VoiceTokenRequest", "type": "object" }, "VoiceTokenResponse": { "properties": { "conversation_id": { "format": "uuid", "title": "Conversation Id", "type": "string" }, "participant_identity": { "title": "Participant Identity", "type": "string" }, "room_name": { "title": "Room Name", "type": "string" }, "server_url": { "title": "Server Url", "type": "string" }, "session_id": { "format": "uuid", "title": "Session Id", "type": "string" }, "token": { "title": "Token", "type": "string" } }, "required": [ "token", "server_url", "room_name", "participant_identity", "session_id", "conversation_id" ], "title": "VoiceTokenResponse", "type": "object" }, "VoiceTtsRequest": { "properties": { "backend": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional TTS backend/model override (e.g. kokoro).", "title": "Backend" }, "engine": { "anyOf": [ { "enum": [ "gemini-realtime", "openai-realtime", "self-hosted" ], "type": "string" }, { "type": "null" } ], "description": "The speaker's voice engine (TIDY-20000); `voice` is resolved to one of its voices and rendered through it. Absent: the engine whose catalogue holds `voice`, else Tidy's own voice.", "title": "Engine" }, "text": { "description": "Text to synthesize (markdown ok).", "minLength": 1, "title": "Text", "type": "string" }, "voice": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional voice override.", "title": "Voice" } }, "required": [ "text" ], "title": "VoiceTtsRequest", "type": "object" }, "VoiceUsageResponse": { "properties": { "active_minutes_used": { "title": "Active Minutes Used", "type": "number" }, "cost": { "anyOf": [ { "$ref": "#/components/schemas/VoiceCostBreakdown" }, { "type": "null" } ] }, "has_active_session": { "title": "Has Active Session", "type": "boolean" }, "month": { "title": "Month", "type": "string" }, "session_count": { "title": "Session Count", "type": "integer" }, "total_cost_cents": { "title": "Total Cost Cents", "type": "integer" } }, "required": [ "month", "active_minutes_used", "session_count", "total_cost_cents", "has_active_session" ], "title": "VoiceUsageResponse", "type": "object" }, "VolumePeriod": { "properties": { "by_category": { "additionalProperties": { "type": "integer" }, "title": "By Category", "type": "object" }, "by_split": { "additionalProperties": { "type": "integer" }, "title": "By Split", "type": "object" }, "period": { "title": "Period", "type": "string" }, "received": { "title": "Received", "type": "integer" }, "sent": { "title": "Sent", "type": "integer" } }, "required": [ "period", "received", "sent", "by_category", "by_split" ], "title": "VolumePeriod", "type": "object" }, "WatchFirstRunRequest": { "description": "Body for ``POST /workflows/{script_id}/watch-first-run`` (TIDY-11602 / D3).\n\nArms a ``workflow_first_run`` continuation at save+enable time, BEFORE any run\nid exists. The first REAL triggered run's completion event claims it and the\nassistant reports the run to the user in ``conversation_id``.", "properties": { "agent_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "AI-employee persona agent_id to preserve across the report turn.", "title": "Agent Id" }, "conversation_id": { "description": "Conversation to resume with the first-run report.", "title": "Conversation Id", "type": "string" }, "notify_policy": { "default": "on_complete", "description": "on_complete | on_error | on_each_batch | silent", "title": "Notify Policy", "type": "string" } }, "required": [ "conversation_id" ], "title": "WatchFirstRunRequest", "type": "object" }, "WatchFirstRunResponse": { "properties": { "continuation_id": { "title": "Continuation Id", "type": "string" }, "status": { "title": "Status", "type": "string" } }, "required": [ "continuation_id", "status" ], "title": "WatchFirstRunResponse", "type": "object" }, "WatchProvider": { "description": "One streaming provider as TMDB names it (e.g. \"Max\", \"Apple TV\").", "properties": { "name": { "title": "Name", "type": "string" } }, "required": [ "name" ], "title": "WatchProvider", "type": "object" }, "WatchProviders": { "description": "Per-region availability buckets for one title.", "properties": { "buy": { "default": [], "items": { "$ref": "#/components/schemas/WatchProvider" }, "title": "Buy", "type": "array" }, "rent": { "default": [], "items": { "$ref": "#/components/schemas/WatchProvider" }, "title": "Rent", "type": "array" }, "stream": { "default": [], "items": { "$ref": "#/components/schemas/WatchProvider" }, "title": "Stream", "type": "array" } }, "title": "WatchProviders", "type": "object" }, "WatchRequest": { "description": "Watch registration request (topic_name is optional — defaults to config).", "properties": { "topic_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "GCP Pub/Sub topic. Falls back to GCP_GMAIL_PUBSUB_TOPIC env var.", "title": "Topic Name" } }, "title": "WatchRequest", "type": "object" }, "WatchResponse": { "description": "Watch registration result.", "properties": { "connection_id": { "title": "Connection Id", "type": "string" }, "expiration": { "title": "Expiration", "type": "string" }, "history_id": { "title": "History Id", "type": "string" } }, "required": [ "connection_id", "history_id", "expiration" ], "title": "WatchResponse", "type": "object" }, "WeatherData": { "description": "Weather data for the feed header and detail view.\n\nFetched from NWS API based on user's home location.\nIncludes current conditions plus extended forecast.", "properties": { "condition": { "description": "Weather condition: sunny, cloudy, rainy, snowy", "examples": [ "sunny", "cloudy" ], "title": "Condition", "type": "string" }, "detailedForecast": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Full detailed forecast for current period", "title": "Detailedforecast" }, "forecast": { "description": "Extended forecast periods (up to 14 periods / 7 days)", "items": { "$ref": "#/components/schemas/ForecastPeriod" }, "title": "Forecast", "type": "array" }, "iconUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "NWS weather icon URL", "title": "Iconurl" }, "locationName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Location name for the forecast", "examples": [ "Berlin, CT" ], "title": "Locationname" }, "shortForecast": { "description": "Short forecast text from NWS", "examples": [ "Mostly Sunny", "Partly Cloudy" ], "title": "Shortforecast", "type": "string" }, "temperature": { "description": "Current temperature in Fahrenheit", "examples": [ 72 ], "title": "Temperature", "type": "integer" }, "updatedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "When the forecast was last updated (ISO timestamp)", "title": "Updatedat" }, "windDirection": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Current wind direction", "examples": [ "N", "SW", "NNE" ], "title": "Winddirection" }, "windSpeed": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Current wind speed", "examples": [ "10 mph", "5 to 10 mph" ], "title": "Windspeed" } }, "required": [ "temperature", "condition", "shortForecast" ], "title": "WeatherData", "type": "object" }, "WeatherResponse": { "description": "Weather response wrapper.\n\n``weather`` is null when the account has no home location set (or the\nupstream NWS forecast is unavailable). ``home_location_set`` distinguishes\n\"no home location configured\" from \"we have a location but no forecast\",\nand ``message`` carries a short, user-facing explanation in either case.", "properties": { "home_location_set": { "description": "Whether the account has a home latitude/longitude configured.", "title": "Home Location Set", "type": "boolean" }, "message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Human-readable explanation when no forecast is returned.", "title": "Message" }, "weather": { "anyOf": [ { "$ref": "#/components/schemas/WeatherData" }, { "type": "null" } ], "description": "Current conditions + extended forecast; null when unavailable." } }, "required": [ "home_location_set" ], "title": "WeatherResponse", "type": "object" }, "WebClippingGalleryItem": { "properties": { "capture_mode": { "title": "Capture Mode", "type": "string" }, "captured_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Captured At" }, "created_at": { "title": "Created At", "type": "string" }, "note_id": { "title": "Note Id", "type": "string" }, "page_title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Page Title" }, "screenshot_attachment_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Screenshot Attachment Id" }, "screenshot_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Screenshot Url" }, "site_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Site Name" }, "tags": { "items": { "type": "string" }, "title": "Tags", "type": "array" }, "thumbnail_attachment_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Thumbnail Attachment Id" }, "thumbnail_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Thumbnail Url" }, "title": { "title": "Title", "type": "string" }, "url": { "title": "Url", "type": "string" } }, "required": [ "note_id", "title", "url", "capture_mode", "tags", "created_at" ], "title": "WebClippingGalleryItem", "type": "object" }, "WebClippingGalleryResponse": { "properties": { "items": { "items": { "$ref": "#/components/schemas/WebClippingGalleryItem" }, "title": "Items", "type": "array" } }, "required": [ "items" ], "title": "WebClippingGalleryResponse", "type": "object" }, "WebClippingIngestionRequest": { "properties": { "force": { "default": false, "title": "Force", "type": "boolean" } }, "title": "WebClippingIngestionRequest", "type": "object" }, "WebClippingIngestionResponse": { "properties": { "content_char_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Content Char Count" }, "content_hash": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Content Hash" }, "error_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error Code" }, "note_id": { "title": "Note Id", "type": "string" }, "source_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Source Url" }, "status": { "title": "Status", "type": "string" } }, "required": [ "note_id", "status" ], "title": "WebClippingIngestionResponse", "type": "object" }, "WebClippingScreenshotResponse": { "properties": { "attachment_id": { "description": "Generated screenshot object id", "title": "Attachment Id", "type": "string" }, "content_type": { "title": "Content Type", "type": "string" }, "photo_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Set when capture_mode='image_capture' produced a photos row (the clipped image becomes a photo-faceted file). TIDY-13904.", "title": "Photo Id" }, "size_bytes": { "title": "Size Bytes", "type": "integer" }, "storage_path": { "description": "Object path in the attachments bucket", "title": "Storage Path", "type": "string" }, "thumbnail_attachment_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Deterministic inline thumbnail derivative object id", "title": "Thumbnail Attachment Id" }, "thumbnail_content_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Thumbnail Content Type" }, "thumbnail_generated_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Thumbnail Generated At" }, "thumbnail_size_bytes": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Thumbnail Size Bytes" }, "thumbnail_storage_path": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Object path for inline thumbnail derivative", "title": "Thumbnail Storage Path" }, "thumbnail_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Authenticated storage proxy URL for inline thumbnail derivative", "title": "Thumbnail Url" }, "url": { "description": "Authenticated storage proxy URL", "title": "Url", "type": "string" } }, "required": [ "attachment_id", "url", "storage_path", "content_type", "size_bytes" ], "title": "WebClippingScreenshotResponse", "type": "object" }, "WebClippingStatusResponse": { "properties": { "count": { "title": "Count", "type": "integer" }, "latest_captured_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Latest Captured At" }, "latest_note_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Latest Note Id" }, "latest_screenshot_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Latest Screenshot Url" }, "saved": { "title": "Saved", "type": "boolean" } }, "required": [ "saved", "count" ], "title": "WebClippingStatusResponse", "type": "object" }, "WebSearchMeSummary": { "properties": { "account_id": { "format": "uuid", "title": "Account Id", "type": "string" }, "enforcement_enabled": { "title": "Enforcement Enabled", "type": "boolean" }, "limit": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Limit" }, "period_end": { "format": "date-time", "title": "Period End", "type": "string" }, "period_start": { "format": "date-time", "title": "Period Start", "type": "string" }, "period_type": { "title": "Period Type", "type": "string" }, "provider": { "title": "Provider", "type": "string" }, "remaining": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Remaining" }, "resource_type": { "title": "Resource Type", "type": "string" }, "tenant_id": { "format": "uuid", "title": "Tenant Id", "type": "string" }, "used": { "title": "Used", "type": "number" } }, "required": [ "tenant_id", "account_id", "resource_type", "provider", "period_type", "period_start", "period_end", "used", "limit", "remaining", "enforcement_enabled" ], "title": "WebSearchMeSummary", "type": "object" }, "WebSearchRequest": { "properties": { "consent_token": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Echo the consent_token from a checkpoint_required 402 to continue.", "title": "Consent Token" }, "conversation_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Conversation Id" }, "depth": { "default": "basic", "description": "basic uses 1 Tavily unit; advanced uses 2. Tidy credits follow the configured resource price.", "enum": [ "basic", "advanced" ], "title": "Depth", "type": "string" }, "include_answer": { "default": false, "description": "Ask the provider for a short synthesized answer too.", "title": "Include Answer", "type": "boolean" }, "max_results": { "default": 5, "maximum": 10.0, "minimum": 1.0, "title": "Max Results", "type": "integer" }, "query": { "description": "What to search the web for.", "maxLength": 400, "minLength": 1, "title": "Query", "type": "string" }, "topic": { "default": "general", "enum": [ "general", "news" ], "title": "Topic", "type": "string" } }, "required": [ "query" ], "title": "WebSearchRequest", "type": "object" }, "WebSearchResponse": { "properties": { "answer": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Answer" }, "credits": { "description": "Tidy credits actually charged to the member, not provider units.", "title": "Credits", "type": "number" }, "query": { "title": "Query", "type": "string" }, "results": { "items": { "$ref": "#/components/schemas/WebSearchResult" }, "title": "Results", "type": "array" }, "usage_event_id": { "format": "uuid", "title": "Usage Event Id", "type": "string" } }, "required": [ "query", "results", "credits", "usage_event_id" ], "title": "WebSearchResponse", "type": "object" }, "WebSearchResult": { "properties": { "content": { "title": "Content", "type": "string" }, "published_date": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Published Date" }, "score": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "title": "Score" }, "title": { "title": "Title", "type": "string" }, "url": { "title": "Url", "type": "string" } }, "required": [ "title", "url", "content" ], "title": "WebSearchResult", "type": "object" }, "WebhookDestination": { "properties": { "auth_scheme": { "enum": [ "none", "bearer", "header" ], "title": "Auth Scheme", "type": "string" }, "editable": { "title": "Editable", "type": "boolean" }, "enabled": { "title": "Enabled", "type": "boolean" }, "has_secret": { "title": "Has Secret", "type": "boolean" }, "header_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Header Name" }, "host": { "title": "Host", "type": "string" }, "last_delivery_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Last Delivery At" }, "last_delivery_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Last Delivery Status" }, "plugin_id": { "title": "Plugin Id", "type": "string" }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Url" } }, "required": [ "plugin_id", "host", "auth_scheme", "has_secret", "enabled", "editable" ], "title": "WebhookDestination", "type": "object" }, "WebhookDestinationEnabled": { "additionalProperties": false, "properties": { "enabled": { "title": "Enabled", "type": "boolean" } }, "required": [ "enabled" ], "title": "WebhookDestinationEnabled", "type": "object" }, "WebhookDestinationSave": { "additionalProperties": false, "description": "Connect a webhook destination, or change one (``plugin_id``).", "properties": { "auth_scheme": { "enum": [ "none", "bearer", "header" ], "title": "Auth Scheme", "type": "string" }, "header_name": { "anyOf": [ { "maxLength": 120, "type": "string" }, { "type": "null" } ], "title": "Header Name" }, "label": { "anyOf": [ { "maxLength": 200, "type": "string" }, { "type": "null" } ], "title": "Label" }, "plugin_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Plugin Id" }, "secret": { "anyOf": [ { "maxLength": 4096, "type": "string" }, { "type": "null" } ], "title": "Secret" }, "url": { "maxLength": 2048, "minLength": 1, "title": "Url", "type": "string" } }, "required": [ "url", "auth_scheme" ], "title": "WebhookDestinationSave", "type": "object" }, "WebhookDestinationTestResult": { "properties": { "attempts": { "title": "Attempts", "type": "integer" }, "delivered": { "title": "Delivered", "type": "boolean" }, "delivery_id": { "title": "Delivery Id", "type": "string" }, "destination": { "$ref": "#/components/schemas/WebhookDestination" }, "message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Message" }, "status_code": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Status Code" } }, "required": [ "delivered", "attempts", "delivery_id", "destination" ], "title": "WebhookDestinationTestResult", "type": "object" }, "WebhookHealthConnection": { "description": "Per-connection webhook health snapshot.", "properties": { "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Email" }, "id": { "title": "Id", "type": "string" }, "is_stale": { "title": "Is Stale", "type": "boolean" }, "last_webhook_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Last Webhook At" }, "last_webhook_failure_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Last Webhook Failure At" }, "last_webhook_failure_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Last Webhook Failure Reason" }, "provider_type": { "title": "Provider Type", "type": "string" }, "push_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Push Type" }, "webhook_failure_count": { "title": "Webhook Failure Count", "type": "integer" } }, "required": [ "id", "provider_type", "webhook_failure_count", "is_stale" ], "title": "WebhookHealthConnection", "type": "object" }, "WebhookHealthResponse": { "description": "Aggregate response for the admin panel.", "properties": { "connections": { "items": { "$ref": "#/components/schemas/WebhookHealthConnection" }, "title": "Connections", "type": "array" } }, "required": [ "connections" ], "title": "WebhookHealthResponse", "type": "object" }, "WebhookOkResponse": { "properties": { "ok": { "title": "Ok", "type": "boolean" } }, "required": [ "ok" ], "title": "WebhookOkResponse", "type": "object" }, "WeeklyBreakdown": { "properties": { "email_received": { "title": "Email Received", "type": "integer" }, "focus_hours": { "title": "Focus Hours", "type": "number" }, "meeting_hours": { "title": "Meeting Hours", "type": "number" }, "period": { "title": "Period", "type": "string" }, "tasks_completed": { "title": "Tasks Completed", "type": "integer" }, "tasks_created": { "title": "Tasks Created", "type": "integer" } }, "required": [ "period", "email_received", "meeting_hours", "focus_hours", "tasks_completed", "tasks_created" ], "title": "WeeklyBreakdown", "type": "object" }, "WhyEntry": { "properties": { "after": { "default": null, "title": "After" }, "before": { "default": null, "title": "Before" }, "can_undo": { "default": false, "title": "Can Undo", "type": "boolean" }, "changed_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Changed At" }, "evidence_refs": { "default": [], "items": { "type": "string" }, "title": "Evidence Refs", "type": "array" }, "field": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Field" }, "kind": { "enum": [ "change", "rollback" ], "title": "Kind", "type": "string" }, "label": { "default": "Updated by Tidy", "title": "Label", "type": "string" }, "output_index": { "title": "Output Index", "type": "integer" }, "reversible": { "default": false, "title": "Reversible", "type": "boolean" }, "run_id": { "format": "uuid", "title": "Run Id", "type": "string" } }, "required": [ "run_id", "output_index", "kind" ], "title": "WhyEntry", "type": "object" }, "WhyResponse": { "properties": { "entries": { "items": { "$ref": "#/components/schemas/WhyEntry" }, "title": "Entries", "type": "array" }, "primitive_id": { "format": "uuid", "title": "Primitive Id", "type": "string" }, "primitive_type": { "title": "Primitive Type", "type": "string" } }, "required": [ "primitive_type", "primitive_id", "entries" ], "title": "WhyResponse", "type": "object" }, "WideNotificationPreferences": { "description": "Full notification preferences surface used by settings UI.", "properties": { "auto_expiry_enabled": { "default": true, "title": "Auto Expiry Enabled", "type": "boolean" }, "digest_frequency": { "default": "daily", "title": "Digest Frequency", "type": "string" }, "digest_time": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": "08:00", "title": "Digest Time" }, "phone_number": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Phone Number" }, "phone_verified": { "default": false, "title": "Phone Verified", "type": "boolean" }, "push_enabled": { "default": true, "title": "Push Enabled", "type": "boolean" }, "quiet_hours_end": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Quiet Hours End" }, "quiet_hours_start": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Quiet Hours Start" }, "receive_billing": { "default": true, "title": "Receive Billing", "type": "boolean" }, "receive_event_digests": { "default": true, "title": "Receive Event Digests", "type": "boolean" }, "receive_event_reminders": { "default": true, "title": "Receive Event Reminders", "type": "boolean" }, "receive_insights": { "default": true, "title": "Receive Insights", "type": "boolean" }, "receive_marketing": { "default": false, "title": "Receive Marketing", "type": "boolean" }, "receive_task_reminders": { "default": true, "title": "Receive Task Reminders", "type": "boolean" }, "sms_consent_given": { "default": false, "title": "Sms Consent Given", "type": "boolean" }, "sms_consent_grants": { "default": [], "items": { "$ref": "#/components/schemas/SmsConsentGrant" }, "title": "Sms Consent Grants", "type": "array" }, "sms_consent_phone_number": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Sms Consent Phone Number" }, "sms_consent_terms_version": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Sms Consent Terms Version" }, "sms_consent_timestamp": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Sms Consent Timestamp" }, "sms_enabled": { "default": false, "title": "Sms Enabled", "type": "boolean" }, "sms_resume_number": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Sms Resume Number" }, "sms_stopped_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Sms Stopped At" } }, "title": "WideNotificationPreferences", "type": "object" }, "WideNotificationPreferencesUpdateResponse": { "description": "``PUT /notifications/preferences`` response (TIDY-18062).\n\nAdditive by construction: ``success`` is exactly the key this endpoint has\nalways returned, with the same value and type, so every caller that reads\nonly ``success`` (settings/privacy auto-expiry, admin/notifications/\npreferences, onboarding/EmailFeaturesShowcase) is byte-identical. The\n``preferences`` object is the new half — the row as it now reads, written by\nthis request. It exists so a step-shaped caller (SMS setup: phone, then\nconsent, then verify) can advance on the response it already holds instead\nof issuing a re-GET in the middle of a consent flow, which is where\nTIDY-18046 lived. The narrow PUT returned the row from the start; that is\nthe whole reason its callers could not move until now.", "properties": { "preferences": { "$ref": "#/components/schemas/WideNotificationPreferences" }, "success": { "default": true, "title": "Success", "type": "boolean" } }, "required": [ "preferences" ], "title": "WideNotificationPreferencesUpdateResponse", "type": "object" }, "WidgetPresetCreateRequest": { "description": "Save a selection as a reusable built-in.", "properties": { "doc": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Doc" }, "name": { "maxLength": 200, "minLength": 1, "title": "Name", "type": "string" }, "props": { "additionalProperties": true, "title": "Props", "type": "object" }, "visibility": { "default": "private", "maxLength": 16, "title": "Visibility", "type": "string" }, "widget_id": { "maxLength": 128, "minLength": 1, "title": "Widget Id", "type": "string" } }, "required": [ "name", "widget_id" ], "title": "WidgetPresetCreateRequest", "type": "object" }, "WidgetPresetDetail": { "properties": { "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "doc": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "title": "Doc" }, "id": { "format": "uuid", "title": "Id", "type": "string" }, "name": { "title": "Name", "type": "string" }, "owner_id": { "format": "uuid", "title": "Owner Id", "type": "string" }, "props": { "additionalProperties": true, "title": "Props", "type": "object" }, "tenant_id": { "format": "uuid", "title": "Tenant Id", "type": "string" }, "updated_at": { "format": "date-time", "title": "Updated At", "type": "string" }, "visibility": { "title": "Visibility", "type": "string" }, "widget_id": { "title": "Widget Id", "type": "string" } }, "required": [ "id", "tenant_id", "owner_id", "name", "widget_id", "visibility", "created_at", "updated_at" ], "title": "WidgetPresetDetail", "type": "object" }, "WidgetPresetList": { "properties": { "presets": { "items": { "$ref": "#/components/schemas/WidgetPresetSummary" }, "title": "Presets", "type": "array" } }, "required": [ "presets" ], "title": "WidgetPresetList", "type": "object" }, "WidgetPresetSummary": { "properties": { "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "id": { "format": "uuid", "title": "Id", "type": "string" }, "name": { "title": "Name", "type": "string" }, "owner_id": { "format": "uuid", "title": "Owner Id", "type": "string" }, "tenant_id": { "format": "uuid", "title": "Tenant Id", "type": "string" }, "updated_at": { "format": "date-time", "title": "Updated At", "type": "string" }, "visibility": { "title": "Visibility", "type": "string" }, "widget_id": { "title": "Widget Id", "type": "string" } }, "required": [ "id", "tenant_id", "owner_id", "name", "widget_id", "visibility", "created_at", "updated_at" ], "title": "WidgetPresetSummary", "type": "object" }, "WidgetPresetUpdateRequest": { "description": "Patch a preset. Editing ``props`` is what updates every LINKED instance\nof it — which is the whole point of the linked mode, so it is an ordinary\nPATCH rather than a special publish step.", "properties": { "doc": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Doc" }, "name": { "anyOf": [ { "maxLength": 200, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Name" }, "props": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Props" }, "visibility": { "anyOf": [ { "maxLength": 16, "type": "string" }, { "type": "null" } ], "title": "Visibility" } }, "title": "WidgetPresetUpdateRequest", "type": "object" }, "WikiLinkSyncItem": { "description": "One wiki-link entry to be upserted as a `linked_references` row.", "properties": { "block_created_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Authored date of the source block (its createdAt attr, TIDY-8315), canonical ISO-8601 UTC with trailing Z. Absent/None → NULL (unknown); never fabricated. Naive (tz-less) datetimes are rejected.", "title": "Block Created At" }, "display_text": { "default": "", "description": "Rendered inline label", "title": "Display Text", "type": "string" }, "link_source": { "default": "wiki_link_sync", "description": "Provenance tag (wiki_link_sync or content_embed)", "title": "Link Source", "type": "string" }, "link_type": { "default": "wiki_link", "description": "Relationship type (wiki_link, parent_of for activity embeds)", "title": "Link Type", "type": "string" }, "source_block_excerpt": { "default": "", "description": "Plain-text excerpt around the link", "title": "Source Block Excerpt", "type": "string" }, "source_block_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Block UUID the link appears in (precise provenance)", "title": "Source Block Id" }, "target_id": { "description": "UUID of the linked primitive", "title": "Target Id", "type": "string" }, "target_type": { "description": "Type of the linked primitive", "title": "Target Type", "type": "string" }, "trigger_style": { "default": "wiki", "description": "Original inline trigger: 'wiki' or 'at'", "title": "Trigger Style", "type": "string" } }, "required": [ "target_type", "target_id" ], "title": "WikiLinkSyncItem", "type": "object" }, "WikiLinkSyncRequest": { "description": "Request body: replace all wiki-link rows for the source container.", "properties": { "links": { "description": "Desired set of wiki-link rows. Existing wiki-link-sourced rows NOT in this list are deleted.", "items": { "$ref": "#/components/schemas/WikiLinkSyncItem" }, "title": "Links", "type": "array" } }, "title": "WikiLinkSyncRequest", "type": "object" }, "WikiLinkSyncResponse": { "description": "Response: total count of rows after the sync.", "properties": { "count": { "description": "Number of rows inserted", "title": "Count", "type": "integer" } }, "required": [ "count" ], "title": "WikiLinkSyncResponse", "type": "object" }, "WithheldSkillCredential": { "description": "A declared skill slot that gets NO value this turn, and why (TIDY-19569 F1).\n\nNames only — never a credential id or value. This is what the harness tells\nthe model; it is not the enforcement (a withheld key simply has no value).\n``reason``: ``missing`` (nothing lent for this harness), ``revoked`` /\n``refresh_error`` / ``rotation_required`` (lent but unusable),\n``ambiguous`` (more than one usable credential — Tidy never picks one),\n``unsatisfiable_on_harness`` (a Tidy/harness control key, or a harness\nwithout per-turn credential env), ``not_available_here`` (lent, but not to\nwhoever this turn runs as — another member's conversation), or\n``not_declared_by_job`` (a scheduled job materializes only what it named).\n\nWith ``include_granted_env`` it also names this turn's own lends that get no\nvalue; ``skills`` is then empty and ``required`` false when no carried skill\ndeclares the key, and ``turn_limit_exceeded`` means more lends than one turn\nmay carry, so none of them was delivered.", "properties": { "detail": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Detail" }, "env_key": { "title": "Env Key", "type": "string" }, "reason": { "enum": [ "missing", "revoked", "refresh_error", "rotation_required", "ambiguous", "unsatisfiable_on_harness", "not_available_here", "not_declared_by_job", "credential_privacy_unsupported", "turn_limit_exceeded" ], "title": "Reason", "type": "string" }, "required": { "title": "Required", "type": "boolean" }, "required_by": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "default": null, "title": "Required By" }, "skills": { "items": { "type": "string" }, "title": "Skills", "type": "array" } }, "required": [ "env_key", "skills", "required", "reason" ], "title": "WithheldSkillCredential", "type": "object" }, "WorkConfigUpdate": { "additionalProperties": false, "description": "Per-project work configuration shape (TIDY-11821 / D13).\n\nValidates the `work_config` JSONB payload on PATCH/PUT. A strict model:\nunknown keys are rejected (422), and every value is type-checked. We\nvalidate SHAPE, not vocabulary (D15 superseded): `icon_map` is a flat\n``{type_value: icon_value}`` map where each ``icon_value`` is whatever the\ncanonical unified IconPicker produces — a bare Lucide name OR a serialized\n``{\"kind\",\"value\"}`` JSON string for emoji / image / ai-image. Both are\nplain strings, so the ``Dict[str, str]`` type accepts the full contract\nwithout constraining to a Lucide name. All fields are optional so a partial\nconfig (e.g. just an icon map) is accepted; the resolver layers stored\nvalues over the code-level defaults (R44). NULL stays NULL.", "properties": { "estimate_property": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Property key whose value is the per-row estimate (minutes)", "title": "Estimate Property" }, "facet_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Work facet slug/id (default 'task')", "title": "Facet Id" }, "icon_map": { "anyOf": [ { "additionalProperties": { "type": "string" }, "type": "object" }, { "type": "null" } ], "description": "Canonical icon value per type value: {value: icon}. Each icon is a bare Lucide name OR a serialized {kind,value} JSON string (emoji/image), as produced by the unified IconPicker.", "title": "Icon Map" }, "tracked_source": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Tracked-time source for the rollup (e.g. 'time_logs')", "title": "Tracked Source" }, "type_property": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Select property on the work facet used as the 'type'", "title": "Type Property" } }, "title": "WorkConfigUpdate", "type": "object" }, "WorkGraphItem": { "properties": { "assignee_account_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Assignee Account Id" }, "assignee_display_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Assignee Display Name" }, "assignee_employee": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Assignee Employee" }, "conversation_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Conversation Id" }, "conversation_running": { "default": false, "title": "Conversation Running", "type": "boolean" }, "conversation_title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Conversation Title" }, "item_ref": { "title": "Item Ref", "type": "string" }, "linked_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "With an anchor: when this item was first linked to it.", "title": "Linked At" }, "links": { "description": "With an anchor: each link between it and this item, oldest first.", "items": { "$ref": "#/components/schemas/WorkGraphLink" }, "title": "Links", "type": "array" }, "priority": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Priority" }, "resolved": { "default": false, "title": "Resolved", "type": "boolean" }, "status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Status" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Title" } }, "required": [ "item_ref" ], "title": "WorkGraphItem", "type": "object" }, "WorkGraphLink": { "properties": { "direction": { "description": "`out`: the anchor is the link's source (it is this item's parent, or depends on it).", "enum": [ "out", "in" ], "title": "Direction", "type": "string" }, "link_type": { "description": "The link's type, e.g. `parent_of` or `depends_on`.", "title": "Link Type", "type": "string" } }, "required": [ "link_type", "direction" ], "title": "WorkGraphLink", "type": "object" }, "WorkGraphResponse": { "properties": { "anchor_item_ref": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Anchor Item Ref" }, "items": { "items": { "$ref": "#/components/schemas/WorkGraphItem" }, "title": "Items", "type": "array" } }, "title": "WorkGraphResponse", "type": "object" }, "WorkOrdersRetiredProblem": { "description": "The problem+json body the retired admission route answers.", "properties": { "code": { "const": "resource_gone", "title": "Code", "type": "string" }, "detail": { "title": "Detail", "type": "string" }, "error_code": { "const": "work_orders_retired", "title": "Error Code", "type": "string" }, "status": { "const": 410, "title": "Status", "type": "integer" } }, "required": [ "status", "code", "error_code", "detail" ], "title": "WorkOrdersRetiredProblem", "type": "object" }, "WorkflowCodeResponse": { "properties": { "code": { "title": "Code", "type": "string" }, "id": { "title": "Id", "type": "string" }, "language": { "title": "Language", "type": "string" }, "version": { "title": "Version", "type": "integer" } }, "required": [ "id", "code", "language", "version" ], "title": "WorkflowCodeResponse", "type": "object" }, "WorkflowCreate": { "properties": { "code": { "default": "", "title": "Code", "type": "string" }, "creating_conversation_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Creating Conversation Id" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "enabled": { "default": false, "title": "Enabled", "type": "boolean" }, "generation_metadata": { "additionalProperties": true, "title": "Generation Metadata", "type": "object" }, "language": { "default": "python", "title": "Language", "type": "string" }, "name": { "title": "Name", "type": "string" }, "trigger_config": { "additionalProperties": true, "title": "Trigger Config", "type": "object" }, "trigger_type": { "default": "manual", "title": "Trigger Type", "type": "string" }, "visibility": { "default": "private", "title": "Visibility", "type": "string" } }, "required": [ "name" ], "title": "WorkflowCreate", "type": "object" }, "WorkflowInputSpec": { "description": "A single declared input on a bindable workflow (TIDY-11015 / S1).\n\nDeclared inputs live in ``workflow_scripts.trigger_config.inputs[]`` (no new\nstore — ``trigger_config`` is the existing freeform JSONB). The facet-action\nauthoring picker (consumed later by S3/S8) reads these to know which inputs\nan action must map, and the invoke path (D6) reads ``required`` to decide\nwhich unmapped inputs become prompt-needed.", "properties": { "key": { "description": "Workflow input name", "title": "Key", "type": "string" }, "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Human label for authoring/prompt", "title": "Label" }, "required": { "default": false, "description": "Whether the workflow requires this input", "title": "Required", "type": "boolean" }, "type": { "default": "string", "description": "Declared input type", "title": "Type", "type": "string" } }, "required": [ "key" ], "title": "WorkflowInputSpec", "type": "object" }, "WorkflowResponse": { "properties": { "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "created_by": { "title": "Created By", "type": "string" }, "creating_conversation_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Creating Conversation Id" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "enabled": { "title": "Enabled", "type": "boolean" }, "execution_count": { "title": "Execution Count", "type": "integer" }, "failure_count": { "default": 0, "title": "Failure Count", "type": "integer" }, "generation_metadata": { "additionalProperties": true, "title": "Generation Metadata", "type": "object" }, "id": { "title": "Id", "type": "string" }, "language": { "title": "Language", "type": "string" }, "last_run_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Last Run At" }, "last_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Status" }, "name": { "title": "Name", "type": "string" }, "success_count": { "default": 0, "title": "Success Count", "type": "integer" }, "tenant_id": { "title": "Tenant Id", "type": "string" }, "trigger_config": { "additionalProperties": true, "title": "Trigger Config", "type": "object" }, "trigger_type": { "title": "Trigger Type", "type": "string" }, "updated_at": { "format": "date-time", "title": "Updated At", "type": "string" }, "version": { "title": "Version", "type": "integer" }, "visibility": { "default": "private", "title": "Visibility", "type": "string" } }, "required": [ "id", "tenant_id", "created_by", "name", "description", "language", "version", "trigger_type", "trigger_config", "enabled", "execution_count", "last_run_at", "last_status", "created_at", "updated_at" ], "title": "WorkflowResponse", "type": "object" }, "WorkflowUpdate": { "properties": { "code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Code" }, "creating_conversation_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Creating Conversation Id" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "enabled": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Enabled" }, "ephemeral": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Ephemeral" }, "generation_metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Generation Metadata" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name" }, "trigger_config": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Trigger Config" }, "trigger_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Trigger Type" }, "visibility": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Visibility" } }, "title": "WorkflowUpdate", "type": "object" }, "WorkforceFunnelResponse": { "properties": { "deploy_failures": { "items": { "$ref": "#/components/schemas/DeployFailureRow" }, "title": "Deploy Failures", "type": "array" }, "funnel": { "$ref": "#/components/schemas/FunnelCounts" }, "health_checks": { "items": { "$ref": "#/components/schemas/HealthCheckRateRow" }, "title": "Health Checks", "type": "array" }, "plugins_needing_reauth": { "items": { "$ref": "#/components/schemas/PluginReauthRow" }, "title": "Plugins Needing Reauth", "type": "array" }, "ttfc": { "$ref": "#/components/schemas/TtfcSummary" }, "window": { "title": "Window", "type": "string" }, "window_days": { "title": "Window Days", "type": "integer" }, "workshops": { "items": { "$ref": "#/components/schemas/WorkshopTenantRow" }, "title": "Workshops", "type": "array" } }, "required": [ "window", "window_days", "funnel", "workshops", "deploy_failures", "plugins_needing_reauth", "ttfc", "health_checks" ], "title": "WorkforceFunnelResponse", "type": "object" }, "WorkshopAcpRegistryAgent": { "description": "TIDY-19931 (F7) — one agent of the ACP registry, as this workshop can use it.", "properties": { "authors": { "items": { "type": "string" }, "title": "Authors", "type": "array" }, "builtin": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Builtin" }, "description": { "default": "", "title": "Description", "type": "string" }, "distribution": { "anyOf": [ { "enum": [ "binary", "npx", "uvx" ], "type": "string" }, { "type": "null" } ], "default": null, "title": "Distribution" }, "icon": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Icon" }, "id": { "title": "Id", "type": "string" }, "installable": { "title": "Installable", "type": "boolean" }, "installed_version": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Installed Version" }, "license": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "License" }, "name": { "title": "Name", "type": "string" }, "repository": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Repository" }, "runtime": { "title": "Runtime", "type": "string" }, "unavailable_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Unavailable Reason" }, "update_available": { "default": false, "title": "Update Available", "type": "boolean" }, "version": { "title": "Version", "type": "string" }, "website": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Website" } }, "required": [ "runtime", "id", "name", "version", "installable" ], "title": "WorkshopAcpRegistryAgent", "type": "object" }, "WorkshopAcpRegistryResponse": { "description": "TIDY-19931 (F7) — the ACP registry, filtered to what this workshop runs:\ninstalled first, then installable, then the rest, each by name.", "properties": { "agents": { "items": { "$ref": "#/components/schemas/WorkshopAcpRegistryAgent" }, "title": "Agents", "type": "array" }, "fetched_at": { "format": "date-time", "title": "Fetched At", "type": "string" }, "platform": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Platform" }, "stale": { "default": false, "title": "Stale", "type": "boolean" } }, "required": [ "fetched_at" ], "title": "WorkshopAcpRegistryResponse", "type": "object" }, "WorkshopAllowDockerRequest": { "properties": { "allow_docker": { "title": "Allow Docker", "type": "boolean" } }, "required": [ "allow_docker" ], "title": "WorkshopAllowDockerRequest", "type": "object" }, "WorkshopAppBrowserResponse": { "properties": { "app_id": { "title": "App Id", "type": "string" }, "browser_account_id": { "description": "The app's own browser on its workshop.", "title": "Browser Account Id", "type": "string" }, "name": { "title": "Name", "type": "string" }, "port": { "title": "Port", "type": "integer" }, "session_id": { "description": "The live session of that browser: watch and drive it like any protected browser session (tickets, mode, stream).", "title": "Session Id", "type": "string" }, "start_url": { "description": "Where the app's page is, inside that browser.", "title": "Start Url", "type": "string" } }, "required": [ "app_id", "name", "port", "browser_account_id", "session_id", "start_url" ], "title": "WorkshopAppBrowserResponse", "type": "object" }, "WorkshopAppDirectBody": { "properties": { "capabilities": { "description": "What this device can dial: `lan_v1` (the same-network lane), `direct_v1` (a WebRTC link).", "items": { "type": "string" }, "maxItems": 8, "title": "Capabilities", "type": "array" }, "lan_addresses": { "description": "This device's LAN addresses, `address/prefix`: whether it shares the box's network.", "items": { "type": "string" }, "maxItems": 16, "title": "Lan Addresses", "type": "array" }, "tls_fingerprint": { "description": "This view's own certificate (RFC 8122, `sha-256 AB:…`): the box admits only it.", "pattern": "^sha-256 [0-9A-F]{2}(?::[0-9A-F]{2}){31}$", "title": "Tls Fingerprint", "type": "string" } }, "required": [ "tls_fingerprint" ], "title": "WorkshopAppDirectBody", "type": "object" }, "WorkshopAppDirectLane": { "properties": { "addresses": { "description": "The box's LAN addresses it now listens on, for this device only.", "items": { "type": "string" }, "title": "Addresses", "type": "array" }, "connect_ms": { "description": "How long the box listens; connect within it.", "title": "Connect Ms", "type": "integer" }, "port": { "title": "Port", "type": "integer" } }, "required": [ "addresses", "port", "connect_ms" ], "title": "WorkshopAppDirectLane", "type": "object" }, "WorkshopAppDirectLink": { "properties": { "ice_servers": { "description": "STUN servers; there is no TURN, the relay is the fallback.", "items": { "type": "string" }, "title": "Ice Servers", "type": "array" }, "link_id": { "title": "Link Id", "type": "string" }, "signal_path": { "description": "The signaling WebSocket for this link (bearer-authenticated).", "title": "Signal Path", "type": "string" } }, "required": [ "link_id", "ice_servers", "signal_path" ], "title": "WorkshopAppDirectLink", "type": "object" }, "WorkshopAppDirectManifestBody": { "properties": { "tls_fingerprint": { "pattern": "^sha-256 [0-9A-F]{2}(?::[0-9A-F]{2}){31}$", "title": "Tls Fingerprint", "type": "string" } }, "required": [ "tls_fingerprint" ], "title": "WorkshopAppDirectManifestBody", "type": "object" }, "WorkshopAppDirectResponse": { "properties": { "box_fingerprint": { "description": "The certificate the box presents (RFC 8122).", "title": "Box Fingerprint", "type": "string" }, "lane": { "anyOf": [ { "$ref": "#/components/schemas/WorkshopAppDirectLane" }, { "type": "null" } ], "default": null }, "lease_ms": { "description": "How long the box admits the view after Tidy's last lease; it ends the view past it.", "title": "Lease Ms", "type": "integer" }, "link": { "anyOf": [ { "$ref": "#/components/schemas/WorkshopAppDirectLink" }, { "type": "null" } ], "default": null }, "path": { "description": "`lan`: dial the box over TLS; `link`: offer it a WebRTC link.", "enum": [ "lan", "link" ], "title": "Path", "type": "string" }, "session": { "$ref": "#/components/schemas/WorkshopAppDirectSession" }, "session_id": { "title": "Session Id", "type": "string" } }, "required": [ "session_id", "path", "box_fingerprint", "session", "lease_ms" ], "title": "WorkshopAppDirectResponse", "type": "object" }, "WorkshopAppDirectSession": { "properties": { "expires_at": { "description": "When it lapses (ISO 8601 UTC); ask for a fresh one before.", "title": "Expires At", "type": "string" }, "manifest": { "additionalProperties": true, "description": "The Tidy-signed `app.session` every stream carries, naming this view and certificate.", "title": "WorkshopAppDirectSessionManifest", "type": "object" }, "manifest_digest": { "title": "Manifest Digest", "type": "string" }, "signature": { "title": "Signature", "type": "string" }, "signing_key_id": { "title": "Signing Key Id", "type": "string" } }, "required": [ "manifest", "manifest_digest", "signature", "signing_key_id", "expires_at" ], "title": "WorkshopAppDirectSession", "type": "object" }, "WorkshopAppRegister": { "properties": { "name": { "description": "What the app is called in Tidy.", "maxLength": 80, "minLength": 1, "title": "Name", "type": "string" }, "port": { "description": "The port it listens on at 127.0.0.1 on the workshop. Nothing else is reachable.", "maximum": 65535.0, "minimum": 1.0, "title": "Port", "type": "integer" } }, "required": [ "name", "port" ], "title": "WorkshopAppRegister", "type": "object" }, "WorkshopAppRelayUsageSummary": { "description": "The caller's workshop-app bytes Tidy's app relay carried today (UTC),\nboth ways. No allowance: ``limit`` and ``remaining`` are always null and\n``enforcement_enabled`` false.", "properties": { "account_id": { "format": "uuid", "title": "Account Id", "type": "string" }, "enforcement_enabled": { "title": "Enforcement Enabled", "type": "boolean" }, "limit": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Limit" }, "period_end": { "format": "date-time", "title": "Period End", "type": "string" }, "period_start": { "format": "date-time", "title": "Period Start", "type": "string" }, "period_type": { "title": "Period Type", "type": "string" }, "provider": { "title": "Provider", "type": "string" }, "remaining": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Remaining" }, "resource_type": { "title": "Resource Type", "type": "string" }, "tenant_id": { "format": "uuid", "title": "Tenant Id", "type": "string" }, "used": { "title": "Used", "type": "number" } }, "required": [ "tenant_id", "account_id", "resource_type", "provider", "period_type", "period_start", "period_end", "used", "limit", "remaining", "enforcement_enabled" ], "title": "WorkshopAppRelayUsageSummary", "type": "object" }, "WorkshopAppResponse": { "properties": { "id": { "title": "Id", "type": "string" }, "message": { "title": "Message", "type": "string" }, "name": { "title": "Name", "type": "string" }, "port": { "title": "Port", "type": "integer" }, "record_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "The app's record once approved.", "title": "Record Id" }, "state": { "description": "pending | approved | declined", "title": "State", "type": "string" }, "viewer_identity": { "anyOf": [ { "$ref": "#/components/schemas/WorkshopAppViewerIdentity" }, { "type": "null" } ], "default": null, "description": "How the app learns who is using it: every request Tidy carries to it holds `header`, a JWT naming the person (sub = Tidy id, email, name). Verify it against `keys_url` with audience `audience` and issuer `issuer`." }, "workshop_id": { "title": "Workshop Id", "type": "string" } }, "required": [ "id", "workshop_id", "name", "port", "state", "message" ], "title": "WorkshopAppResponse", "type": "object" }, "WorkshopAppSessionResponse": { "properties": { "app_id": { "title": "App Id", "type": "string" }, "expires_at": { "description": "The latest the pass can last (ISO 8601 UTC).", "title": "Expires At", "type": "string" }, "name": { "title": "Name", "type": "string" }, "origin": { "description": "The app's own origin for this pass.", "title": "Origin", "type": "string" }, "session_id": { "title": "Session Id", "type": "string" }, "url": { "description": "Load this once, within a minute: it spends a single-use code for the pass and lands on the app.", "title": "Url", "type": "string" } }, "required": [ "session_id", "app_id", "name", "origin", "url", "expires_at" ], "title": "WorkshopAppSessionResponse", "type": "object" }, "WorkshopAppViewerIdentity": { "properties": { "audience": { "description": "The `aud` the app accepts: its own id.", "title": "Audience", "type": "string" }, "header": { "description": "The request header that names the viewer: a signed JWT.", "title": "Header", "type": "string" }, "issuer": { "description": "The `iss` the app accepts: Tidy's origin.", "title": "Issuer", "type": "string" }, "keys_url": { "description": "The JWKS the app verifies it against (EdDSA, Ed25519).", "title": "Keys Url", "type": "string" } }, "required": [ "header", "keys_url", "audience", "issuer" ], "title": "WorkshopAppViewerIdentity", "type": "object" }, "WorkshopAppViewerKeysResponse": { "properties": { "keys": { "description": "JWKS: the public keys signing this app's viewers.", "items": { "additionalProperties": { "type": "string" }, "type": "object" }, "title": "Keys", "type": "array" } }, "required": [ "keys" ], "title": "WorkshopAppViewerKeysResponse", "type": "object" }, "WorkshopAttachRequest": { "description": "Assign an employee to this workshop.\n\nTIDY-19802 (D4): on a daemon-run workshop the attach deploys, so the plugin\naccess the employee needs there — and the skills Define picked\n(``skill_gives``) — ride the same request, reviewed before the person\nconfirmed. Omitted, an employee that would arrive without required access\nis refused (409 ``skill_plugin_access_required``) before the roster edge.\n\n``working_directory`` is additive (TIDY-18796). On a daemon-run workshop the\nattach IS the deploy, so a path collected by the caller had nowhere to go:\nthe journey's Deploy step asked the member for one, attach carried only the\naccount id, and ``deploy_employee`` composed\n``{EMPLOYEE_HOME_ROOT}/<account>/work`` instead. The member watched their own\nanswer be replaced by an invented path with nothing saying so. Omitted still\nmeans \"compose the default\" — every pre-existing caller keeps that behaviour.", "properties": { "agent_account_id": { "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", "title": "Agent Account Id", "type": "string" }, "assign_pending": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Assign Pending" }, "plugin_access": { "anyOf": [ { "items": { "$ref": "#/components/schemas/PluginAccessChoice" }, "maxItems": 16, "type": "array" }, { "type": "null" } ], "title": "Plugin Access" }, "requirements_hash": { "anyOf": [ { "maxLength": 64, "minLength": 64, "type": "string" }, { "type": "null" } ], "title": "Requirements Hash" }, "secret_files": { "anyOf": [ { "items": { "$ref": "#/components/schemas/SecretFileChoice" }, "maxItems": 16, "type": "array" }, { "type": "null" } ], "title": "Secret Files" }, "skill_gives": { "items": { "$ref": "#/components/schemas/SkillGive" }, "maxItems": 64, "title": "Skill Gives", "type": "array" }, "working_directory": { "anyOf": [ { "maxLength": 2048, "minLength": 2, "type": "string" }, { "type": "null" } ], "title": "Working Directory" } }, "required": [ "agent_account_id" ], "title": "WorkshopAttachRequest", "type": "object" }, "WorkshopBrowserEnrollment": { "properties": { "controller_id": { "format": "uuid", "title": "Controller Id", "type": "string" }, "enrollment_token": { "title": "Enrollment Token", "type": "string" }, "expires_at": { "format": "date-time", "title": "Expires At", "type": "string" }, "host_instance_id": { "format": "uuid", "title": "Host Instance Id", "type": "string" }, "key_generation": { "title": "Key Generation", "type": "integer" }, "tenant_id": { "format": "uuid", "title": "Tenant Id", "type": "string" }, "workshop_id": { "format": "uuid", "title": "Workshop Id", "type": "string" } }, "required": [ "controller_id", "workshop_id", "host_instance_id", "key_generation", "enrollment_token", "expires_at", "tenant_id" ], "title": "WorkshopBrowserEnrollment", "type": "object" }, "WorkshopBrowserInstall": { "properties": { "archive_sha256": { "pattern": "^[0-9a-f]{64}$", "title": "Archive Sha256", "type": "string" }, "archive_size": { "exclusiveMinimum": 0, "maximum": 1073741824, "title": "Archive Size", "type": "integer" }, "archive_url": { "maxLength": 2048, "minLength": 1, "pattern": "^https://", "title": "Archive Url", "type": "string" }, "enrollment": { "$ref": "#/components/schemas/WorkshopBrowserEnrollment" }, "runtime_version": { "maxLength": 64, "minLength": 1, "title": "Runtime Version", "type": "string" } }, "required": [ "archive_url", "archive_sha256", "archive_size", "runtime_version", "enrollment" ], "title": "WorkshopBrowserInstall", "type": "object" }, "WorkshopCapabilityReport": { "additionalProperties": false, "properties": { "arch": { "maxLength": 64, "minLength": 1, "title": "Arch", "type": "string" }, "disk_free_bytes": { "maximum": 9007199254740991.0, "minimum": 0.0, "title": "Disk Free Bytes", "type": "integer" }, "isolation": { "discriminator": { "mapping": { "protected": "#/components/schemas/ProtectedIsolation", "unenforced": "#/components/schemas/UnenforcedIsolation" }, "propertyName": "status" }, "oneOf": [ { "$ref": "#/components/schemas/ProtectedIsolation" }, { "$ref": "#/components/schemas/UnenforcedIsolation" } ], "title": "Isolation" }, "libc": { "anyOf": [ { "maxLength": 100, "type": "string" }, { "type": "null" } ], "title": "Libc" }, "report_at": { "format": "date-time", "title": "Report At", "type": "string" }, "runtime_integrity_error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Runtime Integrity Error" }, "tools": { "$ref": "#/components/schemas/WorkshopTools" } }, "required": [ "tools", "disk_free_bytes", "arch", "libc", "isolation", "report_at" ], "title": "WorkshopCapabilityReport", "type": "object" }, "WorkshopCreateRequest": { "properties": { "kind": { "default": "machine", "enum": [ "machine", "cloud" ], "title": "Kind", "type": "string" }, "name": { "maxLength": 200, "minLength": 1, "title": "Name", "type": "string" }, "request_key": { "anyOf": [ { "maxLength": 128, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Request Key" } }, "required": [ "name" ], "title": "WorkshopCreateRequest", "type": "object" }, "WorkshopDaemonAdoptRequest": { "description": "`install-workshop.sh --heal` on a timer-path box (TIDY-18237): the\ncontinuity token is the authority, exactly like the heartbeat.", "properties": { "host_continuity_token": { "minLength": 1, "title": "Host Continuity Token", "type": "string" }, "host_firewall_mode": { "anyOf": [ { "enum": [ "provisioned", "byo" ], "type": "string" }, { "type": "null" } ], "title": "Host Firewall Mode" }, "host_instance_id": { "minLength": 1, "title": "Host Instance Id", "type": "string" } }, "required": [ "host_instance_id", "host_continuity_token" ], "title": "WorkshopDaemonAdoptRequest", "type": "object" }, "WorkshopDaemonEmployee": { "description": "One adopted employee runtime as the daemon sees it (TIDY-18237).", "properties": { "agent_account_id": { "title": "Agent Account Id", "type": "string" }, "state": { "enum": [ "running", "stopped", "crashed", "starting" ], "title": "State", "type": "string" }, "stop_reason": { "anyOf": [ { "enum": [ "operator", "revoked", "upgrade" ], "type": "string" }, { "type": "null" } ], "title": "Stop Reason" } }, "required": [ "agent_account_id", "state" ], "title": "WorkshopDaemonEmployee", "type": "object" }, "WorkshopDaemonHarness": { "description": "One harness the daemon found installed on the box (TIDY-18237). The\nsame shape an employee's connector reports, so the capability evaluator\nmerges the two without a second vocabulary.", "properties": { "auth_methods": { "anyOf": [ { "items": { "$ref": "#/components/schemas/AcpAuthMethodReport" }, "type": "array" }, { "type": "null" } ], "title": "Auth Methods" }, "auth_state": { "anyOf": [ { "maxLength": 64, "type": "string" }, { "type": "null" } ], "title": "Auth State" }, "managed": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Managed" }, "name": { "anyOf": [ { "maxLength": 160, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Name" }, "observation_seq": { "anyOf": [ { "minimum": 1.0, "type": "integer" }, { "type": "null" } ], "title": "Observation Seq" }, "observed_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Observed At" }, "runtime": { "maxLength": 64, "title": "Runtime", "type": "string" }, "version": { "anyOf": [ { "maxLength": 64, "type": "string" }, { "type": "null" } ], "title": "Version" } }, "required": [ "runtime" ], "title": "WorkshopDaemonHarness", "type": "object" }, "WorkshopDaemonInstallResponse": { "description": "Integrity pins for the resident daemon install (TIDY-18237). Public —\nthe artifacts are public and the pins are what make the thin fetcher\nsafe; nothing here is a credential.\n\nTIDY-18239 (S5): resolved per `host_os` / `host_arch` (Linux, macOS,\nWindows); the tuple the pins were resolved for is echoed back so an\ninstaller can refuse a mismatch before it fetches anything.", "properties": { "archive_sha256": { "title": "Archive Sha256", "type": "string" }, "archive_size": { "title": "Archive Size", "type": "integer" }, "archive_url": { "title": "Archive Url", "type": "string" }, "bootstrap_sha256": { "title": "Bootstrap Sha256", "type": "string" }, "bootstrap_size": { "title": "Bootstrap Size", "type": "integer" }, "bootstrap_url": { "title": "Bootstrap Url", "type": "string" }, "host_arch": { "default": "x86_64", "title": "Host Arch", "type": "string" }, "host_os": { "default": "linux", "title": "Host Os", "type": "string" }, "runtime_version": { "title": "Runtime Version", "type": "string" } }, "required": [ "bootstrap_url", "bootstrap_sha256", "bootstrap_size", "archive_url", "archive_sha256", "archive_size", "runtime_version" ], "title": "WorkshopDaemonInstallResponse", "type": "object" }, "WorkshopDeployRequest": { "description": "Deploy (adopt) an assigned employee onto its workshop through the\ndaemon. Mirrors the fields of the old setup-command mint that still matter\nwhen nobody pastes anything. TIDY-19802: a redeploy onto the same\nworkshop revalidates plugin access too; valid unchanged access asks\nnothing.", "properties": { "assign_pending": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Assign Pending" }, "harness_extensions": { "default": "on", "description": "'off' starts the employee with its own harness extensions and packages turned off (only Tidy's own load), for an employee whose harness will not start. Its configuration is untouched; the next deploy without 'off' turns them back on. pi only; the workshop must run connector 1.1.737 or newer.", "enum": [ "on", "off" ], "title": "Harness Extensions", "type": "string" }, "plugin_access": { "anyOf": [ { "items": { "$ref": "#/components/schemas/PluginAccessChoice" }, "maxItems": 16, "type": "array" }, { "type": "null" } ], "title": "Plugin Access" }, "requirements_hash": { "anyOf": [ { "maxLength": 64, "minLength": 64, "type": "string" }, { "type": "null" } ], "title": "Requirements Hash" }, "secret_files": { "anyOf": [ { "items": { "$ref": "#/components/schemas/SecretFileChoice" }, "maxItems": 16, "type": "array" }, { "type": "null" } ], "title": "Secret Files" }, "skill_gives": { "items": { "$ref": "#/components/schemas/SkillGive" }, "maxItems": 64, "title": "Skill Gives", "type": "array" }, "working_directory": { "anyOf": [ { "maxLength": 512, "type": "string" }, { "type": "null" } ], "title": "Working Directory" } }, "title": "WorkshopDeployRequest", "type": "object" }, "WorkshopDeployStatus": { "description": "The ledger plus the push job currently carrying it, if one is open.\nThe ledger is not synced (it is server-owned progress, not a primitive),\nso this is how a surface reads it.", "properties": { "agent_account_id": { "title": "Agent Account Id", "type": "string" }, "approver": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Approver" }, "job": { "anyOf": [ { "$ref": "#/components/schemas/WorkshopPushJob" }, { "type": "null" } ], "default": null }, "steps": { "items": { "$ref": "#/components/schemas/WorkshopDeployStep" }, "title": "Steps", "type": "array" }, "summary": { "additionalProperties": true, "title": "Summary", "type": "object" }, "workshop_id": { "title": "Workshop Id", "type": "string" } }, "required": [ "workshop_id", "agent_account_id", "steps", "summary" ], "title": "WorkshopDeployStatus", "type": "object" }, "WorkshopDeployStep": { "description": "One row of the employee's deploy ledger — the step list the employee\ncard and the workshop's Team tab render (R10).", "properties": { "detail": { "additionalProperties": true, "title": "Detail", "type": "object" }, "last_error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Last Error" }, "status": { "enum": [ "pending", "running", "ready", "error", "unverified" ], "title": "Status", "type": "string" }, "step": { "title": "Step", "type": "string" }, "updated_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Updated At" } }, "required": [ "step", "status" ], "title": "WorkshopDeployStep", "type": "object" }, "WorkshopDeployStepRetry": { "description": "What a step Retry queued: the step's own job, or — for the harness and\nthe adopt — a fresh deploy.", "properties": { "action": { "enum": [ "rerun", "redeploy" ], "title": "Action", "type": "string" }, "job": { "anyOf": [ { "$ref": "#/components/schemas/WorkshopPushJob" }, { "type": "null" } ], "default": null }, "restarts_employee": { "default": false, "title": "Restarts Employee", "type": "boolean" }, "step": { "enum": [ "harness", "credentials", "mcp", "skills", "roots", "health_check" ], "title": "Step", "type": "string" } }, "required": [ "step", "action" ], "title": "WorkshopDeployStepRetry", "type": "object" }, "WorkshopDeployStepRetryRequest": { "description": "Retry one failed deploy step (TIDY-20019 F8). Additive (F11): a Retry\nthat redeploys carries the access reviewed for it, as a deploy does, so\napproving access from a deploy step keeps this Retry's restart gate.", "properties": { "assign_pending": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Assign Pending" }, "plugin_access": { "anyOf": [ { "items": { "$ref": "#/components/schemas/PluginAccessChoice" }, "maxItems": 16, "type": "array" }, { "type": "null" } ], "title": "Plugin Access" }, "requirements_hash": { "anyOf": [ { "maxLength": 64, "minLength": 64, "type": "string" }, { "type": "null" } ], "title": "Requirements Hash" }, "restart": { "anyOf": [ { "enum": [ "if_idle", "anyway" ], "type": "string" }, { "type": "null" } ], "description": "Only for a Retry that redeploys an employee already running on the box, which restarts its harness. Absent, such a Retry refuses 'deploy_retry_restarts_employee' so the surface can say so first; 'if_idle' restarts it unless a turn is in progress ('employee_turn_in_progress'); 'anyway' restarts it and ends that turn.", "title": "Restart" }, "secret_files": { "anyOf": [ { "items": { "$ref": "#/components/schemas/SecretFileChoice" }, "maxItems": 16, "type": "array" }, { "type": "null" } ], "title": "Secret Files" }, "skill_gives": { "items": { "$ref": "#/components/schemas/SkillGive" }, "maxItems": 64, "title": "Skill Gives", "type": "array" } }, "title": "WorkshopDeployStepRetryRequest", "type": "object" }, "WorkshopDetachRequest": { "properties": { "agent_account_id": { "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", "title": "Agent Account Id", "type": "string" } }, "required": [ "agent_account_id" ], "title": "WorkshopDetachRequest", "type": "object" }, "WorkshopDurability": { "description": "TIDY-19309: the one durability answer, derived from `lifecycle` by\n`services/workshop_durability.py` — the words the card shows.", "properties": { "fix": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Fix" }, "runs_as": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Runs As" }, "state": { "enum": [ "durable", "stops_at_logout", "not_durable", "unknown" ], "title": "State", "type": "string" }, "summary": { "title": "Summary", "type": "string" }, "supervisor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Supervisor" }, "supervisor_kind": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Supervisor Kind" }, "verified_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Verified At" } }, "required": [ "state", "summary" ], "title": "WorkshopDurability", "type": "object" }, "WorkshopEmployeeMemoryReading": { "description": "One employee's memory as its workshop's daemon sampled it (TIDY-19932).", "properties": { "agent_account_id": { "maxLength": 64, "title": "Agent Account Id", "type": "string" }, "memory_bytes": { "minimum": 0.0, "title": "Memory Bytes", "type": "integer" }, "memory_limit_bytes": { "anyOf": [ { "minimum": 0.0, "type": "integer" }, { "type": "null" } ], "title": "Memory Limit Bytes" } }, "required": [ "agent_account_id", "memory_bytes" ], "title": "WorkshopEmployeeMemoryReading", "type": "object" }, "WorkshopEmployeeSetupCommandRequest": { "description": "Deploy an ASSIGNED employee onto its workshop's box (TIDY-17341).\n\nThe define journey names a person and no machine, so a portable employee is\ncreated UNBOUND and has no install command. This is where it gets one — and\nthe machine facts come from the WORKSHOP, not from the person: OS and\narchitecture are read off the workshop row, and the only thing the owner\nstill has to say is which project directory on that box the employee works\nin, because no server can know that.\n\nThe OS-conditioned fields mirror the establish journey's defaults\n(linux → glibc/systemd-user, macos → launch-agent) and are overridable for\na box that differs.", "properties": { "host_os_major": { "anyOf": [ { "minimum": 12.0, "type": "integer" }, { "type": "null" } ], "title": "Host Os Major" }, "install_harness_if_missing": { "default": true, "title": "Install Harness If Missing", "type": "boolean" }, "libc": { "anyOf": [ { "enum": [ "glibc", "musl" ], "type": "string" }, { "type": "null" } ], "title": "Libc" }, "libc_min": { "anyOf": [ { "pattern": "^[0-9]+\\.[0-9]+$", "type": "string" }, { "type": "null" } ], "title": "Libc Min" }, "lifecycle": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Lifecycle" }, "working_directory": { "maxLength": 2048, "minLength": 2, "title": "Working Directory", "type": "string" } }, "required": [ "working_directory" ], "title": "WorkshopEmployeeSetupCommandRequest", "type": "object" }, "WorkshopEmployeeSetupCommandResponse": { "properties": { "agent_account_id": { "title": "Agent Account Id", "type": "string" }, "expires_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Expires At" }, "harness": { "title": "Harness", "type": "string" }, "host_arch": { "title": "Host Arch", "type": "string" }, "host_os": { "title": "Host Os", "type": "string" }, "setup_command": { "title": "Setup Command", "type": "string" }, "workshop_id": { "title": "Workshop Id", "type": "string" } }, "required": [ "workshop_id", "agent_account_id", "setup_command", "host_os", "host_arch", "harness" ], "title": "WorkshopEmployeeSetupCommandResponse", "type": "object" }, "WorkshopEnrollRequest": { "properties": { "host_arch": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Host Arch" }, "host_os": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Host Os" }, "machine_anchor": { "anyOf": [ { "pattern": "^[0-9a-f]{64}$", "type": "string" }, { "type": "null" } ], "title": "Machine Anchor" }, "machine_fingerprint": { "minLength": 1, "title": "Machine Fingerprint", "type": "string" } }, "required": [ "machine_fingerprint" ], "title": "WorkshopEnrollRequest", "type": "object" }, "WorkshopEnrollResponse": { "properties": { "browser_install": { "anyOf": [ { "$ref": "#/components/schemas/WorkshopBrowserInstall" }, { "type": "null" } ], "default": null }, "gateway_status": { "enum": [ "unenrolled", "enrolling", "online", "offline", "tombstoned", "revoked" ], "title": "Gateway Status", "type": "string" }, "host_continuity_token": { "title": "Host Continuity Token", "type": "string" }, "host_instance_id": { "title": "Host Instance Id", "type": "string" }, "hosting": { "anyOf": [ { "enum": [ "provisioned", "byo" ], "type": "string" }, { "type": "null" } ], "default": null, "title": "Hosting" }, "install_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Install Id" }, "signing_key_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Signing Key Id" }, "signing_public_key": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Signing Public Key" }, "tenant_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Tenant Id" }, "workshop_id": { "title": "Workshop Id", "type": "string" }, "workshop_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Workshop Name" }, "workshop_pat": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Workshop Pat" } }, "required": [ "workshop_id", "host_instance_id", "host_continuity_token", "gateway_status" ], "title": "WorkshopEnrollResponse", "type": "object" }, "WorkshopEnrollmentAttemptRequest": { "description": "TIDY-18239 (S5): an installer that gave up on the box before (or after)\nthe claim tells Tidy why. Token-bearing like the claim itself — the token\nis resolved, never consumed, so the owner can retry the same command —\nand the Windows-only facts (`execution_policy_blocked`,\n`defender_quarantined`) are what support asks for first.", "properties": { "defender_quarantined": { "default": false, "title": "Defender Quarantined", "type": "boolean" }, "detail": { "additionalProperties": true, "title": "Workshop enrollment attempt detail", "type": "object" }, "enrollment_token": { "minLength": 1, "title": "Enrollment Token", "type": "string" }, "execution_policy_blocked": { "default": false, "title": "Execution Policy Blocked", "type": "boolean" }, "failure_code": { "maxLength": 64, "minLength": 1, "title": "Failure Code", "type": "string" }, "host_arch": { "anyOf": [ { "maxLength": 32, "type": "string" }, { "type": "null" } ], "title": "Host Arch" }, "host_os": { "anyOf": [ { "maxLength": 32, "type": "string" }, { "type": "null" } ], "title": "Host Os" }, "os_edition": { "anyOf": [ { "maxLength": 120, "type": "string" }, { "type": "null" } ], "title": "Os Edition" }, "outcome": { "default": "failed", "enum": [ "failed", "refused" ], "title": "Outcome", "type": "string" } }, "required": [ "enrollment_token", "failure_code" ], "title": "WorkshopEnrollmentAttemptRequest", "type": "object" }, "WorkshopEnrollmentAttemptResponse": { "properties": { "recorded": { "title": "Recorded", "type": "boolean" } }, "required": [ "recorded" ], "title": "WorkshopEnrollmentAttemptResponse", "type": "object" }, "WorkshopEnrollmentBindingRequest": { "description": "TIDY-19557: which workshop, in which workspace, a setup command was\nminted for. Token-bearing like the claim; the token is resolved, never\nconsumed.", "properties": { "enrollment_token": { "minLength": 1, "title": "Enrollment Token", "type": "string" } }, "required": [ "enrollment_token" ], "title": "WorkshopEnrollmentBindingRequest", "type": "object" }, "WorkshopEnrollmentBindingResponse": { "properties": { "tenant_id": { "title": "Tenant Id", "type": "string" }, "workshop_id": { "title": "Workshop Id", "type": "string" } }, "required": [ "workshop_id", "tenant_id" ], "title": "WorkshopEnrollmentBindingResponse", "type": "object" }, "WorkshopEnrollmentNote": { "description": "The pinned note that says \"here is the machine you just added\". A\nfailure is reported, never swallowed: the installer prints it.", "properties": { "detail": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Detail" }, "note_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Note Id" }, "status": { "enum": [ "recorded", "failed" ], "title": "Status", "type": "string" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Title" } }, "required": [ "status" ], "title": "WorkshopEnrollmentNote", "type": "object" }, "WorkshopFileWriteRequest": { "description": "A file edited in Tidy, saved over the version the editor loaded.\n\n`expected_sha256` is that version's whole-file hash (`fs.read`'s\n`snapshot_hash`): the workshop refuses the save with `file_changed` when\nthe file on disk no longer hashes to it (TIDY-19604 F3).", "properties": { "content": { "maxLength": 1048576, "title": "Content", "type": "string" }, "expected_sha256": { "pattern": "^[a-f0-9]{64}$", "title": "Expected Sha256", "type": "string" }, "path": { "maxLength": 4096, "minLength": 1, "title": "Path", "type": "string" } }, "required": [ "path", "content", "expected_sha256" ], "title": "WorkshopFileWriteRequest", "type": "object" }, "WorkshopFileWriteResponse": { "description": "What the workshop read back after the save: the editor's next base.", "properties": { "mode": { "title": "Mode", "type": "string" }, "path": { "title": "Path", "type": "string" }, "sha256": { "title": "Sha256", "type": "string" }, "size": { "title": "Size", "type": "integer" } }, "required": [ "sha256", "size", "mode", "path" ], "title": "WorkshopFileWriteResponse", "type": "object" }, "WorkshopGatewayClaimRequest": { "description": "Redeemed BY the machine, from inside the setup command.", "properties": { "enrollment_token": { "minLength": 1, "title": "Enrollment Token", "type": "string" }, "host_arch": { "title": "Host Arch", "type": "string" }, "host_attestation_public_key": { "anyOf": [ { "pattern": "^[A-Za-z0-9+/]{43}=$", "type": "string" }, { "type": "null" } ], "title": "Host Attestation Public Key" }, "host_firewall_mode": { "anyOf": [ { "enum": [ "provisioned", "byo" ], "type": "string" }, { "type": "null" } ], "title": "Host Firewall Mode" }, "host_os": { "title": "Host Os", "type": "string" }, "machine_anchor": { "anyOf": [ { "pattern": "^[0-9a-f]{64}$", "type": "string" }, { "type": "null" } ], "title": "Machine Anchor" }, "machine_fingerprint": { "minLength": 1, "title": "Machine Fingerprint", "type": "string" }, "os_edition": { "anyOf": [ { "maxLength": 120, "type": "string" }, { "type": "null" } ], "title": "Os Edition" } }, "required": [ "enrollment_token", "machine_fingerprint", "host_os", "host_arch" ], "title": "WorkshopGatewayClaimRequest", "type": "object" }, "WorkshopGatewayLifecycleRequest": { "description": "The installer's last step (TIDY-18037). Continuity-token authenticated,\nlike the heartbeat: the box holds no Tidy session.", "properties": { "base_url": { "maxLength": 500, "minLength": 1, "title": "Base Url", "type": "string" }, "host_continuity_token": { "minLength": 1, "title": "Host Continuity Token", "type": "string" }, "host_instance_id": { "minLength": 1, "title": "Host Instance Id", "type": "string" }, "hostname": { "maxLength": 255, "minLength": 1, "title": "Hostname", "type": "string" }, "lifecycle": { "$ref": "#/components/schemas/WorkshopLifecycle" }, "machine_anchor": { "anyOf": [ { "pattern": "^[0-9a-f]{64}$", "type": "string" }, { "type": "null" } ], "title": "Machine Anchor" }, "machine_fingerprint": { "anyOf": [ { "maxLength": 255, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Machine Fingerprint" }, "runtime_version": { "maxLength": 64, "minLength": 1, "title": "Runtime Version", "type": "string" }, "uninstalled": { "default": false, "title": "Uninstalled", "type": "boolean" }, "update_error": { "anyOf": [ { "maxLength": 1000, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Update Error" } }, "required": [ "host_instance_id", "host_continuity_token", "lifecycle", "base_url", "hostname", "runtime_version" ], "title": "WorkshopGatewayLifecycleRequest", "type": "object" }, "WorkshopGatewayLifecycleResponse": { "properties": { "durable": { "title": "Durable", "type": "boolean" }, "hosting": { "anyOf": [ { "enum": [ "provisioned", "byo" ], "type": "string" }, { "type": "null" } ], "default": null, "title": "Hosting" }, "note": { "$ref": "#/components/schemas/WorkshopEnrollmentNote" }, "workshop_name": { "title": "Workshop Name", "type": "string" } }, "required": [ "workshop_name", "durable", "note" ], "title": "WorkshopGatewayLifecycleResponse", "type": "object" }, "WorkshopHarnessCatalogEntry": { "description": "TIDY-19931 (F7, Platform Fit E) — one harness a workshop can be given:\na built-in Tidy drives on its own adapter, or an agent of the ACP registry\nwith a build for its platform.", "properties": { "description": { "default": "", "title": "Description", "type": "string" }, "distribution": { "anyOf": [ { "enum": [ "binary", "npx", "uvx" ], "type": "string" }, { "type": "null" } ], "default": null, "title": "Distribution" }, "icon": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Icon" }, "installable": { "title": "Installable", "type": "boolean" }, "installed": { "default": false, "title": "Installed", "type": "boolean" }, "installed_version": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Installed Version" }, "managed": { "default": false, "title": "Managed", "type": "boolean" }, "name": { "title": "Name", "type": "string" }, "runtime": { "title": "Runtime", "type": "string" }, "source": { "enum": [ "built_in", "acp_registry" ], "title": "Source", "type": "string" }, "unavailable_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Unavailable Reason" }, "update_available": { "default": false, "title": "Update Available", "type": "boolean" }, "version": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Version" }, "website": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Website" } }, "required": [ "runtime", "name", "source", "installable" ], "title": "WorkshopHarnessCatalogEntry", "type": "object" }, "WorkshopHarnessCatalogResponse": { "description": "TIDY-19931 (F7, Platform Fit E) — every harness this workshop can be\ngiven, built-in and registry, through one path: installed first, then\ninstallable, built-ins before registry agents, each by name.", "properties": { "fetched_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Fetched At" }, "harnesses": { "items": { "$ref": "#/components/schemas/WorkshopHarnessCatalogEntry" }, "title": "Harnesses", "type": "array" }, "platform": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Platform" }, "registry_unavailable": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Registry Unavailable" }, "stale": { "default": false, "title": "Stale", "type": "boolean" } }, "title": "WorkshopHarnessCatalogResponse", "type": "object" }, "WorkshopHarnessHoldersResponse": { "description": "Who still resolves to this runtime on this box (TIDY-18788).", "properties": { "holders": { "items": { "$ref": "#/components/schemas/HarnessHolder" }, "title": "Holders", "type": "array" }, "removal_pending": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Removal Pending" } }, "title": "WorkshopHarnessHoldersResponse", "type": "object" }, "WorkshopHarnessProcesses": { "description": "TIDY-19933 (F9) — one employee's harness processes, as its last heartbeat said.\n\n`budget` is the owner's Parallel sessions setting; `running` (turns now),\n`holding` (processes kept for background work) and `warm` (kept for a next\nturn) count the conversations taking it. Warm ones never pass the budget;\na person's turn always runs, so the others can.", "properties": { "budget": { "title": "Budget", "type": "integer" }, "holding": { "title": "Holding", "type": "integer" }, "running": { "title": "Running", "type": "integer" }, "warm": { "title": "Warm", "type": "integer" } }, "required": [ "budget", "running", "holding", "warm" ], "title": "WorkshopHarnessProcesses", "type": "object" }, "WorkshopHeartbeatRequest": { "properties": { "boot_id": { "anyOf": [ { "maxLength": 64, "type": "string" }, { "type": "null" } ], "title": "Boot Id" }, "capability_report": { "anyOf": [ { "$ref": "#/components/schemas/WorkshopCapabilityReport" }, { "type": "null" } ] }, "daemon_version": { "anyOf": [ { "maxLength": 64, "type": "string" }, { "type": "null" } ], "title": "Daemon Version" }, "employees": { "items": { "$ref": "#/components/schemas/WorkshopDaemonEmployee" }, "title": "Employees", "type": "array" }, "harnesses": { "items": { "$ref": "#/components/schemas/WorkshopDaemonHarness" }, "title": "Harnesses", "type": "array" }, "host_continuity_token": { "title": "Host Continuity Token", "type": "string" }, "host_instance_id": { "title": "Host Instance Id", "type": "string" }, "hosting_preflight": { "default": false, "title": "Hosting Preflight", "type": "boolean" }, "hostname": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "title": "Hostname" }, "lifecycle": { "anyOf": [ { "$ref": "#/components/schemas/WorkshopLifecycle" }, { "$ref": "#/components/schemas/WorkshopLifecycleUnknown" }, { "type": "null" } ], "title": "Lifecycle" }, "machine_anchor": { "anyOf": [ { "pattern": "^[0-9a-f]{64}$", "type": "string" }, { "type": "null" } ], "title": "Machine Anchor" }, "machine_fingerprint": { "anyOf": [ { "maxLength": 255, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Machine Fingerprint" }, "memory": { "anyOf": [ { "$ref": "#/components/schemas/WorkshopMemoryReport" }, { "type": "null" } ] }, "mounts": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "maxItems": 64, "type": "array" }, { "type": "null" } ], "title": "Mounts" }, "paused": { "default": false, "title": "Paused", "type": "boolean" }, "signing_key_id": { "anyOf": [ { "maxLength": 64, "type": "string" }, { "type": "null" } ], "title": "Signing Key Id" } }, "required": [ "host_instance_id", "host_continuity_token" ], "title": "WorkshopHeartbeatRequest", "type": "object" }, "WorkshopHeartbeatResponse": { "properties": { "accepts_browser_runtime": { "default": true, "title": "Accepts Browser Runtime", "type": "boolean" }, "accepts_gh": { "default": true, "title": "Accepts Gh", "type": "boolean" }, "accepts_memory": { "default": true, "title": "Accepts Memory", "type": "boolean" }, "cleanup_token": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Cleanup Token" }, "employee_elevation": { "anyOf": [ { "additionalProperties": { "type": "boolean" }, "type": "object" }, { "type": "null" } ], "default": null, "title": "Employee Elevation" }, "employee_memory_ceiling_bytes": { "anyOf": [ { "additionalProperties": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "type": "object" }, { "type": "null" } ], "default": null, "title": "Employee Memory Ceiling Bytes" }, "gateway_status": { "enum": [ "unenrolled", "enrolling", "online", "offline", "tombstoned", "revoked" ], "title": "Gateway Status", "type": "string" }, "hosting": { "anyOf": [ { "enum": [ "provisioned", "byo" ], "type": "string" }, { "type": "null" } ], "default": null, "title": "Hosting" }, "paused": { "default": false, "title": "Paused", "type": "boolean" }, "pending_jobs": { "default": 0, "title": "Pending Jobs", "type": "integer" }, "revoked": { "default": false, "title": "Revoked", "type": "boolean" }, "tenant_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Tenant Id" } }, "required": [ "gateway_status" ], "title": "WorkshopHeartbeatResponse", "type": "object" }, "WorkshopInstallPolicyAuthority": { "description": "The box approver's authority, not a workspace-role guess (TIDY-19770).", "properties": { "approver_name": { "title": "Approver Name", "type": "string" }, "may_approve": { "title": "May Approve", "type": "boolean" }, "may_request": { "title": "May Request", "type": "boolean" } }, "required": [ "may_approve", "may_request", "approver_name" ], "title": "WorkshopInstallPolicyAuthority", "type": "object" }, "WorkshopLifecycle": { "description": "TIDY-18037: whether the workshop outlives the login that installed it,\nas MEASURED by the installer after it started the daemon — never asserted.\n\nThe daemon runs under the OS's own boot-time supervisor (a systemd system\nunit, a launchd LaunchDaemon, a Windows service), so no human session and\nno linger is involved. `durable` is true only when that supervisor is\nenabled at boot AND the daemon came up and stayed up; the installer exits\nnon-zero instead of reporting anything else.", "properties": { "durable": { "title": "Durable", "type": "boolean" }, "enabled_at_boot": { "title": "Enabled At Boot", "type": "boolean" }, "identity_path": { "maxLength": 500, "minLength": 1, "title": "Identity Path", "type": "string" }, "linger": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Linger" }, "running": { "title": "Running", "type": "boolean" }, "runs_as": { "maxLength": 200, "minLength": 1, "title": "Runs As", "type": "string" }, "supervisor": { "maxLength": 200, "minLength": 1, "title": "Supervisor", "type": "string" }, "supervisor_kind": { "enum": [ "systemd_system", "launchd_daemon", "windows_service", "systemd_user", "login_session" ], "title": "Supervisor Kind", "type": "string" }, "verified_at": { "format": "date-time", "title": "Verified At", "type": "string" } }, "required": [ "supervisor_kind", "supervisor", "runs_as", "identity_path", "enabled_at_boot", "running", "durable", "verified_at" ], "title": "WorkshopLifecycle", "type": "object" }, "WorkshopLifecycleUnknown": { "description": "TIDY-19309: the daemon measured and could NOT name what supervises it\n(its cgroup is not a systemd unit, or systemd did not answer). Sent instead\nof silence so a box once measured durable stops being shown durable on the\ninstaller's old word. Never durable; the installer never reports it.", "properties": { "durable": { "const": false, "default": false, "title": "Durable", "type": "boolean" }, "reason": { "maxLength": 500, "minLength": 1, "title": "Reason", "type": "string" }, "running": { "const": true, "default": true, "title": "Running", "type": "boolean" }, "supervisor_kind": { "const": "unknown", "title": "Supervisor Kind", "type": "string" }, "verified_at": { "format": "date-time", "title": "Verified At", "type": "string" } }, "required": [ "supervisor_kind", "reason", "verified_at" ], "title": "WorkshopLifecycleUnknown", "type": "object" }, "WorkshopListResponse": { "properties": { "workshops": { "items": { "$ref": "#/components/schemas/WorkshopResponse" }, "title": "Workshops", "type": "array" } }, "required": [ "workshops" ], "title": "WorkshopListResponse", "type": "object" }, "WorkshopMemoryEnforcement": { "description": "Whether this box holds its employees to ceilings, and if not, why.", "properties": { "employees_high_bytes": { "anyOf": [ { "minimum": 0.0, "type": "integer" }, { "type": "null" } ], "title": "Employees High Bytes" }, "employees_max_bytes": { "anyOf": [ { "minimum": 0.0, "type": "integer" }, { "type": "null" } ], "title": "Employees Max Bytes" }, "reason": { "anyOf": [ { "maxLength": 500, "type": "string" }, { "type": "null" } ], "title": "Reason" }, "status": { "enum": [ "enforced", "unenforced" ], "title": "Status", "type": "string" } }, "required": [ "status" ], "title": "WorkshopMemoryEnforcement", "type": "object" }, "WorkshopMemoryPressure": { "properties": { "detail": { "anyOf": [ { "maxLength": 300, "type": "string" }, { "type": "null" } ], "title": "Detail" }, "reason": { "anyOf": [ { "enum": [ "employees_at_limit", "host_memory_low" ], "type": "string" }, { "type": "null" } ], "title": "Reason" }, "state": { "enum": [ "ok", "pressure" ], "title": "State", "type": "string" } }, "required": [ "state" ], "title": "WorkshopMemoryPressure", "type": "object" }, "WorkshopMemoryReport": { "description": "TIDY-19932 (F8) — the box's memory for its beat: what the ceilings were\nderived from, whether they are enforced, pressure (None where it is not\nmeasured on that OS), and each running employee's reading.", "properties": { "available_bytes": { "anyOf": [ { "minimum": 0.0, "type": "integer" }, { "type": "null" } ], "title": "Available Bytes" }, "employees": { "items": { "$ref": "#/components/schemas/WorkshopEmployeeMemoryReading" }, "maxItems": 64, "title": "Employees", "type": "array" }, "enforcement": { "$ref": "#/components/schemas/WorkshopMemoryEnforcement" }, "pressure": { "anyOf": [ { "$ref": "#/components/schemas/WorkshopMemoryPressure" }, { "type": "null" } ] }, "total_bytes": { "minimum": 0.0, "title": "Total Bytes", "type": "integer" } }, "required": [ "total_bytes", "enforcement" ], "title": "WorkshopMemoryReport", "type": "object" }, "WorkshopMemoryState": { "description": "TIDY-19932 (F8) — the workshop's memory as its daemon last reported it.", "properties": { "available_bytes": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Available Bytes" }, "employees_high_bytes": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Employees High Bytes" }, "employees_max_bytes": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Employees Max Bytes" }, "enforced": { "title": "Enforced", "type": "boolean" }, "pressure": { "anyOf": [ { "enum": [ "ok", "pressure" ], "type": "string" }, { "type": "null" } ], "default": null, "title": "Pressure" }, "pressure_detail": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Pressure Detail" }, "total_bytes": { "title": "Total Bytes", "type": "integer" }, "unenforced_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Unenforced Reason" } }, "required": [ "total_bytes", "enforced" ], "title": "WorkshopMemoryState", "type": "object" }, "WorkshopMountBrowseRequest": { "description": "Browse one directory on a reported mount.\n\n``path`` is RELATIVE to the mount point (``\"\"`` or ``\"/\"`` = the root). The\nserver canonicalizes it before signing; a path that would resolve outside\nthe mount is refused at the boundary, never signed.", "properties": { "path": { "default": "", "maxLength": 1024, "title": "Path", "type": "string" } }, "title": "WorkshopMountBrowseRequest", "type": "object" }, "WorkshopMountBrowseResponse": { "description": "The answer to a browse request.\n\n``state`` mirrors the job's own vocabulary: ``succeeded`` carries\n``entries``; ``queued`` means the workshop was not reachable when the wait\nexpired (the mount list from the last beat still stands); ``refused`` /\n``failed`` carry the box's own ``error`` — a box on an older runtime\nrefuses with ``unsupported`` and the UI says the box is about to learn\nthis, not that the member did something wrong.", "properties": { "entries": { "items": { "$ref": "#/components/schemas/WorkshopMountEntry" }, "title": "Entries", "type": "array" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Error" }, "job_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Job Id" }, "mount_id": { "title": "Mount Id", "type": "string" }, "path": { "title": "Path", "type": "string" }, "refusal_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Refusal Code" }, "state": { "title": "State", "type": "string" }, "truncated": { "default": false, "title": "Truncated", "type": "boolean" }, "workshop_id": { "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", "title": "Workshop Id", "type": "string" } }, "required": [ "workshop_id", "mount_id", "path", "state" ], "title": "WorkshopMountBrowseResponse", "type": "object" }, "WorkshopMountEntry": { "description": "One entry of a `fs.browse` listing, as the box saw it.", "properties": { "kind": { "enum": [ "file", "dir", "symlink" ], "title": "Kind", "type": "string" }, "mtime": { "format": "date-time", "title": "Mtime", "type": "string" }, "name": { "title": "Name", "type": "string" }, "size": { "minimum": 0, "title": "Size", "type": "integer" } }, "required": [ "name", "kind", "size", "mtime" ], "title": "WorkshopMountEntry", "type": "object" }, "WorkshopMountFact": { "description": "One mounted volume as the box reports it in its beat.\n\nSizes are the daemon's `statfs` numbers in BYTES; a mount whose stats the\nbox could not read omits them rather than claiming zero. `id` is the first\n12 hex chars of `sha256(kind + \"\\u0000\" + mount_point)` — stable per mount,\nURL-safe (the mount point may contain `/`), and what `fs.browse` names,\nso the UI never types a path the box would have to guess.", "properties": { "free_bytes": { "anyOf": [ { "minimum": 0, "type": "integer" }, { "type": "null" } ], "default": null, "title": "Free Bytes" }, "id": { "maxLength": 512, "minLength": 1, "title": "Id", "type": "string" }, "kind": { "maxLength": 64, "minLength": 1, "title": "Kind", "type": "string" }, "mount_point": { "maxLength": 512, "minLength": 1, "title": "Mount Point", "type": "string" }, "name": { "maxLength": 256, "minLength": 1, "title": "Name", "type": "string" }, "removable": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "title": "Removable" }, "size_bytes": { "anyOf": [ { "minimum": 0, "type": "integer" }, { "type": "null" } ], "default": null, "title": "Size Bytes" } }, "required": [ "id", "name", "kind", "mount_point" ], "title": "WorkshopMountFact", "type": "object" }, "WorkshopMountMkdirRequest": { "description": "Create a folder on a reported mount.\n\n``path`` is RELATIVE to the mount point, the same boundary as a browse:\nthe server canonicalizes it before signing, and the box re-checks it\nagainst its real filesystem. A name the sensitive list withholds is\nrefused on the box, never created.", "properties": { "path": { "maxLength": 1024, "minLength": 1, "title": "Path", "type": "string" } }, "required": [ "path" ], "title": "WorkshopMountMkdirRequest", "type": "object" }, "WorkshopMountMkdirResponse": { "description": "The answer to a folder creation: the directory, absolute on the box.", "properties": { "mount_id": { "title": "Mount Id", "type": "string" }, "path": { "title": "Path", "type": "string" }, "state": { "title": "State", "type": "string" }, "workshop_id": { "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", "title": "Workshop Id", "type": "string" } }, "required": [ "workshop_id", "mount_id", "path", "state" ], "title": "WorkshopMountMkdirResponse", "type": "object" }, "WorkshopMountShareCreateRequest": { "description": "Share one folder on a reported mount to one or more VEs at a role.\n\n``path`` is RELATIVE to the mount point (``\"\"`` = the mount root) — the\nserver canonicalizes it to the absolute prefix the grant reaches, the same\nboundary a browse signs under. ``employee_account_ids`` are the VEs the\ngrant authorizes; each must be on this workshop's roster. ``role`` is a\ncapability: ``read`` is a scoped read, ``read_write`` a scoped read + write.", "properties": { "employee_account_ids": { "items": { "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", "type": "string" }, "maxItems": 64, "minItems": 1, "title": "Employee Account Ids", "type": "array" }, "path": { "default": "", "maxLength": 1024, "title": "Path", "type": "string" }, "role": { "enum": [ "read", "read_write" ], "title": "Role", "type": "string" } }, "required": [ "role", "employee_account_ids" ], "title": "WorkshopMountShareCreateRequest", "type": "object" }, "WorkshopMountShareCreateResponse": { "description": "The grants the create minted — one row per (VE, role), newest first.", "properties": { "mount_id": { "title": "Mount Id", "type": "string" }, "shares": { "items": { "$ref": "#/components/schemas/WorkshopMountShareRecord" }, "title": "Shares", "type": "array" }, "state": { "title": "State", "type": "string" }, "workshop_id": { "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", "title": "Workshop Id", "type": "string" } }, "required": [ "workshop_id", "mount_id", "shares", "state" ], "title": "WorkshopMountShareCreateResponse", "type": "object" }, "WorkshopMountShareRecord": { "description": "One live grant, as the member sees it: what, to whom, at which role.", "properties": { "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "created_by": { "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", "title": "Created By", "type": "string" }, "employee_account_id": { "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", "title": "Employee Account Id", "type": "string" }, "employee_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Employee Name" }, "id": { "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", "title": "Id", "type": "string" }, "mount_id": { "title": "Mount Id", "type": "string" }, "path": { "title": "Path", "type": "string" }, "revoked_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Revoked At" }, "role": { "enum": [ "read", "read_write" ], "title": "Role", "type": "string" } }, "required": [ "id", "mount_id", "path", "role", "employee_account_id", "created_by", "created_at" ], "title": "WorkshopMountShareRecord", "type": "object" }, "WorkshopMountShareRevokeResponse": { "description": "The grant the revoke removed: its id echoed, its revocation stamped.", "properties": { "mount_id": { "title": "Mount Id", "type": "string" }, "share_id": { "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", "title": "Share Id", "type": "string" }, "state": { "title": "State", "type": "string" }, "workshop_id": { "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", "title": "Workshop Id", "type": "string" } }, "required": [ "workshop_id", "mount_id", "share_id", "state" ], "title": "WorkshopMountShareRevokeResponse", "type": "object" }, "WorkshopMountSharesListResponse": { "description": "The live grants on a mount, newest first (revoked ones are gone).", "properties": { "mount_id": { "title": "Mount Id", "type": "string" }, "shares": { "items": { "$ref": "#/components/schemas/WorkshopMountShareRecord" }, "title": "Shares", "type": "array" }, "workshop_id": { "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", "title": "Workshop Id", "type": "string" } }, "required": [ "workshop_id", "mount_id" ], "title": "WorkshopMountSharesListResponse", "type": "object" }, "WorkshopMountUploadBeginRequest": { "description": "Begin a save session: the file's ``path`` (relative to the mount)\nand its full ``size`` in bytes. The server works out the slice schedule\nfrom the size; the box opens the temp file the slices will fill.", "properties": { "path": { "maxLength": 1024, "minLength": 1, "title": "Path", "type": "string" }, "size": { "minimum": 0.0, "title": "Size", "type": "integer" } }, "required": [ "path", "size" ], "title": "WorkshopMountUploadBeginRequest", "type": "object" }, "WorkshopMountUploadBeginResponse": { "description": "The session's token and the slice schedule the uploader must follow.", "properties": { "chunk_size": { "title": "Chunk Size", "type": "integer" }, "mount_id": { "title": "Mount Id", "type": "string" }, "state": { "title": "State", "type": "string" }, "total_chunks": { "title": "Total Chunks", "type": "integer" }, "upload_id": { "title": "Upload Id", "type": "string" }, "workshop_id": { "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", "title": "Workshop Id", "type": "string" } }, "required": [ "workshop_id", "mount_id", "upload_id", "chunk_size", "total_chunks", "state" ], "title": "WorkshopMountUploadBeginResponse", "type": "object" }, "WorkshopMountUploadChunkRequest": { "description": "One slice of the session: its index ``seq`` (0-based), the file's\n``size`` re-declared so the slice's exact length is checkable, and the\nslice's bytes base64-encoded. The server seals the slice to the box's\nper-boot key and signs its digest into the frame.", "properties": { "content": { "title": "Content", "type": "string" }, "path": { "maxLength": 1024, "minLength": 1, "title": "Path", "type": "string" }, "seq": { "minimum": 0.0, "title": "Seq", "type": "integer" }, "size": { "minimum": 0.0, "title": "Size", "type": "integer" } }, "required": [ "path", "size", "seq", "content" ], "title": "WorkshopMountUploadChunkRequest", "type": "object" }, "WorkshopMountUploadChunkResponse": { "description": "How many bytes the box holds for the session now.", "properties": { "mount_id": { "title": "Mount Id", "type": "string" }, "state": { "title": "State", "type": "string" }, "upload_id": { "title": "Upload Id", "type": "string" }, "workshop_id": { "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", "title": "Workshop Id", "type": "string" }, "written": { "minimum": 0, "title": "Written", "type": "integer" } }, "required": [ "workshop_id", "mount_id", "upload_id", "written", "state" ], "title": "WorkshopMountUploadChunkResponse", "type": "object" }, "WorkshopMountUploadCommitRequest": { "description": "Commit the session: the file's ``path`` and ``size`` re-declared. The\nbox checks its own size, reports the hash it read back, and renames the\ntemp onto the final path atomically.", "properties": { "path": { "maxLength": 1024, "minLength": 1, "title": "Path", "type": "string" }, "size": { "minimum": 0.0, "title": "Size", "type": "integer" } }, "required": [ "path", "size" ], "title": "WorkshopMountUploadCommitRequest", "type": "object" }, "WorkshopMountUploadCommitResponse": { "description": "What the box read back after the rename.", "properties": { "mode": { "title": "Mode", "type": "string" }, "mount_id": { "title": "Mount Id", "type": "string" }, "path": { "title": "Path", "type": "string" }, "sha256": { "title": "Sha256", "type": "string" }, "size": { "minimum": 0, "title": "Size", "type": "integer" }, "state": { "title": "State", "type": "string" }, "upload_id": { "title": "Upload Id", "type": "string" }, "workshop_id": { "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", "title": "Workshop Id", "type": "string" } }, "required": [ "workshop_id", "mount_id", "upload_id", "sha256", "size", "mode", "path", "state" ], "title": "WorkshopMountUploadCommitResponse", "type": "object" }, "WorkshopMountsListItem": { "description": "One member-visible workshop and its mounted volumes.\n\n``mounts`` is the box's LAST report, mirrored onto the facet record: ``None``\nmeans the box has not reported a reading yet (older runtime, or no beat\nsince this server shipped) — the UI says \"not reported\" and does not\nfabricate an empty list. ``gateway_status`` is the machine's own\nliveness: a browse against an ``offline``/``revoked``/``unenrolled``\nworkshop will not answer until it beats back, so the UI says so instead\nof spinning.", "properties": { "gateway_status": { "enum": [ "unenrolled", "enrolling", "online", "offline", "tombstoned", "revoked" ], "title": "Gateway Status", "type": "string" }, "gateway_status_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Gateway Status At" }, "id": { "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", "title": "Id", "type": "string" }, "mounts": { "anyOf": [ { "items": { "$ref": "#/components/schemas/WorkshopMountFact" }, "type": "array" }, { "type": "null" } ], "default": null, "title": "Mounts" }, "name": { "title": "Name", "type": "string" } }, "required": [ "id", "name", "gateway_status" ], "title": "WorkshopMountsListItem", "type": "object" }, "WorkshopMountsListResponse": { "properties": { "workshops": { "items": { "$ref": "#/components/schemas/WorkshopMountsListItem" }, "title": "Workshops", "type": "array" } }, "required": [ "workshops" ], "title": "WorkshopMountsListResponse", "type": "object" }, "WorkshopMoveListResponse": { "properties": { "moves": { "items": { "$ref": "#/components/schemas/WorkshopMoveRecord" }, "title": "Moves", "type": "array" } }, "required": [ "moves" ], "title": "WorkshopMoveListResponse", "type": "object" }, "WorkshopMoveRecord": { "properties": { "agent_account_id": { "title": "Agent Account Id", "type": "string" }, "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "display_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Display Name" }, "failed_step": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Failed Step" }, "from_kind": { "default": "workshop", "enum": [ "workshop", "hosted" ], "title": "From Kind", "type": "string" }, "from_workshop_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "From Workshop Id" }, "id": { "title": "Id", "type": "string" }, "last_error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Last Error" }, "left_work_behind": { "title": "Left Work Behind", "type": "boolean" }, "redeploy_batch_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Redeploy Batch Id" }, "settle_mode": { "title": "Settle Mode", "type": "string" }, "state": { "title": "State", "type": "string" }, "target_kind": { "default": "workshop", "enum": [ "workshop", "hosted" ], "title": "Target Kind", "type": "string" }, "to_workshop_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "To Workshop Id" }, "updated_at": { "format": "date-time", "title": "Updated At", "type": "string" } }, "required": [ "id", "agent_account_id", "state", "settle_mode", "left_work_behind", "created_at", "updated_at" ], "title": "WorkshopMoveRecord", "type": "object" }, "WorkshopMoveRequest": { "description": "TIDY-19802: the target's plugin access is approved with the move.", "properties": { "agent_account_id": { "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", "title": "Agent Account Id", "type": "string" }, "assign_pending": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Assign Pending" }, "force": { "default": false, "title": "Force", "type": "boolean" }, "plugin_access": { "anyOf": [ { "items": { "$ref": "#/components/schemas/PluginAccessChoice" }, "maxItems": 16, "type": "array" }, { "type": "null" } ], "title": "Plugin Access" }, "requirements_hash": { "anyOf": [ { "maxLength": 64, "minLength": 64, "type": "string" }, { "type": "null" } ], "title": "Requirements Hash" }, "secret_files": { "anyOf": [ { "items": { "$ref": "#/components/schemas/SecretFileChoice" }, "maxItems": 16, "type": "array" }, { "type": "null" } ], "title": "Secret Files" }, "skill_gives": { "items": { "$ref": "#/components/schemas/SkillGive" }, "maxItems": 64, "title": "Skill Gives", "type": "array" } }, "required": [ "agent_account_id" ], "title": "WorkshopMoveRequest", "type": "object" }, "WorkshopMoveResponse": { "properties": { "agent_account_id": { "title": "Agent Account Id", "type": "string" }, "display_name": { "title": "Display Name", "type": "string" }, "failed_step": { "anyOf": [ { "enum": [ "harness", "credentials", "mcp", "skills", "roots", "health_check" ], "type": "string" }, { "type": "null" } ], "default": null, "title": "Failed Step" }, "from_workshop_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "From Workshop Id" }, "from_workshop_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "From Workshop Name" }, "host_rebind_token": { "title": "Host Rebind Token", "type": "string" }, "left_work_behind": { "default": false, "title": "Left Work Behind", "type": "boolean" }, "materialization": { "$ref": "#/components/schemas/MaterializationSummary" }, "move_id": { "title": "Move Id", "type": "string" }, "plugin_access": { "items": { "$ref": "#/components/schemas/AppliedPluginAccess" }, "title": "Plugin Access", "type": "array" }, "push_job_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Push Job Id" }, "push_job_state": { "anyOf": [ { "enum": [ "awaiting_approval", "queued", "dispatched", "running", "succeeded", "failed", "cancelled", "refused" ], "type": "string" }, { "type": "null" } ], "default": null, "title": "Push Job State" }, "rebind_receipt_id": { "title": "Rebind Receipt Id", "type": "string" }, "state": { "enum": [ "settling", "detaching", "enrolling", "materializing", "active", "failed" ], "title": "State", "type": "string" }, "to_workshop_id": { "title": "To Workshop Id", "type": "string" }, "to_workshop_name": { "title": "To Workshop Name", "type": "string" }, "unsettled_conversations": { "items": { "$ref": "#/components/schemas/UnsettledConversation" }, "title": "Unsettled Conversations", "type": "array" } }, "required": [ "move_id", "agent_account_id", "display_name", "to_workshop_id", "to_workshop_name", "state", "materialization", "rebind_receipt_id", "host_rebind_token" ], "title": "WorkshopMoveResponse", "type": "object" }, "WorkshopPolicyResponse": { "description": "TIDY-19557: the turn-time policy the connector reads for its own workshop.\n`allow_docker` arms the connector's filtering Docker proxy; false (the\ndefault, and for an employee on Tidy compute) keeps Docker refused.", "properties": { "allow_docker": { "default": false, "title": "Allow Docker", "type": "boolean" } }, "title": "WorkshopPolicyResponse", "type": "object" }, "WorkshopProviderCatalog": { "properties": { "connect": { "default": [], "items": { "$ref": "#/components/schemas/ProviderConnectOption" }, "title": "Connect", "type": "array" }, "providers": { "items": { "enum": [ "digitalocean", "hetzner", "lightsail", "ovh" ], "type": "string" }, "title": "Providers", "type": "array" } }, "required": [ "providers" ], "title": "WorkshopProviderCatalog", "type": "object" }, "WorkshopPushJob": { "properties": { "agent_account_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Agent Account Id" }, "approved_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Approved At" }, "approved_by": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Approved By" }, "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "daemon_boot_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Daemon Boot Id" }, "depends_on_job_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Depends On Job Id" }, "dispatched_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Dispatched At" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Error" }, "finished_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Finished At" }, "id": { "title": "Id", "type": "string" }, "kind": { "enum": [ "employee.adopt", "employee.retire", "harness.ensure", "tool.install", "root.ensure", "root.inspect", "root.expose", "root.detach", "browser.install", "workshop.uninstall", "mcp.materialize", "skills.materialize", "health.check", "keys.ship", "keys.revoke", "snapshot.export", "harness.remove", "workshop.update", "host.setup", "docker.elevation_revoke", "host.devices", "fs.browse", "file.transfer" ], "title": "Kind", "type": "string" }, "manifest": { "additionalProperties": true, "title": "Manifest", "type": "object" }, "manifest_digest": { "title": "Manifest Digest", "type": "string" }, "policy_outcome": { "anyOf": [ { "enum": [ "automatic", "approved", "denied" ], "type": "string" }, { "type": "null" } ], "default": null, "title": "Policy Outcome" }, "progress": { "items": { "$ref": "#/components/schemas/PushJobProgress" }, "title": "Progress", "type": "array" }, "refusal_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Refusal Code" }, "requested_by": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Requested By" }, "signature": { "title": "Signature", "type": "string" }, "signing_key_id": { "title": "Signing Key Id", "type": "string" }, "state": { "enum": [ "awaiting_approval", "queued", "dispatched", "running", "succeeded", "failed", "cancelled", "refused" ], "title": "State", "type": "string" }, "workshop_id": { "title": "Workshop Id", "type": "string" } }, "required": [ "id", "workshop_id", "kind", "state", "manifest", "manifest_digest", "signature", "signing_key_id", "created_at" ], "title": "WorkshopPushJob", "type": "object" }, "WorkshopPushJobEnqueueResponse": { "description": "What a deploy-shaped verb returns: the adopt job plus the policy-gated\n`harness.ensure` it waits on when the box lacks the harness.", "properties": { "job": { "$ref": "#/components/schemas/WorkshopPushJob" }, "plugin_access": { "items": { "$ref": "#/components/schemas/AppliedPluginAccess" }, "title": "Plugin Access", "type": "array" }, "prerequisite": { "anyOf": [ { "$ref": "#/components/schemas/WorkshopPushJob" }, { "type": "null" } ], "default": null } }, "required": [ "job" ], "title": "WorkshopPushJobEnqueueResponse", "type": "object" }, "WorkshopPushJobListResponse": { "properties": { "jobs": { "items": { "$ref": "#/components/schemas/WorkshopPushJob" }, "title": "Jobs", "type": "array" } }, "required": [ "jobs" ], "title": "WorkshopPushJobListResponse", "type": "object" }, "WorkshopPushPolicyFloorRequest": { "properties": { "floor": { "enum": [ "automatic", "ask_installs" ], "title": "Floor", "type": "string" } }, "required": [ "floor" ], "title": "WorkshopPushPolicyFloorRequest", "type": "object" }, "WorkshopPushPolicyFloorResponse": { "properties": { "floor": { "enum": [ "automatic", "ask_installs" ], "title": "Floor", "type": "string" } }, "required": [ "floor" ], "title": "WorkshopPushPolicyFloorResponse", "type": "object" }, "WorkshopPushPolicyRequest": { "properties": { "push_policy": { "enum": [ "automatic", "ask_installs", "ask_all" ], "title": "Push Policy", "type": "string" } }, "required": [ "push_policy" ], "title": "WorkshopPushPolicyRequest", "type": "object" }, "WorkshopPushRequestApprove": { "description": "Approve exactly the reviewed request. The digest is required: a\nrequest without one is refused, never applied as a legacy approve.", "properties": { "scope_digest": { "pattern": "^[0-9a-f]{64}$", "title": "Scope Digest", "type": "string" } }, "required": [ "scope_digest" ], "title": "WorkshopPushRequestApprove", "type": "object" }, "WorkshopPushRequestReview": { "description": "One page of the review of what approving a held job releases.\n\nEvery page carries the same `scope_digest`; fetch pages until\n`next_cursor` is null, then approve with that digest. A request that\nchanged between pages answers 409 `push_request_changed` and the review\nstarts again. The totals cover the whole request, not the page.", "properties": { "already_queued": { "title": "Already Queued", "type": "integer" }, "follow_up": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Follow Up" }, "held_for_own_approval": { "title": "Held For Own Approval", "type": "integer" }, "items": { "items": { "$ref": "#/components/schemas/WorkshopPushReviewItem" }, "title": "Items", "type": "array" }, "job_id": { "title": "Job Id", "type": "string" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Next Cursor" }, "open_jobs": { "title": "Open Jobs", "type": "integer" }, "released_jobs": { "title": "Released Jobs", "type": "integer" }, "reviewable": { "title": "Reviewable", "type": "boolean" }, "scope_digest": { "title": "Scope Digest", "type": "string" }, "unreviewable_jobs": { "title": "Unreviewable Jobs", "type": "integer" }, "version": { "title": "Version", "type": "string" }, "workshop_id": { "title": "Workshop Id", "type": "string" } }, "required": [ "workshop_id", "job_id", "version", "scope_digest", "open_jobs", "released_jobs", "already_queued", "held_for_own_approval", "unreviewable_jobs", "reviewable", "items" ], "title": "WorkshopPushRequestReview", "type": "object" }, "WorkshopPushReviewDetail": { "description": "One thing a job does, in words: \"Folder\" — \"/srv/app\".", "properties": { "label": { "title": "Label", "type": "string" }, "value": { "title": "Value", "type": "string" } }, "required": [ "label", "value" ], "title": "WorkshopPushReviewDetail", "type": "object" }, "WorkshopPushReviewItem": { "description": "One open job of the request, as the person approving reads it (TIDY-19802 U2).\n\nNever its manifest, signature or claim token: `details` says what it\ndoes from an allowlist per kind, and `undisclosed_fields` names any\nmanifest field no rule explains, so an unexplained parameter is shown\nrather than silently approved.", "properties": { "agent_account_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Agent Account Id" }, "coverage": { "enum": [ "complete", "incomplete", "unavailable" ], "title": "Coverage", "type": "string" }, "depends_on_job_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Depends On Job Id" }, "details": { "items": { "$ref": "#/components/schemas/WorkshopPushReviewDetail" }, "title": "Details", "type": "array" }, "employee_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Employee Name" }, "id": { "title": "Id", "type": "string" }, "kind": { "enum": [ "employee.adopt", "employee.retire", "harness.ensure", "tool.install", "root.ensure", "root.inspect", "root.expose", "root.detach", "browser.install", "workshop.uninstall", "mcp.materialize", "skills.materialize", "health.check", "keys.ship", "keys.revoke", "snapshot.export", "harness.remove", "workshop.update", "host.setup", "docker.elevation_revoke", "host.devices", "fs.browse", "file.transfer" ], "title": "Kind", "type": "string" }, "manifest_digest": { "title": "Manifest Digest", "type": "string" }, "plugin_visible": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "title": "Plugin Visible" }, "released": { "title": "Released", "type": "boolean" }, "second_look": { "title": "Second Look", "type": "boolean" }, "state": { "enum": [ "awaiting_approval", "queued" ], "title": "State", "type": "string" }, "summary": { "title": "Summary", "type": "string" }, "undisclosed_fields": { "items": { "type": "string" }, "title": "Undisclosed Fields", "type": "array" } }, "required": [ "id", "kind", "state", "released", "second_look", "manifest_digest", "summary", "coverage" ], "title": "WorkshopPushReviewItem", "type": "object" }, "WorkshopReadRequest": { "properties": { "params": { "additionalProperties": true, "title": "Workshop Read Params", "type": "object" }, "recipient_key": { "maxLength": 128, "minLength": 40, "title": "Recipient Key", "type": "string" }, "verb": { "enum": [ "fs.list", "fs.stat", "fs.snapshotEstimate", "fs.read", "fs.search", "git.status", "git.diff" ], "title": "Verb", "type": "string" } }, "required": [ "verb", "recipient_key" ], "title": "WorkshopReadRequest", "type": "object" }, "WorkshopReadResponse": { "properties": { "error": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "title": "Error" }, "ok": { "title": "Ok", "type": "boolean" }, "rpc_id": { "format": "uuid", "title": "Rpc Id", "type": "string" }, "sealed_body": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "title": "Sealed Body" }, "storage": { "anyOf": [ { "$ref": "#/components/schemas/SnapshotStorage" }, { "type": "null" } ], "default": null } }, "required": [ "rpc_id", "ok" ], "title": "WorkshopReadResponse", "type": "object" }, "WorkshopRedeployFailure": { "properties": { "agent_account_id": { "title": "Agent Account Id", "type": "string" }, "code": { "title": "Code", "type": "string" }, "display_name": { "title": "Display Name", "type": "string" }, "message": { "title": "Message", "type": "string" }, "plan": { "anyOf": [ { "$ref": "#/components/schemas/SkillPluginAccessPlan" }, { "type": "null" } ], "default": null } }, "required": [ "agent_account_id", "display_name", "code", "message" ], "title": "WorkshopRedeployFailure", "type": "object" }, "WorkshopRedeployRequest": { "properties": { "force": { "default": false, "title": "Force", "type": "boolean" }, "plugin_access_by_employee": { "items": { "$ref": "#/components/schemas/EmployeeDeployAccess" }, "maxItems": 200, "title": "Plugin Access By Employee", "type": "array" }, "target_workshop_id": { "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", "title": "Target Workshop Id", "type": "string" } }, "required": [ "target_workshop_id" ], "title": "WorkshopRedeployRequest", "type": "object" }, "WorkshopRedeployResponse": { "properties": { "failed": { "items": { "$ref": "#/components/schemas/WorkshopRedeployFailure" }, "title": "Failed", "type": "array" }, "from_workshop_id": { "title": "From Workshop Id", "type": "string" }, "moved": { "items": { "$ref": "#/components/schemas/WorkshopMoveResponse" }, "title": "Moved", "type": "array" }, "redeploy_batch_id": { "title": "Redeploy Batch Id", "type": "string" }, "to_workshop_id": { "title": "To Workshop Id", "type": "string" } }, "required": [ "redeploy_batch_id", "from_workshop_id", "to_workshop_id" ], "title": "WorkshopRedeployResponse", "type": "object" }, "WorkshopRelayUsageSummary": { "description": "The workspace's relayed transfer bytes today (UTC) against its daily\nallowance. The shape of every service-usage summary; ``used`` is the\nworkspace's, since the allowance is per workspace.", "properties": { "account_id": { "format": "uuid", "title": "Account Id", "type": "string" }, "enforcement_enabled": { "title": "Enforcement Enabled", "type": "boolean" }, "limit": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Limit" }, "period_end": { "format": "date-time", "title": "Period End", "type": "string" }, "period_start": { "format": "date-time", "title": "Period Start", "type": "string" }, "period_type": { "title": "Period Type", "type": "string" }, "provider": { "title": "Provider", "type": "string" }, "remaining": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Remaining" }, "resource_type": { "title": "Resource Type", "type": "string" }, "tenant_id": { "format": "uuid", "title": "Tenant Id", "type": "string" }, "used": { "title": "Used", "type": "number" } }, "required": [ "tenant_id", "account_id", "resource_type", "provider", "period_type", "period_start", "period_end", "used", "limit", "remaining", "enforcement_enabled" ], "title": "WorkshopRelayUsageSummary", "type": "object" }, "WorkshopResponse": { "properties": { "allow_docker": { "default": false, "title": "Allow Docker", "type": "boolean" }, "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "daemon_version": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Daemon Version" }, "durability": { "anyOf": [ { "$ref": "#/components/schemas/WorkshopDurability" }, { "type": "null" } ], "default": null }, "effective_push_policy": { "default": "ask_installs", "enum": [ "automatic", "ask_installs", "ask_all" ], "title": "Effective Push Policy", "type": "string" }, "enrollment_token_expires_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Enrollment Token Expires At" }, "enrollment_token_issued_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Enrollment Token Issued At" }, "gateway_status": { "enum": [ "unenrolled", "enrolling", "online", "offline", "tombstoned", "revoked" ], "title": "Gateway Status", "type": "string" }, "gateway_status_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Gateway Status At" }, "host_arch": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Host Arch" }, "host_instance_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Host Instance Id" }, "host_os": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Host Os" }, "id": { "title": "Id", "type": "string" }, "install_policy_authority": { "anyOf": [ { "$ref": "#/components/schemas/WorkshopInstallPolicyAuthority" }, { "type": "null" } ], "default": null }, "kind": { "enum": [ "machine", "cloud" ], "title": "Kind", "type": "string" }, "last_seen_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Last Seen At" }, "lifecycle": { "anyOf": [ { "$ref": "#/components/schemas/WorkshopLifecycle" }, { "$ref": "#/components/schemas/WorkshopLifecycleUnknown" }, { "type": "null" } ], "default": null, "title": "Lifecycle" }, "machine_lost_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Machine Lost At" }, "memory": { "anyOf": [ { "$ref": "#/components/schemas/WorkshopMemoryState" }, { "type": "null" } ], "default": null }, "name": { "title": "Name", "type": "string" }, "paused_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Paused At" }, "plugin_access": { "items": { "$ref": "#/components/schemas/AppliedPluginAccess" }, "title": "Plugin Access", "type": "array" }, "push_job_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Push Job Id" }, "push_job_state": { "anyOf": [ { "enum": [ "awaiting_approval", "queued", "dispatched", "running", "succeeded", "failed", "cancelled", "refused" ], "type": "string" }, { "type": "null" } ], "default": null, "title": "Push Job State" }, "push_policy": { "default": "ask_installs", "enum": [ "automatic", "ask_installs", "ask_all" ], "title": "Push Policy", "type": "string" }, "record_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Record Id" }, "revoked_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Revoked At" }, "roster": { "items": { "$ref": "#/components/schemas/WorkshopRosterEntry" }, "title": "Roster", "type": "array" }, "signing_key_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Signing Key Id" }, "sleep_state": { "default": "awake", "enum": [ "awake", "asleep" ], "title": "Sleep State", "type": "string" }, "slept_since": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Slept Since" }, "update_error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Update Error" }, "update_policy": { "default": "automatic", "enum": [ "automatic", "ask" ], "title": "Update Policy", "type": "string" }, "update_state": { "anyOf": [ { "enum": [ "current", "available", "updating", "failed", "manual" ], "type": "string" }, { "type": "null" } ], "default": null, "title": "Update State" }, "update_target_version": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Update Target Version" }, "updated_at": { "format": "date-time", "title": "Updated At", "type": "string" } }, "required": [ "id", "name", "kind", "gateway_status", "created_at", "updated_at" ], "title": "WorkshopResponse", "type": "object" }, "WorkshopRevokeRequest": { "description": "Revoke is irreversible for the old identity (D17). `uninstall` also\nqueues the box's self-uninstall behind a one-use cleanup capability.", "properties": { "destroy_server": { "default": false, "title": "Destroy Server", "type": "boolean" }, "reason": { "anyOf": [ { "maxLength": 200, "type": "string" }, { "type": "null" } ], "title": "Reason" }, "uninstall": { "default": true, "title": "Uninstall", "type": "boolean" } }, "title": "WorkshopRevokeRequest", "type": "object" }, "WorkshopRevokeResponse": { "properties": { "cleanup_job": { "anyOf": [ { "$ref": "#/components/schemas/WorkshopPushJob" }, { "type": "null" } ], "default": null }, "detached_employees": { "items": { "type": "string" }, "title": "Detached Employees", "type": "array" }, "local_uninstall_command": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Local Uninstall Command" }, "revoked_at": { "format": "date-time", "title": "Revoked At", "type": "string" }, "revoked_employees": { "items": { "type": "string" }, "title": "Revoked Employees", "type": "array" }, "revoked_pats": { "title": "Revoked Pats", "type": "integer" }, "server_destroy": { "anyOf": [ { "$ref": "#/components/schemas/WorkshopServerDestroy" }, { "type": "null" } ], "default": null }, "workshop_id": { "title": "Workshop Id", "type": "string" } }, "required": [ "workshop_id", "revoked_at", "revoked_pats", "revoked_employees" ], "title": "WorkshopRevokeResponse", "type": "object" }, "WorkshopRosterEntry": { "properties": { "agent_account_id": { "title": "Agent Account Id", "type": "string" }, "contact_id": { "title": "Contact Id", "type": "string" }, "display_name": { "title": "Display Name", "type": "string" }, "harness_processes": { "anyOf": [ { "$ref": "#/components/schemas/WorkshopHarnessProcesses" }, { "type": "null" } ], "default": null }, "installation_state": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Installation State" }, "memory_bytes": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Memory Bytes" }, "memory_limit_bytes": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Memory Limit Bytes" } }, "required": [ "agent_account_id", "contact_id", "display_name" ], "title": "WorkshopRosterEntry", "type": "object" }, "WorkshopSendEndpoint": { "description": "One end of a Send (TIDY-19414 F11 S3): a Project Root or one of the\nvolumes the workshop reports (a laptop's SD card, a NAS share), and a\nfolder under it. The box re-proves the endpoint before a byte moves.", "properties": { "id": { "maxLength": 64, "minLength": 1, "pattern": "^[0-9A-Za-z-]+$", "title": "Id", "type": "string" }, "kind": { "enum": [ "root", "mount" ], "title": "Kind", "type": "string" }, "path": { "default": "", "maxLength": 1024, "title": "Path", "type": "string" } }, "required": [ "kind", "id" ], "title": "WorkshopSendEndpoint", "type": "object" }, "WorkshopSendItem": { "description": "A file or a folder in the source folder, by its own name. A file's size\nis the one the listing showed: its vouch binds it.", "properties": { "kind": { "enum": [ "file", "dir" ], "title": "Kind", "type": "string" }, "name": { "maxLength": 255, "minLength": 1, "title": "Name", "type": "string" }, "size_bytes": { "default": 0, "maximum": 9007199254740991.0, "minimum": 0.0, "title": "Size Bytes", "type": "integer" } }, "required": [ "name", "kind" ], "title": "WorkshopSendItem", "type": "object" }, "WorkshopSendRequest": { "description": "Send files and folders to a folder on another workshop.", "properties": { "items": { "items": { "$ref": "#/components/schemas/WorkshopSendItem" }, "maxItems": 2000, "minItems": 1, "title": "Items", "type": "array" }, "source": { "$ref": "#/components/schemas/WorkshopSendEndpoint" }, "target": { "$ref": "#/components/schemas/WorkshopSendEndpoint" }, "target_workshop_id": { "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", "title": "Target Workshop Id", "type": "string" } }, "required": [ "source", "items", "target_workshop_id", "target" ], "title": "WorkshopSendRequest", "type": "object" }, "WorkshopSendResponse": { "description": "The Send, and the record that shows it move.", "properties": { "files_total": { "title": "Files Total", "type": "integer" }, "record_id": { "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", "title": "Record Id", "type": "string" }, "state": { "enum": [ "awaiting_approval", "listing", "sending", "paused", "done", "failed", "cancelled" ], "title": "State", "type": "string" }, "title": { "title": "Title", "type": "string" }, "transfer_id": { "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", "title": "Transfer Id", "type": "string" } }, "required": [ "transfer_id", "record_id", "state", "title", "files_total" ], "title": "WorkshopSendResponse", "type": "object" }, "WorkshopServerDestroy": { "description": "What became of the machine Tidy made (TIDY-18830).\n\nPresent on every revoke of a Tidy-PROVISIONED workshop, whichever way the\nmember chose — `kept_running` is not silence, it is the sentence that says\nthe server is still billing. `requested` is deliberately not \"destroyed\":\nonly the provider's own confirmation, which the operation lane observes and\nrecords, may claim the machine is gone.", "properties": { "message": { "title": "Message", "type": "string" }, "operation_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Operation Id" }, "provider": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Provider" }, "provider_resource_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Provider Resource Id" }, "state": { "enum": [ "requested", "kept_running", "failed", "unrecorded" ], "title": "State", "type": "string" } }, "required": [ "state", "message" ], "title": "WorkshopServerDestroy", "type": "object" }, "WorkshopSetupCommandRequest": { "description": "The machine half of the establish-workshop journey. No employee fields\nlive here — that is the whole point of the split (D2).", "properties": { "host_arch": { "enum": [ "x86_64", "aarch64" ], "title": "Host Arch", "type": "string" }, "host_os": { "enum": [ "linux", "macos", "windows" ], "title": "Host Os", "type": "string" }, "lifecycle": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Lifecycle" } }, "required": [ "host_os", "host_arch" ], "title": "WorkshopSetupCommandRequest", "type": "object" }, "WorkshopSetupCommandResponse": { "properties": { "expires_at": { "format": "date-time", "title": "Expires At", "type": "string" }, "host_arch": { "title": "Host Arch", "type": "string" }, "host_os": { "title": "Host Os", "type": "string" }, "setup_command": { "title": "Setup Command", "type": "string" }, "workshop_id": { "title": "Workshop Id", "type": "string" } }, "required": [ "workshop_id", "setup_command", "expires_at", "host_os", "host_arch" ], "title": "WorkshopSetupCommandResponse", "type": "object" }, "WorkshopSignInTarget": { "properties": { "employee_account_id": { "title": "Employee Account Id", "type": "string" }, "employee_display_name": { "title": "Employee Display Name", "type": "string" }, "runtime": { "title": "Runtime", "type": "string" }, "workshop_id": { "title": "Workshop Id", "type": "string" } }, "required": [ "workshop_id", "runtime", "employee_account_id", "employee_display_name" ], "title": "WorkshopSignInTarget", "type": "object" }, "WorkshopSleepStateRequest": { "description": "TIDY-18239 (S5): the Tidy desktop app on the workshop machine reports\nthe OS suspend/resume it observed, so a missed heartbeat while the lid is\nclosed reads as \"offline while asleep\" rather than as a lost box.", "properties": { "state": { "enum": [ "awake", "asleep" ], "title": "State", "type": "string" } }, "required": [ "state" ], "title": "WorkshopSleepStateRequest", "type": "object" }, "WorkshopSleepStateResponse": { "properties": { "gateway_status": { "enum": [ "unenrolled", "enrolling", "online", "offline", "tombstoned", "revoked" ], "title": "Gateway Status", "type": "string" }, "sleep_state": { "enum": [ "awake", "asleep" ], "title": "Sleep State", "type": "string" }, "slept_since": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Slept Since" }, "workshop_id": { "title": "Workshop Id", "type": "string" } }, "required": [ "workshop_id", "sleep_state", "gateway_status" ], "title": "WorkshopSleepStateResponse", "type": "object" }, "WorkshopTenantRow": { "description": "Current workshop gateway state for one tenant.", "properties": { "last_heartbeat_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Last Heartbeat At" }, "offline": { "default": 0, "title": "Offline", "type": "integer" }, "online": { "default": 0, "title": "Online", "type": "integer" }, "revoked": { "default": 0, "title": "Revoked", "type": "integer" }, "tenant": { "title": "Tenant", "type": "string" }, "tenant_id": { "title": "Tenant Id", "type": "string" } }, "required": [ "tenant_id", "tenant" ], "title": "WorkshopTenantRow", "type": "object" }, "WorkshopTools": { "additionalProperties": false, "properties": { "browser_controller": { "$ref": "#/components/schemas/ToolPresence" }, "docker": { "$ref": "#/components/schemas/ToolPresence" }, "gh": { "anyOf": [ { "$ref": "#/components/schemas/ToolPresence" }, { "type": "null" } ] }, "git": { "$ref": "#/components/schemas/ToolPresence" }, "node": { "$ref": "#/components/schemas/ToolPresence" }, "npm": { "anyOf": [ { "$ref": "#/components/schemas/ToolPresence" }, { "type": "null" } ] }, "python": { "$ref": "#/components/schemas/ToolPresence" } }, "required": [ "git", "python", "node", "docker", "browser_controller" ], "title": "WorkshopTools", "type": "object" }, "WorkshopTransferAuthorizeRequest": { "description": "Authorize one workshop→workshop transfer.\n\n``source_*`` names the file on the SOURCE workshop (this route is\n``POST /workshops/{source_workshop_id}/transfers`` — the box the file\nleaves); ``target_*`` names where it lands. ``size_bytes`` is the size the\nbrowse listing showed: the vouch binds it and the source box refuses a file\nthat no longer has it. The checksum is the source box's own — it hashes\nwhat it sends, and the target re-hashes what it wrote.", "properties": { "size_bytes": { "maximum": 9007199254740991.0, "minimum": 0.0, "title": "Size Bytes", "type": "integer" }, "source_path": { "maxLength": 1024, "minLength": 1, "title": "Source Path", "type": "string" }, "source_root_id": { "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", "title": "Source Root Id", "type": "string" }, "target_path": { "maxLength": 1024, "minLength": 1, "title": "Target Path", "type": "string" }, "target_root_id": { "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", "title": "Target Root Id", "type": "string" }, "target_workshop_id": { "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", "title": "Target Workshop Id", "type": "string" } }, "required": [ "source_root_id", "source_path", "target_workshop_id", "target_root_id", "target_path", "size_bytes" ], "title": "WorkshopTransferAuthorizeRequest", "type": "object" }, "WorkshopTransferAuthorizeResponse": { "description": "The authorization the backend minted and the job it queued.", "properties": { "deadline_ms": { "title": "Deadline Ms", "type": "integer" }, "job_id": { "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", "title": "Job Id", "type": "string" }, "mode": { "const": "relay", "title": "Mode", "type": "string" }, "session_id": { "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", "title": "Session Id", "type": "string" }, "source": { "$ref": "#/components/schemas/WorkshopTransferRendezvous" }, "state": { "enum": [ "awaiting_approval", "queued", "dispatched", "running", "succeeded", "failed", "cancelled", "refused" ], "title": "State", "type": "string" }, "target": { "$ref": "#/components/schemas/WorkshopTransferRendezvous" } }, "required": [ "session_id", "job_id", "state", "mode", "deadline_ms", "source", "target" ], "title": "WorkshopTransferAuthorizeResponse", "type": "object" }, "WorkshopTransferRendezvous": { "description": "One side of the rendezvous as the vouch binds it.", "properties": { "name": { "title": "Name", "type": "string" }, "path": { "title": "Path", "type": "string" }, "root_id": { "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", "title": "Root Id", "type": "string" }, "workshop_id": { "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", "title": "Workshop Id", "type": "string" } }, "required": [ "workshop_id", "name", "root_id", "path" ], "title": "WorkshopTransferRendezvous", "type": "object" }, "WorkshopTunnelListItem": { "properties": { "created_at": { "title": "Created At", "type": "string" }, "detail": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Its latest line, or why it closed.", "title": "Detail" }, "direction": { "description": "`out` from the workshop asked about, `in` to it.", "title": "Direction", "type": "string" }, "id": { "title": "Id", "type": "string" }, "local_port": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Local Port" }, "path": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "How its latest connection went: directly on the same network, directly over the internet, or relayed through Tidy.", "title": "Path" }, "port": { "title": "Port", "type": "integer" }, "record_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Record Id" }, "requested_by": { "title": "Requested By", "type": "string" }, "source_name": { "title": "Source Name", "type": "string" }, "source_workshop_id": { "title": "Source Workshop Id", "type": "string" }, "state": { "description": "pending | open | declined | closed", "title": "State", "type": "string" }, "status": { "description": "The state in words, and where it listens.", "title": "Status", "type": "string" }, "target_name": { "title": "Target Name", "type": "string" }, "target_workshop_id": { "title": "Target Workshop Id", "type": "string" } }, "required": [ "id", "direction", "source_workshop_id", "source_name", "target_workshop_id", "target_name", "port", "state", "status", "requested_by", "created_at" ], "title": "WorkshopTunnelListItem", "type": "object" }, "WorkshopTunnelListResponse": { "properties": { "tunnels": { "items": { "$ref": "#/components/schemas/WorkshopTunnelListItem" }, "title": "Tunnels", "type": "array" } }, "required": [ "tunnels" ], "title": "WorkshopTunnelListResponse", "type": "object" }, "WorkshopTunnelRequest": { "properties": { "local_port": { "anyOf": [ { "maximum": 65535.0, "minimum": 1.0, "type": "integer" }, { "type": "null" } ], "description": "The port on this workshop's 127.0.0.1 that reaches it. Left out, the workshop picks one (the same port when it is free and above 1023) and keeps it.", "title": "Local Port" }, "port": { "description": "The port on that workshop's 127.0.0.1 (22 for SSH, 5432 for Postgres, …).", "maximum": 65535.0, "minimum": 1.0, "title": "Port", "type": "integer" }, "target_workshop": { "description": "The workshop the tunnel reaches: its id, or its exact name.", "maxLength": 120, "minLength": 1, "title": "Target Workshop", "type": "string" } }, "required": [ "target_workshop", "port" ], "title": "WorkshopTunnelRequest", "type": "object" }, "WorkshopTunnelResponse": { "properties": { "id": { "title": "Id", "type": "string" }, "local_port": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Where it listens on the source's 127.0.0.1, once it does.", "title": "Local Port" }, "message": { "title": "Message", "type": "string" }, "port": { "title": "Port", "type": "integer" }, "record_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "The tunnel's record once approved.", "title": "Record Id" }, "source_workshop_id": { "title": "Source Workshop Id", "type": "string" }, "state": { "description": "pending | open | declined | closed", "title": "State", "type": "string" }, "target_workshop_id": { "title": "Target Workshop Id", "type": "string" } }, "required": [ "id", "source_workshop_id", "target_workshop_id", "port", "state", "message" ], "title": "WorkshopTunnelResponse", "type": "object" }, "WorkshopUpdatePolicyRequest": { "properties": { "update_policy": { "enum": [ "automatic", "ask" ], "title": "Update Policy", "type": "string" } }, "required": [ "update_policy" ], "title": "WorkshopUpdatePolicyRequest", "type": "object" }, "WorkshopUpdateRequest": { "properties": { "kind": { "anyOf": [ { "enum": [ "machine", "cloud" ], "type": "string" }, { "type": "null" } ], "title": "Kind" }, "name": { "anyOf": [ { "maxLength": 200, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Name" } }, "title": "WorkshopUpdateRequest", "type": "object" }, "WorkspaceAccountsResponse": { "description": "GET /api/v1/workspace/accounts — person info + tenant list.", "properties": { "display_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Display Name" }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Email" }, "is_system_admin": { "default": false, "description": "Platform-wide System Administrator capability from accounts.is_admin.", "title": "Is System Admin", "type": "boolean" }, "person_id": { "format": "uuid", "title": "Person Id", "type": "string" }, "tenants": { "items": { "$ref": "#/components/schemas/WorkspaceTenant" }, "title": "Tenants", "type": "array" } }, "required": [ "person_id", "tenants" ], "title": "WorkspaceAccountsResponse", "type": "object" }, "WorkspaceConnectRequest": { "properties": { "admin_email": { "format": "email", "title": "Admin Email", "type": "string" } }, "required": [ "admin_email" ], "title": "WorkspaceConnectRequest", "type": "object" }, "WorkspaceConnectResponse": { "properties": { "admin_email": { "title": "Admin Email", "type": "string" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Error" }, "success": { "title": "Success", "type": "boolean" } }, "required": [ "success", "admin_email" ], "title": "WorkspaceConnectResponse", "type": "object" }, "WorkspaceCurrentResponse": { "description": "GET /api/v1/workspace/current — active workspace context.", "properties": { "account_type": { "default": "personal", "title": "Account Type", "type": "string" }, "person_id": { "format": "uuid", "title": "Person Id", "type": "string" }, "role": { "title": "Role", "type": "string" }, "tenant_id": { "format": "uuid", "title": "Tenant Id", "type": "string" }, "tenant_name": { "title": "Tenant Name", "type": "string" } }, "required": [ "person_id", "tenant_id", "tenant_name", "role" ], "title": "WorkspaceCurrentResponse", "type": "object" }, "WorkspaceGuestPolicy": { "properties": { "allow_cross_workspace_channels": { "title": "Allow Cross Workspace Channels", "type": "boolean" }, "allow_external_guests": { "title": "Allow External Guests", "type": "boolean" }, "default_expiration_days": { "title": "Default Expiration Days", "type": "integer" }, "federation_allowed_servers": { "items": { "type": "string" }, "title": "Federation Allowed Servers", "type": "array" }, "require_admin_approval": { "title": "Require Admin Approval", "type": "boolean" } }, "required": [ "allow_external_guests", "require_admin_approval", "default_expiration_days", "allow_cross_workspace_channels", "federation_allowed_servers" ], "title": "WorkspaceGuestPolicy", "type": "object" }, "WorkspaceMemberResponse": { "properties": { "account_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Account Id" }, "avatar_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Avatar Url" }, "display_name": { "title": "Display Name", "type": "string" }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Email" }, "is_bot": { "default": false, "title": "Is Bot", "type": "boolean" }, "is_guest": { "default": false, "title": "Is Guest", "type": "boolean" }, "is_self": { "default": false, "title": "Is Self", "type": "boolean" }, "last_active_ms": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Last Active Ms" }, "matrix_id": { "title": "Matrix Id", "type": "string" }, "member_kind": { "default": "human", "title": "Member Kind", "type": "string" }, "presence": { "default": "unavailable", "title": "Presence", "type": "string" } }, "required": [ "matrix_id", "display_name" ], "title": "WorkspaceMemberResponse", "type": "object" }, "WorkspaceMembersResponse": { "properties": { "members": { "items": { "$ref": "#/components/schemas/WorkspaceMemberResponse" }, "title": "Members", "type": "array" }, "recent_partners": { "items": { "type": "string" }, "title": "Recent Partners", "type": "array" } }, "required": [ "members", "recent_partners" ], "title": "WorkspaceMembersResponse", "type": "object" }, "WorkspaceSettingsResponse": { "properties": { "require_capability_approval": { "title": "Require Capability Approval", "type": "boolean" } }, "required": [ "require_capability_approval" ], "title": "WorkspaceSettingsResponse", "type": "object" }, "WorkspaceStatusResponse": { "description": "Connection status for Google Workspace DWD.", "properties": { "admin_email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Admin Email" }, "connected": { "title": "Connected", "type": "boolean" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Error" }, "last_verified_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Last Verified At" }, "sa_key_configured": { "title": "Sa Key Configured", "type": "boolean" } }, "required": [ "connected", "sa_key_configured" ], "title": "WorkspaceStatusResponse", "type": "object" }, "WorkspaceSwitchResponse": { "description": "POST /api/v1/workspace/switch/{tenant_id} response.", "properties": { "role": { "title": "Role", "type": "string" }, "success": { "title": "Success", "type": "boolean" }, "tenant_id": { "format": "uuid", "title": "Tenant Id", "type": "string" }, "tenant_name": { "title": "Tenant Name", "type": "string" } }, "required": [ "success", "tenant_id", "tenant_name", "role" ], "title": "WorkspaceSwitchResponse", "type": "object" }, "WorkspaceTemplateListItem": { "properties": { "chips": { "items": { "type": "string" }, "title": "Chips", "type": "array" }, "family": { "title": "Family", "type": "string" }, "hero_media": { "additionalProperties": true, "title": "Hero Media", "type": "object" }, "name": { "title": "Name", "type": "string" }, "slug": { "title": "Slug", "type": "string" }, "status": { "title": "Status", "type": "string" }, "summary": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Summary" }, "version": { "title": "Version", "type": "integer" }, "what_you_get": { "$ref": "#/components/schemas/WorkspaceTemplateSummary" } }, "required": [ "slug", "name", "family", "chips", "summary", "hero_media", "version", "status", "what_you_get" ], "title": "WorkspaceTemplateListItem", "type": "object" }, "WorkspaceTemplateResponse": { "properties": { "ai_employees": { "items": { "$ref": "#/components/schemas/AiEmployeeItem" }, "title": "Ai Employees", "type": "array" }, "chips": { "items": { "type": "string" }, "title": "Chips", "type": "array" }, "definition": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Definition" }, "family": { "title": "Family", "type": "string" }, "hero_media": { "additionalProperties": true, "title": "Hero Media", "type": "object" }, "landing_ref": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Landing Ref" }, "name": { "title": "Name", "type": "string" }, "slug": { "title": "Slug", "type": "string" }, "status": { "title": "Status", "type": "string" }, "summary": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Summary" }, "usage_guide": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Usage Guide" }, "version": { "title": "Version", "type": "integer" }, "what_you_get": { "$ref": "#/components/schemas/WorkspaceTemplateSummary" } }, "required": [ "slug", "name", "family", "chips", "summary", "hero_media", "usage_guide", "version", "status", "what_you_get" ], "title": "WorkspaceTemplateResponse", "type": "object" }, "WorkspaceTemplateSummary": { "description": "Generated 'what you get' summary — counts + names per kind (D24).", "properties": { "counts": { "additionalProperties": { "type": "integer" }, "title": "Counts", "type": "object" }, "items": { "additionalProperties": { "items": { "type": "string" }, "type": "array" }, "title": "Items", "type": "object" } }, "required": [ "counts", "items" ], "title": "WorkspaceTemplateSummary", "type": "object" }, "WorkspaceTemplateUpsertRequest": { "description": "Create/update a catalog template (admin authoring lane).", "properties": { "chips": { "items": { "type": "string" }, "title": "Chips", "type": "array" }, "definition": { "additionalProperties": true, "title": "Definition", "type": "object" }, "family": { "default": "business", "enum": [ "business", "personal" ], "title": "Family", "type": "string" }, "hero_media": { "additionalProperties": true, "title": "Hero Media", "type": "object" }, "name": { "minLength": 1, "title": "Name", "type": "string" }, "slug": { "maxLength": 128, "minLength": 1, "title": "Slug", "type": "string" }, "summary": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Summary" }, "usage_guide": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Usage Guide" } }, "required": [ "slug", "name" ], "title": "WorkspaceTemplateUpsertRequest", "type": "object" }, "WorkspaceTemplateValidateResponse": { "properties": { "errors": { "items": { "$ref": "#/components/schemas/ValidationErrorDetail" }, "title": "Errors", "type": "array" }, "valid": { "title": "Valid", "type": "boolean" }, "what_you_get": { "anyOf": [ { "$ref": "#/components/schemas/WorkspaceTemplateSummary" }, { "type": "null" } ] } }, "required": [ "valid" ], "title": "WorkspaceTemplateValidateResponse", "type": "object" }, "WorkspaceTenant": { "description": "A single tenant membership for the workspace accounts response.", "properties": { "account_type": { "default": "personal", "title": "Account Type", "type": "string" }, "display_name": { "title": "Display Name", "type": "string" }, "env": { "default": "prod", "description": "Tenant environment: 'prod' or 'sandbox'.", "title": "Env", "type": "string" }, "is_current": { "title": "Is Current", "type": "boolean" }, "last_active_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Last Active At" }, "role": { "title": "Role", "type": "string" }, "status": { "title": "Status", "type": "string" }, "tenant_id": { "format": "uuid", "title": "Tenant Id", "type": "string" } }, "required": [ "tenant_id", "display_name", "role", "status", "is_current" ], "title": "WorkspaceTenant", "type": "object" }, "WrappedResponse": { "properties": { "period": { "title": "Period", "type": "string" }, "period_label": { "title": "Period Label", "type": "string" }, "stats": { "$ref": "#/components/schemas/WrappedStats" } }, "required": [ "period", "period_label", "stats" ], "title": "WrappedResponse", "type": "object" }, "WrappedStats": { "properties": { "avg_response_time_seconds": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Avg Response Time Seconds" }, "badges_earned": { "title": "Badges Earned", "type": "integer" }, "best_response_time_seconds": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Best Response Time Seconds" }, "busiest_day": { "anyOf": [ { "$ref": "#/components/schemas/BusiestDay" }, { "type": "null" } ] }, "focus_hours_total": { "title": "Focus Hours Total", "type": "number" }, "inbox_zero_streak_best": { "title": "Inbox Zero Streak Best", "type": "integer" }, "longest_thread": { "anyOf": [ { "$ref": "#/components/schemas/LongestThread" }, { "type": "null" } ] }, "tasks_completed": { "title": "Tasks Completed", "type": "integer" }, "top_contacts": { "items": { "$ref": "#/components/schemas/TopContactStat" }, "title": "Top Contacts", "type": "array" }, "total_emails_received": { "title": "Total Emails Received", "type": "integer" }, "total_emails_sent": { "title": "Total Emails Sent", "type": "integer" } }, "required": [ "total_emails_sent", "total_emails_received", "avg_response_time_seconds", "best_response_time_seconds", "busiest_day", "top_contacts", "longest_thread", "tasks_completed", "inbox_zero_streak_best", "badges_earned", "focus_hours_total" ], "title": "WrappedStats", "type": "object" }, "WritingStyleResponse": { "description": "User's writing style profile.", "properties": { "closing_style": { "title": "Closing Style", "type": "string" }, "greeting_style": { "title": "Greeting Style", "type": "string" }, "samples_analyzed": { "title": "Samples Analyzed", "type": "integer" }, "tone_formal": { "title": "Tone Formal", "type": "number" }, "tone_length": { "title": "Tone Length", "type": "string" } }, "required": [ "tone_formal", "tone_length", "greeting_style", "closing_style", "samples_analyzed" ], "title": "WritingStyleResponse", "type": "object" }, "_AccountKindBreakdown": { "properties": { "by_source": { "default": [], "items": { "$ref": "#/components/schemas/_AccountKindSourceBreakdown" }, "title": "By Source", "type": "array" }, "calls": { "default": 0, "title": "Calls", "type": "integer" }, "cost_usd": { "default": 0.0, "title": "Cost Usd", "type": "number" }, "tokens": { "default": 0, "title": "Tokens", "type": "integer" }, "usage_kind": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Usage Kind" } }, "title": "_AccountKindBreakdown", "type": "object" }, "_AccountKindSourceBreakdown": { "properties": { "calls": { "default": 0, "title": "Calls", "type": "integer" }, "cost_usd": { "default": 0.0, "title": "Cost Usd", "type": "number" }, "import_source": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Import Source" } }, "title": "_AccountKindSourceBreakdown", "type": "object" }, "_BinaryImageResponse": { "description": "Marker response model — the actual body is a streamed PNG.", "properties": {}, "title": "_BinaryImageResponse", "type": "object" }, "_HtmlPageResponse": { "description": "Marker model — the actual body is a server-rendered HTML document.", "properties": {}, "title": "_HtmlPageResponse", "type": "object" }, "_IcsStreamResponse": { "description": "Marker response model — real body is a text/calendar stream.", "properties": {}, "title": "_IcsStreamResponse", "type": "object" }, "_RawEmailStreamResponse": { "description": "Marker response model — the real body is a binary ``message/rfc822`` stream.\n\nFastAPI requires a ``response_model`` for coverage; generated SDKs treat this\nas an opaque body (OpenAPI ``content: message/rfc822``).", "properties": {}, "title": "_RawEmailStreamResponse", "type": "object" }, "api_service__models__campaigns__ScheduleRequest": { "properties": { "scheduled_at": { "description": "Fire time (ISO 8601 UTC).", "format": "date-time", "title": "Scheduled At", "type": "string" } }, "required": [ "scheduled_at" ], "title": "ScheduleRequest", "type": "object" }, "api_service__models__connection_policy__SendAsAddress": { "description": "A single send-as address from a provider connection.", "properties": { "display_name": { "title": "Display Name", "type": "string" }, "email": { "title": "Email", "type": "string" }, "is_alias": { "default": false, "title": "Is Alias", "type": "boolean" }, "is_default": { "default": false, "title": "Is Default", "type": "boolean" }, "provider": { "title": "Provider", "type": "string" }, "provider_connection_id": { "title": "Provider Connection Id", "type": "string" } }, "required": [ "provider_connection_id", "email", "display_name", "provider" ], "title": "SendAsAddress", "type": "object" }, "api_service__models__contact__OrganizationSummary": {}, "api_service__models__contact_merge__ContactSummary": {}, "api_service__models__contact_merge__MergeRequest": { "description": "Request for POST /api/v1/contacts/merge.\n\nAttributes:\n primary_id: ID of contact to keep\n secondary_id: ID of contact to merge\n edited_contact: Optional user edits to merged result", "properties": { "create_note_from_unmapped": { "default": true, "description": "Deprecated (TIDY-12173): no longer creates a note. contact_merge_audit is the authoritative record of unmapped/superseded values. Accepted for backward compatibility; has no effect.", "title": "Create Note From Unmapped", "type": "boolean" }, "edited_contact": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "User's edits to the merged contact (optional)", "title": "Edited Contact" }, "primary_id": { "description": "Contact ID to keep (survives merge)", "title": "Primary Id", "type": "string" }, "secondary_id": { "description": "Contact ID to merge (will be deleted)", "title": "Secondary Id", "type": "string" } }, "required": [ "primary_id", "secondary_id" ], "title": "MergeRequest", "type": "object" }, "api_service__models__delegation__RevokeResponse": {}, "api_service__models__email_base__PaginationInfo": { "description": "Pagination metadata for list responses.\n\nAttributes:\n total: Total number of items matching query\n limit: Items per page\n offset: Current offset\n has_more: Whether more items are available\n\nExample:\n {\"total\": 127, \"limit\": 50, \"offset\": 0, \"has_more\": true}", "properties": { "has_more": { "description": "Whether more items available", "title": "Has More", "type": "boolean" }, "limit": { "description": "Items per page", "title": "Limit", "type": "integer" }, "offset": { "description": "Current offset", "title": "Offset", "type": "integer" }, "total": { "description": "Total number of items", "title": "Total", "type": "integer" } }, "required": [ "total", "limit", "offset", "has_more" ], "title": "PaginationInfo", "type": "object" }, "api_service__models__email_requests__SnoozeRequest": { "description": "Request body for snooze email endpoint.\n\nAttributes:\n wake_at: ISO 8601 timestamp when the email should reappear\n\nExample:\n {\"wake_at\": \"2026-01-20T09:00:00Z\"}\n\nRelated: KCC-3348 S5.4 Snooze & Mute", "properties": { "wake_at": { "description": "Timestamp when email should reappear", "format": "date-time", "title": "Wake At", "type": "string" } }, "required": [ "wake_at" ], "title": "SnoozeRequest", "type": "object" }, "api_service__models__entity_promotion__PromoteRequest": { "properties": { "create_separate": { "default": false, "description": "Explicit 'do not merge' — keep a separate entity", "title": "Create Separate", "type": "boolean" }, "merge_target_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Explicit strong-match merge target id", "title": "Merge Target Id" }, "to_visibility": { "description": "Target tier: 'shared' or 'global'", "title": "To Visibility", "type": "string" } }, "required": [ "to_visibility" ], "title": "PromoteRequest", "type": "object" }, "api_service__models__family_members__FamilyMemberCreate": { "description": "Request body for creating a family member.", "properties": { "date_of_birth": { "anyOf": [ { "format": "date", "type": "string" }, { "type": "null" } ], "title": "Date Of Birth" }, "email": { "anyOf": [ { "format": "email", "type": "string" }, { "type": "null" } ], "title": "Email" }, "full_name": { "maxLength": 255, "minLength": 1, "title": "Full Name", "type": "string" }, "phone": { "anyOf": [ { "maxLength": 50, "type": "string" }, { "type": "null" } ], "title": "Phone" }, "relationship": { "enum": [ "spouse", "partner", "child", "parent", "grandparent", "sibling", "other" ], "title": "Relationship", "type": "string" } }, "required": [ "full_name", "relationship" ], "title": "FamilyMemberCreate", "type": "object" }, "api_service__models__family_members__FamilyMemberResponse": { "description": "Family-member row returned by CRUD and onboarding APIs.", "properties": { "contact_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Contact Id" }, "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "created_by": { "format": "uuid", "title": "Created By", "type": "string" }, "date_of_birth": { "anyOf": [ { "format": "date", "type": "string" }, { "type": "null" } ], "title": "Date Of Birth" }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Email" }, "full_name": { "title": "Full Name", "type": "string" }, "id": { "format": "uuid", "title": "Id", "type": "string" }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Phone" }, "relationship": { "enum": [ "spouse", "partner", "child", "parent", "grandparent", "sibling", "other" ], "title": "Relationship", "type": "string" }, "tenant_id": { "format": "uuid", "title": "Tenant Id", "type": "string" }, "updated_at": { "format": "date-time", "title": "Updated At", "type": "string" } }, "required": [ "id", "tenant_id", "created_by", "full_name", "relationship", "created_at", "updated_at" ], "title": "FamilyMemberResponse", "type": "object" }, "api_service__models__family_members__FamilyMembersListResponse": { "description": "List response for family-member management.", "properties": { "members": { "items": { "$ref": "#/components/schemas/api_service__models__family_members__FamilyMemberResponse" }, "title": "Members", "type": "array" }, "total_count": { "title": "Total Count", "type": "integer" } }, "required": [ "total_count" ], "title": "FamilyMembersListResponse", "type": "object" }, "api_service__models__feed_cards__CheckDuplicateResponse": { "description": "Response for duplicate check.\n\nUsed in:\n - POST /api/v1/feed/check-duplicate\n\nAttributes:\n is_duplicate: Whether content is duplicate\n existing_card_id: ID of existing card if duplicate\n existing_card_title: Title of existing card if duplicate\n\nRelated: migration 154_feed_cards_extensions.sql", "properties": { "existing_card_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ID of existing card if duplicate", "title": "Existing Card Id" }, "existing_card_title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Title of existing card if duplicate", "title": "Existing Card Title" }, "is_duplicate": { "description": "Whether content is duplicate", "title": "Is Duplicate", "type": "boolean" } }, "required": [ "is_duplicate" ], "title": "CheckDuplicateResponse", "type": "object" }, "api_service__models__links__ContactSummary": { "description": "Summary of a related contact.", "properties": { "id": { "description": "Contact ID (UUID)", "title": "Id", "type": "string" }, "link_direction": { "default": "outgoing", "description": "Direction of the edge relative to the primitive you asked about: 'outgoing' (the edge starts there and points at this one) or 'incoming' (this one points AT it). TIDY-15687.", "title": "Link Direction", "type": "string" }, "link_type": { "description": "How this contact is related", "title": "Link Type", "type": "string" }, "name": { "description": "Contact name", "title": "Name", "type": "string" }, "organization": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Organization", "title": "Organization" }, "role": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Contact role", "title": "Role" }, "type": { "const": "contact", "default": "contact", "title": "Type", "type": "string" } }, "required": [ "id", "name", "link_type" ], "title": "ContactSummary", "type": "object" }, "api_service__models__links__OrganizationSummary": { "description": "Summary of a related organization.", "properties": { "contact_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Number of contacts", "title": "Contact Count" }, "id": { "description": "Organization ID (UUID)", "title": "Id", "type": "string" }, "link_direction": { "default": "outgoing", "description": "Direction of the edge relative to the primitive you asked about: 'outgoing' (the edge starts there and points at this one) or 'incoming' (this one points AT it). TIDY-15687.", "title": "Link Direction", "type": "string" }, "link_type": { "description": "How this organization is related", "title": "Link Type", "type": "string" }, "name": { "description": "Organization name", "title": "Name", "type": "string" }, "org_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Organization type", "title": "Org Type" }, "type": { "const": "organization", "default": "organization", "title": "Type", "type": "string" } }, "required": [ "id", "name", "link_type" ], "title": "OrganizationSummary", "type": "object" }, "api_service__models__links__TaskSummary": { "description": "Summary of a related task.", "properties": { "due_date": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Task due date", "title": "Due Date" }, "id": { "description": "Task ID (UUID)", "title": "Id", "type": "string" }, "link_direction": { "default": "outgoing", "description": "Direction of the edge relative to the primitive you asked about: 'outgoing' (the edge starts there and points at this one) or 'incoming' (this one points AT it). TIDY-15687.", "title": "Link Direction", "type": "string" }, "link_type": { "description": "How this task is related", "title": "Link Type", "type": "string" }, "status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Task status", "title": "Status" }, "title": { "description": "Task title", "title": "Title", "type": "string" }, "type": { "const": "task", "default": "task", "title": "Type", "type": "string" } }, "required": [ "id", "title", "link_type" ], "title": "TaskSummary", "type": "object" }, "api_service__models__news_updates__PaginationInfo": { "description": "Pagination metadata for list responses.\n\nAttributes:\n total: Total number of items\n limit: Items per page\n offset: Current offset\n has_more: Whether more items available\n\nExample:\n {\n \"total\": 127,\n \"limit\": 50,\n \"offset\": 0,\n \"has_more\": true\n }", "properties": { "has_more": { "description": "Whether more items available", "title": "Has More", "type": "boolean" }, "limit": { "description": "Items per page", "title": "Limit", "type": "integer" }, "offset": { "description": "Current offset", "title": "Offset", "type": "integer" }, "total": { "description": "Total number of items", "title": "Total", "type": "integer" } }, "required": [ "total", "limit", "offset", "has_more" ], "title": "PaginationInfo", "type": "object" }, "api_service__models__organization_merge__OrganizationSummary": { "description": "Lightweight organization projection used in pairs and clusters.", "properties": { "approval_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Approval Status" }, "category": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Category" }, "contact_count": { "default": 0, "title": "Contact Count", "type": "integer" }, "id": { "title": "Id", "type": "string" }, "inserted_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Inserted At" }, "legal_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Legal Name" }, "name": { "title": "Name", "type": "string" }, "parent_organization_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Parent Organization Id" }, "type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Type" } }, "required": [ "id", "name" ], "title": "OrganizationSummary", "type": "object" }, "api_service__models__photo_faces__DismissResponse": {}, "api_service__models__profile__FamilyMemberCreate": { "description": "Request model for creating a family member.", "properties": { "date_of_birth": { "anyOf": [ { "format": "date", "type": "string" }, { "type": "null" } ], "description": "Date of birth", "title": "Date Of Birth" }, "email": { "anyOf": [ { "maxLength": 320, "type": "string" }, { "type": "null" } ], "description": "Email address", "title": "Email" }, "full_name": { "description": "Full name", "maxLength": 255, "minLength": 1, "title": "Full Name", "type": "string" }, "gender": { "anyOf": [ { "pattern": "^(male|female|other|prefer_not_to_say)$", "type": "string" }, { "type": "null" } ], "description": "Gender: male, female, other, prefer_not_to_say", "title": "Gender" }, "phone": { "anyOf": [ { "maxLength": 50, "type": "string" }, { "type": "null" } ], "description": "Phone number", "title": "Phone" }, "relationship": { "description": "Relationship to user", "pattern": "^(spouse|partner|child|parent|grandparent|sibling|other)$", "title": "Relationship", "type": "string" } }, "required": [ "full_name", "relationship" ], "title": "FamilyMemberCreate", "type": "object" }, "api_service__models__profile__FamilyMemberResponse": {}, "api_service__models__project__DismissSuggestionResponse": {}, "api_service__models__task_dependency__TaskSummary": { "description": "Lightweight task info included in dependency listings.", "properties": { "id": { "title": "Id", "type": "string" }, "status": { "title": "Status", "type": "string" }, "title": { "title": "Title", "type": "string" } }, "required": [ "id", "title", "status" ], "title": "TaskSummary", "type": "object" }, "api_service__models__template_install__ApplyRequest": { "description": "Apply a template. ``conflict_overrides`` maps a definition ref to a\nresolution ('rename'); refs not listed use the default skip-existing policy.", "properties": { "conflict_overrides": { "additionalProperties": { "type": "string" }, "title": "Conflict Overrides", "type": "object" } }, "title": "ApplyRequest", "type": "object" }, "api_service__models__template_install__UninstallRequest": { "description": "cascade_facet_refs = archive-eligible facet refs the user opted to fully\nremove (definition + user instances), after the preview showed exact counts.", "properties": { "cascade_facet_refs": { "items": { "type": "string" }, "title": "Cascade Facet Refs", "type": "array" } }, "title": "UninstallRequest", "type": "object" }, "api_service__routers__account__ChangePlanRequest": { "description": "Request model for changing plan.", "properties": { "plan_name": { "description": "New plan tier id: core, plus, max", "title": "Plan Name", "type": "string" } }, "required": [ "plan_name" ], "title": "ChangePlanRequest", "type": "object" }, "api_service__routers__admin_chat_emoji__OkResponse": {}, "api_service__routers__admin_chat_retention__OkResponse": {}, "api_service__routers__admin_play_review_queue__RejectBody": { "properties": { "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Reason" } }, "title": "RejectBody", "type": "object" }, "api_service__routers__admin_recipe_engine__AuditListResponse": {}, "api_service__routers__ai_chat__OkResponse": { "properties": { "ok": { "default": true, "title": "Ok", "type": "boolean" } }, "title": "OkResponse", "type": "object" }, "api_service__routers__analytics__narrative__DismissResponse": { "properties": { "dismissed": { "title": "Dismissed", "type": "boolean" } }, "required": [ "dismissed" ], "title": "DismissResponse", "type": "object" }, "api_service__routers__analytics__narrative__GenerateRequest": { "properties": { "period": { "default": "week", "title": "Period", "type": "string" } }, "title": "GenerateRequest", "type": "object" }, "api_service__routers__audit__AuditListResponse": {}, "api_service__routers__billing_stripe__ChangePlanRequest": { "properties": { "billing_interval": { "title": "Billing Interval", "type": "string" }, "plan_id": { "title": "Plan Id", "type": "string" } }, "required": [ "plan_id", "billing_interval" ], "title": "ChangePlanRequest", "type": "object" }, "api_service__routers__calendar_schedule__ScheduleRequest": { "description": "POST body for the schedule endpoints.\n\nThe payload shape is validated at dispatch time per the method value.", "properties": { "method": { "enum": [ "to_week", "to_day", "to_time", "unschedule" ], "title": "Method", "type": "string" }, "payload": { "additionalProperties": true, "title": "Payload", "type": "object" } }, "required": [ "method" ], "title": "ScheduleRequest", "type": "object" }, "api_service__routers__cards__ErrorResponse": { "description": "Error response.", "properties": { "details": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "Additional context", "title": "Details" }, "error": { "description": "Error code", "title": "Error", "type": "string" }, "message": { "description": "Human-readable error message", "title": "Message", "type": "string" } }, "required": [ "error", "message" ], "title": "ErrorResponse", "type": "object" }, "api_service__routers__channels__OkResponse": {}, "api_service__routers__chat_relay__CreateDmRequest": { "properties": { "assistant": { "default": false, "title": "Assistant", "type": "boolean" }, "member_account_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Member Account Id" } }, "title": "CreateDmRequest", "type": "object" }, "api_service__routers__chat_relay__CreateDmResponse": {}, "api_service__routers__chat_summarization__PromoteRequest": { "properties": { "folder_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Folder Id" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Title" } }, "title": "PromoteRequest", "type": "object" }, "api_service__routers__contacts__recent__RecentContact": {}, "api_service__routers__contacts__recent__RecentContactsResponse": {}, "api_service__routers__contacts__sync__SyncStatusResponse": { "description": "Overall sync status across all sources.", "properties": { "google": { "$ref": "#/components/schemas/SyncSourceStatus" }, "google_directory": { "$ref": "#/components/schemas/SyncSourceStatus" } }, "required": [ "google" ], "title": "SyncStatusResponse", "type": "object" }, "api_service__routers__cross_account__AuditListResponse": { "properties": { "entries": { "items": { "$ref": "#/components/schemas/AuditEntryResponse" }, "title": "Entries", "type": "array" }, "total": { "title": "Total", "type": "integer" } }, "required": [ "entries", "total" ], "title": "AuditListResponse", "type": "object" }, "api_service__routers__defense_suggestions__DismissResponse": { "properties": { "durable": { "title": "Durable", "type": "boolean" }, "status": { "title": "Status", "type": "string" } }, "required": [ "status", "durable" ], "title": "DismissResponse", "type": "object" }, "api_service__routers__drafts__CreateDraftRequest": { "description": "Body for ``POST /api/v1/drafts/{primitive_kind}``.\n\n``id`` MUST be supplied by the caller. For mobile + web parity, the\ndeterministic-id generator (S2) computes a stable UUID locally so the\nclient and server agree on the row's identity from keystroke 1.", "properties": { "id": { "description": "Client-supplied draft row id", "format": "uuid", "title": "Id", "type": "string" }, "initial_fields": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "Optional bootstrap overrides applied to the row at INSERT time. Unknown keys for the given primitive are silently ignored.", "title": "Initial Fields" } }, "required": [ "id" ], "title": "CreateDraftRequest", "type": "object" }, "api_service__routers__email_image_proxy___BinaryStreamResponse": { "description": "Marker response model for binary image bodies (OpenAPI contract only).", "properties": {}, "title": "_BinaryStreamResponse", "type": "object" }, "api_service__routers__emails__ai_models__SnoozeRequest": { "description": "Request to snooze a follow-up.", "properties": { "snooze_days": { "default": 7, "maximum": 30.0, "minimum": 1.0, "title": "Snooze Days", "type": "integer" } }, "title": "SnoozeRequest", "type": "object" }, "api_service__routers__emails__compose_contacts__RecentContact": { "description": "A recently contacted email address.", "properties": { "avatar_schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Custom vector avatar schema (JSON string)", "title": "Avatar Schema" }, "contact_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Matched contact UUID (avatar seed), if the address is a contact", "title": "Contact Id" }, "email": { "description": "Email address", "title": "Email", "type": "string" }, "icon": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "User-set unified icon value", "title": "Icon" }, "last_sent": { "description": "Most recent send timestamp", "format": "date-time", "title": "Last Sent", "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Display name if known", "title": "Name" }, "photo_source": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Photo provenance discriminator", "title": "Photo Source" }, "photo_thumbnail": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Inline photo thumbnail (data URL)", "title": "Photo Thumbnail" }, "photo_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Contact photo URL", "title": "Photo Url" }, "send_count": { "description": "Number of times contacted", "title": "Send Count", "type": "integer" } }, "required": [ "email", "send_count", "last_sent" ], "title": "RecentContact", "type": "object" }, "api_service__routers__emails__compose_contacts__RecentContactsResponse": { "description": "Response for recently contacted list.", "properties": { "contacts": { "description": "Recently contacted addresses", "items": { "$ref": "#/components/schemas/api_service__routers__emails__compose_contacts__RecentContact" }, "title": "Contacts", "type": "array" } }, "required": [ "contacts" ], "title": "RecentContactsResponse", "type": "object" }, "api_service__routers__emails__compose_models__CreateDraftRequest": { "additionalProperties": false, "description": "Request body for creating a new email draft.", "properties": { "bcc_recipients": { "description": "BCC recipients", "items": { "$ref": "#/components/schemas/EmailRecipient" }, "title": "Bcc Recipients", "type": "array" }, "body_html": { "default": "", "description": "HTML body content", "title": "Body Html", "type": "string" }, "body_markdown": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The body as Markdown; raw HTML in it stays text. The server renders it into body_prosemirror, body_html and body_text, so send it instead of those three. A reply's or forward's quoted original is kept below it.", "title": "Body Markdown" }, "body_prosemirror": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "Authoritative ProseMirror doc for the compose body (TIDY-8977 S10). When supplied, the send pipeline renders this via EmailRenderer to produce email-safe HTML at send time; body_html is ignored. The field is also persisted for re-edit so the editor can rehydrate.", "title": "Body Prosemirror" }, "body_text": { "default": "", "description": "Plain text body content", "title": "Body Text", "type": "string" }, "cc_recipients": { "description": "CC recipients", "items": { "$ref": "#/components/schemas/EmailRecipient" }, "title": "Cc Recipients", "type": "array" }, "compose_type": { "default": "new", "description": "Type: new, reply, reply_all, forward, reply_private", "title": "Compose Type", "type": "string" }, "project_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "description": "Associated project for drafts created from a project workspace", "title": "Project Id" }, "reply_to_email_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "description": "Email ID this is a reply to", "title": "Reply To Email Id" }, "subject": { "default": "", "description": "Email subject", "title": "Subject", "type": "string" }, "to_recipients": { "description": "To recipients", "items": { "$ref": "#/components/schemas/EmailRecipient" }, "title": "To Recipients", "type": "array" } }, "title": "CreateDraftRequest", "type": "object" }, "api_service__routers__emails__compose_send_as__SendAsAddress": { "description": "A single send-as address from a provider connection.\n\nField names match what the frontend expects directly.", "properties": { "display_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Display name for this address", "title": "Display Name" }, "email": { "description": "Email address", "title": "Email", "type": "string" }, "is_alias": { "description": "True if this is an alias, not the primary address", "title": "Is Alias", "type": "boolean" }, "is_default": { "default": false, "description": "True if this is the default send-as address", "title": "Is Default", "type": "boolean" }, "provider": { "description": "Provider type (google, zoho, microsoft, etc.)", "title": "Provider", "type": "string" }, "provider_connection_id": { "description": "UUID of the provider connection", "title": "Provider Connection Id", "type": "string" } }, "required": [ "provider_connection_id", "provider", "email", "is_alias" ], "title": "SendAsAddress", "type": "object" }, "api_service__routers__emails__subject_suggestion__DismissSuggestionResponse": { "properties": { "email_id": { "format": "uuid", "title": "Email Id", "type": "string" }, "suggested_subject": { "title": "Suggested Subject", "type": "null" } }, "required": [ "email_id" ], "title": "DismissSuggestionResponse", "type": "object" }, "api_service__routers__first_run_sync__SyncStatusResponse": { "description": "Unified sync status for a provider connection.", "properties": { "config_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Config Id" }, "connection_id": { "title": "Connection Id", "type": "string" }, "first_run_active": { "default": false, "title": "First Run Active", "type": "boolean" }, "overall_status": { "default": "idle", "title": "Overall Status", "type": "string" }, "phases": { "additionalProperties": { "$ref": "#/components/schemas/SyncPhaseStatus" }, "default": {}, "title": "Phases", "type": "object" } }, "required": [ "connection_id" ], "title": "SyncStatusResponse", "type": "object" }, "api_service__routers__generation__GenerateRequest": { "description": "Start one generation from a bundle.\n\nBoth fields default to the bundle's own binding: `facet_slug` to the output\ntype it was bound to, `instructions` to the stored override. Passing either\nsteers THIS run only — and never the modality, producer tier or target\nprimitive, which belong to the output type (D4).", "properties": { "confirm_estimate_fingerprint": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The `estimate_fingerprint` of the estimate the user was shown, echoed back (TIDY-17831 / R8). REQUIRED alongside `confirm_estimated_cost_micros` for an `expensive` output type. It must match a freshly computed estimate EXACTLY; any change to the sources, the reviewed instruction, the chosen options, the route or the breakdown returns 409 with the new estimate and creates no job — including when the price fell.", "title": "Confirm Estimate Fingerprint" }, "confirm_estimated_cost_micros": { "anyOf": [ { "minimum": 0.0, "type": "integer" }, { "type": "null" } ], "description": "The estimate the user was shown, echoed back. REQUIRED for an output type in the `expensive` cost class (TIDY-15710 / D19): a materially higher fresh estimate is refused with the new figure rather than committing the user to a price they never saw.", "title": "Confirm Estimated Cost Micros" }, "existing_primitive_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "When set, the T1 facet-instance producer enriches this note instead of minting a second one (TIDY-17380).", "title": "Existing Primitive Id" }, "facet_slug": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Output type to generate; defaults to the bundle's binding", "title": "Facet Slug" }, "instructions": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Free-text steering for this run; defaults to the bundle's override", "title": "Instructions" }, "producer_options": { "anyOf": [ { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "boolean" } ] }, "type": "object" }, { "type": "null" } ], "description": "The per-invocation choices this output type declares in `generation.invocation_fields` (TIDY-17830), keyed by field. Absent keys take the definition's defaults; an unknown key, a choice the field does not offer, a wrong scalar type, an over-long text or a field hidden by its `visible_when` rule is a named 422 and creates nothing. Omitting the whole map is valid and behaves exactly as it did before the field existed.", "title": "Producer Options" }, "seeded_fields": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "Caller-owned field values frozen onto the job snapshot and merged after extract (TIDY-17380 / S12 stub). Capture-owned keys such as episode id must arrive here; the model does not set them.", "title": "Seeded Fields" }, "style": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "One of the style presets this output type declares in `template_layout.style_presets`, for THIS run (TIDY-15713). Absent means the type's own default. A style the type does not offer is refused with the choices, never quietly defaulted.", "title": "Style" }, "surface": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Client surface that started the generation (observability)", "title": "Surface" }, "wiki_candidates": { "anyOf": [ { "additionalProperties": { "type": "string" }, "type": "object" }, { "type": "null" } ], "description": "Caller-supplied wiki-link map of display name → typed id (TIDY-17390 / S9). Frozen onto the job snapshot and unioned with the default resolver. Internal callers (podcast adapter) pass a bounded set; web generate may omit this and use the default only.", "title": "Wiki Candidates" } }, "title": "GenerateRequest", "type": "object" }, "api_service__routers__matrix_dm__CreateDmRequest": { "description": "Request body for POST /api/v1/matrix/dm.\n\n`target_account_ids` may include the sentinel \"@tidy-bot\" to add the bot\nexplicitly. The caller is implicitly added; passing the caller in the\nlist returns 400.", "properties": { "include_self": { "default": true, "title": "Include Self", "type": "boolean" }, "target_account_ids": { "items": { "type": "string" }, "maxItems": 49, "minItems": 1, "title": "Target Account Ids", "type": "array" } }, "required": [ "target_account_ids" ], "title": "CreateDmRequest", "type": "object" }, "api_service__routers__matrix_dm__CreateDmResponse": { "properties": { "created_at": { "title": "Created At", "type": "string" }, "deduplicated": { "title": "Deduplicated", "type": "boolean" }, "id": { "title": "Id", "type": "string" }, "name": { "title": "Name", "type": "string" }, "participants": { "items": { "$ref": "#/components/schemas/DmParticipantResponse" }, "title": "Participants", "type": "array" }, "room_id": { "title": "Room Id", "type": "string" }, "room_type": { "default": "dm", "title": "Room Type", "type": "string" } }, "required": [ "id", "room_id", "name", "participants", "deduplicated", "created_at" ], "title": "CreateDmResponse", "type": "object" }, "api_service__routers__matrix_message_management__OkResponse": { "properties": { "ok": { "default": true, "title": "Ok", "type": "boolean" } }, "title": "OkResponse", "type": "object" }, "api_service__routers__notes__versions___BinaryStreamResponse": { "description": "Marker response model for binary streams (see storage_proxy.py).", "properties": {}, "title": "_BinaryStreamResponse", "type": "object" }, "api_service__routers__notes__yjs_bulk_upload__ApplyRequest": { "properties": { "entries": { "items": { "$ref": "#/components/schemas/UploadEntry" }, "title": "Entries", "type": "array" } }, "required": [ "entries" ], "title": "ApplyRequest", "type": "object" }, "api_service__routers__oauth_admin__RevokeResponse": { "properties": { "ok": { "title": "Ok", "type": "boolean" } }, "required": [ "ok" ], "title": "RevokeResponse", "type": "object" }, "api_service__routers__onboarding__models__FamilyMembersListResponse": { "description": "Response model for listing family members saved during onboarding.", "properties": { "members": { "description": "Saved family members for this tenant", "items": { "$ref": "#/components/schemas/FamilyMemberRecord" }, "title": "Members", "type": "array" }, "total_count": { "description": "Total family members for tenant", "title": "Total Count", "type": "integer" } }, "required": [ "total_count" ], "title": "FamilyMembersListResponse", "type": "object" }, "api_service__routers__public_campaign_assets___AssetStreamResponse": { "description": "Placeholder schema — the endpoint streams raw bytes.", "properties": {}, "title": "_AssetStreamResponse", "type": "object" }, "api_service__routers__public_forms___AssetStreamResponse": { "description": "Marker model — the actual body is streamed asset bytes.", "properties": {}, "title": "_AssetStreamResponse", "type": "object" }, "api_service__routers__storage_proxy___BinaryStreamResponse": { "description": "Marker response model for binary streams.\n\nFastAPI requires a response_model to pass coverage checks; actual binary\nbodies are returned via :class:`~fastapi.responses.Response`. This type\nexists solely to satisfy the schema contract — generated SDKs treat it as\nan opaque body (see OpenAPI ``content: application/octet-stream``).", "properties": {}, "title": "_BinaryStreamResponse", "type": "object" }, "api_service__routers__trmnl__UninstallRequest": { "properties": { "user_uuid": { "title": "User Uuid", "type": "string" } }, "required": [ "user_uuid" ], "title": "UninstallRequest", "type": "object" }, "api_service__routers__upload__ErrorResponse": { "description": "Error response.", "properties": { "error": { "description": "Error code", "title": "Error", "type": "string" }, "message": { "description": "Human-readable error message", "title": "Message", "type": "string" } }, "required": [ "error", "message" ], "title": "ErrorResponse", "type": "object" }, "api_service__routers__ve_proposals__RejectBody": { "properties": { "reason": { "anyOf": [ { "maxLength": 2000, "type": "string" }, { "type": "null" } ], "title": "Reason" } }, "title": "RejectBody", "type": "object" }, "api_service__services__project_dedup_service__CheckDuplicateResponse": { "description": "Response for duplicate check.", "properties": { "has_duplicates": { "default": false, "description": "True if any project exceeds similarity threshold", "title": "Has Duplicates", "type": "boolean" }, "similar_projects": { "description": "List of similar existing projects", "items": { "$ref": "#/components/schemas/SimilarProject" }, "title": "Similar Projects", "type": "array" } }, "title": "CheckDuplicateResponse", "type": "object" }, "api_service__services__project_dedup_service__MergeRequest": { "description": "Request to merge projects.", "properties": { "source_ids": { "description": "UUIDs of projects to merge (will be archived)", "items": { "type": "string" }, "title": "Source Ids", "type": "array" }, "target_id": { "description": "UUID of target project (will receive all items)", "title": "Target Id", "type": "string" } }, "required": [ "source_ids", "target_id" ], "title": "MergeRequest", "type": "object" } }, "securitySchemes": { "HTTPBasic": { "scheme": "basic", "type": "http" }, "HTTPBearer": { "scheme": "bearer", "type": "http" }, "OAuth2": { "description": "OAuth 2.1 authorization-code flow. Scope definitions are authoritative here and in `tidy://schema/scopes`; bundles for common agent profiles are published as `x-tidy-scope-bundles`.", "flows": { "authorizationCode": { "authorizationUrl": "https://tidy.engineering/oauth/authorize", "scopes": { "activities:archive": "Archive and unarchive tasks and activities (reversible)", "admin:audit": "Read workspace-wide audit log", "admin:members": "Manage workspace members", "admin:workspace": "Manage workspace settings", "agent_control:write": "Send control events to running agents", "agent_ledger:read": "Query the operation ledger for your visible work", "agent_ledger:write": "Ingest captured operations into the ledger", "agent_sessions:read": "Read agent conversations", "agent_sessions:write": "Record agent conversations", "assistant:invoke": "Invoke the Tidy assistant from connected clients", "audit:read": "Read audit log entries", "calendar:delete": "Delete calendar events", "calendar:read": "Read your calendar events", "calendar:write": "Create and update calendar events", "chat:send": "Send chat messages on your behalf", "comments:read": "Read comments on your items", "comments:write": "Create and update comments", "contacts:read": "Read your contacts", "contacts:write": "Create and update contacts", "data:export": "Export your Tidy data as a downloadable archive", "data:import": "Import data into Tidy from external sources", "email:patch": "Update email read/star/label state", "email:read": "Read your emails", "email:send": "Send emails on your behalf", "email:triage": "Triage (screen, categorize) your inbox", "evidence:read": "Read agent evidence records", "evidence:write": "Record agent evidence", "facets:extract": "Extract facets from your content", "facets:manage": "Create and modify facet definitions (schemas)", "facets:read": "Read extracted facets (structured data)", "files:delete": "Delete files", "files:read": "Read your files", "files:write": "Upload and update files", "links:write": "Create and modify typed links between items", "memory:enrich": "Contribute derived facts to your shared memory", "memory:observe": "Record the agent's own episodic observations", "memory:recall": "Recall structured facets and relationships", "memory:search": "Search your memory graph", "mobile_devices:write": "Register mobile devices for notifications and sync", "notes:delete": "Delete notes", "notes:patch": "Update existing notes", "notes:read": "Read your notes", "notes:write": "Create new notes", "openapi:read": "Discover the Tidy API via OpenAPI spec", "podcast:generate": "Generate podcast episodes from your content", "podcast:read": "Read your podcast subscriptions and episodes", "podcast:write": "Subscribe to podcasts and manage your playlists and play queue", "primitives:read": "Read workspace primitives created from facets", "primitives:write": "Create and update workspace primitives", "projects:read": "Read your projects", "projects:write": "Create and update projects", "search:read": "Search your Tidy library", "sms:send": "Send SMS messages on your behalf", "tags:read": "Read your tag library", "tasks:read": "Read your tasks", "tasks:write": "Create and update tasks", "templates:manage": "Create, update, and delete templates", "tokens:manage": "Manage your API tokens", "views:manage": "Configure database views and saved views", "webhooks:manage": "Manage outbound webhook subscriptions", "workflow:cancel": "Cancel running workflows", "workflow:execute": "Execute workflows on your behalf", "workflow:status": "Check workflow status" }, "tokenUrl": "https://tidy.engineering/oauth/token" } }, "type": "oauth2" } } }, "info": { "description": "Tidy public REST API. This spec is the canonical contract — SDKs, the MCP adapter, and partner integrations all generate from it. See https://docs.tidy.engineering for guides.", "title": "Tidy API", "version": "1.0.0" }, "openapi": "3.1.0", "paths": { "/.well-known/assetlinks.json": { "get": { "description": "Serve Android App Links ownership statements for com.tidy.mobile.", "operationId": "android_assetlinks", "responses": { "200": { "content": { "application/json": { "schema": { "items": { "additionalProperties": true, "type": "object" }, "title": "Response Android Assetlinks", "type": "array" } } }, "description": "Successful Response" } }, "summary": "Android Assetlinks", "tags": [ "well-known", "well-known" ] } }, "/.well-known/jwks.json": { "get": { "operationId": "jwks", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JwksResponse" } } }, "description": "Successful Response" } }, "summary": "Jwks Endpoint", "tags": [ "oauth" ] } }, "/.well-known/oauth-authorization-server": { "get": { "description": "RFC 8414 OAuth Authorization Server Metadata.\n\nMCP clients (claude.ai, mcp-inspector) chain from the protected\nresource metadata's ``authorization_servers[0]`` to this endpoint to\ndiscover ``authorization_endpoint`` / ``token_endpoint`` /\n``registration_endpoint`` for the OAuth dance. Without this, the MCP\nOAuth flow fails before it begins.", "operationId": "oauthAuthorizationServer", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenIDConfigurationResponse" } } }, "description": "Successful Response" } }, "summary": "Oauth Authorization Server", "tags": [ "oauth" ] } }, "/.well-known/oauth-authorization-server/mcp": { "get": { "description": "RFC 8414 metadata under the ``/mcp`` suffix.\n\nSome MCP clients append the resource path to the AS metadata path\n(mirroring how ``oauth-protected-resource/mcp`` is segmented). We\nserve the same body so either discovery shape works.", "operationId": "oauthAuthorizationServerMcp", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenIDConfigurationResponse" } } }, "description": "Successful Response" } }, "summary": "Oauth Authorization Server Mcp", "tags": [ "oauth" ] } }, "/.well-known/oauth-clients": { "get": { "description": "List all registered static OAuth clients.\n\nPer MCP 2026-07-28, static client metadata is published at stable URLs\nso clients can fetch their configuration without DCR. This endpoint\nreturns the full registry; individual clients are served at\n/.well-known/oauth-clients/{client_id}.", "operationId": "listStaticClients", "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response" } }, "summary": "List Static Clients", "tags": [ "oauth" ] } }, "/.well-known/oauth-clients/{client_id}": { "get": { "description": "Serve the static client metadata document for client_id.\n\nPer MCP 2026-07-28, first-party agent clients fetch their metadata from\nthis stable URL instead of registering via /oauth/register. The OAuth\nserver accepts these clients on authorize + token paths without a\nDCR round-trip.", "operationId": "getStaticClientMetadata", "parameters": [ { "in": "path", "name": "client_id", "required": true, "schema": { "title": "Client Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Get Static Client Metadata", "tags": [ "oauth" ] } }, "/.well-known/oauth-protected-resource": { "get": { "operationId": "oauthProtectedResource", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProtectedResourceMetadataResponse" } } }, "description": "Successful Response" } }, "summary": "Oauth Protected Resource", "tags": [ "oauth" ] } }, "/.well-known/oauth-protected-resource/api/v1/mcp": { "get": { "description": "RFC 9728 path-form metadata for the MCP resource.\n\nFor a protected resource at ``https://host/api/v1/mcp``, RFC 9728 clients\ncan request ``https://host/.well-known/oauth-protected-resource/api/v1/mcp``.\nWe also keep the legacy ``/mcp`` shorthand above, but the path-form URL is\nwhat the Pi MCP client requested after successful OAuth authorization.", "operationId": "oauthProtectedResourceApiV1Mcp", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProtectedResourceMetadataResponse" } } }, "description": "Successful Response" } }, "summary": "Oauth Protected Resource Api V1 Mcp", "tags": [ "oauth" ] } }, "/.well-known/oauth-protected-resource/mcp": { "get": { "operationId": "oauthProtectedResourceMcp", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProtectedResourceMetadataResponse" } } }, "description": "Successful Response" } }, "summary": "Oauth Protected Resource Mcp", "tags": [ "oauth" ] } }, "/.well-known/openid-configuration": { "get": { "operationId": "openidConfiguration", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenIDConfigurationResponse" } } }, "description": "Successful Response" } }, "summary": "Openid Configuration", "tags": [ "oauth" ] } }, "/.well-known/{endpoint}": { "get": { "description": "Return 501 Not Implemented until F3 populates specific endpoints.", "operationId": "well_known_stub", "parameters": [ { "in": "path", "name": "endpoint", "required": true, "schema": { "title": "Endpoint", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Well Known Stub", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Well Known Stub", "tags": [ "well-known", "well-known" ] } }, "/agent-runtime/{path}": { "get": { "operationId": "getAgentRuntimeArtifact", "parameters": [ { "in": "path", "name": "path", "required": true, "schema": { "title": "Path", "type": "string" } }, { "in": "header", "name": "authorization", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Authorization" } }, { "in": "header", "name": "Range", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Range" } } ], "responses": { "200": { "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Get Agent Runtime Artifact", "tags": [ "agent-runtime" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/2/auth/{username}/login.json": { "post": { "operationId": "gpodderLogin", "parameters": [ { "in": "path", "name": "username", "required": true, "schema": { "title": "Username", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Gpodderlogin", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] }, { "HTTPBasic": [] } ], "summary": "Gpodder Login", "tags": [ "gpodder" ] } }, "/api/2/auth/{username}/logout.json": { "post": { "operationId": "gpodderLogout", "parameters": [ { "in": "path", "name": "username", "required": true, "schema": { "title": "Username", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Gpodderlogout", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] }, { "HTTPBasic": [] } ], "summary": "Gpodder Logout", "tags": [ "gpodder" ] } }, "/api/2/devices/{username}.json": { "get": { "operationId": "listGpodderDevices", "parameters": [ { "in": "path", "name": "username", "required": true, "schema": { "title": "Username", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/GpodderDeviceResponse" }, "title": "Response Listgpodderdevices", "type": "array" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] }, { "HTTPBasic": [] } ], "summary": "List Gpodder Devices", "tags": [ "gpodder" ] } }, "/api/2/devices/{username}/{device_id}.json": { "post": { "operationId": "updateGpodderDevice", "parameters": [ { "in": "path", "name": "username", "required": true, "schema": { "title": "Username", "type": "string" } }, { "in": "path", "name": "device_id", "required": true, "schema": { "title": "Device Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GpodderDeviceUpdateRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Updategpodderdevice", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] }, { "HTTPBasic": [] } ], "summary": "Update Gpodder Device", "tags": [ "gpodder" ] } }, "/api/2/episodes/{username}.json": { "get": { "operationId": "getGpodderEpisodeActions", "parameters": [ { "in": "path", "name": "username", "required": true, "schema": { "title": "Username", "type": "string" } }, { "in": "query", "name": "since", "required": false, "schema": { "anyOf": [ { "minimum": 0, "type": "integer" }, { "type": "null" } ], "title": "Since" } }, { "in": "query", "name": "podcast", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Podcast" } }, { "in": "query", "name": "device", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Device" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 500, "maximum": 2000, "minimum": 1, "title": "Limit", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GpodderEpisodesResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] }, { "HTTPBasic": [] } ], "summary": "Get Gpodder Episode Actions", "tags": [ "gpodder" ] }, "post": { "operationId": "postGpodderEpisodeActions", "parameters": [ { "in": "path", "name": "username", "required": true, "schema": { "title": "Username", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "title": "Payload" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GpodderUpdatedUrlsResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] }, { "HTTPBasic": [] } ], "summary": "Post Gpodder Episode Actions", "tags": [ "gpodder" ] } }, "/api/2/subscriptions/{username}/{device_id}.json": { "get": { "operationId": "getGpodderSubscriptionsDelta", "parameters": [ { "in": "path", "name": "username", "required": true, "schema": { "title": "Username", "type": "string" } }, { "in": "path", "name": "device_id", "required": true, "schema": { "title": "Device Id", "type": "string" } }, { "in": "query", "name": "since", "required": false, "schema": { "anyOf": [ { "minimum": 0, "type": "integer" }, { "type": "null" } ], "title": "Since" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GpodderSubscriptionsDeltaResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] }, { "HTTPBasic": [] } ], "summary": "Get Gpodder Subscriptions Delta", "tags": [ "gpodder" ] }, "post": { "operationId": "postGpodderSubscriptionsDelta", "parameters": [ { "in": "path", "name": "username", "required": true, "schema": { "title": "Username", "type": "string" } }, { "in": "path", "name": "device_id", "required": true, "schema": { "title": "Device Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GpodderSubscriptionChangesRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GpodderUpdatedUrlsResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] }, { "HTTPBasic": [] } ], "summary": "Post Gpodder Subscriptions Delta", "tags": [ "gpodder" ] } }, "/api/v1/access-scopes": { "post": { "operationId": "createResourceAccessScope", "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceScopeResponse" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Create Resource Access Scope", "tags": [ "access-scopes" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Owner-only configured sharing controls" } }, "/api/v1/access-scopes/{scope_id}/grants": { "post": { "operationId": "grantResourceAccessScope", "parameters": [ { "in": "path", "name": "scope_id", "required": true, "schema": { "format": "uuid", "title": "Scope Id", "type": "string" } }, { "in": "header", "name": "If-Match", "required": true, "schema": { "title": "If-Match", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceScopeGrantRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceScopeResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Grant Resource Access Scope", "tags": [ "access-scopes" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Owner-only configured sharing controls" } }, "/api/v1/access-scopes/{scope_id}/grants/{grant_id}": { "delete": { "operationId": "revokeResourceAccessScopeGrant", "parameters": [ { "in": "path", "name": "scope_id", "required": true, "schema": { "format": "uuid", "title": "Scope Id", "type": "string" } }, { "in": "path", "name": "grant_id", "required": true, "schema": { "format": "uuid", "title": "Grant Id", "type": "string" } }, { "in": "header", "name": "If-Match", "required": true, "schema": { "title": "If-Match", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceScopeResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Revoke Resource Access Scope Grant", "tags": [ "access-scopes" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Owner-only configured sharing controls" } }, "/api/v1/account/connection-policy": { "get": { "description": "Return the current tenant's connection policy.\n\nReturns a default unrestricted policy if no row exists.", "operationId": "getConnectionPolicy", "parameters": [ { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectionPolicyResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get account connection policy", "tags": [ "connection-policy", "connection-policy" ] }, "put": { "description": "Update the tenant's connection policy. Requires Owner or Admin role.", "operationId": "updateConnectionPolicy", "parameters": [ { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectionPolicyUpdateRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectionPolicyResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Update account connection policy", "tags": [ "connection-policy", "connection-policy" ] } }, "/api/v1/account/delete": { "post": { "description": "Create or join a durable account-erasure operation. Returns 202 with an operation receipt. External provider erasure never runs in this request. Both modes require session-bound recent authentication. Set immediate to queue execution now; the default is a 7-day cancellable grace period.", "operationId": "requestAccountDeletion", "parameters": [ { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScheduleDeletionRequest" } } }, "required": true }, "responses": { "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeletionScheduleResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Schedule account deletion", "tags": [ "account" ], "x-mcp-skip": true } }, "/api/v1/account/delete/cancel": { "post": { "description": "Cancel a pending deletion within the grace period (TIDY-7383).", "operationId": "cancelAccountDeletion", "parameters": [ { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelDeletionResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Cancel scheduled account deletion", "tags": [ "account" ], "x-mcp-skip": true } }, "/api/v1/account/delete/preflight": { "get": { "description": "Read-only plan of what account erasure would do: target classes, retained-category names, and ownership-transfer or policy blockers. Does not create an operation or delete anything.", "operationId": "getAccountDeletionPreflight", "parameters": [ { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeletionPreflightResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Preview account deletion scope", "tags": [ "account" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/account/delete/status": { "get": { "description": "Returns the most recent deletion schedule (pending, cancelled or executed) for the current account. Used by settings UI to reflect pending grace period (TIDY-7383).", "operationId": "getAccountDeletionStatus", "parameters": [ { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeletionStatusResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get account deletion status", "tags": [ "account" ], "x-mcp-skip": true } }, "/api/v1/account/delete/status/receipt": { "get": { "description": "Independent status lookup after the session is torn down.", "operationId": "getAccountDeletionStatusByReceipt", "parameters": [ { "in": "query", "name": "token", "required": true, "schema": { "minLength": 16, "title": "Token", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeletionStatusResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Get account deletion status by receipt", "tags": [ "account" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/account/email-preferences": { "get": { "description": "Returns the tenant default-send-as plus per-user OOO + signature template bindings.", "operationId": "getEmailPreferences", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailPreferencesResponse" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get email preferences", "tags": [ "email-preferences", "email-preferences" ] }, "patch": { "description": "Partial update of tenant + per-user email preferences. OOO and signature `*_template_id` fields are validated against the email facet (422 on mismatch).", "operationId": "patchEmailPreferences", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailPreferencesPatch" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailPreferencesResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Patch email preferences", "tags": [ "email-preferences", "email-preferences" ] }, "put": { "description": "Replace the tenant default-send-as. Backwards-compatible path.", "operationId": "updateEmailPreferences", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailPreferencesUpdate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailPreferencesResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Set tenant default send-as", "tags": [ "email-preferences", "email-preferences" ] } }, "/api/v1/account/email-signature/resolve": { "post": { "description": "Returns the rendered signature the send pipeline would append for these recipients, without sending anything. Clients that show the signature in the composer (Android, TIDY-15634) call this so the internal/external slot decision stays server-side — the same classification the send path uses — and then send with suppress_signature=true.", "operationId": "resolveEmailSignature", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignatureResolveRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignatureResolveResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Resolve the signature for a recipient set", "tags": [ "email-preferences", "email-preferences" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/account/export": { "post": { "description": "Request a GDPR-compliant data export.\n\n Creates an export job that will compile all user data.\n Use GET /account/export/{job_id} to check status.\n\n Related: 011-auth-user-onboarding T063", "operationId": "requestDataExport", "parameters": [ { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataExportRequest" } } }, "required": true }, "responses": { "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataExportResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Request data export", "tags": [ "account" ] } }, "/api/v1/account/export/{job_id}": { "get": { "description": "Check status of a data export job.\n\n Returns download URL when complete.\n\n Related: 011-auth-user-onboarding T064", "operationId": "getExportStatus", "parameters": [ { "in": "path", "name": "job_id", "required": true, "schema": { "title": "Job Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataExportResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get export status", "tags": [ "account" ] } }, "/api/v1/account/password": { "post": { "description": "Change the user's password.\n\n Requires current password for verification.\n Password must be at least 8 characters.\n\n Related: 011-auth-user-onboarding T062", "operationId": "changePassword", "parameters": [ { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangePasswordRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangePasswordResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Change password", "tags": [ "account" ] } }, "/api/v1/account/plan": { "get": { "description": "Get the current user's subscription plan and feature access.\n\n Returns the real plan tier id (core/plus/max), whether bulk import is\n enabled, and the list of enabled features — all resolved through the\n entitlement resolver. Used by desktop bridge app to verify feature access.", "operationId": "getAccountPlan", "parameters": [ { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountPlanResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get account plan", "tags": [ "account" ] }, "post": { "description": "Change the user's subscription plan.\n\n Updates the plan_tier in the tenant record.\n For development/testing - bypasses payment processing.", "operationId": "changeAccountPlan", "parameters": [ { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_service__routers__account__ChangePlanRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountPlanResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Change account plan", "tags": [ "account" ] } }, "/api/v1/account/security/device-status": { "get": { "description": "Report whether THIS device (this token) has been revoked and must wipe.\n\nThe client polls this on connect/reconnect. wipe_required is true when the\ntoken's issued-at predates the account's forced-wipe epoch — the signal a\nrevoked device uses to clear its local SQLite before it loses sync entirely.", "operationId": "getDeviceStatus", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeviceStatusResponse" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Whether this device must wipe its local data", "tags": [ "security" ], "x-mcp-skip": true } }, "/api/v1/account/security/revoke-devices": { "post": { "description": "Sign out every device for the current account and arm a forced wipe.\n\nCascades refresh-family revocation (existing session-revocation machinery)\nso no device can refresh its short-lived sync token, then stamps\n``accounts.sessions_wiped_at`` so every pre-revocation device wipes its\nlocal plaintext on reconnect.", "operationId": "revokeDevices", "parameters": [ { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevokeDevicesResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Revoke all of my devices and force a remote wipe", "tags": [ "security" ], "x-mcp-skip": true } }, "/api/v1/account/security/sessions": { "get": { "operationId": "listSignedInSessions", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedInSessionsResponse" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List the devices and apps signed in to my account", "tags": [ "security" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/account/security/sessions/{family_id}/revoke": { "post": { "operationId": "revokeSignedInSession", "parameters": [ { "in": "path", "name": "family_id", "required": true, "schema": { "format": "uuid", "title": "Family Id", "type": "string" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Sign one device or app out of my account", "tags": [ "security" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/account/usage/by-kind": { "get": { "description": "Return per-`usage_kind` aggregation for the calling account.\n\nScoped by `tenant_id` (NOT `account_id`) on `llm_usage_logs` because\nthe table doesn't carry an `account_id` column today — webhook calls\nonly know the tenant. The privacy AC (R4 AC2) is honored at the auth\nlayer (caller can only fetch their own tenant's usage; we don't\ndistinguish per-member spend within a tenant yet).", "operationId": "getAccountUsageByKind", "parameters": [ { "description": "'current' | 'previous' | YYYY-MM (e.g. '2026-04')", "in": "query", "name": "period", "required": false, "schema": { "default": "current", "description": "'current' | 'previous' | YYYY-MM (e.g. '2026-04')", "title": "Period", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountUsageByKindResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Per-account LLM usage breakdown by usage_kind", "tags": [ "account-usage" ] } }, "/api/v1/account/voice-preference": { "get": { "description": "Return the caller's own persona voice: gender, voice, engine, speed.", "operationId": "getAccountVoicePreference", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoicePreference" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get the caller's own persona voice preference", "tags": [ "account-voice", "account-voice" ], "x-mcp-skip": true }, "put": { "description": "Persist the caller's own persona voice and echo the stored values.\n\nA caller may only write its OWN preference — the account id comes from the\nverified bearer, never from the request body.", "operationId": "setAccountVoicePreference", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoicePreference" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoicePreference" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Set the caller's own persona voice preference", "tags": [ "account-voice", "account-voice" ], "x-mcp-skip": true } }, "/api/v1/accounts/me": { "get": { "description": "Returns the authenticated caller's account profile including timezone identity fields. If the account is still at the post-migration UTC sentinel and the caller provides `browser_tz`, we silently seed the fields to the detected zone and stamp `timezone_auto_detected_at`. Works for operators with no tenant membership (TIDY-17775).", "operationId": "getMe", "parameters": [ { "description": "IANA zone from the caller's browser. Used only for silent first-login seeding; ignored once the account has any non-default timezone state.", "in": "query", "name": "browser_tz", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "IANA zone from the caller's browser. Used only for silent first-login seeding; ignored once the account has any non-default timezone state.", "title": "Browser Tz" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountMe" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get the caller's account profile", "tags": [ "accounts-me" ] }, "patch": { "description": "Partial update. Currently supports `home_timezone` and `active_timezone`. Non-IANA values return 400. Works for operators with no tenant membership (TIDY-17775).", "operationId": "updateMe", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountMeUpdate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountMe" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Update the caller's timezone identity", "tags": [ "accounts-me" ] } }, "/api/v1/accounts/phone-numbers": { "get": { "operationId": "listAccountPhoneNumbers", "parameters": [ { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PhoneNumberListResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List account phone numbers", "tags": [ "phone-numbers" ] }, "post": { "operationId": "createAccountPhoneNumber", "parameters": [ { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PhoneNumberCreate" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PhoneNumberResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Create account phone number", "tags": [ "phone-numbers" ] } }, "/api/v1/accounts/phone-numbers/{phone_id}": { "delete": { "operationId": "deleteAccountPhoneNumber", "parameters": [ { "in": "path", "name": "phone_id", "required": true, "schema": { "format": "uuid", "title": "Phone Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Delete account phone number", "tags": [ "phone-numbers" ] }, "patch": { "operationId": "updateAccountPhoneNumber", "parameters": [ { "in": "path", "name": "phone_id", "required": true, "schema": { "format": "uuid", "title": "Phone Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PhoneNumberUpdate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PhoneNumberResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Update account phone number", "tags": [ "phone-numbers" ] } }, "/api/v1/activities": { "get": { "description": "List activities for authenticated user's tenant with filtering.", "operationId": "listActivities", "parameters": [ { "in": "query", "name": "status", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Status" } }, { "in": "query", "name": "category", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Category" } }, { "in": "query", "name": "priority", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Priority" } }, { "description": "Filter by applied facet slug", "in": "query", "name": "facet_slug", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by applied facet slug", "title": "Facet Slug" } }, { "in": "query", "name": "project_id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Project Id" } }, { "in": "query", "name": "owner", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Owner" } }, { "in": "query", "name": "is_recurring", "required": false, "schema": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is Recurring" } }, { "in": "query", "name": "snoozed", "required": false, "schema": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Snoozed" } }, { "in": "query", "name": "approval_status", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Approval Status" } }, { "in": "query", "name": "has_due_datetime", "required": false, "schema": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Has Due Datetime" } }, { "in": "query", "name": "due_date_lte", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Due Date Lte" } }, { "in": "query", "name": "search", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Search" } }, { "description": "Sort order. One of: score, due_date, updated_at, created_at, start, title, due_date_asc, due_date_desc, created_desc, created_asc, priority_desc. priority_desc follows the facet's own priority options, first option first. Omitted: newest created first.", "in": "query", "name": "sort_by", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Sort order. One of: score, due_date, updated_at, created_at, start, title, due_date_asc, due_date_desc, created_desc, created_asc, priority_desc. priority_desc follows the facet's own priority options, first option first. Omitted: newest created first.", "title": "Sort By" } }, { "description": "Include archived activities (excluded from default surfaces).", "in": "query", "name": "include_archived", "required": false, "schema": { "default": false, "description": "Include archived activities (excluded from default surfaces).", "title": "Include Archived", "type": "boolean" } }, { "description": "Projection: 'compact' returns the agent field set (id, short_id, title, status, priority, category, project/parent, owner, due, archived, updated_at) — no bodies or facet payloads. 'full' (default) returns the complete shape. (TIDY-14996)", "in": "query", "name": "fields", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Projection: 'compact' returns the agent field set (id, short_id, title, status, priority, category, project/parent, owner, due, archived, updated_at) — no bodies or facet payloads. 'full' (default) returns the complete shape. (TIDY-14996)", "title": "Fields" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 100, "maximum": 1000, "minimum": 1, "title": "Limit", "type": "integer" } }, { "in": "query", "name": "offset", "required": false, "schema": { "default": 0, "minimum": 0, "title": "Offset", "type": "integer" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Listactivities", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List activities with filtering", "tags": [ "activities", "Activities" ] }, "post": { "description": "Create a new activity. Auto-sets owner to the request principal when not provided.", "operationId": "createActivity", "parameters": [ { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActivityCreate" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActivityResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Create new activity", "tags": [ "activities" ] } }, "/api/v1/activities/archive-bulk": { "post": { "description": "Archive a batch. Every id gets an explicit outcome — no silent partials.", "operationId": "archiveActivitiesBulk", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActivityArchiveBulkRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActivityArchiveBulkResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Archive multiple activities with per-id outcomes", "tags": [ "activities" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/activities/by-short-id/{short_id}": { "get": { "description": "Exact-match resolution of a stored short ID (R5).\n\nThe identity is immutable: any historically minted ID resolves to its\nrecord regardless of the record's current project. Archived records\nresolve (the response carries ``archived``/``archived_at``).", "operationId": "resolveActivityByShortId", "parameters": [ { "in": "path", "name": "short_id", "required": true, "schema": { "title": "Short Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActivityResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Resolve an activity by its immutable short ID", "tags": [ "activities" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/activities/claimable": { "get": { "description": "Called at wake time (event-driven — never in a polling loop).", "operationId": "listClaimableActivities", "parameters": [ { "in": "query", "name": "ready_status", "required": false, "schema": { "default": "ready_build", "maxLength": 64, "title": "Ready Status", "type": "string" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 25, "maximum": 100, "minimum": 1, "title": "Limit", "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cursor" } }, { "description": "Typed ID with prefix 'P' (or bare UUID during deprecation)", "in": "query", "name": "project_id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Typed ID with prefix 'P' (or bare UUID during deprecation)", "title": "Project Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClaimableResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Ready, unclaimed, unblocked tasks for agent pull", "tags": [ "activities" ], "x-local-capability": "cloud" } }, "/api/v1/activities/commitments-dashboard": { "get": { "description": "Returns owed/owing counts and top-5 lists per direction. Replaces the deprecated /api/v1/commitments/dashboard (TIDY-8945).", "operationId": "getCommitmentsDashboard", "parameters": [ { "in": "header", "name": "X-Trace-Id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommitmentDashboardResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Dashboard summary for commitment-flavored activities", "tags": [ "activities", "activities" ] } }, "/api/v1/activities/complete-bulk": { "post": { "description": "Per-id results; each id's cascade is its own transaction — a single\nrecord's cascade is never partially applied (R7 negative AC).", "operationId": "completeActivitiesBulk", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompleteBulkRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompleteBulkResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Bulk hierarchy-aware completion (per-id transactions)", "tags": [ "activities" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/activities/recalculate-scores": { "post": { "description": "Recompute score cache for tenant activities.", "operationId": "recalculateScores", "parameters": [ { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActivityScoreRecalculateRequest" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActivityScoreRecalculateResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Recalculate cached activity scores", "tags": [ "activities" ] } }, "/api/v1/activities/ve-queue-depth": { "get": { "description": "Queue depth per VE (TIDY-16719 / R10): open tasks each agent member\nowns, how many are under a live claim, and the oldest unclaimed task —\nwhat the Manager's dashboards read to flag work sitting past SLA.", "operationId": "getVeQueueDepth", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VeQueueDepthResponse" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Per-virtual-employee open/claimed task counts", "tags": [ "activities" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/activities/{activity_id}": { "delete": { "description": "Soft delete activity.", "operationId": "deleteActivity", "parameters": [ { "description": "Typed ID with prefix 'A'", "in": "path", "name": "activity_id", "required": true, "schema": { "description": "Typed ID with prefix 'A'", "title": "Activity Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Delete activity", "tags": [ "activities" ] }, "get": { "description": "Get activity details by ID with attachments and active comments.", "operationId": "getActivity", "parameters": [ { "description": "Typed ID with prefix 'A'", "in": "path", "name": "activity_id", "required": true, "schema": { "description": "Typed ID with prefix 'A'", "title": "Activity Id", "type": "string" } }, { "description": "Include resolved comments (TIDY-14992 D18). The default compact read carries unresolved discussion only.", "in": "query", "name": "include_resolved", "required": false, "schema": { "default": false, "description": "Include resolved comments (TIDY-14992 D18). The default compact read carries unresolved discussion only.", "title": "Include Resolved", "type": "boolean" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActivityResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get activity details", "tags": [ "activities" ] }, "patch": { "description": "Update activity using PATCH.", "operationId": "updateActivityPatch", "parameters": [ { "description": "Typed ID with prefix 'A'", "in": "path", "name": "activity_id", "required": true, "schema": { "description": "Typed ID with prefix 'A'", "title": "Activity Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActivityUpdate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActivityResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Update activity (partial update)", "tags": [ "activities" ] }, "put": { "description": "Update activity using PUT.", "operationId": "updateActivityPut", "parameters": [ { "description": "Typed ID with prefix 'A'", "in": "path", "name": "activity_id", "required": true, "schema": { "description": "Typed ID with prefix 'A'", "title": "Activity Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActivityUpdate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActivityResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Update activity (full replace)", "tags": [ "activities" ] } }, "/api/v1/activities/{activity_id}/archive": { "post": { "description": "Archive an activity. Idempotent — re-archiving keeps the original audit pair.", "operationId": "archiveActivity", "parameters": [ { "description": "Typed ID with prefix 'A'", "in": "path", "name": "activity_id", "required": true, "schema": { "description": "Typed ID with prefix 'A'", "title": "Activity Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActivityArchiveResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Archive an activity (reversible, never deletes)", "tags": [ "activities" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/activities/{activity_id}/assign": { "post": { "description": "The one door through which an employee may assign work to another\nemployee (TIDY-17344 / F3): authorized on the item, recorded with the\nassigning employee, and spawning nothing — the assignee picks the work up\non its own wake.", "operationId": "assignActivityAsEmployee", "parameters": [ { "description": "Typed ID with prefix 'A'", "in": "path", "name": "activity_id", "required": true, "schema": { "description": "Typed ID with prefix 'A'", "title": "Activity Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssignRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssignResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Assign an item to a member or employee, as an employee", "tags": [ "activities" ], "x-local-capability": "cloud" } }, "/api/v1/activities/{activity_id}/backlinks": { "get": { "description": "Get all pages/primitives that link TO this activity.", "operationId": "getActivityBacklinks", "parameters": [ { "description": "Typed ID with prefix 'A'", "in": "path", "name": "activity_id", "required": true, "schema": { "description": "Typed ID with prefix 'A'", "title": "Activity Id", "type": "string" } }, { "in": "query", "name": "search", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Search" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "maximum": 200, "minimum": 1, "title": "Limit", "type": "integer" } }, { "description": "Include backlinks authored by archived activities", "in": "query", "name": "include_archived", "required": false, "schema": { "default": false, "description": "Include backlinks authored by archived activities", "title": "Include Archived", "type": "boolean" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Getactivitybacklinks", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "The linked-reference read FAILED — problem+json with `code: links_unavailable` (retryable). Distinct from a 200 carrying an empty list, which means there genuinely are no backlinks (TIDY-16299)." } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get items that link to this activity", "tags": [ "activities" ] } }, "/api/v1/activities/{activity_id}/body/edits": { "post": { "description": "Pins ``A-<activity_id>`` and delegates to the one coordinator.", "operationId": "applyActivityBodyEdits", "parameters": [ { "description": "Typed ID with prefix 'A'", "in": "path", "name": "activity_id", "required": true, "schema": { "description": "Typed ID with prefix 'A'", "title": "Activity Id", "type": "string" } }, { "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Idempotency-Key" } }, { "in": "header", "name": "X-Tidy-Acting-Principal", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tidy-Acting-Principal" } }, { "in": "header", "name": "X-Internal-Service", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service" } }, { "in": "header", "name": "X-Internal-Service-Key", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service-Key" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BodyEditsRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BodyEditsResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Apply diff edits (CRDT) to the task's collaborative body", "tags": [ "activities" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Legacy wire-compat adapter for external callers. MCP/assistant clients use POST /api/v1/primitives/{typed_id}/content/edits." } }, "/api/v1/activities/{activity_id}/bounce": { "post": { "description": "Routes to the recorded assigner, else to the employee's owner. The\nitem keeps its state and gains a visible bounce note; it is never left\nunassigned, and nothing is retried automatically.", "operationId": "bounceActivity", "parameters": [ { "description": "Typed ID with prefix 'A'", "in": "path", "name": "activity_id", "required": true, "schema": { "description": "Typed ID with prefix 'A'", "title": "Activity Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BounceRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BounceResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Hand an item back — the assignee cannot complete it", "tags": [ "activities" ], "x-local-capability": "cloud" } }, "/api/v1/activities/{activity_id}/claim": { "post": { "description": "Exactly one agent wins; the loser gets 409 with the current holder.\nRe-claim by the holder extends the lease (idempotent).", "operationId": "claimActivity", "parameters": [ { "description": "Typed ID with prefix 'A'", "in": "path", "name": "activity_id", "required": true, "schema": { "description": "Typed ID with prefix 'A'", "title": "Activity Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClaimRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClaimResponse" } } }, "description": "Successful Response" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClaimResponse" } } }, "description": "Conflict" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Atomically claim an activity for an agent (CAS)", "tags": [ "activities" ], "x-local-capability": "cloud" } }, "/api/v1/activities/{activity_id}/complete": { "post": { "description": "Complete an activity under the R7 hierarchy contract.\n\nDone-ness derives from facet-definition status categories — never from\nhard-coded status strings. Unfinished descendants produce a 409 whose\npayload is the machine-readable conflict (S11's prompt renders the same\ncontract).", "operationId": "completeActivity", "parameters": [ { "description": "Typed ID with prefix 'A'", "in": "path", "name": "activity_id", "required": true, "schema": { "description": "Typed ID with prefix 'A'", "title": "Activity Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompleteRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompleteResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Hierarchy-aware completion (check | cascade | exception)", "tags": [ "activities" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/activities/{activity_id}/completion-report": { "get": { "description": "Machine-queryable delivery record — never parse the body prose.", "operationId": "getCompletionReport", "parameters": [ { "description": "Typed ID with prefix 'A'", "in": "path", "name": "activity_id", "required": true, "schema": { "description": "Typed ID with prefix 'A'", "title": "Activity Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompletionReportGetResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Read the structured completion report (current + history)", "tags": [ "activities" ], "x-local-capability": "cloud", "x-mcp-skip": true }, "put": { "description": "PUT = retry-safe: same execution_id updates the ONE Completion section\nin place; a new execution_id makes it current and archives the prior run.", "operationId": "putCompletionReport", "parameters": [ { "description": "Typed ID with prefix 'A'", "in": "path", "name": "activity_id", "required": true, "schema": { "description": "Typed ID with prefix 'A'", "title": "Activity Id", "type": "string" } }, { "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "maxLength": 128, "title": "Idempotency-Key" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompletionReportPut" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompletionReportPutResponse" } } }, "description": "Successful Response", "headers": { "X-Tidy-Op-Id": { "schema": { "type": "string" } }, "X-Tidy-Op-Outcome": { "description": "replayed: this Idempotency-Key had already landed; nothing was written again", "schema": { "enum": [ "applied", "replayed" ], "type": "string" } } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentConflictResponse" } } }, "description": "collab_liveness_unprovable (retry the same key) or idempotency_key_reused", "headers": { "Retry-After": { "schema": { "type": "integer" } }, "X-Tidy-Op-Id": { "schema": { "type": "string" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Write/replace the task's completion report (idempotent)", "tags": [ "activities" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/activities/{activity_id}/coverage": { "get": { "description": "Coverage ladder for one requirement, with contributing links.\n\nComputed from ``implements`` links + evidence at read time — coverage is\nnever stored and no API accepts a coverage value (D16 negative AC).", "operationId": "getRequirementCoverage", "parameters": [ { "description": "Typed ID with prefix 'A'", "in": "path", "name": "activity_id", "required": true, "schema": { "description": "Typed ID with prefix 'A'", "title": "Activity Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequirementCoverage" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Computed implementation coverage for a requirement", "tags": [ "links" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/activities/{activity_id}/delegations": { "get": { "operationId": "listActivityDelegations", "parameters": [ { "description": "Typed ID with prefix 'A'", "in": "path", "name": "activity_id", "required": true, "schema": { "description": "Typed ID with prefix 'A'", "title": "Activity Id", "type": "string" } }, { "description": "Wait up to this many seconds for every hand-off to come back. Never cancels one.", "in": "query", "name": "wait_s", "required": false, "schema": { "default": 0, "description": "Wait up to this many seconds for every hand-off to come back. Never cancels one.", "maximum": 50, "minimum": 0, "title": "Wait S", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActivityDelegationsResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "The tasks handed on from an item, and where each stands", "tags": [ "activities" ], "x-local-capability": "cloud" }, "post": { "operationId": "createActivityDelegation", "parameters": [ { "description": "Typed ID with prefix 'A'", "in": "path", "name": "activity_id", "required": true, "schema": { "description": "Typed ID with prefix 'A'", "title": "Activity Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActivityDelegationCreateRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActivityDelegationCreateResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Hand a child task under an item you work to a colleague", "tags": [ "activities" ], "x-local-capability": "cloud" } }, "/api/v1/activities/{activity_id}/dev-status": { "patch": { "deprecated": true, "description": "Write a retired dev-work state as the task's status (TIDY-19611).\n\nThe task's status is the one vocabulary: this maps the old word onto it\nand writes it through the task writer, so the board moves, edit history\nrecords it and automations fire, exactly as for ``PATCH /tasks/{id}``.\nAn unknown word, or one the workspace's task statuses cannot represent\n(no blocked state), is rejected 422.", "operationId": "setActivityDevStatus", "parameters": [ { "description": "Typed ID with prefix 'A'", "in": "path", "name": "activity_id", "required": true, "schema": { "description": "Typed ID with prefix 'A'", "title": "Activity Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DevStatusUpdateRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DevStatusResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Set an activity's dev-work state (deprecated: set the task's status)", "tags": [ "activities" ], "x-local-capability": "cloud" } }, "/api/v1/activities/{activity_id}/history": { "get": { "description": "Fetch server-authored edit history for an activity.", "operationId": "getActivityHistory", "parameters": [ { "description": "Typed ID with prefix 'A'", "in": "path", "name": "activity_id", "required": true, "schema": { "description": "Typed ID with prefix 'A'", "title": "Activity Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActivityEditHistoryResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get activity edit history", "tags": [ "activities" ] } }, "/api/v1/activities/{activity_id}/history/{change_set_id}/restore": { "post": { "description": "Restore a prior activity edit batch using the stored old values.", "operationId": "restoreActivityChangeSet", "parameters": [ { "in": "path", "name": "change_set_id", "required": true, "schema": { "title": "Change Set Id", "type": "string" } }, { "description": "Typed ID with prefix 'A'", "in": "path", "name": "activity_id", "required": true, "schema": { "description": "Typed ID with prefix 'A'", "title": "Activity Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActivityResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Restore an activity change set", "tags": [ "activities" ] } }, "/api/v1/activities/{activity_id}/interaction": { "post": { "description": "Record that the user interacted with an activity (open, edit, link).\n\nUpdates last_interaction_at on the activity for sorting/prioritization.", "operationId": "recordActivityInteraction", "parameters": [ { "description": "Typed ID with prefix 'A'", "in": "path", "name": "activity_id", "required": true, "schema": { "description": "Typed ID with prefix 'A'", "title": "Activity Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActivityInteractionRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActivityInteractionResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Record a user interaction with an activity", "tags": [ "activities" ] } }, "/api/v1/activities/{activity_id}/move": { "post": { "operationId": "moveActivity", "parameters": [ { "in": "path", "name": "activity_id", "required": true, "schema": { "title": "Activity Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MoveRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MoveResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Move an activity to another project (or personal scope)", "tags": [ "move" ] } }, "/api/v1/activities/{activity_id}/release": { "post": { "description": "Only the holder agent or a human member may release. ``crashed``\nleaves every other field untouched for re-pull.", "operationId": "releaseActivityClaim", "parameters": [ { "description": "Typed ID with prefix 'A'", "in": "path", "name": "activity_id", "required": true, "schema": { "description": "Typed ID with prefix 'A'", "title": "Activity Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReleaseRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReleaseResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Release an agent's claim on an activity", "tags": [ "activities" ], "x-local-capability": "cloud" } }, "/api/v1/activities/{activity_id}/resolve-commitment": { "put": { "description": "Manually mark a commitment-flavored activity as resolved. Replaces PUT /api/v1/commitments/{id}/resolve (TIDY-8945).", "operationId": "resolveCommitmentActivity", "parameters": [ { "in": "path", "name": "activity_id", "required": true, "schema": { "title": "Activity Id", "type": "string" } }, { "in": "header", "name": "X-Trace-Id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Resolvecommitmentactivity", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Resolve a commitment-flavored activity", "tags": [ "activities", "activities" ] } }, "/api/v1/activities/{activity_id}/restore": { "post": { "description": "Clear a soft-deleted activity's tombstone — the undo leg of DELETE.\n\n A deleted activity leaves every PowerSync bucket (they all filter\n `deleted_at IS NULL`), so a client cannot undo its own delete locally: the\n row is gone from its database. Undo comes back through here.\n\n Idempotent: restoring an activity that is not deleted succeeds.\n\n Related: TIDY-15644 (bulk delete with undo on mobile).", "operationId": "restoreActivity", "parameters": [ { "description": "Typed ID with prefix 'A'", "in": "path", "name": "activity_id", "required": true, "schema": { "description": "Typed ID with prefix 'A'", "title": "Activity Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Restore a soft-deleted activity", "tags": [ "activities" ], "x-local-capability": "cloud" } }, "/api/v1/activities/{activity_id}/schedule-task": { "post": { "description": "Write scheduling state on an activities row (task facet) via\nsemantic verbs.\n\nDispatches to ActivitiesWriter.schedule_task_to_week /\nschedule_task_to_day / schedule_task_to_time / unschedule_task.\nUnlike calendar events, tasks DO support ``unschedule`` (the\nunplanned state).", "operationId": "scheduleActivityTask", "parameters": [ { "in": "path", "name": "activity_id", "required": true, "schema": { "title": "Activity Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_service__routers__calendar_schedule__ScheduleRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScheduleResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Assign task activity to unplanned/week/day/time (TIDY-7074)", "tags": [ "calendar-schedule" ] } }, "/api/v1/activities/{activity_id}/score-breakdown": { "get": { "description": "Return the scoring factor breakdown for an activity.", "operationId": "getScoreBreakdown", "parameters": [ { "description": "Typed ID with prefix 'A'", "in": "path", "name": "activity_id", "required": true, "schema": { "description": "Typed ID with prefix 'A'", "title": "Activity Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScoreBreakdownResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get score calculation breakdown for an activity", "tags": [ "activities" ] } }, "/api/v1/activities/{activity_id}/unarchive": { "post": { "description": "Unarchive an activity. A never-archived record is a typed 409 no-op error.", "operationId": "unarchiveActivity", "parameters": [ { "description": "Typed ID with prefix 'A'", "in": "path", "name": "activity_id", "required": true, "schema": { "description": "Typed ID with prefix 'A'", "title": "Activity Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActivityArchiveResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Restore an archived activity to default surfaces", "tags": [ "activities" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/activities/{activity_id}/wiki-links/sync": { "post": { "description": "DELETE-then-INSERT replaces all `linked_references` rows sourced from\n wiki-link sync for the given activity, with the provided set. Rows\n authored by other sources are preserved.\n\n Hierarchy (`link_type='parent_of'`) rows are excluded in both directions:\n they are derived server-side from `activities.parent_activity_id`\n (migration 793), never written or deleted by this endpoint. Clients\n express activity-in-activity hierarchy by setting the parent column;\n any `parent_of` item in the payload is dropped.", "operationId": "syncActivityWikiLinks", "parameters": [ { "description": "Activity UUID", "in": "path", "name": "activity_id", "required": true, "schema": { "description": "Activity UUID", "title": "Activity Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WikiLinkSyncRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WikiLinkSyncResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Atomically replace wiki-link rows for an activity", "tags": [ "links" ] } }, "/api/v1/activity": { "get": { "operationId": "listActivityFeed", "parameters": [ { "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "maximum": 200, "minimum": 1, "title": "Limit", "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cursor" } }, { "in": "query", "name": "types", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Types" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActivityFeedResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List chat activity feed items", "tags": [ "activity", "activity" ], "x-mcp-skip": true } }, "/api/v1/activity-delegations/{delegation_id}/cancel": { "post": { "operationId": "cancelActivityDelegation", "parameters": [ { "description": "The hand-off's id.", "in": "path", "name": "delegation_id", "required": true, "schema": { "description": "The hand-off's id.", "format": "uuid", "title": "Delegation Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActivityDelegationCancelRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActivityDelegationCancelResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Cancel a hand-off and everything handed on under it", "tags": [ "activities" ], "x-local-capability": "cloud" } }, "/api/v1/activity/beacon": { "post": { "description": "Upsert per-surface daily counts for the authenticated caller.\n\nValidation (fail loud — the contract is closed):\n * unknown surface -> 422 (closed vocabulary, enforced by the model)\n * >20 events/batch -> 422 (enforced by the model)\n * missing/invalid auth -> 401 (enforced by the auth dependency)\n\nBursts/duplicates simply increment the counter; event-level idempotence is\nnot required (marts only need \"active that day\").", "operationId": "recordActivityBeacon", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BeaconRequest" } } }, "required": true }, "responses": { "204": { "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Record a privacy-light engagement beacon (authed)", "tags": [ "activity", "activity" ], "x-mcp-skip": true } }, "/api/v1/activity/mark-all-read": { "post": { "operationId": "markAllActivityRead", "parameters": [ { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActivityMarkAllReadResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Mark all chat activity items read", "tags": [ "activity", "activity" ], "x-mcp-skip": true } }, "/api/v1/activity/unread-count": { "get": { "operationId": "getActivityUnreadCount", "parameters": [ { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActivityUnreadCountResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get unread chat activity count", "tags": [ "activity", "activity" ], "x-mcp-skip": true } }, "/api/v1/activity/{notification_id}/read": { "patch": { "operationId": "setActivityReadState", "parameters": [ { "in": "path", "name": "notification_id", "required": true, "schema": { "format": "uuid", "title": "Notification Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActivityReadRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActivityReadResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Set one activity item read state", "tags": [ "activity", "activity" ], "x-mcp-skip": true } }, "/api/v1/address-books": { "get": { "operationId": "listAddressBooks", "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/AddressBookResponse" }, "title": "Response Listaddressbooks", "type": "array" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List visible address books", "tags": [ "address-books" ] }, "post": { "operationId": "createAddressBook", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddressBookCreateRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddressBookResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Create an address book", "tags": [ "address-books" ] } }, "/api/v1/address-books/{address_book_id}": { "delete": { "operationId": "deleteAddressBook", "parameters": [ { "in": "path", "name": "address_book_id", "required": true, "schema": { "format": "uuid", "title": "Address Book Id", "type": "string" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Delete an address book", "tags": [ "address-books" ] }, "patch": { "operationId": "updateAddressBook", "parameters": [ { "in": "path", "name": "address_book_id", "required": true, "schema": { "format": "uuid", "title": "Address Book Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddressBookUpdateRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddressBookResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Update an address book", "tags": [ "address-books" ] } }, "/api/v1/address-books/{address_book_id}/members": { "post": { "operationId": "addAddressBookMember", "parameters": [ { "in": "path", "name": "address_book_id", "required": true, "schema": { "format": "uuid", "title": "Address Book Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddressBookMemberRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddressBookMemberResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Add a contact or organization to an address book", "tags": [ "address-books" ] } }, "/api/v1/address-books/{address_book_id}/members/{primitive_type}/{primitive_id}": { "delete": { "operationId": "removeAddressBookMember", "parameters": [ { "in": "path", "name": "address_book_id", "required": true, "schema": { "format": "uuid", "title": "Address Book Id", "type": "string" } }, { "in": "path", "name": "primitive_type", "required": true, "schema": { "title": "Primitive Type", "type": "string" } }, { "in": "path", "name": "primitive_id", "required": true, "schema": { "format": "uuid", "title": "Primitive Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddressBookMemberResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Remove a contact or organization from an address book", "tags": [ "address-books" ] } }, "/api/v1/address-books/{address_book_id}/share-all-members": { "post": { "operationId": "shareAllAddressBookMembers", "parameters": [ { "in": "path", "name": "address_book_id", "required": true, "schema": { "format": "uuid", "title": "Address Book Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddressBookShareAllResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Share all caller-owned address book members", "tags": [ "address-books" ] } }, "/api/v1/admin/account-deletions": { "get": { "operationId": "listAccountDeletions", "parameters": [ { "description": "Comma-separated operation statuses.", "in": "query", "name": "status", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": "failed,retrying,manual_review,verifying", "description": "Comma-separated operation statuses.", "title": "Status" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/DeletionOperationSummary" }, "title": "Response Listaccountdeletions", "type": "array" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List Account Deletions", "tags": [ "admin-account-deletion" ], "x-mcp-skip": true } }, "/api/v1/admin/account-deletions/adopt": { "post": { "operationId": "adoptAccountDeletion", "parameters": [ { "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Idempotency-Key" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeletionAdoptRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeletionAdoptResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Adopt Account Deletion", "tags": [ "admin-account-deletion" ], "x-mcp-skip": true } }, "/api/v1/admin/account-deletions/{operation_id}": { "get": { "operationId": "inspectAccountDeletion", "parameters": [ { "in": "path", "name": "operation_id", "required": true, "schema": { "format": "uuid", "title": "Operation Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeletionInspectResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Inspect Account Deletion", "tags": [ "admin-account-deletion" ], "x-mcp-skip": true } }, "/api/v1/admin/account-deletions/{operation_id}/accept-exception": { "post": { "description": "Close a manual_review operation whose only gap is former_customers_scope.\n\nRe-verifies first; anything residual, any policy violation or any other\nunverified store answers 409 exception_not_applicable and changes nothing.", "operationId": "acceptAccountDeletionException", "parameters": [ { "in": "path", "name": "operation_id", "required": true, "schema": { "format": "uuid", "title": "Operation Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeletionResumeRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeletionResumeResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Accept Account Deletion Exception", "tags": [ "admin-account-deletion" ], "x-mcp-skip": true } }, "/api/v1/admin/account-deletions/{operation_id}/resume": { "post": { "operationId": "resumeAccountDeletion", "parameters": [ { "in": "path", "name": "operation_id", "required": true, "schema": { "format": "uuid", "title": "Operation Id", "type": "string" } }, { "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Idempotency-Key" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeletionResumeRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeletionResumeResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Resume Account Deletion", "tags": [ "admin-account-deletion" ], "x-mcp-skip": true } }, "/api/v1/admin/accounts": { "get": { "description": "Type-ahead search over tenants by name / owner email for the picker.", "operationId": "adminSearchAccounts", "parameters": [ { "description": "Match tenant name or owner email", "in": "query", "name": "q", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Match tenant name or owner email", "title": "Q" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 20, "maximum": 50, "minimum": 1, "title": "Limit", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/AccountSearchResult" }, "title": "Response Adminsearchaccounts", "type": "array" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Search Accounts", "tags": [ "admin-accounts", "admin-accounts" ], "x-mcp-skip": true } }, "/api/v1/admin/accounts/{tenant_id}": { "get": { "description": "One consolidated payload for the account detail page.", "operationId": "adminGetAccountDetail", "parameters": [ { "in": "path", "name": "tenant_id", "required": true, "schema": { "format": "uuid", "title": "Tenant Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountDetailResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Account Detail", "tags": [ "admin-accounts", "admin-accounts" ], "x-mcp-skip": true } }, "/api/v1/admin/accounts/{tenant_id}/addon-inboxes": { "put": { "description": "Set a paying workspace's add-on inboxes on its Stripe subscription.\n\nThe owner's own path (setInboxAddons): an increase is charged prorated, a\ndecrease that would strand a connected inbox is refused, an exempt\nworkspace never reaches Stripe. Without a live subscription an operator\ngrants inboxes with an ``inboxes`` override instead (owner decision 6).\nStripe first; audited on the platform chain and the workspace's.", "operationId": "adminSetAccountAddonInboxes", "parameters": [ { "in": "path", "name": "tenant_id", "required": true, "schema": { "format": "uuid", "title": "Tenant Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddonInboxesRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InboxAddonResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Set Account Addon Inboxes", "tags": [ "admin-accounts", "admin-accounts" ], "x-mcp-skip": true } }, "/api/v1/admin/accounts/{tenant_id}/credit-grants": { "post": { "description": "Grant (or, negative, correct) a workspace's credits for its current\nperiod. No dependency on the operator's own workspace, which a tenantless\noperator does not have; audited on the platform chain and the workspace's.", "operationId": "adminGrantCredits", "parameters": [ { "in": "path", "name": "tenant_id", "required": true, "schema": { "format": "uuid", "title": "Tenant Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditGrantRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditGrantResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Admin Grant Credits", "tags": [ "admin-credits", "admin-credits" ], "x-mcp-skip": true } }, "/api/v1/admin/accounts/{tenant_id}/discounts": { "get": { "description": "The discounts on a workspace's Stripe subscription, and the coupons on\nits plane an operator can apply.", "operationId": "adminListAccountDiscounts", "parameters": [ { "in": "path", "name": "tenant_id", "required": true, "schema": { "format": "uuid", "title": "Tenant Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountDiscountsResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List Account Discounts", "tags": [ "admin-accounts", "admin-accounts" ], "x-mcp-skip": true }, "post": { "description": "Put a coupon on the workspace's subscription, keeping its other\ndiscounts. Stripe first; audited on the workspace's chain.", "operationId": "adminApplyAccountCoupon", "parameters": [ { "in": "path", "name": "tenant_id", "required": true, "schema": { "format": "uuid", "title": "Tenant Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplyCouponRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountDiscountsResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Apply Account Coupon", "tags": [ "admin-accounts", "admin-accounts" ], "x-mcp-skip": true } }, "/api/v1/admin/accounts/{tenant_id}/discounts/{discount_id}": { "delete": { "description": "Take one discount off the workspace's subscription. Tidy's own (the\nexempt coupon, a referral reward) are refused: un-exempting removes the\nexempt one. Stripe first; audited on the workspace's chain.", "operationId": "adminRemoveAccountDiscount", "parameters": [ { "in": "path", "name": "tenant_id", "required": true, "schema": { "format": "uuid", "title": "Tenant Id", "type": "string" } }, { "in": "path", "name": "discount_id", "required": true, "schema": { "title": "Discount Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountDiscountsResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Remove Account Discount", "tags": [ "admin-accounts", "admin-accounts" ], "x-mcp-skip": true } }, "/api/v1/admin/accounts/{tenant_id}/overrides": { "get": { "operationId": "adminListAccountOverrides", "parameters": [ { "in": "path", "name": "tenant_id", "required": true, "schema": { "format": "uuid", "title": "Tenant Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/AccountOverrideResponse" }, "title": "Response Adminlistaccountoverrides", "type": "array" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List Overrides", "tags": [ "admin-plan-tiers", "admin-plan-tiers" ], "x-mcp-skip": true }, "post": { "operationId": "adminCreateAccountOverride", "parameters": [ { "in": "path", "name": "tenant_id", "required": true, "schema": { "format": "uuid", "title": "Tenant Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountOverrideCreate" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountOverrideResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Create Override", "tags": [ "admin-plan-tiers", "admin-plan-tiers" ], "x-mcp-skip": true } }, "/api/v1/admin/accounts/{tenant_id}/overrides/{override_id}": { "delete": { "operationId": "adminRevokeAccountOverride", "parameters": [ { "in": "path", "name": "tenant_id", "required": true, "schema": { "format": "uuid", "title": "Tenant Id", "type": "string" } }, { "in": "path", "name": "override_id", "required": true, "schema": { "format": "uuid", "title": "Override Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Adminrevokeaccountoverride", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Revoke Override", "tags": [ "admin-plan-tiers", "admin-plan-tiers" ], "x-mcp-skip": true } }, "/api/v1/admin/accounts/{tenant_id}/tier": { "put": { "description": "Assign a plan tier to an account (new-model authority; audited).\n\nA workspace with a live Stripe subscription changes plan through that\nsubscription, on the same path as the owner's change-plan: an upgrade now\nwith proration, a downgrade at period end, and the webhook mirrors the tier\n(owner decision 1, TIDY-19279). Writing plan_tier directly there would be\noverwritten by the next webhook. Only a workspace with no live Stripe link\n(exempt, comp, or never subscribed) has plan_tier written here.\n\nThe audit row lands on the TARGET tenant's chain, like override\ncreate/revoke; there is no dependency on the operator's own tenant, which\na tenantless operator does not have.", "operationId": "adminAssignAccountTier", "parameters": [ { "in": "path", "name": "tenant_id", "required": true, "schema": { "format": "uuid", "title": "Tenant Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TierAssignRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TierAssignResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Assign Account Tier", "tags": [ "admin-accounts", "admin-accounts" ], "x-mcp-skip": true } }, "/api/v1/admin/accounts/{tenant_id}/trial-end": { "put": { "description": "Set a workspace's no-card trial end — an extended trial, or ending it.\n\nOnly a workspace on the no-card trial has one to set: a Stripe-linked\nsubscription's trial is Stripe's (decision 1), and an exempt workspace has\nno trial (it never pays). A workspace still 'none' is put on the trial.\nAudited on the target tenant's chain in the same transaction.", "operationId": "adminSetAccountTrialEnd", "parameters": [ { "in": "path", "name": "tenant_id", "required": true, "schema": { "format": "uuid", "title": "Tenant Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrialEndRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrialEndResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Set Account Trial End", "tags": [ "admin-accounts", "admin-accounts" ], "x-mcp-skip": true } }, "/api/v1/admin/agents/dreamer/pause-tenant": { "post": { "operationId": "pauseTenantDreamer", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DreamerPauseRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DreamerPauseResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Pause (or unpause) the Dreamer tenant-wide", "tags": [ "agents", "agents" ], "x-mcp-skip": true, "x-mcp-skip-reason": "User/admin settings toggle for the browser UI." } }, "/api/v1/admin/alert-preferences": { "get": { "description": "Return the caller's alert prefs, seeding defaults on first access.", "operationId": "listAdminAlertPreferences", "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/AlertPreference" }, "title": "Response Listadminalertpreferences", "type": "array" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List Alert Preferences", "tags": [ "admin-alerts" ] }, "put": { "description": "Upsert one alert preference for the caller.", "operationId": "upsertAdminAlertPreference", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AlertPreferenceUpsert" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AlertPreference" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Upsert Alert Preference", "tags": [ "admin-alerts" ] } }, "/api/v1/admin/alert-preferences/test-fire": { "post": { "description": "Fire a test alert through the caller's configured channel(s) for the\ngiven event_type. Returns the routing summary.", "operationId": "testFireAdminAlert", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TestFireRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Testfireadminalert", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Test Fire Alert", "tags": [ "admin-alerts" ] } }, "/api/v1/admin/analytics/adoption": { "get": { "description": "Cross-tenant adoption for every catalogued product event: active tenants over the window vs eligible (active-status) tenants, with a per-day trend. Bounded windows only (1–90 days). Admin-gated (TIDY-17573).", "operationId": "getAdminAdoption", "parameters": [ { "in": "query", "name": "days", "required": false, "schema": { "default": 30, "maximum": 90, "minimum": 1, "title": "Days", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdoptionResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Feature-adoption metrics per catalogued event", "tags": [ "admin-analytics" ], "x-mcp-skip": true, "x-mcp-skip-reason": "Operator console aggregate (S11); not agent-callable." } }, "/api/v1/admin/audit-logs": { "get": { "description": "Filtered, keyset-paginated audit-log read. Self-audits the access.\n\ntidy-tenant-wide-justified: compliance audit-trail read across all tenants;\nreturns audit metadata only, no member primitive payload. Tenantless\nplatform operators are admitted (TIDY-17596) — the query is fleet-wide by\ndesign and their read self-audits on the platform chain.", "operationId": "listAdminAuditLogs", "parameters": [ { "in": "query", "name": "actor", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Actor" } }, { "in": "query", "name": "action_type", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Action Type" } }, { "in": "query", "name": "action_prefix", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Action Prefix" } }, { "in": "query", "name": "tenant", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Tenant" } }, { "in": "query", "name": "target_type", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Target Type" } }, { "in": "query", "name": "target_id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Target Id" } }, { "in": "query", "name": "date_from", "required": false, "schema": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Date From" } }, { "in": "query", "name": "date_to", "required": false, "schema": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Date To" } }, { "in": "query", "name": "ip", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Ip" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cursor" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "maximum": 200, "minimum": 1, "title": "Limit", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuditLogPage" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List Audit Logs", "tags": [ "admin-audit-logs" ] } }, "/api/v1/admin/audit-logs/export": { "get": { "description": "Stream a CSV of the filtered audit-log rows. Bounded at _MAX_EXPORT. The\nexport is itself audited.\n\ntidy-tenant-wide-justified: compliance audit-trail export across all tenants;\naudit metadata only.", "operationId": "exportAdminAuditLogs", "parameters": [ { "in": "query", "name": "actor", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Actor" } }, { "in": "query", "name": "action_type", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Action Type" } }, { "in": "query", "name": "action_prefix", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Action Prefix" } }, { "in": "query", "name": "tenant", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Tenant" } }, { "in": "query", "name": "target_type", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Target Type" } }, { "in": "query", "name": "target_id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Target Id" } }, { "in": "query", "name": "date_from", "required": false, "schema": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Date From" } }, { "in": "query", "name": "date_to", "required": false, "schema": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Date To" } }, { "in": "query", "name": "ip", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Ip" } } ], "responses": { "200": { "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Export Audit Logs", "tags": [ "admin-audit-logs" ] } }, "/api/v1/admin/backfill/drawing-previews": { "post": { "description": "Regenerates the server-side preview SVG for every drawing note that has scene content but no servable preview object. Closes the gap for drawings that predate the change-driven regeneration trigger (TIDY-12284) or whose earlier render failed. Idempotent: drawings that already have a servable preview are skipped. TIDY-13318. With force=true, also re-renders drawings whose stored preview still contains the SVG 2-only 'auto-start-reverse' marker that AndroidSVG rejects, bumping drawing_version so devices refetch (TIDY-13325).", "operationId": "backfillDrawingPreviews", "parameters": [ { "in": "query", "name": "force", "required": false, "schema": { "default": false, "title": "Force", "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Backfilldrawingpreviews", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Backfill missing drawing preview SVGs", "tags": [ "admin", "admin-backfill" ] } }, "/api/v1/admin/backfill/email-memory": { "post": { "description": "TIDY-17079: publishes each of a tenant's historical body-depth emails through the existing memory.write queue as a VECTOR_ONLY trace write (local TEI embedding; keyword search reads the trace, no graph_triples, zero LLM spend), so semantic search covers emails predating the pipeline's memory dispatch. Scans oldest-first by (sent_at, id); header-depth, quarantined, soft-deleted, and already-traced emails are never dispatched. Resume by passing the returned next_cursor back verbatim as `cursor`; a null next_cursor means the tenant's sweep is complete.", "operationId": "backfillEmailMemory", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailMemoryBackfillRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Backfillemailmemory", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Backfill historical emails into memory (VECTOR_ONLY)", "tags": [ "admin", "admin-backfill" ] } }, "/api/v1/admin/backfill/zoho-empty-attachments": { "post": { "description": "TIDY-6721: Re-extract attachments for Zoho emails that have attachments = '[]' in the DB. Updates the attachments JSONB column and queues each for pipeline reprocessing so calendar routing works.", "operationId": "backfillZohoEmptyAttachments", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Backfillzohoemptyattachments", "type": "object" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Backfill empty-attachment Zoho emails", "tags": [ "admin", "admin-backfill" ] } }, "/api/v1/admin/backfill/zoho-inline-images": { "post": { "description": "TIDY-13553: scans Zoho-source emails whose decrypted body still carries proprietary /mail/ImageDisplay? URLs (which only resolve inside Zoho webmail), downloads each image via the Zoho attachment API, stores a copy, and rewrites the stored body columns to point at it. Also re-extracts attachments (content_id/is_inline) and stamps has_content_images/content_image_count. Idempotent: a row with no remaining ImageDisplay URLs is a no-op. Chunked + resumable via the returned last_id cursor; pass email_id to repair a single row.", "operationId": "backfillZohoInlineImages", "parameters": [ { "in": "query", "name": "email_id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Email Id" } }, { "in": "query", "name": "after_id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "After Id" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 200, "title": "Limit", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Backfillzohoinlineimages", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Repair Zoho emails with un-rewritten inline ImageDisplay URLs", "tags": [ "admin", "admin-backfill" ] } }, "/api/v1/admin/backfill/zoho-null-bodies": { "post": { "description": "Re-fetches body content for Zoho emails that were stored with NULL body_text/body_html due to the envelope unwrap bug (TIDY-6179). Queues each email for full pipeline processing.", "operationId": "backfillZohoNullBodies", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Backfillzohonullbodies", "type": "object" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Backfill NULL-body Zoho emails", "tags": [ "admin", "admin-backfill" ] } }, "/api/v1/admin/backfill/zoho-presigned-image-urls": { "post": { "description": "TIDY-14307: bodies written by the Zoho inline-image rewriter before the fix carry presigned storage URLs with a 1-year expiry that MinIO/SeaweedFS rejects outright (over the 7-day SigV4 cap), so every such image is broken. The bytes are already in object storage — this repair rewrites each dead URL to the stable authenticated proxy URL (/api/v1/storage/{bucket}/{path}) in body_html, body_html_sanitized, and message_content_html, and projects the repaired plaintext into email_bodies_recent. Pure string transform: no provider calls, so it also repairs rows whose Zoho connection is revoked. Idempotent: a row with no presigned own-bucket URLs is a no-op. Chunked + resumable via the returned last_id cursor; pass email_id to repair a single row.", "operationId": "backfillZohoPresignedImageUrls", "parameters": [ { "in": "query", "name": "email_id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Email Id" } }, { "in": "query", "name": "after_id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "After Id" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 200, "title": "Limit", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Backfillzohopresignedimageurls", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Repair email bodies carrying dead presigned storage URLs", "tags": [ "admin", "admin-backfill" ] } }, "/api/v1/admin/billing/accounts": { "get": { "description": "List all accounts with their billing status.", "operationId": "listBillingAccounts", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillingAccountsResponse" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List Billing Accounts", "tags": [ "admin-billing" ] } }, "/api/v1/admin/billing/accounts/{tenant_id}/flag-beta": { "post": { "description": "Flag an account as billing exempt (beta/grandfathered).\n\nExempt means \"no charges\" only: the plan still gates features and limits\n(TIDY-19279). A workspace with a live Stripe subscription is kept from\nbeing charged by a 100%-off coupon on that subscription, taken off again\nwhen it is un-exempted (owner decision 6); Stripe is changed first, so a\nStripe refusal leaves the flag as it was. The toggle is an operator write,\nso it lands on the platform audit chain and the workspace's in the same\ntransaction (fail-closed).", "operationId": "flagBeta", "parameters": [ { "in": "path", "name": "tenant_id", "required": true, "schema": { "title": "Tenant Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FlagBetaRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Flagbeta", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Flag Beta", "tags": [ "admin-billing" ] } }, "/api/v1/admin/billing/accounts/{tenant_id}/override-credits": { "post": { "deprecated": true, "description": "Compatibility for older clients; the one audited grant owns the write.\n\nNew clients must call adminGrantCredits and supply their own reason.", "operationId": "overrideCredits", "parameters": [ { "in": "path", "name": "tenant_id", "required": true, "schema": { "title": "Tenant Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OverrideCreditsRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Overridecredits", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Override Credits", "tags": [ "admin-billing" ] } }, "/api/v1/admin/billing/accounts/{tenant_id}/repair-stripe-link": { "post": { "description": "Detach a workspace from a Stripe subscription or customer Stripe no\nlonger has (the drift report's subscription_missing / customer_missing).\n\nAsks Stripe first and clears only the ids Stripe answers resource_missing\nfor; a missing subscription leaves the workspace with status 'none' and no\nmirrored price, period or add-ons. Refuses (409) when Stripe still has\nboth. Audited on the platform chain and the workspace's in the write's\ntransaction\n(TIDY-19279). tidy-tenant-wide-justified: platform-admin repair of one\ntenant's billing linkage columns.", "operationId": "repairStripeLink", "parameters": [ { "in": "path", "name": "tenant_id", "required": true, "schema": { "title": "Tenant Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RepairStripeLinkResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Repair Stripe Link", "tags": [ "admin-billing" ], "x-mcp-skip": true } }, "/api/v1/admin/billing/former-customer": { "get": { "description": "Operator lookup of minimized Stripe finance refs by supplied email.\n\nThe backend HMACs the email. The hash, pepper, and card data never appear\nin the response. tidy-tenant-wide-justified: platform-admin finance lookup\nover tenantless retained refs; audited on the platform chain.", "operationId": "getFormerCustomerBilling", "parameters": [ { "in": "query", "name": "email", "required": true, "schema": { "minLength": 3, "title": "Email", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FormerCustomerBillingLookupResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Former Customer Billing", "tags": [ "admin-billing" ], "x-mcp-skip": true } }, "/api/v1/admin/billing/mode": { "get": { "description": "Whether this deployment charges for real: read from the mode of the\nStripe key new workspaces bill on, never from configuration that could\ndisagree with it (the admin header shows it).", "operationId": "getBillingMode", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillingModeResponse" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Billing Mode", "tags": [ "admin-billing" ], "x-mcp-skip": true } }, "/api/v1/admin/billing/stripe-reconciliation": { "get": { "description": "Read-only: every Stripe-linked tenant whose mirrored plan, status, price,\nadd-on inboxes or period disagree with Stripe, and whether this deployment's\nwebhook endpoint subscribes to every event the consumer handles (TIDY-19279).\nOperator CLI twin: services/api/scripts/stripe_reconcile.py.", "operationId": "getStripeReconciliation", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StripeReconciliationResponse" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Stripe Reconciliation", "tags": [ "admin-billing" ], "x-mcp-skip": true } }, "/api/v1/admin/bootstrap/redeem": { "post": { "description": "Consume-once redemption of the installer-generated bootstrap secret. Caller authenticates with a Supabase access token AND a verified email address; success grants accounts.is_admin to the calling account and permanently burns the secret. Refuses (typed 403/409) when no live secret exists, the secret does not match, the cluster already has operators, or the caller is already an admin.", "operationId": "redeemBootstrapSecret", "parameters": [ { "in": "header", "name": "authorization", "required": false, "schema": { "default": "", "title": "Authorization", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BootstrapRedeemRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BootstrapRedeemResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Redeem the install-time bootstrap secret (TIDY-17565)", "tags": [ "admin-bootstrap", "admin-bootstrap" ], "x-mcp-skip": true, "x-mcp-skip-reason": "Install-time first-operator bootstrap; operator-only, never agent-callable." } }, "/api/v1/admin/chat": { "get": { "operationId": "getAdminChatIndex", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminChatIndexResponse" } } }, "description": "Successful Response" } }, "summary": "Load the workspace chat admin index", "tags": [ "admin-chat" ], "x-mcp-skip": true, "x-mcp-skip-reason": "Console index only; MCP tools expose concrete admin chat operations." } }, "/api/v1/admin/chat/audit": { "get": { "operationId": "listChatAuditEntries", "parameters": [ { "in": "query", "name": "actor_id", "required": false, "schema": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Actor Id" } }, { "in": "query", "name": "actor_type", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Actor Type" } }, { "in": "query", "name": "action_prefix", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Action Prefix" } }, { "in": "query", "name": "resource_type", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Resource Type" } }, { "in": "query", "name": "resource_id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Resource Id" } }, { "in": "query", "name": "since", "required": false, "schema": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Since" } }, { "in": "query", "name": "until", "required": false, "schema": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Until" } }, { "in": "query", "name": "outcome", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Outcome" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "maximum": 200, "minimum": 1, "title": "Limit", "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cursor" } }, { "in": "query", "name": "format", "required": false, "schema": { "default": "json", "enum": [ "json", "csv" ], "title": "Format", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatAuditListResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "List chat-scoped audit entries", "tags": [ "admin-chat-audit" ] } }, "/api/v1/admin/chat/audit/{entry_id}": { "get": { "operationId": "getChatAuditEntry", "parameters": [ { "in": "path", "name": "entry_id", "required": true, "schema": { "format": "uuid", "title": "Entry Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatAuditEntryResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Get a chat-scoped audit entry", "tags": [ "admin-chat-audit" ], "x-mcp-skip": true, "x-mcp-skip-reason": "Use chat_admin_list_audit_entries; single-entry UI drilldown is not an MCP workflow." } }, "/api/v1/admin/chat/capabilities": { "get": { "operationId": "getAdminChatCapabilityMatrix", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminChatCapabilityMatrixResponse" } } }, "description": "Successful Response" } }, "summary": "Chat capability matrix + current holders", "tags": [ "admin-chat" ] } }, "/api/v1/admin/chat/channels": { "get": { "operationId": "listAdminChatChannels", "parameters": [ { "in": "query", "name": "name", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "maximum": 200, "minimum": 1, "title": "Limit", "type": "integer" } }, { "in": "query", "name": "offset", "required": false, "schema": { "default": 0, "minimum": 0, "title": "Offset", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListAdminChannelsResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "List all tenant channels (admin directory)", "tags": [ "admin-chat" ] } }, "/api/v1/admin/chat/emoji": { "get": { "operationId": "listAdminChatEmoji", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminCustomEmojiListResponse" } } }, "description": "Successful Response" } }, "summary": "List workspace custom emoji (admin)", "tags": [ "admin-chat-emoji" ] }, "post": { "operationId": "uploadAdminChatEmoji", "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/Body_uploadAdminChatEmoji" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomEmojiResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Upload a workspace custom emoji", "tags": [ "admin-chat-emoji" ] } }, "/api/v1/admin/chat/emoji/{emoji_id}": { "delete": { "operationId": "deleteAdminChatEmoji", "parameters": [ { "in": "path", "name": "emoji_id", "required": true, "schema": { "title": "Emoji Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_service__routers__admin_chat_emoji__OkResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Delete a workspace custom emoji", "tags": [ "admin-chat-emoji" ] } }, "/api/v1/admin/chat/encryption": { "get": { "operationId": "getAdminChatEncryption", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EncryptionConfigResponse" } } }, "description": "Successful Response" } }, "summary": "Load chat encryption policy and encrypted DM summaries", "tags": [ "admin-chat-encryption" ] }, "put": { "operationId": "updateAdminChatEncryption", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EncryptionConfigRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EncryptionConfigResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Update the workspace chat encryption policy", "tags": [ "admin-chat-encryption" ] } }, "/api/v1/admin/chat/exports": { "get": { "operationId": "listChatExportJobs", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListChatExportJobsResponse" } } }, "description": "Successful Response" } }, "summary": "List chat export jobs", "tags": [ "admin-chat-export" ] }, "post": { "operationId": "createChatExportJob", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatExportRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatExportJobResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Create a chat export job", "tags": [ "admin-chat-export" ] } }, "/api/v1/admin/chat/exports/{job_id}": { "get": { "operationId": "getChatExportJob", "parameters": [ { "in": "path", "name": "job_id", "required": true, "schema": { "title": "Job Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatExportJobResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Get a chat export job", "tags": [ "admin-chat-export" ], "x-mcp-skip": true, "x-mcp-skip-reason": "chat_admin_list_exports returns job details; no separate MCP lookup needed." } }, "/api/v1/admin/chat/exports/{job_id}/download": { "get": { "operationId": "downloadChatExportJob", "parameters": [ { "in": "path", "name": "job_id", "required": true, "schema": { "title": "Job Id", "type": "string" } } ], "responses": { "200": { "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Download a completed chat export archive", "tags": [ "admin-chat-export" ], "x-mcp-skip": true, "x-mcp-skip-reason": "Binary archive downloads are browser/file-transfer flows, not MCP tool payloads." } }, "/api/v1/admin/chat/huddles": { "get": { "operationId": "listAdminChatHuddles", "parameters": [ { "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "maximum": 200, "minimum": 1, "title": "Limit", "type": "integer" } }, { "in": "query", "name": "offset", "required": false, "schema": { "default": 0, "minimum": 0, "title": "Offset", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListAdminHuddlesResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "List active and recent huddles (admin)", "tags": [ "admin-chat" ] } }, "/api/v1/admin/chat/huddles/{huddle_id}/end": { "post": { "operationId": "adminEndChatHuddle", "parameters": [ { "in": "path", "name": "huddle_id", "required": true, "schema": { "title": "Huddle Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminHuddleResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Force-end a huddle (admin)", "tags": [ "admin-chat" ] } }, "/api/v1/admin/chat/legal-holds": { "get": { "operationId": "listChatLegalHolds", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListLegalHoldsResponse" } } }, "description": "Successful Response" } }, "summary": "List active chat legal holds", "tags": [ "admin-chat-legal-hold" ] }, "post": { "operationId": "applyChatLegalHold", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegalHoldRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegalHoldResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Apply a chat legal hold", "tags": [ "admin-chat-legal-hold" ] } }, "/api/v1/admin/chat/legal-holds/{hold_id}": { "delete": { "operationId": "releaseChatLegalHold", "parameters": [ { "in": "path", "name": "hold_id", "required": true, "schema": { "title": "Hold Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReleaseLegalHoldResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Release a chat legal hold", "tags": [ "admin-chat-legal-hold" ] } }, "/api/v1/admin/chat/message-edits": { "get": { "operationId": "listAdminChatMessageEdits", "parameters": [ { "in": "query", "name": "kind", "required": false, "schema": { "anyOf": [ { "enum": [ "edit", "delete" ], "type": "string" }, { "type": "null" } ], "title": "Kind" } }, { "in": "query", "name": "room_id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Room Id" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "maximum": 200, "minimum": 1, "title": "Limit", "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cursor" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListChatMessageEditsResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "List API-issued chat message edits and deletions (compliance mirror)", "tags": [ "admin-chat-settings" ] } }, "/api/v1/admin/chat/polls": { "get": { "operationId": "listAdminChatPolls", "parameters": [ { "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "maximum": 200, "minimum": 1, "title": "Limit", "type": "integer" } }, { "in": "query", "name": "offset", "required": false, "schema": { "default": 0, "minimum": 0, "title": "Offset", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListAdminPollsResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "List open and recently closed polls (admin)", "tags": [ "admin-chat" ] } }, "/api/v1/admin/chat/retention": { "get": { "operationId": "listChatRetentionPolicies", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListRetentionPoliciesResponse" } } }, "description": "Successful Response" } }, "summary": "List chat retention policies", "tags": [ "admin-chat-retention" ] }, "post": { "operationId": "createChatRetentionPolicy", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetentionPolicyRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetentionPolicyResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Create or update a chat retention policy", "tags": [ "admin-chat-retention" ] } }, "/api/v1/admin/chat/retention/run-now": { "post": { "operationId": "runChatRetentionWorkerNow", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetentionRunResponse" } } }, "description": "Successful Response" } }, "summary": "Run chat retention worker now", "tags": [ "admin-chat-retention" ], "x-mcp-skip": true, "x-mcp-skip-reason": "Operational maintenance action; retained for admin UI/manual operations only." } }, "/api/v1/admin/chat/retention/{policy_id}": { "delete": { "operationId": "deleteChatRetentionPolicy", "parameters": [ { "in": "path", "name": "policy_id", "required": true, "schema": { "title": "Policy Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_service__routers__admin_chat_retention__OkResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Delete a chat retention policy", "tags": [ "admin-chat-retention" ] }, "put": { "operationId": "updateChatRetentionPolicy", "parameters": [ { "in": "path", "name": "policy_id", "required": true, "schema": { "title": "Policy Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetentionPolicyRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetentionPolicyResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Update a chat retention policy", "tags": [ "admin-chat-retention" ] } }, "/api/v1/admin/chat/settings": { "get": { "operationId": "getAdminChatSettings", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminChatSettingsResponse" } } }, "description": "Successful Response" } }, "summary": "Get workspace chat message-governance settings", "tags": [ "admin-chat-settings" ] }, "put": { "operationId": "updateAdminChatSettings", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAdminChatSettingsRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminChatSettingsResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Update workspace chat message-governance settings", "tags": [ "admin-chat-settings" ] } }, "/api/v1/admin/chat/users": { "get": { "operationId": "listAdminChatUsers", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListAdminChatUsersResponse" } } }, "description": "Successful Response" } }, "summary": "List chat users (humans, bots, guests)", "tags": [ "admin-chat" ] } }, "/api/v1/admin/coaching-knowledge/chunks/{chunk_id}": { "delete": { "operationId": "deleteCoachingChunk", "parameters": [ { "in": "path", "name": "chunk_id", "required": true, "schema": { "title": "Chunk Id", "type": "string" } }, { "in": "query", "name": "document_id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Document Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteChunkResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Delete a single coaching knowledge chunk", "tags": [ "admin-coaching" ], "x-mcp-skip": true } }, "/api/v1/admin/coaching-knowledge/documents": { "get": { "description": "List all coaching documents with chunk counts.\n\n Returns documents from coaching_documents table with full metadata,\n or falls back to aggregating from chunks if documents table is empty.\n\n **Admin Only**: Requires admin role.\n\n Related: KCC-3086, KCC-3087", "operationId": "listCoachingDocuments", "parameters": [ { "in": "query", "name": "module", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Module" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentListResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List coaching documents", "tags": [ "admin-coaching" ] } }, "/api/v1/admin/coaching-knowledge/documents/by-id/{document_id}": { "delete": { "operationId": "deleteCoachingDocumentById", "parameters": [ { "in": "path", "name": "document_id", "required": true, "schema": { "title": "Document Id", "type": "string" } }, { "in": "query", "name": "delete_storage", "required": false, "schema": { "default": false, "title": "Delete Storage", "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteDocumentByIdResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Delete a coaching document (by id) and its chunks", "tags": [ "admin-coaching" ], "x-mcp-skip": true } }, "/api/v1/admin/coaching-knowledge/documents/{document_id}": { "patch": { "description": "Update document metadata (tags, description).\n\n **Admin Only**: Requires admin role.\n\n Related: KCC-3086", "operationId": "updateCoachingDocument", "parameters": [ { "in": "path", "name": "document_id", "required": true, "schema": { "title": "Document Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateDocumentRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Updatecoachingdocument", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Update document metadata", "tags": [ "admin-coaching" ] } }, "/api/v1/admin/coaching-knowledge/documents/{document_id}/content": { "get": { "description": "Get the full extracted markdown content of a document.\n\n Returns the markdown text extracted by docling for viewing/debugging.\n\n **Admin Only**: Requires admin role.\n\n Related: KCC-3086", "operationId": "getCoachingDocumentContent", "parameters": [ { "in": "path", "name": "document_id", "required": true, "schema": { "title": "Document Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentContentResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get document extracted content", "tags": [ "admin-coaching" ] }, "put": { "description": "Update the extracted markdown content of a document.\n\n This allows editing the extracted content before re-chunking.\n After saving, use the reprocess endpoint to regenerate chunks.\n\n **Admin Only**: Requires admin role.\n\n Related: KCC-3086", "operationId": "updateCoachingDocumentContent", "parameters": [ { "in": "path", "name": "document_id", "required": true, "schema": { "title": "Document Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateContentRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentContentResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Update document extracted content", "tags": [ "admin-coaching" ] } }, "/api/v1/admin/coaching-knowledge/documents/{document_id}/rechunk": { "post": { "description": "Re-chunk a document using its existing extracted_content.\n\n This does NOT re-extract from the original PDF/file. It uses the\n (possibly edited) extracted content already saved in the database.\n\n Use this after editing the extracted content to regenerate chunks\n without losing your edits.\n\n **Admin Only**: Requires admin role.\n\n Related: KCC-3086", "operationId": "rechunkCoachingDocument", "parameters": [ { "in": "path", "name": "document_id", "required": true, "schema": { "title": "Document Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RechunkResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Re-chunk document from existing content", "tags": [ "admin-coaching" ] } }, "/api/v1/admin/coaching-knowledge/documents/{source_document}": { "delete": { "description": "Delete a document and all its chunks.\n\n Deletes:\n 1. Document record from coaching_documents table\n 2. All chunks linked to this document (via CASCADE)\n 3. Optionally the file from storage (if delete_file=true)\n\n **Admin Only**: Requires admin role.\n\n Related: KCC-3086, KCC-3087", "operationId": "deleteCoachingDocument", "parameters": [ { "in": "path", "name": "source_document", "required": true, "schema": { "title": "Source Document", "type": "string" } }, { "in": "query", "name": "delete_file", "required": false, "schema": { "default": false, "title": "Delete File", "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteDocumentResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Delete document and chunks", "tags": [ "admin-coaching" ] } }, "/api/v1/admin/coaching-knowledge/extract": { "post": { "description": "Extract content from a document but DO NOT create chunks.\n\n This is step 1 of a two-step workflow:\n 1. Extract content (this endpoint) - runs docling, stores extracted markdown\n 2. Process chunks (rechunk endpoint) - user triggers after editing\n\n Use this when you want to review/edit extracted content before chunking.\n\n **Admin Only**: Requires admin role.\n\n Related: KCC-3086", "operationId": "extractCoachingDocumentOnly", "parameters": [ { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProcessDocumentRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExtractOnlyResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Extract document content only (no chunking)", "tags": [ "admin-coaching" ] } }, "/api/v1/admin/coaching-knowledge/page": { "get": { "operationId": "getCoachingKnowledgePage", "parameters": [ { "in": "query", "name": "page", "required": false, "schema": { "default": 1, "minimum": 1, "title": "Page", "type": "integer" } }, { "in": "query", "name": "module", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Module" } }, { "in": "query", "name": "expand", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Expand" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CoachingKnowledgePageResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Coaching-knowledge admin page bundle", "tags": [ "admin-coaching" ], "x-mcp-skip": true } }, "/api/v1/admin/coaching-knowledge/process": { "post": { "description": "Process an existing document in the coaching-knowledge storage bucket.\n\n Use this to re-process a document or process documents uploaded directly\n to storage.\n\n **Admin Only**: Requires admin role.\n\n Related: KCC-3087", "operationId": "processCoachingDocument", "parameters": [ { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProcessDocumentRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProcessDocumentResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Process existing document", "tags": [ "admin-coaching" ] } }, "/api/v1/admin/coaching-knowledge/upload": { "post": { "description": "Upload a document to the coaching-knowledge Supabase Storage bucket. This is the first step of a two-phase admin flow — after upload the caller invokes `/extract` (extract content only) or `/process` (extract + chunk). Max size: 10MB. Allowed types: PDF, TXT, DOCX, MD, JSON, YAML. Absorbs the retired Supabase-direct BFF (TIDY-7383).", "operationId": "uploadCoachingDocument", "parameters": [ { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/Body_uploadCoachingDocument" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StorageOnlyUploadResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Upload coaching document (storage-only)", "tags": [ "admin-coaching" ] } }, "/api/v1/admin/coaching/compaction-config": { "get": { "operationId": "listCoachingCompactionConfig", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompactionConfigListResponse" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List coaching compaction config", "tags": [ "admin-coaching" ], "x-mcp-skip": true }, "patch": { "operationId": "updateCoachingCompactionConfig", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateCompactionConfigRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Updatecoachingcompactionconfig", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Update a coaching compaction config row", "tags": [ "admin-coaching" ], "x-mcp-skip": true } }, "/api/v1/admin/dashboard/needs-attention": { "get": { "description": "Aggregate everything that needs admin action today. Cached 30s.", "operationId": "getAdminNeedsAttention", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NeedsAttentionResponse" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Admin operational nerve-center aggregation", "tags": [ "admin", "admin-stats" ] } }, "/api/v1/admin/delegation/grants/bulk": { "post": { "description": "Bulk-create grants on behalf of members. Capability-gated, transactional\nper grant; partial failures are reported in ``errors``.\n\nThe ``manage_delegation`` capability is checked inline at call time (fail\nclosed) rather than via an eager ``Depends`` factory — the factory would\ninstantiate ``ApiServiceConfig`` at import, which breaks OpenAPI generation\non hosts without production secrets.", "operationId": "bulkCreateDelegationGrants", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkGrantRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkGrantResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Bulk Create Grants", "tags": [ "admin-delegation", "admin-delegation" ], "x-mcp-skip": true } }, "/api/v1/admin/email-manifests/{manifest_id}/reconciliation-review": { "post": { "description": "Records operator acknowledgement + proven provider evidence for a stalled pending_send manifest. The reconciliation scheduler may then void it. No typed content is returned.", "operationId": "reviewEmailManifestReconciliation", "parameters": [ { "in": "path", "name": "manifest_id", "required": true, "schema": { "format": "uuid", "title": "Manifest Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReconciliationReviewRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReconciliationReviewResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Acknowledge reconciliation review for an embed manifest", "tags": [ "admin-email-manifests" ], "x-mcp-skip": true, "x-mcp-skip-reason": "Tenant-ops break-glass surface; not an agent-callable tool." } }, "/api/v1/admin/email-writeback/jobs": { "get": { "operationId": "listEmailWritebackJobs", "parameters": [ { "in": "query", "name": "status", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Status" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "maximum": 200, "minimum": 1, "title": "Limit", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/EmailWritebackJobResponse" }, "title": "Response Listemailwritebackjobs", "type": "array" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List IMAP writeback jobs", "tags": [ "admin", "admin-email-writeback" ] } }, "/api/v1/admin/email-writeback/jobs/{job_id}/retry": { "post": { "operationId": "retryFailedEmailWritebackJob", "parameters": [ { "in": "path", "name": "job_id", "required": true, "schema": { "format": "uuid", "title": "Job Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailWritebackRetryResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Retry a failed IMAP writeback job", "tags": [ "admin", "admin-email-writeback" ] } }, "/api/v1/admin/erasure-audit/{tenant_id}": { "get": { "description": "Audit that a deleted tenant left zero residual content. READ-ONLY.\n\ntidy-tenant-wide-justified: compliance erasure-verification across a deleted\ntenant's tables; returns residual/retention COUNTS and metadata only, never a\nprimitive row payload.", "operationId": "getErasureAudit", "parameters": [ { "in": "path", "name": "tenant_id", "required": true, "schema": { "format": "uuid", "title": "Tenant Id", "type": "string" } }, { "description": "Account email — enables the former_customers suppression check.", "in": "query", "name": "email", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Account email — enables the former_customers suppression check.", "title": "Email" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErasureAuditResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Erasure Audit", "tags": [ "admin-erasure-audit" ], "x-mcp-skip": true } }, "/api/v1/admin/feature-switches": { "get": { "operationId": "getAdminFeatureSwitches", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeatureSwitchLandscapeResponse" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "The feature-switch landscape: descriptors, global defaults, counts, debt", "tags": [ "admin-feature-switches" ], "x-mcp-skip": true, "x-mcp-skip-reason": "Operator rollout control; not an agent-callable tool." } }, "/api/v1/admin/feature-switches/{key}/global": { "put": { "description": "Platform-plane write: NO tenant dependency, platform-chain audit.\n\nA tenantless operator (typ=admin, no membership) must reach this —\ndepending on ``get_current_tenant_id`` here 403'd every operator flip\nwith ``operator_token_not_supported`` (TIDY-17521 adversary F2).", "operationId": "putAdminFeatureSwitchGlobal", "parameters": [ { "in": "path", "name": "key", "required": true, "schema": { "title": "Key", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GlobalDefaultRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GlobalDefaultResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Set (or unset) a switch's global default and beta cohort", "tags": [ "admin-feature-switches" ], "x-mcp-skip": true, "x-mcp-skip-reason": "Operator rollout control; not an agent-callable tool." } }, "/api/v1/admin/feed-artwork": { "get": { "operationId": "listFeedArtworks", "parameters": [ { "in": "query", "name": "facet_type", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Facet Type" } }, { "in": "query", "name": "subject", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Subject" } }, { "in": "query", "name": "mood", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Mood" } }, { "in": "query", "name": "season", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Season" } }, { "in": "query", "name": "time_of_day", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Time Of Day" } }, { "in": "query", "name": "status", "required": false, "schema": { "anyOf": [ { "enum": [ "active", "rejected", "removed" ], "type": "string" }, { "type": "null" } ], "title": "Status" } }, { "in": "query", "name": "min_score", "required": false, "schema": { "anyOf": [ { "maximum": 10, "minimum": 0, "type": "number" }, { "type": "null" } ], "title": "Min Score" } }, { "in": "query", "name": "max_score", "required": false, "schema": { "anyOf": [ { "maximum": 10, "minimum": 0, "type": "number" }, { "type": "null" } ], "title": "Max Score" } }, { "description": "Words that must each match the image's id (or its prefix), family, subject, scene, generation prompt or the quality gate's defects.", "in": "query", "name": "q", "required": false, "schema": { "anyOf": [ { "maxLength": 200, "type": "string" }, { "type": "null" } ], "description": "Words that must each match the image's id (or its prefix), family, subject, scene, generation prompt or the quality gate's defects.", "title": "Q" } }, { "description": "Only images the quality gate's scorer named defects on.", "in": "query", "name": "defects", "required": false, "schema": { "default": false, "description": "Only images the quality gate's scorer named defects on.", "title": "Defects", "type": "boolean" } }, { "description": "Exactly these images.", "in": "query", "name": "id", "required": false, "schema": { "default": [], "description": "Exactly these images.", "items": { "format": "uuid", "type": "string" }, "maxItems": 50, "title": "Id", "type": "array" } }, { "in": "query", "name": "sort", "required": false, "schema": { "default": "newest", "enum": [ "newest", "score_desc", "score_asc" ], "title": "Sort", "type": "string" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 60, "maximum": 200, "minimum": 1, "title": "Limit", "type": "integer" } }, { "in": "query", "name": "offset", "required": false, "schema": { "default": 0, "minimum": 0, "title": "Offset", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeedArtworkPage" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List Feed Artworks", "tags": [ "admin-feed-artwork", "admin-feed-artwork" ], "x-mcp-skip": true, "x-mcp-skip-reason": "Platform-operator curation of the global Feed artwork library; not an agent-callable tool." } }, "/api/v1/admin/feed-artwork/generate": { "post": { "description": "Paint `count` images of the operator's scene in the house style, each\nscored by the vision gate and filed into the library under the chosen tags.\n\nServer-Sent Events: `progress` (stage and elapsed seconds, every couple of\nseconds), `artwork` per filed image, `failed` naming the lane that failed,\n`done` with the tally.", "operationId": "generateFeedArtwork", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeedArtworkGenerateRequest" } } }, "required": true }, "responses": { "200": { "content": { "text/event-stream": {} }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Generate Feed Artwork", "tags": [ "admin-feed-artwork", "admin-feed-artwork" ], "x-mcp-skip": true, "x-mcp-skip-reason": "Platform-operator curation of the global Feed artwork library; not an agent-callable tool." } }, "/api/v1/admin/feed-artwork/vocabulary": { "get": { "operationId": "getFeedArtworkVocabulary", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeedArtworkVocabulary" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Feed Artwork Vocabulary", "tags": [ "admin-feed-artwork", "admin-feed-artwork" ], "x-mcp-skip": true, "x-mcp-skip-reason": "Platform-operator curation of the global Feed artwork library; not an agent-callable tool." } }, "/api/v1/admin/feed-artwork/{artwork_id}/status": { "put": { "description": "Remove an image (it stops being assigned: it leaves the synced catalog,\nand every card wearing it re-picks on its member's next sync), or restore\na removed one. Never a delete.", "operationId": "setFeedArtworkStatus", "parameters": [ { "in": "path", "name": "artwork_id", "required": true, "schema": { "format": "uuid", "title": "Artwork Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeedArtworkStatusRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeedArtwork" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Set Feed Artwork Status", "tags": [ "admin-feed-artwork", "admin-feed-artwork" ], "x-mcp-skip": true, "x-mcp-skip-reason": "Platform-operator curation of the global Feed artwork library; not an agent-callable tool." } }, "/api/v1/admin/google-workspace/connect": { "post": { "description": "Stamp the tenant's super-admin email and probe DWD.\n\nThe probe builds a delegated service and runs a 1-page directory list.\nFailure surfaces the Google API error (no PII added by us) so the\nadmin can fix the consent in admin.google.com.", "operationId": "connectGoogleWorkspace", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceConnectRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceConnectResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Connect Google Workspace via DWD", "tags": [ "admin", "admin-google-workspace" ] } }, "/api/v1/admin/google-workspace/disconnect": { "post": { "description": "Clear the tenant's DWD admin email. Existing imported contacts stay.", "operationId": "disconnectGoogleWorkspace", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceStatusResponse" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Disconnect Google Workspace DWD", "tags": [ "admin", "admin-google-workspace" ] } }, "/api/v1/admin/google-workspace/status": { "get": { "description": "Return current Workspace DWD connection state for the tenant.", "operationId": "getGoogleWorkspaceStatus", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceStatusResponse" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Google Workspace DWD status", "tags": [ "admin", "admin-google-workspace" ] } }, "/api/v1/admin/google-workspace/verify": { "post": { "description": "Re-probe an already-connected Workspace DWD.", "operationId": "verifyGoogleWorkspace", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceStatusResponse" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Re-verify the existing Google Workspace DWD connection", "tags": [ "admin", "admin-google-workspace" ] } }, "/api/v1/admin/growth/counters": { "get": { "description": "Current-state growth knobs: subscribers by tier, trial count,\nthis-cycle signups/subscribers, and attribution capture-health (last 24h).\n\nDeliberately NOT movement analytics (MRR/churn/cohorts belong to\nTIDY-11914). Every value is a cheap on-read count. Attribution counts come\nfrom `attribution_events`; the api-service DB role bypasses that table's\ndeny-all RLS, so the reads run through the same service connection.", "operationId": "getGrowthCounters", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Getgrowthcounters", "type": "object" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Growth Counters", "tags": [ "growth-admin" ] } }, "/api/v1/admin/growth/coupons": { "post": { "description": "Create a Stripe coupon on the operator plane (audited).", "operationId": "createStripeCoupon", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCouponRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Createstripecoupon", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Create Coupon", "tags": [ "growth-admin" ], "x-mcp-skip": true } }, "/api/v1/admin/growth/coupons/{coupon_id}": { "delete": { "description": "Retire a coupon: Stripe deletes it, so nothing new can use it.\n\nSubscriptions already carrying it keep their discount (Stripe's model).\nTidy's own coupons (the exempt coupon, referral rewards) are refused.", "operationId": "retireStripeCoupon", "parameters": [ { "in": "path", "name": "coupon_id", "required": true, "schema": { "title": "Coupon Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Retirestripecoupon", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Retire Coupon", "tags": [ "growth-admin" ], "x-mcp-skip": true } }, "/api/v1/admin/growth/invite-codes": { "get": { "description": "List all invite codes with creator info. Paginated.", "operationId": "listAllInviteCodes", "parameters": [ { "in": "query", "name": "status", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Status" } }, { "in": "query", "name": "created_by", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Created By" } }, { "in": "query", "name": "page", "required": false, "schema": { "default": 1, "minimum": 1, "title": "Page", "type": "integer" } }, { "in": "query", "name": "per_page", "required": false, "schema": { "default": 50, "maximum": 200, "minimum": 1, "title": "Per Page", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Listallinvitecodes", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List All Invite Codes", "tags": [ "growth-admin" ] } }, "/api/v1/admin/growth/invite-codes/bulk-action": { "post": { "description": "Extend expiry or deactivate invite codes in bulk.", "operationId": "bulkActionInviteCodes", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkActionRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Bulkactioninvitecodes", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Bulk Action Invite Codes", "tags": [ "growth-admin" ] } }, "/api/v1/admin/growth/invite-codes/generate": { "post": { "description": "Generate N founder invite codes with a custom prefix and configured expiry.\n\nPlatform-plane aware (TIDY-17568): the minting admin's account identity\n(name/email) is read account-wide with NO membership join — a tenantless\nplatform operator has no `person_account_memberships` row by design. When\nthe admin DOES hold a membership (tenanted admin) their primary tenant is\nattached exactly as before; when they are tenantless the code carries SQL\nNULL tenant_id — never an invented attachment. Either way the code\nredeems through the unchanged customer funnel (`enforce_invite_gate`\nkeys on code/status/expiry only), where the redeemer's own provision\ncreates their account+tenant context.\n\nEvery mint is audited onto the NULL-tenant platform chain (S1 convention:\n`action LIKE 'platform.%'`), NOT a session tenant.", "operationId": "generateInviteCodes", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerateCodesRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Generateinvitecodes", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Generate Invite Codes", "tags": [ "growth-admin" ] } }, "/api/v1/admin/growth/promo-codes": { "get": { "description": "The operator plane's promotion codes (active and inactive) and coupons.\n\n``livemode`` and ``dashboard_url`` say which Stripe mode they are in, so\nthe dashboard links follow the deployment (TIDY-19279).", "operationId": "listPromoCodes", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Listpromocodes", "type": "object" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List Promo Codes", "tags": [ "growth-admin" ] }, "post": { "description": "Create a Stripe promotion code on the operator plane (audited), on an\nexisting coupon or on a new one made from the discount fields.", "operationId": "createPromoCode", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePromoCodeRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Createpromocode", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Create Promo Code", "tags": [ "growth-admin" ] } }, "/api/v1/admin/growth/promo-codes/{promo_id}/toggle": { "put": { "description": "Activate or deactivate a Stripe promotion code (audited). A founder\nbatch carrying a deactivated code subscribes at the plan's price.", "operationId": "togglePromoCode", "parameters": [ { "in": "path", "name": "promo_id", "required": true, "schema": { "title": "Promo Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TogglePromoCodeRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Togglepromocode", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Toggle Promo Code", "tags": [ "growth-admin" ] } }, "/api/v1/admin/growth/referrals": { "get": { "description": "List all referral rewards with account info.", "operationId": "listReferrals", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Listreferrals", "type": "object" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List Referrals", "tags": [ "growth-admin" ] } }, "/api/v1/admin/growth/signup-leads": { "get": { "description": "List captured waitlist leads (R15/R16 admin visibility).\n\nSurfaces everyone who wanted in — blocked no-code signup attempts and\nmarketing-waitlist captures mirrored into `signup_leads` — including their\nconverted state, so the admin sees the full demand funnel. Optional\n`converted` filter narrows to converted / not-yet-converted leads.", "operationId": "getSignupLeads", "parameters": [ { "in": "query", "name": "converted", "required": false, "schema": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Converted" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 500, "maximum": 2000, "minimum": 1, "title": "Limit", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Getsignupleads", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Signup Leads", "tags": [ "growth-admin" ] } }, "/api/v1/admin/growth/user-invite-stats": { "get": { "description": "Per-human-user invite performance aggregate (R17/R19).\n\nGroups `invite_codes` by `created_by_account_id`, joined to `accounts`, with\nthe user's allowance/renewal record. Returns generated / redeemed /\noutstanding / last_activity per inviter, ordered by redemptions so the admin\ncan surface high performers at a glance. Service/agent members\n(`agent_members` rows or `member_type='virtual_employee'` memberships) are\nexcluded from the human inviter view.", "operationId": "getUserInviteStats", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Getuserinvitestats", "type": "object" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get User Invite Stats", "tags": [ "growth-admin" ] } }, "/api/v1/admin/growth/users/{account_id}/allowance": { "get": { "description": "Read a user's effective invite allowance + renewal audit (dashboard).", "operationId": "getUserInviteAllowance", "parameters": [ { "in": "path", "name": "account_id", "required": true, "schema": { "title": "Account Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Getuserinviteallowance", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get User Invite Allowance", "tags": [ "growth-admin" ] } }, "/api/v1/admin/growth/users/{account_id}/renew-invites": { "post": { "description": "Renew (re-up) a user's invite allowance beyond the global cap (R18).\n\nIncrements `granted_allowance` (by the global default or an explicit\n`amount`) and `renewal_count`, recording `updated_by`. Works for a\ncurrently-ineligible/unsubscribed user — the grant is stored and takes\neffect when they become eligible. Returns the post-renewal allowance state\n(granted, renewal_count, effective, remaining) for the growth dashboard.", "operationId": "renewUserInvites", "parameters": [ { "in": "path", "name": "account_id", "required": true, "schema": { "title": "Account Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RenewInvitesRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Renewuserinvites", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Renew User Invites", "tags": [ "growth-admin" ] } }, "/api/v1/admin/guest-activity": { "get": { "operationId": "listGuestActivity", "parameters": [ { "in": "query", "name": "guest_account_id", "required": false, "schema": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Guest Account Id" } }, { "in": "query", "name": "action", "required": false, "schema": { "anyOf": [ { "pattern": "^guest_(invited|signed_in|message_sent|facet_opened|revoked|expired)$", "type": "string" }, { "type": "null" } ], "title": "Action" } }, { "in": "query", "name": "since", "required": false, "schema": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Since" } }, { "in": "query", "name": "until", "required": false, "schema": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Until" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cursor" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 100, "maximum": 500, "minimum": 1, "title": "Limit", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GuestActivityResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "List guest activity rows for the workspace", "tags": [ "guest-audit" ], "x-mcp-skip": true } }, "/api/v1/admin/guests/{guest_account_id}/revoke": { "post": { "operationId": "revokeGuest", "parameters": [ { "in": "path", "name": "guest_account_id", "required": true, "schema": { "format": "uuid", "title": "Guest Account Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevokeGuestRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevokeGuestResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Revoke a guest's workspace access", "tags": [ "guest-audit" ], "x-mcp-skip": true } }, "/api/v1/admin/in-app-alerts": { "get": { "description": "Unresolved in-app alerts for the banner: account-targeted to the caller\nOR all-admin broadcasts (account_id IS NULL).", "operationId": "listAdminInAppAlerts", "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/InAppAlert" }, "title": "Response Listadmininappalerts", "type": "array" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List In App Alerts", "tags": [ "admin-alerts" ] } }, "/api/v1/admin/in-app-alerts/resolve-bulk": { "post": { "description": "Resolve every alert the caller can see for one event_type (or an explicit\nid list). Backs the banner's grouped \"resolve all\" action.", "operationId": "resolveAdminInAppAlertsBulk", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkResolveRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Resolveadmininappalertsbulk", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Resolve In App Alerts Bulk", "tags": [ "admin-alerts" ] } }, "/api/v1/admin/in-app-alerts/{alert_id}/resolve": { "post": { "description": "Resolve (dismiss) a banner alert.", "operationId": "resolveAdminInAppAlert", "parameters": [ { "in": "path", "name": "alert_id", "required": true, "schema": { "format": "uuid", "title": "Alert Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Resolveadmininappalert", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Resolve In App Alert", "tags": [ "admin-alerts" ] } }, "/api/v1/admin/knowledge-lint-findings": { "get": { "description": "Return Knowledge Lint findings for a tenant (admin operator triage).\n\ntidy-tenant-wide-justified: admin triage surface; the operator selects the\ntenant explicitly and every row is filtered to that tenant_id.", "operationId": "getKnowledgeLintFindings", "parameters": [ { "description": "Tenant to triage.", "in": "query", "name": "tenant_id", "required": true, "schema": { "description": "Tenant to triage.", "format": "uuid", "title": "Tenant Id", "type": "string" } }, { "description": "Filter to one lint category.", "in": "query", "name": "category", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter to one lint category.", "title": "Category" } }, { "description": "Only open findings.", "in": "query", "name": "unresolved_only", "required": false, "schema": { "default": true, "description": "Only open findings.", "title": "Unresolved Only", "type": "boolean" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 200, "maximum": 1000, "minimum": 1, "title": "Limit", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LintFindingsResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List Knowledge Lint findings for a tenant", "tags": [ "admin", "admin-knowledge-lint" ], "x-mcp-skip": true, "x-mcp-skip-reason": "Admin operator triage surface; not an agent tool." } }, "/api/v1/admin/knowledge-packs": { "get": { "operationId": "listKnowledgePacks", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PackCatalogResponse" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List Packs", "tags": [ "admin-knowledge-packs" ], "x-mcp-skip": true } }, "/api/v1/admin/knowledge-packs/versions/{version_id}/transition": { "post": { "operationId": "transitionKnowledgePackVersion", "parameters": [ { "in": "path", "name": "version_id", "required": true, "schema": { "format": "uuid", "title": "Version Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PackTransitionRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PackTransitionResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Transition Pack Version", "tags": [ "admin-knowledge-packs" ], "x-mcp-skip": true } }, "/api/v1/admin/knowledge-packs/{slug}": { "get": { "operationId": "getKnowledgePack", "parameters": [ { "in": "path", "name": "slug", "required": true, "schema": { "title": "Slug", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PackDetailResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Pack", "tags": [ "admin-knowledge-packs" ], "x-mcp-skip": true } }, "/api/v1/admin/knowledge-packs/{slug}/preview": { "post": { "description": "Operator preview (R33/TIDY-14820): run a pack under an explicit audited\nprincipal with the SAME member-visible predicates as production. The only\nconsumer allowed to bypass the cache; the bypass is recorded and\nrate-limited by the runtime.", "operationId": "previewKnowledgePack", "parameters": [ { "in": "path", "name": "slug", "required": true, "schema": { "title": "Slug", "type": "string" } }, { "in": "header", "name": "X-Preview-Principal", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Preview-Principal" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PackPreviewRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PackPreviewResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Preview Pack", "tags": [ "admin-knowledge-packs" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/admin/limit-posture": { "get": { "description": "Per-dimension utilization distribution + hot-bucket tenants (R18).", "operationId": "adminLimitPosture", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LimitPostureResponse" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Limit Posture", "tags": [ "admin-limit-posture", "admin-limit-posture" ], "x-mcp-skip": true } }, "/api/v1/admin/llm-logs": { "get": { "description": "Get paginated LLM usage logs for admin review.\n\nTIDY-8637 (S6): ``model_tier`` filters to specific tier labels (multi-value);\n``batch_filter`` toggles between batched / sync / all; ``batch_id`` narrows\nto a single batch. Tier values are validated against the canonical\n``{low, medium, high, critical}`` set; anything else returns 422.", "operationId": "getLlmLogs", "parameters": [ { "in": "query", "name": "page", "required": false, "schema": { "default": 1, "minimum": 1, "title": "Page", "type": "integer" } }, { "in": "query", "name": "page_size", "required": false, "schema": { "default": 50, "maximum": 200, "minimum": 1, "title": "Page Size", "type": "integer" } }, { "in": "query", "name": "service", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Service" } }, { "in": "query", "name": "model", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Model" } }, { "in": "query", "name": "trace_id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Trace Id" } }, { "in": "query", "name": "tenant_id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Tenant Id" } }, { "in": "query", "name": "account_id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Account Id" } }, { "in": "query", "name": "source_type", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Source Type" } }, { "in": "query", "name": "status", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Status" } }, { "in": "query", "name": "cache_only", "required": false, "schema": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Cache Only" } }, { "in": "query", "name": "days", "required": false, "schema": { "default": 7, "maximum": 90, "minimum": 1, "title": "Days", "type": "integer" } }, { "in": "query", "name": "model_tier", "required": false, "schema": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Model Tier" } }, { "in": "query", "name": "batch_filter", "required": false, "schema": { "default": "all", "enum": [ "all", "batched", "sync" ], "title": "Batch Filter", "type": "string" } }, { "in": "query", "name": "batch_id", "required": false, "schema": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Batch Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LLMLogsResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Paginated LLM usage logs with prompts/responses", "tags": [ "admin", "admin-stats" ] } }, "/api/v1/admin/llm-logs/{log_id}": { "get": { "description": "Admin-only lookup of a single llm_usage_logs row by primary key. Used by the pipeline Activity Timeline drill-through.", "operationId": "getLlmLogById", "parameters": [ { "in": "path", "name": "log_id", "required": true, "schema": { "title": "Log Id", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LLMLogEntry" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Single LLM usage log by id", "tags": [ "admin", "admin-stats" ] } }, "/api/v1/admin/llm-usage": { "get": { "description": "Get detailed LLM usage stats from llm_usage_logs.", "operationId": "getLlmUsage", "parameters": [ { "in": "query", "name": "days", "required": false, "schema": { "default": 30, "maximum": 90, "minimum": 1, "title": "Days", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LLMUsageResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "LLM usage and cache statistics", "tags": [ "admin", "admin-stats" ] } }, "/api/v1/admin/llm-usage/by-kind": { "get": { "description": "Aggregate llm_usage_logs by usage_kind / import_source over the\nlast N days. Optional filters narrow to a single tenant / kind /\nsource.\n\nTIDY-9140 / TIDY-9119: drives Settings → Usage and Admin → Usage\nbreakdowns. Returns NULL usage_kind rows as a catch-all bucket the\nUI labels \"Other / uncategorized\".", "operationId": "getLlmUsageByKind", "parameters": [ { "in": "query", "name": "days", "required": false, "schema": { "default": 30, "maximum": 90, "minimum": 1, "title": "Days", "type": "integer" } }, { "in": "query", "name": "tenant_id", "required": false, "schema": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Tenant Id" } }, { "in": "query", "name": "usage_kind", "required": false, "schema": { "anyOf": [ { "maxLength": 50, "type": "string" }, { "type": "null" } ], "title": "Usage Kind" } }, { "in": "query", "name": "import_source", "required": false, "schema": { "anyOf": [ { "maxLength": 50, "type": "string" }, { "type": "null" } ], "title": "Import Source" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminUsageByKindResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "LLM usage aggregated by usage_kind + import_source (admin)", "tags": [ "admin", "admin-stats" ] } }, "/api/v1/admin/llm-usage/by-tier": { "get": { "description": "Aggregate llm_usage_logs by ``model_tier`` for the last N days.\n\nReturns one row per distinct tier value (including NULL tier as a\nseparate row). Sorted by total cost desc so the most expensive tier\nbubbles to the top.\n\nTIDY-8637 (S6): backs the \"Extractor Cost by Tier\" card on /admin/llm-usage.\nEmpty result is an empty list — callers must handle empty state in the UI,\nnot behind a 500.", "operationId": "getLlmUsageByTier", "parameters": [ { "in": "query", "name": "service_name", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": "extractor-service", "title": "Service Name" } }, { "in": "query", "name": "days", "required": false, "schema": { "default": 7, "maximum": 90, "minimum": 1, "title": "Days", "type": "integer" } }, { "in": "query", "name": "tenant_id", "required": false, "schema": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Tenant Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/TierBreakdown" }, "title": "Response Getllmusagebytier", "type": "array" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "LLM usage aggregated by extractor tier", "tags": [ "admin", "admin-stats" ] } }, "/api/v1/admin/metering-health": { "get": { "operationId": "getMeteringHealth", "parameters": [ { "in": "query", "name": "window_days", "required": false, "schema": { "default": 7, "maximum": 90, "minimum": 1, "title": "Window Days", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MeteringHealthResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Metering health: coverage, last-seen, payload posture, reconciliation", "tags": [ "admin-metering-health" ], "x-mcp-skip": true } }, "/api/v1/admin/metering-health/invoices": { "post": { "operationId": "createProviderInvoice", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceCreateRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Record a provider invoice for reconciliation", "tags": [ "admin-metering-health" ], "x-mcp-skip": true } }, "/api/v1/admin/metering-health/pipeline-cost": { "get": { "description": "The standing pipeline-cost metric (TIDY-12081 / F8-S3 / R7).\n\nPer tenant per month: total pipeline cost, emails processed, $/email, tier\nrevenue, margin-consumption %, and the F8 batch (S1) / cache (S2) lever\ndimensions. When the requested month is the current one, refreshes the\nPrometheus gauges so an admin poll keeps /metrics current between the\n15-minute background sweeps.", "operationId": "getPipelineCost", "parameters": [ { "description": "First day of the target calendar month (YYYY-MM-01). Defaults to current month.", "in": "query", "name": "month", "required": false, "schema": { "anyOf": [ { "format": "date", "type": "string" }, { "type": "null" } ], "description": "First day of the target calendar month (YYYY-MM-01). Defaults to current month.", "title": "Month" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PipelineCostResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Standing per-tenant pipeline cost: $/email, revenue, margin, F8 levers", "tags": [ "admin-metering-health" ], "x-mcp-skip": true } }, "/api/v1/admin/model-pricing": { "get": { "description": "List all model pricing entries, ordered by provider then model name.", "operationId": "listModelPricing", "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/ModelPricingRow" }, "title": "Response Listmodelpricing", "type": "array" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List all model pricing", "tags": [ "admin-pricing" ] }, "post": { "description": "Create a new model pricing entry.", "operationId": "createModelPricing", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelPricingCreate" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelPricingRow" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Create model pricing entry", "tags": [ "admin-pricing" ] } }, "/api/v1/admin/model-pricing/{pricing_id}": { "delete": { "operationId": "deleteModelPricing", "parameters": [ { "in": "path", "name": "pricing_id", "required": true, "schema": { "format": "uuid", "title": "Pricing Id", "type": "string" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Delete model pricing entry", "tags": [ "admin-pricing" ] }, "get": { "operationId": "getModelPricing", "parameters": [ { "in": "path", "name": "pricing_id", "required": true, "schema": { "format": "uuid", "title": "Pricing Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelPricingRow" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get model pricing by ID", "tags": [ "admin-pricing" ] }, "put": { "description": "Update a model pricing entry. Only provided fields are updated.\n\nTIDY-8638 (S7): batch_input_cost_per_m / batch_output_cost_per_m\nare accepted alongside the standard list rates. Per the story\nspec, setting only one of the two batch columns (without the\nother) is acceptable but logged — the extractor cache requires\nBOTH columns non-NULL to use the model in the batch lane, so a\nhalf-set row will still be skipped at refresh time.", "operationId": "updateModelPricing", "parameters": [ { "in": "path", "name": "pricing_id", "required": true, "schema": { "format": "uuid", "title": "Pricing Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelPricingUpdate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelPricingRow" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Update model pricing", "tags": [ "admin-pricing" ] } }, "/api/v1/admin/notifications": { "get": { "description": "List admin notifications with optional filters.\n\n Supports filtering by:\n - severity (info, warning, error)\n - service (mrs, orchestrator, api, etc)\n - acknowledged status\n\n Returns notifications with deep links to observability tools.\n\n Related: MRS Agent Optimization - REQ-9", "operationId": "listNotifications", "parameters": [ { "in": "query", "name": "severity", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Severity" } }, { "in": "query", "name": "service", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Service" } }, { "in": "query", "name": "acknowledged", "required": false, "schema": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Acknowledged" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "title": "Limit", "type": "integer" } }, { "in": "query", "name": "offset", "required": false, "schema": { "default": 0, "title": "Offset", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotificationListResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List admin notifications", "tags": [ "admin", "admin-notifications" ] } }, "/api/v1/admin/notifications/acknowledge-all": { "post": { "description": "Mark all unread notifications as acknowledged.", "operationId": "acknowledgeAllNotifications", "parameters": [ { "in": "query", "name": "service", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Service" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Acknowledgeallnotifications", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Acknowledge all notifications", "tags": [ "admin", "admin-notifications" ] } }, "/api/v1/admin/notifications/count": { "get": { "description": "Get counts of unread notifications by severity and service.", "operationId": "getNotificationCounts", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotificationCountResponse" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get notification counts", "tags": [ "admin", "admin-notifications" ] } }, "/api/v1/admin/notifications/sms-provider": { "get": { "description": "Environment-derived status of the platform SMS provider. Credentials are reported as presence booleans only and cannot be set through the API — change the service environment instead.", "operationId": "getAdminSmsProviderStatus", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SmsProviderStatusResponse" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Read the platform SMS provider configuration status", "tags": [ "admin-sms-provider" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/admin/notifications/sms-provider/test": { "post": { "description": "Sends through notification-service's admin test harness, which uses the same MessageSender path production SMS flows use. Recorded against the given tenant (defaults to the caller's).", "operationId": "sendAdminSmsProviderTest", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SmsTestSendRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SmsTestSendResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Send a test SMS through the real send path", "tags": [ "admin-sms-provider" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/admin/notifications/{notification_id}": { "delete": { "description": "Permanently delete a notification.", "operationId": "deleteNotification", "parameters": [ { "in": "path", "name": "notification_id", "required": true, "schema": { "title": "Notification Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Deletenotification", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Delete a notification", "tags": [ "admin", "admin-notifications" ] } }, "/api/v1/admin/notifications/{notification_id}/acknowledge": { "post": { "description": "Mark a notification as acknowledged.", "operationId": "acknowledgeNotification", "parameters": [ { "in": "path", "name": "notification_id", "required": true, "schema": { "title": "Notification Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Acknowledgenotification", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Acknowledge a notification", "tags": [ "admin", "admin-notifications" ] } }, "/api/v1/admin/oauth-apps/{client_pk_id}/review": { "post": { "operationId": "reviewOAuthApp", "parameters": [ { "in": "path", "name": "client_pk_id", "required": true, "schema": { "title": "Client Pk Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReviewRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReviewOAuthAppResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Review Oauth App", "tags": [ "oauth_apps", "oauth_apps" ] } }, "/api/v1/admin/observability/incidents": { "get": { "description": "Server-side proxy to Grafana's embedded Alertmanager-compatible API. Returns currently-firing alerts sorted severity→age with same-origin link-out URLs, cached 15s. When Grafana is unreachable the response is the typed envelope {\"error\": \"grafana_unreachable\"} — never a 500.", "operationId": "adminObservabilityIncidents", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IncidentsResponse" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Firing Grafana-managed alerts for the operator console", "tags": [ "admin-observability", "admin-observability" ], "x-mcp-skip": true, "x-mcp-skip-reason": "Platform-operator observability proxy; operator-console data lane, never agent-callable." } }, "/api/v1/admin/pipeline-canonical-text/{doc_id}": { "get": { "operationId": "getAdminPipelineCanonicalText", "parameters": [ { "in": "path", "name": "doc_id", "required": true, "schema": { "title": "Doc Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PipelineCanonicalTextResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get consolidated markdown for a canonical document", "tags": [ "admin-pipeline-runs" ], "x-mcp-skip": true } }, "/api/v1/admin/pipeline-entitlement/{tenant_id}": { "get": { "description": "Operator posture: a tenant's email-pipeline utilization + stage.", "operationId": "adminGetPipelineEntitlement", "parameters": [ { "in": "path", "name": "tenant_id", "required": true, "schema": { "title": "Tenant Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PipelineEntitlementResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Admin Get Pipeline Entitlement", "tags": [ "pipeline-entitlement", "pipeline-entitlement" ], "x-mcp-skip": true } }, "/api/v1/admin/pipeline-reference-content": { "get": { "operationId": "getAdminPipelineReferenceContent", "parameters": [ { "in": "query", "name": "trace_id", "required": true, "schema": { "title": "Trace Id", "type": "string" } }, { "in": "query", "name": "source_type", "required": true, "schema": { "title": "Source Type", "type": "string" } }, { "in": "query", "name": "source_key", "required": true, "schema": { "title": "Source Key", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PipelineReferenceContentResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get per-reference extraction content for a run", "tags": [ "admin-pipeline-runs" ], "x-mcp-skip": true } }, "/api/v1/admin/pipeline-runs": { "get": { "operationId": "listAdminPipelineRuns", "parameters": [ { "description": "Free-text + key:value search", "in": "query", "name": "q", "required": false, "schema": { "default": "", "description": "Free-text + key:value search", "title": "Q", "type": "string" } }, { "description": "Source-type dropdown filter", "in": "query", "name": "source_type", "required": false, "schema": { "default": "all", "description": "Source-type dropdown filter", "title": "Source Type", "type": "string" } }, { "description": "Overall-status dropdown filter", "in": "query", "name": "status", "required": false, "schema": { "default": "all", "description": "Overall-status dropdown filter", "title": "Status", "type": "string" } }, { "in": "query", "name": "offset", "required": false, "schema": { "default": 0, "minimum": 0, "title": "Offset", "type": "integer" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "maximum": 200, "minimum": 1, "title": "Limit", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PipelineRunsListResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List pipeline runs (filtered/paginated)", "tags": [ "admin-pipeline-runs" ], "x-mcp-skip": true } }, "/api/v1/admin/pipeline-runs/{trace_id}": { "get": { "operationId": "getAdminPipelineRun", "parameters": [ { "in": "path", "name": "trace_id", "required": true, "schema": { "title": "Trace Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PipelineRunDetailResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get a pipeline run by trace id", "tags": [ "admin-pipeline-runs" ], "x-mcp-skip": true } }, "/api/v1/admin/pipeline/dlq/requeue-all": { "post": { "description": "Requeue messages from ALL Dead Letter Queues back to their original queues.\n\n Use with caution - this will retry all failed messages across the entire system.", "operationId": "requeueAllDlqMessages", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Requeuealldlqmessages", "type": "object" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Requeue all DLQ messages", "tags": [ "admin", "admin-pipeline" ] } }, "/api/v1/admin/pipeline/dlq/stats": { "get": { "description": "Get statistics about all Dead Letter Queues (DLQs).\n\n Returns the message count for each DLQ and the total across all DLQs.\n DLQs contain messages that failed processing and can be requeued.", "operationId": "getDlqStats", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DLQStatsResponse" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get DLQ statistics", "tags": [ "admin", "admin-pipeline" ] } }, "/api/v1/admin/pipeline/dlq/{queue_name}/requeue": { "post": { "description": "Requeue all messages from a Dead Letter Queue back to its original queue.\n\n This moves messages that failed processing back to the main queue for retry.\n The queue_name should be the DLQ name (e.g., \"orchestrator.ingest.dlq\").", "operationId": "requeueDlqMessages", "parameters": [ { "in": "path", "name": "queue_name", "required": true, "schema": { "title": "Queue Name", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequeueResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Requeue DLQ messages", "tags": [ "admin", "admin-pipeline" ] } }, "/api/v1/admin/pipeline/extraction/{id}": { "get": { "description": "Look up an extraction (or synthesize one from a graph-reconciled entity).", "operationId": "getAdminExtractionDetail", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "title": "Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExtractionDetailResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Admin extraction detail by extraction_id or entity_id", "tags": [ "admin", "admin-pipeline" ] } }, "/api/v1/admin/pipeline/extractions/{doc_id}": { "get": { "description": "Fetch every extraction produced by the LLM extractor for this doc.", "operationId": "getAdminExtractionsByDoc", "parameters": [ { "in": "path", "name": "doc_id", "required": true, "schema": { "title": "Doc Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExtractionsByDocResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Admin extractions list by canonical doc_id", "tags": [ "admin", "admin-pipeline" ] } }, "/api/v1/admin/pipeline/reconciliation/{doc_id}": { "get": { "description": "Show accepted / discarded primitives produced during reconciliation.", "operationId": "getAdminReconciliationByDoc", "parameters": [ { "in": "path", "name": "doc_id", "required": true, "schema": { "title": "Doc Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReconciliationResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Admin reconciliation results by canonical doc_id", "tags": [ "admin", "admin-pipeline" ] } }, "/api/v1/admin/pipeline/{trace_id}/analyze": { "get": { "description": "Analyze a pipeline run to diagnose why it's stuck (admin only).\n\n Returns comprehensive analysis including:\n - Root cause identification with detailed explanation\n - Stage-by-stage status\n - Service health (RabbitMQ consumers, queue backlogs)\n - Recommended remediation actions\n - Actionable fix buttons with API endpoints\n - Debug links to Grafana/Tempo/Loki\n - Source-type specific diagnosis (email vs desktop bridge)\n\n Related: Pipeline Status Dashboard - Analyze Feature", "operationId": "analyzePipelineEndpoint", "parameters": [ { "in": "path", "name": "trace_id", "required": true, "schema": { "title": "Trace Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PipelineAnalysisResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Analyze stuck pipeline", "tags": [ "admin", "admin-pipeline" ] } }, "/api/v1/admin/pipeline/{trace_id}/mark-failed": { "post": { "description": "Mark a stuck pipeline run as failed to stop tracking it.", "operationId": "markPipelineFailed", "parameters": [ { "in": "path", "name": "trace_id", "required": true, "schema": { "title": "Trace Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarkFailedRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Markpipelinefailed", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Mark pipeline as failed", "tags": [ "admin", "admin-pipeline" ] } }, "/api/v1/admin/pipeline/{trace_id}/reset-and-rerun": { "post": { "description": "Completely reset a pipeline run and re-ingest from scratch.\n\n Deletes ALL derived data:\n - email_canonical, canonical_documents, document_chunks\n - email_crawled_content, processed_attachments\n - Extracted primitives (tasks, calendar_events, contacts) linked via doc_id\n - Dedup records (processed_emails, skipped_emails)\n - Pipeline tracking (ingestion_jobs, pipeline_concurrency, fast_track_results)\n\n Then re-queues the original email/file as a fresh ingestion job.", "operationId": "resetAndRerunPipeline", "parameters": [ { "in": "path", "name": "trace_id", "required": true, "schema": { "title": "Trace Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Resetandrerunpipeline", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Reset and re-run pipeline", "tags": [ "admin", "admin-pipeline" ] } }, "/api/v1/admin/pipeline/{trace_id}/retry": { "post": { "description": "Retry processing a failed or stuck pipeline run from the beginning.\n\n - email: queues a replay on the ingestion outbox. The ingestion worker\n reopens the run and the orchestrator re-reads the body from\n email_canonical. The email must have a body (not a header-only row)\n and must not be under quarantine, and the run must not be held for\n sender screening.\n - file_upload: resets the run and republishes the file to ingest.file.", "operationId": "retryPipeline", "parameters": [ { "in": "path", "name": "trace_id", "required": true, "schema": { "title": "Trace Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetryPipelineRequest", "default": {} } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Retrypipeline", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Retry pipeline processing", "tags": [ "admin", "admin-pipeline" ] } }, "/api/v1/admin/pipeline/{trace_id}/trigger-consolidation": { "post": { "description": "Manually trigger consolidation for a stuck pipeline run.", "operationId": "triggerConsolidation", "parameters": [ { "in": "path", "name": "trace_id", "required": true, "schema": { "title": "Trace Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Triggerconsolidation", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Trigger consolidation", "tags": [ "admin", "admin-pipeline" ] } }, "/api/v1/admin/plan-dimensions": { "get": { "description": "Every plan dimension, in display order — the plan editor and override\ndialog render from this, never from a hand-kept list.", "operationId": "adminListPlanDimensions", "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/PlanDimensionResponse" }, "title": "Response Adminlistplandimensions", "type": "array" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List Plan Dimensions", "tags": [ "admin-plan-tiers", "admin-plan-tiers" ], "x-mcp-skip": true } }, "/api/v1/admin/plan-tiers": { "get": { "description": "The ladder. Its prices are the Stripe mirror, refreshed here when stale.", "operationId": "adminListPlanTiers", "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/PlanTier" }, "title": "Response Adminlistplantiers", "type": "array" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List Plan Tiers", "tags": [ "admin-plan-tiers", "admin-plan-tiers" ], "x-mcp-skip": true } }, "/api/v1/admin/plan-tiers/account-counts": { "get": { "description": "Count of active (non-deleted) tenants on each plan tier — the blast radius\na tier edit applies to.", "operationId": "adminPlanTierAccountCounts", "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/TierAccountCount" }, "title": "Response Adminplantieraccountcounts", "type": "array" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Plan Tier Account Counts", "tags": [ "admin-plans", "admin-plans" ], "x-mcp-skip": true } }, "/api/v1/admin/plan-tiers/{tier_id}": { "put": { "description": "Platform-plane write: NO tenant dependency, platform-chain audit.\n\nplan_tiers is platform-global, so a tenantless operator (typ=admin, no\nmembership) must reach this — ``get_current_tenant_id`` refuses operator\nbearers (TIDY-17521 adversary F2, same as the feature-switch console).", "operationId": "adminUpdatePlanTier", "parameters": [ { "in": "path", "name": "tier_id", "required": true, "schema": { "title": "Tier Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlanTierUpdate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlanTier" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Update Plan Tier", "tags": [ "admin-plan-tiers", "admin-plan-tiers" ], "x-mcp-skip": true } }, "/api/v1/admin/platform/operators": { "get": { "operationId": "listPlatformOperators", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperatorListResponse" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List platform operators", "tags": [ "admin-platform", "admin-platform" ], "x-mcp-skip": true, "x-mcp-skip-reason": "Platform-operator authority management; operator-only, never agent-callable." }, "post": { "operationId": "grantPlatformOperator", "parameters": [ { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperatorGrantRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperatorMutationResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Grant platform-operator to an account by email", "tags": [ "admin-platform", "admin-platform" ], "x-mcp-skip": true, "x-mcp-skip-reason": "Platform-operator authority management; operator-only, never agent-callable." } }, "/api/v1/admin/platform/operators/{account_id}": { "delete": { "operationId": "revokePlatformOperator", "parameters": [ { "in": "path", "name": "account_id", "required": true, "schema": { "title": "Account Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperatorMutationResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Revoke platform-operator from an account", "tags": [ "admin-platform", "admin-platform" ], "x-mcp-skip": true, "x-mcp-skip-reason": "Platform-operator authority management; operator-only, never agent-callable." } }, "/api/v1/admin/platform/podcast-pipeline/status": { "get": { "description": "Compose the three-stage view from ground truth (TIDY-17597 R1).\n\nOne proxy call to the DAG pipeline's ``GET /status`` (the token stays\nserver-side) + one local query against ``podcast_corpus_ingest_log``. The\nproxy outage contract matches P4 S1: unreachable/misconfigured pipeline →\n``200 {pipeline_reachable:false}``, never a 502.", "operationId": "getPlatformPodcastPipelineStatus", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlatformPodcastPipelineStatus" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Podcast pipeline stages: queued -> transcribed-on-DAG -> shipped-per-target (+ received here)", "tags": [ "admin-platform", "admin-platform" ] } }, "/api/v1/admin/platform/portals": { "get": { "operationId": "listAdminPortals", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PortalCatalogResponse" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Operator portal inventory with per-portal gating decisions", "tags": [ "admin-platform", "admin-platform" ], "x-mcp-skip": true, "x-mcp-skip-reason": "Platform-operator infrastructure inventory; operator-only, never agent-callable." } }, "/api/v1/admin/platform/portals/access-attempts": { "post": { "operationId": "recordAdminPortalAccessAttempt", "parameters": [ { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccessAttemptRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccessAttemptResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Record an edge-gated portal access attempt (audit sink)", "tags": [ "admin-platform", "admin-platform" ], "x-mcp-skip": true, "x-mcp-skip-reason": "Audit sink for the nginx auth_request gate; operator tooling only, never agent-callable." } }, "/api/v1/admin/platform/session-status": { "get": { "description": "Resolves the CALLER's platform authority from the DB (accounts.is_admin + platform_operator_grants) — never from token claims, which can lag a revocation. Answer is cached per account for at most 15 seconds.", "operationId": "getPlatformSessionStatus", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionStatusResponse" } } }, "description": "Successful Response" } }, "summary": "Authoritative platform-operator status for the caller", "tags": [ "admin-platform", "admin-platform" ] } }, "/api/v1/admin/play-reviews/queue": { "get": { "operationId": "listPlayReviewQueue", "parameters": [ { "in": "query", "name": "include_resolved", "required": false, "schema": { "default": false, "title": "Include Resolved", "type": "boolean" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 200, "title": "Limit", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Listplayreviewqueue", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List Queue", "tags": [ "admin-play-reviews", "admin-play-reviews" ] } }, "/api/v1/admin/play-reviews/{review_id}/approve": { "post": { "operationId": "approvePlayReview", "parameters": [ { "in": "path", "name": "review_id", "required": true, "schema": { "title": "Review Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApproveBody" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Approveplayreview", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Approve", "tags": [ "admin-play-reviews", "admin-play-reviews" ] } }, "/api/v1/admin/play-reviews/{review_id}/edit": { "post": { "operationId": "editPlayReview", "parameters": [ { "in": "path", "name": "review_id", "required": true, "schema": { "title": "Review Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EditBody" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Editplayreview", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Edit And Post", "tags": [ "admin-play-reviews", "admin-play-reviews" ] } }, "/api/v1/admin/play-reviews/{review_id}/reject": { "post": { "operationId": "rejectPlayReview", "parameters": [ { "in": "path", "name": "review_id", "required": true, "schema": { "title": "Review Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_service__routers__admin_play_review_queue__RejectBody" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Rejectplayreview", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Reject", "tags": [ "admin-play-reviews", "admin-play-reviews" ] } }, "/api/v1/admin/podcasts/auto-transcribe": { "get": { "description": "List Auto-Transcribed podcasts, priority ASC (lower = higher priority).\n\ntidy-tenant-wide-justified: global admin-curated catalog list; no per-tenant\nprimitive row payload — only the platform-owned auto-transcription roster.\n\nWorks for operators with no tenant membership (TIDY-17775).", "operationId": "listAutoTranscribedPodcasts", "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/AutoTranscribedResponse" }, "title": "Response Listautotranscribedpodcasts", "type": "array" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List Auto Transcribed Podcasts", "tags": [ "admin-podcasts" ] }, "post": { "description": "Add a podcast to the Auto-Transcribed list. Audited (fail-closed).\n\nSame RSS URL is permitted in both Featured and Auto-Transcribed (D4 — no\ncross-table uniqueness). Personal feed URLs are rejected (R2 edge case).", "operationId": "addAutoTranscribedPodcast", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutoTranscribedCreate" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutoTranscribedResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Add Auto Transcribed Podcast", "tags": [ "admin-podcasts" ] } }, "/api/v1/admin/podcasts/auto-transcribe/episodes": { "post": { "description": "Idempotent global-catalog upsert keyed by (show_id, guid) (R3).\n\nResolves the show via rss_feed_url (following rss_feed_url_aliases redirects;\ncreating podcast_global_shows on first sight). Re-POSTing the same GUID is a\nno-op (created=false). Used by S7's discovery workflow.\n\ntidy-tenant-wide-justified: global catalog write; no per-tenant primitive\nrow payload — the catalog is tenant-agnostic (Tier A).", "operationId": "upsertDiscoveredEpisode", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DiscoveredEpisode" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DiscoveredEpisodeResult" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Upsert Discovered Episode", "tags": [ "admin-podcasts" ] } }, "/api/v1/admin/podcasts/auto-transcribe/feeds": { "get": { "description": "Feeds + last-seen GUID + curation knobs per feed, for the discovery\nworkflow (R3; P4 S2 R-P4.4/R-P4.5).\n\nRows are returned in discovery order: priority ASC (lower = higher priority),\ntie-broken by created_at DESC — so the workflow enqueues higher-priority\nfeeds' new episodes first. ``diarization_enabled`` flows through to the\npipeline job so the worker can skip diarization for that feed.\n\ntidy-tenant-wide-justified: global admin-curated feed roster for the\ndiscovery workflow; no per-tenant row payload.", "operationId": "listAutoTranscribedFeeds", "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/AutoTranscribedFeed" }, "title": "Response Listautotranscribedfeeds", "type": "array" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List Auto Transcribed Feeds", "tags": [ "admin-podcasts" ] } }, "/api/v1/admin/podcasts/auto-transcribe/status": { "get": { "description": "Live curation status: batch ledger + last corpus ingests + provider avail.\n\ntidy-tenant-wide-justified: global aggregate; no per-tenant primitive row\npayload — only batch summaries, ingest breadcrumbs, and provider status.", "operationId": "getAutoTranscribeStatus", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Getautotranscribestatus", "type": "object" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Auto Transcribe Status Endpoint", "tags": [ "admin-podcasts" ] } }, "/api/v1/admin/podcasts/auto-transcribe/{podcast_id}": { "delete": { "description": "Remove a podcast from the Auto-Transcribed list. Audited (fail-closed).", "operationId": "removeAutoTranscribedPodcast", "parameters": [ { "in": "path", "name": "podcast_id", "required": true, "schema": { "title": "Podcast Id", "type": "string" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Remove Auto Transcribed Podcast", "tags": [ "admin-podcasts" ] }, "patch": { "description": "Update priority and/or diarization_enabled. Audited (fail-closed).", "operationId": "updateAutoTranscribedPodcast", "parameters": [ { "in": "path", "name": "podcast_id", "required": true, "schema": { "title": "Podcast Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutoTranscribedUpdate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutoTranscribedResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Update Auto Transcribed Podcast", "tags": [ "admin-podcasts" ] } }, "/api/v1/admin/podcasts/cuts/bulk-reclassify-ad": { "post": { "description": "Tag N cuts as ``ad`` (extends R70). One audit row per cut.\n\nThe ad classification is carried on the existing ``podcast_cuts.tags`` array\n(idempotent append) — there is no dedicated ad column on the CA1 cut schema,\nso the tag is the real, durable reclassification signal.", "operationId": "bulkReclassifyCutsAd", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkIdsRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkResult" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Bulk Reclassify Cuts Ad", "tags": [ "admin-bulk-actions" ] } }, "/api/v1/admin/podcasts/entities/bulk-reextract": { "post": { "description": "Re-resolve N entity match suggestions as false_positive so the corpus is\nre-derived on the next extraction pass (extends R64/R70). One audit per item.", "operationId": "bulkReextractEntities", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkIdsRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkResult" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Bulk Reextract Entities", "tags": [ "admin-bulk-actions" ] } }, "/api/v1/admin/podcasts/entities/enrichment-counters": { "get": { "description": "Per-source enrichment request counters + the Exa.ai monthly budget for the\nCA9 admin panel (CA7 S3 / R66 admin).\n\ntidy-tenant-wide-justified: platform-level enrichment operational counters\nfor the global corpus (D75); no per-tenant primitive payload.", "operationId": "getPodcastEntityEnrichmentCounters", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnrichmentSourceCountersResponse" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Enrichment Counters", "tags": [ "admin-podcast-entities" ] } }, "/api/v1/admin/podcasts/entities/quarantine-episode": { "post": { "description": "Quarantine an episode's candidate mentions (mass-false-positive case, R70).\n\ntidy-tenant-wide-justified: global corpus moderation action (D75).", "operationId": "quarantinePodcastEpisodeEntities", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuarantineRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Quarantinepodcastepisodeentities", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Quarantine Episode", "tags": [ "admin-podcast-entities" ] } }, "/api/v1/admin/podcasts/entities/run-extraction": { "post": { "description": "Fan out the podcast-entity-worker /extract over the GLOBAL episodes\ntranscribed in the batch (CA7 S2 / D74). Called by the n8n nightly batch\nAFTER transcription+diarization, BEFORE CA6 AI insights.\n\ntidy-tenant-wide-justified: the podcast entity corpus is global (D75); this\ndrives extraction over the shared catalog + its shared transcripts, with no\nper-tenant primitive payload. Personal episodes are never selected, and the\nworker fail-closes on any non-global id (D81).", "operationId": "runPodcastEntityExtraction", "parameters": [ { "in": "query", "name": "batch_id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Batch Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunExtractionResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Run Podcast Entity Extraction", "tags": [ "admin-podcast-entities" ] } }, "/api/v1/admin/podcasts/entities/suggestions": { "get": { "description": "List pending entity match suggestions for admin review (R70).\n\ntidy-tenant-wide-justified: the entity corpus + its admin review queue are\nglobal (D75); no per-tenant primitive payload.", "operationId": "listPodcastEntitySuggestions", "parameters": [ { "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "title": "Limit", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "additionalProperties": true, "type": "object" }, "title": "Response Listpodcastentitysuggestions", "type": "array" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List Suggestions", "tags": [ "admin-podcast-entities" ] } }, "/api/v1/admin/podcasts/entities/suggestions/{suggestion_id}/resolve": { "post": { "description": "Resolve a suggestion: accept (promote/merge), dismiss, false_positive, or\nhomophone_merge into target_entity_id (R70).\n\ntidy-tenant-wide-justified: global corpus approval workflow (D75).", "operationId": "resolvePodcastEntitySuggestion", "parameters": [ { "in": "path", "name": "suggestion_id", "required": true, "schema": { "title": "Suggestion Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResolveSuggestionRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Resolvepodcastentitysuggestion", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Resolve Suggestion", "tags": [ "admin-podcast-entities" ] } }, "/api/v1/admin/podcasts/episodes/bulk-retranscribe": { "post": { "description": "Re-transcribe N episodes (extends R44). One audit row per enqueued item.", "operationId": "bulkRetranscribeEpisodes", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkIdsRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkResult" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Bulk Retranscribe Episodes", "tags": [ "admin-bulk-actions" ] } }, "/api/v1/admin/podcasts/episodes/{episode_id}/retranscribe": { "post": { "description": "Enqueue an episode for re-transcription at the manual HIGH priority (D53).\n\nDe-duped at enqueue: a queued/processing re-transcribe for the same episode\nshort-circuits. Audited (podcast.re_transcribe). On completion the nightly\nbatch stamps a new model-versioned transcript version and re-runs AI\nextraction on the episode's cuts.\n\ntidy-tenant-wide-justified: admin re-transcribe is a global-catalog op over\na platform-owned episode; no per-tenant primitive row payload is involved.", "operationId": "retranscribeEpisode", "parameters": [ { "in": "path", "name": "episode_id", "required": true, "schema": { "title": "Episode Id", "type": "string" } } ], "responses": { "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetranscribeResult" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Retranscribe Episode", "tags": [ "admin-podcasts" ] } }, "/api/v1/admin/podcasts/episodes/{episode_id}/transcript-versions": { "get": { "description": "Version history for a global episode with per-version pinned-cut counts.\n\ntidy-tenant-wide-justified: admin transcript-version history over a GLOBAL\ncatalog episode; no per-tenant primitive row payload leaves the service —\nonly model versions, timestamps, and aggregate cut counts.", "operationId": "listEpisodeTranscriptVersions", "parameters": [ { "in": "path", "name": "episode_id", "required": true, "schema": { "title": "Episode Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/TranscriptVersionItem" }, "title": "Response Listepisodetranscriptversions", "type": "array" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List Episode Transcript Versions", "tags": [ "admin-podcasts" ] } }, "/api/v1/admin/podcasts/featured": { "get": { "description": "List the platform-global Featured roster (TIDY-11910, TIDY-17775).\n\ntidy-tenant-wide-justified: global admin-curated catalog list; no\nper-tenant primitive row payload — only the platform-owned Featured roster.\n\nWorks for operators with no tenant membership.", "operationId": "listFeaturedPodcasts", "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/FeaturedPodcastResponse" }, "title": "Response Listfeaturedpodcasts", "type": "array" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List Featured Podcasts", "tags": [ "admin-podcasts" ] }, "post": { "description": "Add a podcast to the platform-global featured list. Audited (fail-closed).\n\nFeatured podcasts are PLATFORM data (TIDY-11909/TIDY-11910): the row is\nnever stamped with the admin's workspace tenant — added_by_account_id is\nan audit-only record of which admin account touched it (ON DELETE SET\nNULL, so the row survives the admin). Every tenant receives the row via\nthe Tier-A podcast_global_catalog sync bucket.", "operationId": "addFeaturedPodcast", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeaturedPodcastCreate" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeaturedPodcastResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Add Featured Podcast", "tags": [ "admin-podcasts" ] } }, "/api/v1/admin/podcasts/featured/{podcast_id}": { "delete": { "description": "Remove a podcast from the featured list. Audited (fail-closed).", "operationId": "removeFeaturedPodcast", "parameters": [ { "in": "path", "name": "podcast_id", "required": true, "schema": { "title": "Podcast Id", "type": "string" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Remove Featured Podcast", "tags": [ "admin-podcasts" ] } }, "/api/v1/admin/podcasts/pipeline/corpus-status": { "get": { "description": "This env's own corpus view from podcast_corpus_ingest_log (R-P4.3).\n\nNO call to dag — the env's ingest_log is the truth for \"what reached HERE\".\nEmpty log → zeros + empty lists (not an error).", "operationId": "getAdminPipelineCorpusStatus", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CorpusStatusResponse" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "This env's corpus ingest state (from podcast_corpus_ingest_log; no dag call)", "tags": [ "admin-podcast-pipeline", "admin-podcast-pipeline" ] } }, "/api/v1/admin/podcasts/pipeline/status": { "get": { "description": "Proxy the pipeline's /status with a 5s timeout (R-P4.1).\n\nThe X-Pipeline-Token stays server-side. An unreachable pipeline (connection\nerror, timeout, 401 auth misconfig, 5xx) returns 200 with\n``pipeline_reachable:false`` + the reason — NEVER a 502. This is surfacing the\noutage to the operator, not a fallback (no synthesized status is returned).", "operationId": "getAdminPipelineStatus", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PipelineStatusResponse" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Live external-pipeline status (server-side proxy; outage-surfacing)", "tags": [ "admin-podcast-pipeline", "admin-podcast-pipeline" ] } }, "/api/v1/admin/podcasts/pipeline/transcript": { "get": { "description": "Return the env's CURRENT transcript version for an episode (TIDY-11726).\n\nResolution goes through ``podcast_corpus_ingest_log`` on ``(rss_feed_url,\nguid)`` — the pipeline's deterministic UUIDv5 is NOT the env episode id, so a\ndirect id lookup would be wrong. A completion that exists on dag but has not\nreached THIS env yields a 404 (``episode_not_in_env``); the viewer renders an\nexplicit \"not in this environment yet\" state, never an opaque error.\n\nThe transcript itself is read from THIS env's tables — the browser never\ntalks to dag for transcript content (the pipeline /status is status-only).", "operationId": "getAdminPipelineTranscript", "parameters": [ { "description": "Show RSS feed URL (the episode-identity key).", "in": "query", "name": "rss_feed_url", "required": true, "schema": { "description": "Show RSS feed URL (the episode-identity key).", "title": "Rss Feed Url", "type": "string" } }, { "description": "Episode GUID (the episode-identity key).", "in": "query", "name": "guid", "required": true, "schema": { "description": "Episode GUID (the episode-identity key).", "title": "Guid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TranscriptResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "This env's current transcript for an episode resolved by (rss_feed_url, guid)", "tags": [ "admin-podcast-pipeline", "admin-podcast-pipeline" ] } }, "/api/v1/admin/podcasts/qa/attainment": { "get": { "description": "D55 target-attainment (mean WER/DER/name-confidence) + failure prevalence.\n\ntidy-tenant-wide-justified: aggregate QA-corpus reporting; counts/rates only.", "operationId": "getQaAttainment", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Getqaattainment", "type": "object" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Qa Attainment", "tags": [ "admin-podcasts" ] } }, "/api/v1/admin/podcasts/qa/labels": { "post": { "description": "Write one QA label (region / speaker / failure_mode) to the Tier E table.", "operationId": "createQaLabel", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QALabelCreate" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QALabelResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Create Qa Label", "tags": [ "admin-podcasts" ] } }, "/api/v1/admin/podcasts/qa/sample": { "get": { "description": "The current week's stratified QA sample (5-10 episodes, D54).\n\ntidy-tenant-wide-justified: QA sampling over the platform-owned transcript\ncorpus; returns episode ids + quality metadata only.", "operationId": "getQaSample", "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/QASampleEpisode" }, "title": "Response Getqasample", "type": "array" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Qa Sample", "tags": [ "admin-podcasts" ] } }, "/api/v1/admin/podcasts/quality/overview": { "get": { "description": "Quality distribution for the admin Quality tab (status counts, mean\nconfidence, flag-reason prevalence, recent low/failed episodes).\n\nEpisodes ingested before the quality re-wire (NULL quality_status) report\nunder ``not_yet_scored`` and are NEVER counted as failed (backfill note).\n\ntidy-tenant-wide-justified: GLOBAL podcast-corpus quality aggregate; returns\ncounts/rates + platform-owned catalog metadata only, no per-tenant row.", "operationId": "getPodcastQualityOverview", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QualityOverviewResponse" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Podcast Quality Overview", "tags": [ "admin-podcasts" ] } }, "/api/v1/admin/podcasts/transcript-versions/run-retention": { "post": { "description": "Apply the D69 retention policy now (soft-delete beyond newest 3; never a\ncut-pinned version; hard-delete after 90 days soft + unreferenced). Audited.\n\ntidy-tenant-wide-justified: global transcript corpus maintenance; operates\non the platform-owned version store, returns aggregate counts only.", "operationId": "runTranscriptVersionRetention", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetentionResult" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Run Transcript Version Retention", "tags": [ "admin-podcasts" ] } }, "/api/v1/admin/podcasts/transcript-versions/scan-stale": { "post": { "description": "Scan for episodes transcribed with an older model loadout and enqueue them\nat the LOW stale-model tier (D53/D14). n8n calls this after a loadout swap.\n\ntidy-tenant-wide-justified: global re-transcription maintenance over the\nplatform-owned catalog; operates on model-version provenance only.", "operationId": "scanStaleTranscriptVersions", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StaleScanResult" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Scan Stale Transcript Versions", "tags": [ "admin-podcasts" ] } }, "/api/v1/admin/podcasts/usage/batches": { "get": { "operationId": "listOvernightBatches", "parameters": [ { "in": "query", "name": "days", "required": false, "schema": { "default": 7, "maximum": 90, "minimum": 1, "title": "Days", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/OvernightBatchRow" }, "title": "Response Listovernightbatches", "type": "array" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Overnight transcription batches grouped by night (last N days)", "tags": [ "admin-podcast-usage", "admin-podcast-usage" ] } }, "/api/v1/admin/podcasts/usage/batches/queue": { "get": { "description": "Ledger-derived priority metrics (P4 S1, R-P4.2).\n\nThe removed D14 tier queue's per_tier/dead-queue payload is GONE. Metrics now\nderive from the P3 ledger (podcast_transcription_batches/_batch_items,\nprovider='pipeline_priority'): pending items, processing batches, completed\ntoday, failed items, and the oldest pending request's wait.", "operationId": "getBatchQueueMetrics", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PriorityLedgerMetrics" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Live priority-request ledger metrics (pending/in-flight/completed-today/failed)", "tags": [ "admin-podcast-usage", "admin-podcast-usage" ] } }, "/api/v1/admin/podcasts/usage/completed-items": { "get": { "description": "Recent COMPLETED priority-request ledger items (TIDY-11726).\n\nEach row carries its episode-identity key ``(rss_feed_url, guid)`` so the\nadmin transcript viewer can resolve THIS env's transcript when the operator\nclicks the row. ``guid`` comes from the external episode the item references;\n``rss_feed_url`` from that episode's subscription. The transcript itself is\nGLOBAL and resolved through the corpus ingest log by the transcript endpoint.", "operationId": "listCompletedTranscriptionItems", "parameters": [ { "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "maximum": 200, "minimum": 1, "title": "Limit", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/CompletedLedgerItemRow" }, "title": "Response Listcompletedtranscriptionitems", "type": "array" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Completed priority-request ledger items with their (feed, guid) key", "tags": [ "admin-podcast-usage", "admin-podcast-usage" ] } }, "/api/v1/admin/podcasts/usage/cost-trends": { "get": { "operationId": "getPlatformCostTrends", "parameters": [ { "in": "query", "name": "days", "required": false, "schema": { "default": 30, "maximum": 180, "minimum": 1, "title": "Days", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/CostTrendRow" }, "title": "Response Getplatformcosttrends", "type": "array" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Daily platform transcription cost (last N days), split by category", "tags": [ "admin-podcast-usage", "admin-podcast-usage" ] } }, "/api/v1/admin/podcasts/usage/failed-jobs": { "get": { "description": "Failed priority-request ledger ITEMS (P4 S1, R-P4.2).\n\nEach row is a P3-ledger item in the 'failed' state, carrying the error\npayload + failure stage from the P3 failure push, the episode identity, and\nthe requester context the ledger already holds (tenant/account).", "operationId": "listFailedTranscriptionJobs", "parameters": [ { "in": "query", "name": "limit", "required": false, "schema": { "default": 100, "maximum": 500, "minimum": 1, "title": "Limit", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/FailedLedgerItemRow" }, "title": "Response Listfailedtranscriptionjobs", "type": "array" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Failed priority-request ledger items (most recent first)", "tags": [ "admin-podcast-usage", "admin-podcast-usage" ] } }, "/api/v1/admin/podcasts/usage/failed-jobs/{request_ref}/retry": { "post": { "description": "Re-dispatch a FAILED priority request via the P3 client (P4 S1, R-P4.2;\nTIDY-11724 S3 fix).\n\nThe retry creates a NEW priority dispatch through the P3 PipelinePriorityClient\n(a NEW ledger item, target_env = our own env) — it NEVER resurrects old\nprovider-batch machinery (one dispatch path, the P3 engine swap is total). The\nre-dispatch resolves the episode identity (rss_feed_url / guid / audio_url)\nfrom the FAILED LEDGER ITEM ITSELF — it does NOT require a queue_item_id, so a\ndownload-stage failure pushed BEFORE queue-item linkage (queue_item_id IS NULL)\nis still re-dispatchable. A retry of a NON-failed item is a 409. Audited like\nother admin mutations.", "operationId": "retryFailedTranscriptionJob", "parameters": [ { "in": "path", "name": "request_ref", "required": true, "schema": { "format": "uuid", "title": "Request Ref", "type": "string" } } ], "responses": { "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetryFailedJobResult" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Re-dispatch a failed priority request via the pipeline (new ledger item)", "tags": [ "admin-podcast-usage", "admin-podcast-usage" ] } }, "/api/v1/admin/podcasts/usage/jobs/{job_id}": { "get": { "operationId": "getTranscriptionJobDetail", "parameters": [ { "in": "path", "name": "job_id", "required": true, "schema": { "format": "uuid", "title": "Job Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobDetailResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Per-job detail: co-requesters, model, timing, related cuts", "tags": [ "admin-podcast-usage", "admin-podcast-usage" ] } }, "/api/v1/admin/podcasts/usage/tenants": { "get": { "operationId": "listTenantUsageRanking", "parameters": [ { "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "maximum": 500, "minimum": 1, "title": "Limit", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/TenantUsageRow" }, "title": "Response Listtenantusageranking", "type": "array" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Per-tenant transcription usage ranking (this calendar month)", "tags": [ "admin-podcast-usage", "admin-podcast-usage" ] } }, "/api/v1/admin/ranking/kill-switch": { "post": { "description": "Roll a surface back to its previous configuration, or to the baseline.", "operationId": "activateRankingKillSwitch", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KillSwitchRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KillSwitchResult" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Activate Kill Switch", "tags": [ "admin-ranking" ], "x-mcp-skip": true, "x-mcp-skip-reason": "Tenant-admin ranking control; not an agent-callable tool." } }, "/api/v1/admin/ranking/rollout/{surface}": { "get": { "description": "The stage, its evidence, and why it may or may not widen.", "operationId": "getRankingRolloutStatus", "parameters": [ { "in": "path", "name": "surface", "required": true, "schema": { "title": "Surface", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RankingRolloutStatus" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Rollout Status", "tags": [ "admin-ranking" ], "x-mcp-skip": true, "x-mcp-skip-reason": "Platform-operator ranking rollout control; not an agent-callable tool." } }, "/api/v1/admin/ranking/rollout/{surface}/advance": { "post": { "description": "Widen the stage one rung, if the promotion gate passes.\n\nA refusal is a 200 with ``advanced: false`` and the blocking criteria, not an\nerror: \"the evidence is not there yet\" is the normal answer for most of a\nrollout's life, and an operator polling it should not have to parse an\nexception to read a verdict.", "operationId": "advanceRankingRollout", "parameters": [ { "in": "path", "name": "surface", "required": true, "schema": { "title": "Surface", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RankingRolloutAdvanceRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RankingRolloutAdvanceResult" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Advance Rollout", "tags": [ "admin-ranking" ], "x-mcp-skip": true, "x-mcp-skip-reason": "Platform-operator ranking rollout control; not an agent-callable tool." } }, "/api/v1/admin/ranking/rollout/{surface}/rollback": { "post": { "description": "Take the surface to stage 0. Idempotent — a second call is a 200.", "operationId": "rollbackRankingRollout", "parameters": [ { "in": "path", "name": "surface", "required": true, "schema": { "title": "Surface", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RankingRolloutRollbackRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RankingRolloutRollbackResult" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Rollback Rollout", "tags": [ "admin-ranking" ], "x-mcp-skip": true, "x-mcp-skip-reason": "Platform-operator ranking rollout control; not an agent-callable tool." } }, "/api/v1/admin/rate-limit-overrides": { "get": { "operationId": "listRateLimitOverrides", "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/OverrideResponse" }, "title": "Response Listratelimitoverrides", "type": "array" } } }, "description": "Successful Response" } }, "summary": "List Overrides", "tags": [ "rate-limit-overrides", "rate-limit-overrides" ] }, "post": { "operationId": "upsertRateLimitOverride", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OverrideCreate" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OverrideResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Create Override", "tags": [ "rate-limit-overrides", "rate-limit-overrides" ] } }, "/api/v1/admin/rate-limit-overrides/{override_id}": { "delete": { "operationId": "deleteRateLimitOverride", "parameters": [ { "in": "path", "name": "override_id", "required": true, "schema": { "format": "uuid", "title": "Override Id", "type": "string" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Delete Override", "tags": [ "rate-limit-overrides", "rate-limit-overrides" ] } }, "/api/v1/admin/recipe-engine/definitions": { "get": { "operationId": "listRecipeEngineDefinitions", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DefinitionListResponse" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List Definitions", "tags": [ "admin-recipe-engine" ], "x-mcp-skip": true }, "post": { "operationId": "createRecipeEngineDefinition", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DefinitionCreateRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DefinitionSummary" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Create Definition", "tags": [ "admin-recipe-engine" ], "x-mcp-skip": true } }, "/api/v1/admin/recipe-engine/definitions/{definition_id}": { "get": { "operationId": "getRecipeEngineDefinition", "parameters": [ { "in": "path", "name": "definition_id", "required": true, "schema": { "format": "uuid", "title": "Definition Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DefinitionDetailResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Definition", "tags": [ "admin-recipe-engine" ], "x-mcp-skip": true } }, "/api/v1/admin/recipe-engine/definitions/{definition_id}/audit": { "get": { "operationId": "listRecipeEngineAudit", "parameters": [ { "in": "path", "name": "definition_id", "required": true, "schema": { "format": "uuid", "title": "Definition Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_service__routers__admin_recipe_engine__AuditListResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List Audit", "tags": [ "admin-recipe-engine" ], "x-mcp-skip": true } }, "/api/v1/admin/recipe-engine/definitions/{definition_id}/renewed-consent": { "post": { "description": "Flag a suppressed behavior for renewed consent (TIDY-14827, R40).\n\nSurfaces the rationale on every affected member's suppression list; ONLY\nthe member's explicit revoke resumes the behavior — this endpoint never\nlifts a suppression itself. Audited on the lifecycle ledger.", "operationId": "requestRecipeRenewedConsent", "parameters": [ { "in": "path", "name": "definition_id", "required": true, "schema": { "format": "uuid", "title": "Definition Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RenewedConsentRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RenewedConsentResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Request Renewed Consent", "tags": [ "admin-recipe-engine" ], "x-mcp-skip": true } }, "/api/v1/admin/recipe-engine/definitions/{definition_id}/resolve": { "get": { "operationId": "resolveRecipeEngineBinding", "parameters": [ { "in": "path", "name": "definition_id", "required": true, "schema": { "format": "uuid", "title": "Definition Id", "type": "string" } }, { "in": "query", "name": "tenant_id", "required": true, "schema": { "format": "uuid", "title": "Tenant Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResolveBindingResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Resolve Binding", "tags": [ "admin-recipe-engine" ], "x-mcp-skip": true } }, "/api/v1/admin/recipe-engine/definitions/{definition_id}/versions": { "post": { "operationId": "createRecipeEngineVersion", "parameters": [ { "in": "path", "name": "definition_id", "required": true, "schema": { "format": "uuid", "title": "Definition Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VersionCreateRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VersionCreateResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Create Version", "tags": [ "admin-recipe-engine" ], "x-mcp-skip": true } }, "/api/v1/admin/recipe-engine/delegations": { "get": { "operationId": "listRecipeDelegations", "parameters": [ { "in": "query", "name": "agent_account_id", "required": false, "schema": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Agent Account Id" } }, { "in": "query", "name": "include_revoked", "required": false, "schema": { "default": false, "title": "Include Revoked", "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DelegationListResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List Delegations", "tags": [ "admin-recipe-engine" ], "x-local-capability": "cloud", "x-mcp-skip": true }, "post": { "operationId": "createRecipeDelegation", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DelegationCreateRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DelegationModel" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Create Delegation", "tags": [ "admin-recipe-engine" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/admin/recipe-engine/delegations/{delegation_id}": { "patch": { "operationId": "updateRecipeDelegation", "parameters": [ { "in": "path", "name": "delegation_id", "required": true, "schema": { "format": "uuid", "title": "Delegation Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DelegationPatchRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DelegationModel" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Update Delegation", "tags": [ "admin-recipe-engine" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/admin/recipe-engine/delegations/{delegation_id}/revoke": { "post": { "operationId": "revokeRecipeDelegation", "parameters": [ { "in": "path", "name": "delegation_id", "required": true, "schema": { "format": "uuid", "title": "Delegation Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DelegationModel" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Revoke Delegation", "tags": [ "admin-recipe-engine" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/admin/recipe-engine/health/recurrence": { "get": { "operationId": "getRecipeEngineRecurrenceHealth", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecurrenceHealthResponse" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Recurrence Health", "tags": [ "admin-recipe-engine" ], "x-mcp-skip": true } }, "/api/v1/admin/recipe-engine/health/recurrence/{definition_id}/repair": { "post": { "operationId": "repairRecipeEngineRecurrence", "parameters": [ { "in": "path", "name": "definition_id", "required": true, "schema": { "format": "uuid", "title": "Definition Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RepairResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Repair Recurrence", "tags": [ "admin-recipe-engine" ], "x-mcp-skip": true } }, "/api/v1/admin/recipe-engine/opportunities": { "get": { "operationId": "listRecipeOpportunities", "parameters": [ { "in": "query", "name": "status_filter", "required": false, "schema": { "default": "open", "enum": [ "open", "approved", "rejected", "expired" ], "title": "Status Filter", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpportunityListResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List Opportunities", "tags": [ "admin-recipe-engine" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/admin/recipe-engine/opportunities/{opportunity_id}/decide": { "post": { "description": "D9: math suggested — THIS is the accountable decision. Approving\nexecutes the suggested lifecycle action through the audited state machine\n(opportunity id on the lifecycle event); rejecting archives with\nrationale. No unowned automatic promotion exists.", "operationId": "decideRecipeOpportunity", "parameters": [ { "in": "path", "name": "opportunity_id", "required": true, "schema": { "format": "uuid", "title": "Opportunity Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpportunityDecideRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpportunityDecideResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Decide Opportunity", "tags": [ "admin-recipe-engine" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/admin/recipe-engine/replay-compare": { "get": { "operationId": "compareReplaySessions", "parameters": [ { "in": "query", "name": "a", "required": true, "schema": { "format": "uuid", "title": "A", "type": "string" } }, { "in": "query", "name": "b", "required": true, "schema": { "format": "uuid", "title": "B", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReplayCompareResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Compare Replay Sessions", "tags": [ "admin-recipe-engine" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/admin/recipe-engine/replay-sessions": { "get": { "description": "Newest-first session index for the replay manager UI (TIDY-14840).", "operationId": "listReplaySessions", "parameters": [ { "in": "query", "name": "limit", "required": false, "schema": { "default": 100, "maximum": 500, "minimum": 1, "title": "Limit", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReplaySessionListResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List Replay Sessions", "tags": [ "admin-recipe-engine" ], "x-local-capability": "cloud", "x-mcp-skip": true }, "post": { "operationId": "createReplaySession", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReplaySessionCreateRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReplaySessionResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Create Replay Session", "tags": [ "admin-recipe-engine" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/admin/recipe-engine/replay-sessions/{session_id}": { "get": { "operationId": "getReplaySession", "parameters": [ { "in": "path", "name": "session_id", "required": true, "schema": { "format": "uuid", "title": "Session Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReplaySessionResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Replay Session", "tags": [ "admin-recipe-engine" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/admin/recipe-engine/replay-sessions/{session_id}/cancel": { "post": { "operationId": "cancelReplaySession", "parameters": [ { "in": "path", "name": "session_id", "required": true, "schema": { "format": "uuid", "title": "Session Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReplaySessionResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Cancel Replay Session", "tags": [ "admin-recipe-engine" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/admin/recipe-engine/replay-sessions/{session_id}/start": { "post": { "operationId": "startReplaySession", "parameters": [ { "in": "path", "name": "session_id", "required": true, "schema": { "format": "uuid", "title": "Session Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReplaySessionResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Start Replay Session", "tags": [ "admin-recipe-engine" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/admin/recipe-engine/replay-sessions/{session_id}/timeline": { "get": { "operationId": "getReplaySessionTimeline", "parameters": [ { "in": "path", "name": "session_id", "required": true, "schema": { "format": "uuid", "title": "Session Id", "type": "string" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 200, "maximum": 1000, "minimum": 1, "title": "Limit", "type": "integer" } }, { "in": "query", "name": "offset", "required": false, "schema": { "default": 0, "minimum": 0, "title": "Offset", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TimelineResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Replay Session Timeline", "tags": [ "admin-recipe-engine" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/admin/recipe-engine/rollouts": { "post": { "operationId": "createRecipeEngineRollout", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RolloutCreateRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RolloutResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Create Rollout", "tags": [ "admin-recipe-engine" ], "x-mcp-skip": true } }, "/api/v1/admin/recipe-engine/rollouts/{rollout_id}": { "patch": { "operationId": "updateRecipeEngineRollout", "parameters": [ { "in": "path", "name": "rollout_id", "required": true, "schema": { "format": "uuid", "title": "Rollout Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RolloutPatchRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Updaterecipeenginerollout", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Update Rollout", "tags": [ "admin-recipe-engine" ], "x-mcp-skip": true } }, "/api/v1/admin/recipe-engine/runs": { "get": { "operationId": "listRecipeEngineRuns", "parameters": [ { "in": "query", "name": "definition_id", "required": false, "schema": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Definition Id" } }, { "in": "query", "name": "version_id", "required": false, "schema": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Version Id" } }, { "in": "query", "name": "tenant_id", "required": false, "schema": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Tenant Id" } }, { "in": "query", "name": "status", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Status" } }, { "in": "query", "name": "mode", "required": false, "schema": { "anyOf": [ { "enum": [ "live", "replay", "evaluation" ], "type": "string" }, { "type": "null" } ], "title": "Mode" } }, { "in": "query", "name": "since", "required": false, "schema": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Since" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 100, "maximum": 500, "minimum": 1, "title": "Limit", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunListResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List Runs", "tags": [ "admin-recipe-engine" ], "x-mcp-skip": true } }, "/api/v1/admin/recipe-engine/runs/{run_id}": { "get": { "operationId": "getRecipeEngineRun", "parameters": [ { "in": "path", "name": "run_id", "required": true, "schema": { "format": "uuid", "title": "Run Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunDetailResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Run", "tags": [ "admin-recipe-engine" ], "x-mcp-skip": true } }, "/api/v1/admin/recipe-engine/versions/{version_id}/evaluate": { "post": { "description": "Run the ten-class evaluation baseline + readiness gates (TIDY-14830,\nR30/R44). The artifact persists immutably on the candidate version and is\nthe approving principal's evidence.", "operationId": "evaluateRecipeEngineVersion", "parameters": [ { "in": "path", "name": "version_id", "required": true, "schema": { "format": "uuid", "title": "Version Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EvaluateResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Evaluate Version Endpoint", "tags": [ "admin-recipe-engine" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/admin/recipe-engine/versions/{version_id}/transition": { "post": { "operationId": "transitionRecipeEngineVersion", "parameters": [ { "in": "path", "name": "version_id", "required": true, "schema": { "format": "uuid", "title": "Version Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransitionRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransitionResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Transition Version", "tags": [ "admin-recipe-engine" ], "x-mcp-skip": true } }, "/api/v1/admin/saved-queries": { "get": { "description": "List the calling admin's saved queries (per-admin scope).", "operationId": "listAdminSavedQueries", "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/SavedQueryResponse" }, "title": "Response Listadminsavedqueries", "type": "array" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List Saved Queries", "tags": [ "admin-saved-queries" ] }, "post": { "description": "Create a saved query (validates the spec against the allow-list).", "operationId": "createAdminSavedQuery", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SavedQueryCreate" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SavedQueryResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Create Saved Query", "tags": [ "admin-saved-queries" ] } }, "/api/v1/admin/saved-queries/{query_id}": { "delete": { "description": "Delete a saved query (per-admin scope).", "operationId": "deleteAdminSavedQuery", "parameters": [ { "in": "path", "name": "query_id", "required": true, "schema": { "format": "uuid", "title": "Query Id", "type": "string" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Delete Saved Query", "tags": [ "admin-saved-queries" ] }, "patch": { "description": "Rename / edit / reschedule a saved query (per-admin scope).", "operationId": "updateAdminSavedQuery", "parameters": [ { "in": "path", "name": "query_id", "required": true, "schema": { "format": "uuid", "title": "Query Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SavedQueryPatch" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SavedQueryResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Update Saved Query", "tags": [ "admin-saved-queries" ] } }, "/api/v1/admin/saved-queries/{query_id}/run": { "post": { "description": "Execute a saved query's spec against its allow-listed view and return\nmatches. A spec referencing a removed view/column → graceful 400, query\npreserved (edge case).", "operationId": "runAdminSavedQuery", "parameters": [ { "in": "path", "name": "query_id", "required": true, "schema": { "format": "uuid", "title": "Query Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SavedQueryRunResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Run Saved Query", "tags": [ "admin-saved-queries" ] } }, "/api/v1/admin/service-usage/aggregate": { "get": { "description": "Aggregate billable + non-billable usage. Tenant/account/resource/\nprovider/service/tool/channel/status/day are all valid group_by values.\n\nReusable for any future resource family — caller passes\n`resource_type=storage_byte` (etc.) and the same dimensions apply.", "operationId": "adminAggregateServiceUsage", "parameters": [ { "in": "query", "name": "tenant_id", "required": false, "schema": { "anyOf": [ { "items": { "format": "uuid", "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Tenant Id" } }, { "in": "query", "name": "resource_type", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Resource Type" } }, { "in": "query", "name": "provider", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Provider" } }, { "in": "query", "name": "service_name", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Service Name" } }, { "in": "query", "name": "since", "required": false, "schema": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Since" } }, { "in": "query", "name": "until", "required": false, "schema": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Until" } }, { "in": "query", "name": "group_by", "required": false, "schema": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Group By" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/AggregateRow" }, "title": "Response Adminaggregateserviceusage", "type": "array" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Admin Aggregate", "tags": [ "service-usage" ] } }, "/api/v1/admin/settings": { "get": { "description": "Return the growth settings as a key-value dict.", "operationId": "getAllSettings", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Getallsettings", "type": "object" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get All Settings", "tags": [ "growth" ] }, "put": { "description": "Update a single growth setting.", "operationId": "updateSetting", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSettingRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SettingResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Update Setting", "tags": [ "growth" ] } }, "/api/v1/admin/shadow-eval/facet-report": { "get": { "description": "Per-facet edge-vs-backend agreement rate and divergence buckets over recorded facet shadow comparisons (F12-S7 / TIDY-15776), with the fabrication count reported whole rather than averaged into the rate. The evidence behind every automatic demotion, and the surface that shows a facet drifting BEFORE one fires.", "operationId": "getFacetShadowReport", "parameters": [ { "in": "query", "name": "window_days", "required": false, "schema": { "default": 7, "maximum": 90, "minimum": 1, "title": "Window Days", "type": "integer" } }, { "in": "query", "name": "facet_slug", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Facet Slug" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FacetShadowReportResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Per-facet edge quality report", "tags": [ "admin-shadow-eval" ], "x-mcp-skip": true } }, "/api/v1/admin/shadow-eval/report": { "get": { "description": "Per-class schema-validity rate, local-vs-cloud agreement rate, and latency distribution over recorded shadow pairs (S9.5 / TIDY-13270). The evidence for flipping a class's live DESKTOP_OFFLOAD_* flag.", "operationId": "getShadowEvalReport", "parameters": [ { "in": "query", "name": "window_days", "required": false, "schema": { "default": 7, "maximum": 90, "minimum": 1, "title": "Window Days", "type": "integer" } }, { "in": "query", "name": "task_class", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Task Class" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShadowEvalReportResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Desktop shadow-evaluation report", "tags": [ "admin-shadow-eval" ], "x-mcp-skip": true } }, "/api/v1/admin/shared-inbox-memberships": { "get": { "operationId": "listSharedInboxMemberships", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SharedInboxMembershipList" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List the tenant's shared-inbox memberships", "tags": [ "admin-shared-inbox-memberships" ], "x-mcp-skip": true, "x-mcp-skip-reason": "Tenant-admin entitlement management; not an agent-callable tool." } }, "/api/v1/admin/shared-inbox-memberships/{provider_connection_id}/{account_id}": { "delete": { "operationId": "deleteSharedInboxMembership", "parameters": [ { "in": "path", "name": "provider_connection_id", "required": true, "schema": { "format": "uuid", "title": "Provider Connection Id", "type": "string" } }, { "in": "path", "name": "account_id", "required": true, "schema": { "format": "uuid", "title": "Account Id", "type": "string" } }, { "in": "query", "name": "operation_id", "required": true, "schema": { "format": "uuid", "title": "Operation Id", "type": "string" } }, { "in": "query", "name": "expected_version", "required": true, "schema": { "minimum": 1, "title": "Expected Version", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SharedInboxMembership" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Revoke one shared-inbox membership", "tags": [ "admin-shared-inbox-memberships" ], "x-mcp-skip": true, "x-mcp-skip-reason": "Tenant-admin entitlement management; not an agent-callable tool." }, "put": { "operationId": "upsertSharedInboxMembership", "parameters": [ { "in": "path", "name": "provider_connection_id", "required": true, "schema": { "format": "uuid", "title": "Provider Connection Id", "type": "string" } }, { "in": "path", "name": "account_id", "required": true, "schema": { "format": "uuid", "title": "Account Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SharedInboxMembershipUpsert" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SharedInboxMembership" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Grant or update one shared-inbox membership", "tags": [ "admin-shared-inbox-memberships" ], "x-mcp-skip": true, "x-mcp-skip-reason": "Tenant-admin entitlement management; not an agent-callable tool." } }, "/api/v1/admin/sms-templates": { "get": { "operationId": "listAdminSmsTemplates", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SmsTemplateListResponse" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List SMS templates (system + tenant)", "tags": [ "admin-sms-templates" ], "x-mcp-skip": true }, "post": { "operationId": "createAdminSmsTemplate", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SmsTemplateSaveRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SmsTemplateRow" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Create a platform SMS template", "tags": [ "admin-sms-templates" ], "x-mcp-skip": true } }, "/api/v1/admin/sms-templates/{template_id}": { "delete": { "operationId": "deleteAdminSmsTemplate", "parameters": [ { "in": "path", "name": "template_id", "required": true, "schema": { "title": "Template Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Deleteadminsmstemplate", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Delete a non-system SMS template", "tags": [ "admin-sms-templates" ], "x-mcp-skip": true }, "get": { "operationId": "getAdminSmsTemplate", "parameters": [ { "in": "path", "name": "template_id", "required": true, "schema": { "title": "Template Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SmsTemplateRow" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get a single SMS template", "tags": [ "admin-sms-templates" ], "x-mcp-skip": true }, "patch": { "operationId": "toggleAdminSmsTemplate", "parameters": [ { "in": "path", "name": "template_id", "required": true, "schema": { "title": "Template Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SmsTemplateToggleRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Toggleadminsmstemplate", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Toggle SMS template active state", "tags": [ "admin-sms-templates" ], "x-mcp-skip": true }, "put": { "operationId": "updateAdminSmsTemplate", "parameters": [ { "in": "path", "name": "template_id", "required": true, "schema": { "title": "Template Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SmsTemplateSaveRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SmsTemplateRow" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Update SMS template content (ownership columns are create-only)", "tags": [ "admin-sms-templates" ], "x-mcp-skip": true } }, "/api/v1/admin/sources/repair-dangling-email-source-refs": { "post": { "description": "Tenant-scoped operator repair for legacy email_canonical rows whose email_source_id no longer joins to email_source_configs. Dry-run by default. Applies only when preserved tenant_secrets provider identity or provider alias coverage proves exactly one active target source; otherwise returns an explicit unrecoverable/ambiguous status and does not write.", "operationId": "adminRepairDanglingEmailSourceRefs", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RepairDanglingSourceRefsRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RepairDanglingSourceRefsResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Repair legacy dangling email_source_id references", "tags": [ "admin", "admin-sources" ] } }, "/api/v1/admin/sources/{source_id}/backfill-history": { "post": { "description": "TIDY-8904: schedules the history-headers backfill orchestrator for an existing email_source_config that was connected BEFORE TIDY-8897 shipped (the orchestrator only runs from the first-run pipeline). Idempotent — a concurrent call for the same source returns immediately without spawning a second backfill. Returns a job identifier the operator can correlate to header_sync_folder_progress rows. The pre-flight folder discovery here is a fast path that surfaces discovery errors synchronously over HTTP; since TIDY-11796 phase_history_backfill self-heals missing mappings on its own, so the reconciler recovers a stuck source without this endpoint being called.", "operationId": "adminBackfillSourceHistory", "parameters": [ { "description": "email_source_config_id (UUID)", "in": "path", "name": "source_id", "required": true, "schema": { "description": "email_source_config_id (UUID)", "title": "Source Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BackfillHistoryResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Retroactively backfill history headers for an existing source", "tags": [ "admin", "admin-sources" ] } }, "/api/v1/admin/spend/caps/{tenant_id}": { "get": { "operationId": "getAdminTenantSpendCap", "parameters": [ { "in": "path", "name": "tenant_id", "required": true, "schema": { "format": "uuid", "title": "Tenant Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SpendCapResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Read a tenant's monthly LLM spend cap (platform operator)", "tags": [ "admin-spend", "admin-spend" ], "x-mcp-skip": true }, "put": { "description": "Platform-operator lane of the existing spend-cap service.\n\nWrites ``spend_caps`` (the ONE protection-layer cap table), preserves the\nexplicit cache invalidation, audits, and re-evaluates the budget state\nimmediately so raising a cap recovers a hard-stopped tenant at once.", "operationId": "setAdminTenantSpendCap", "parameters": [ { "in": "path", "name": "tenant_id", "required": true, "schema": { "format": "uuid", "title": "Tenant Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminSpendCapUpdate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SpendCapResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Set a tenant's monthly LLM spend cap (platform operator)", "tags": [ "admin-spend", "admin-spend" ], "x-mcp-skip": true } }, "/api/v1/admin/spend/daily-breaker/{service_name}": { "get": { "description": "The breaker's own figure, the raw ledger total, and what separates them.\n\nTIDY-17937: the breaker refused a service at $8.15 while the ledger summed\n$20.61 for the same service and day, and there was no surface on which an\noperator could see both numbers or discover why they differed. This reads\nthe SAME query builder the gate reads\n(``kcc_common.metering.daily_breaker_spend``), so the figure here IS the\nfigure that refuses a call — not a re-derivation that can drift from it —\nand returns the parameterised SQL so the reconciliation can be re-run by\nhand against the same database.", "operationId": "getAdminDailyBreakerReconciliation", "parameters": [ { "in": "path", "name": "service_name", "required": true, "schema": { "title": "Service Name", "type": "string" } }, { "in": "query", "name": "tenant_id", "required": false, "schema": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Tenant Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DailyBreakerReconciliationResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Reconcile a service's daily cost-breaker figure against the ledger", "tags": [ "admin-spend", "admin-spend" ], "x-mcp-skip": true } }, "/api/v1/admin/spend/summary": { "get": { "operationId": "getAdminSpendSummary", "parameters": [ { "in": "query", "name": "window", "required": false, "schema": { "default": "mtd", "pattern": "^mtd$", "title": "Window", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminSpendSummaryResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Admin MTD LLM-spend summary", "tags": [ "admin-spend", "admin-spend" ], "x-mcp-skip": true } }, "/api/v1/admin/stats": { "get": { "description": "Get comprehensive statistics for the admin dashboard.", "operationId": "getAdminStats", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminStatsResponse" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get admin dashboard stats", "tags": [ "admin", "admin-stats" ] } }, "/api/v1/admin/tenant/extraction-defaults": { "get": { "operationId": "getTenantExtractionDefaults", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExtractionDefaultsResponse" } } }, "description": "Successful Response" } }, "summary": "Get tenant-wide default extraction destinations", "tags": [ "extractions", "extractions" ], "x-mcp-skip": true, "x-mcp-skip-reason": "User/admin settings for the browser approval UI." }, "put": { "operationId": "putTenantExtractionDefaults", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExtractionDefaultsBody" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExtractionDefaultsResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Set tenant-wide default extraction destinations", "tags": [ "extractions", "extractions" ], "x-mcp-skip": true, "x-mcp-skip-reason": "User/admin settings for the browser approval UI." } }, "/api/v1/admin/tenant/output-catalog": { "get": { "operationId": "getTenantOutputCatalogEnablement", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OutputCatalogEnablementResponse" } } }, "description": "Successful Response" } }, "summary": "Get tenant enablement overrides for generated output types", "tags": [ "facet-definitions", "facets" ], "x-mcp-skip": true, "x-mcp-skip-reason": "Tenant admin settings surface for the output catalog." }, "put": { "operationId": "putTenantOutputCatalogEnablement", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OutputCatalogEnablementBody" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OutputCatalogEnablementResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Set tenant enablement overrides for generated output types", "tags": [ "facet-definitions", "facets" ], "x-mcp-skip": true, "x-mcp-skip-reason": "Tenant admin settings surface for the output catalog." } }, "/api/v1/admin/tenants": { "get": { "description": "List all tenants in the system (admin only).\n\n Includes summary statistics for each tenant.\n\n Related: 011-auth-user-onboarding T071", "operationId": "listTenants", "parameters": [ { "in": "query", "name": "status_filter", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Status Filter" } }, { "in": "query", "name": "search", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Search" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "title": "Limit", "type": "integer" } }, { "in": "query", "name": "offset", "required": false, "schema": { "default": 0, "title": "Offset", "type": "integer" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantListResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List all tenants", "tags": [ "admin", "admin-tenants" ] } }, "/api/v1/admin/tenants/{target_tenant_id}/podcast-delete": { "post": { "description": "Case B (D68): anonymize a tenant's podcast retention rows (the corpus is\nuntouched). Hard-delete of the tenant-scoped podcast data itself happens via\nthe tenant FK cascade when the tenant row is deleted; this endpoint performs\nthe retain-and-anonymize step that must NOT cascade-delete. Idempotent.", "operationId": "adminDeleteTenantPodcastData", "parameters": [ { "in": "path", "name": "target_tenant_id", "required": true, "schema": { "title": "Target Tenant Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeletionResult" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Admin Delete Tenant Podcast Data", "tags": [ "podcast", "podcast" ] } }, "/api/v1/admin/tenants/{tenant_id}/dashboard": { "get": { "description": "Get comprehensive statistics for a specific tenant (same metrics as admin dashboard).", "operationId": "getTenantDashboard", "parameters": [ { "in": "path", "name": "tenant_id", "required": true, "schema": { "title": "Tenant Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantDashboardResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get tenant-scoped dashboard stats", "tags": [ "admin", "admin-stats" ] } }, "/api/v1/admin/tenants/{tenant_id}/reset": { "post": { "description": "Reset a tenant's test data (admin only).\n\n Deletes transient data (emails, events, tasks) while preserving\n tenant settings and user accounts.\n\n Related: 011-auth-user-onboarding T074", "operationId": "resetTenantData", "parameters": [ { "in": "path", "name": "tenant_id", "required": true, "schema": { "title": "Tenant Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResetTenantResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Reset tenant test data", "tags": [ "admin", "admin-tenants" ] } }, "/api/v1/admin/tenants/{tenant_id}/usage": { "get": { "description": "Get detailed usage statistics for a specific tenant.", "operationId": "getTenantUsage", "parameters": [ { "in": "path", "name": "tenant_id", "required": true, "schema": { "title": "Tenant Id", "type": "string" } }, { "in": "query", "name": "days", "required": false, "schema": { "default": 30, "title": "Days", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantUsageResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get tenant usage statistics", "tags": [ "admin", "admin-stats" ] } }, "/api/v1/admin/unpriced-models": { "get": { "description": "Distinct model names observed in the last ``window_days`` of llm_usage_logs\nthat have NO matching model_pricing row — the operator's fix-it surface for\nthe F1-S1 fail-loud behavior (a model without pricing cannot be used).\n\nReported from the fail-loud marker ingest already wrote, under the ROUTE\nname the operator can actually price — see ``UNPRICED_MODELS_SQL`` for why\nre-deriving the match here was the bug (TIDY-17768).", "operationId": "listUnpricedModels", "parameters": [ { "in": "query", "name": "window_days", "required": false, "schema": { "default": 30, "title": "Window Days", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/UnpricedModel" }, "title": "Response Listunpricedmodels", "type": "array" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Models seen in llm_usage_logs with no pricing row (R13 fail-loud fix-it list)", "tags": [ "admin-pricing" ], "x-mcp-skip": true } }, "/api/v1/admin/usage-summary": { "get": { "description": "Cross-tenant usage aggregate for the admin usage dashboard: per-account usage (`get_admin_usage_summary`), global feedback summary (`get_feedback_summary`), testimonial candidates, and AI-draft counts. Admin-gated; replaces the PostgREST reads the page ran (TIDY-12312).", "operationId": "getAdminUsageSummary", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminUsageSummaryResponse" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Admin usage dashboard aggregate", "tags": [ "admin-usage" ], "x-mcp-skip": true } }, "/api/v1/admin/user-directory": { "get": { "description": "Complete, tenant-grouped human-user directory. Includes accounts with no\nmembership (the platform owner) so the list is never missing a user.", "operationId": "adminUserDirectory", "parameters": [ { "in": "query", "name": "search", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Search" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 1000, "title": "Limit", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/DirectoryUser" }, "title": "Response Adminuserdirectory", "type": "array" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "User Directory", "tags": [ "admin-user-directory", "admin-user-directory" ], "x-mcp-skip": true } }, "/api/v1/admin/users": { "get": { "description": "List/search accounts. tidy-tenant-wide-justified: platform-admin user\ndirectory; returns account identity + admin/suspend/tier flags only, no\nmember primitive payload.", "operationId": "listAdminUsers", "parameters": [ { "in": "query", "name": "search", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Search" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 100, "title": "Limit", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/AdminUserSummary" }, "title": "Response Listadminusers", "type": "array" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List Admin Users", "tags": [ "admin-users" ] }, "post": { "description": "Create a user via GoTrue admin invite (sends the invitation email) and\naudit it. Duplicate email → 409. Invite delivery failure → the account is\nstill created (GoTrue returns the id) and the admin can resend.", "operationId": "createAdminUser", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateUserRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateUserResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Create Admin User", "tags": [ "admin-users" ] } }, "/api/v1/admin/users/{user_id}": { "patch": { "description": "Edit a user: tier (guarded), quota (guarded), sysadmin toggle,\nsuspend/reactivate. Each mutation emits an audit row.", "operationId": "patchAdminUser", "parameters": [ { "in": "path", "name": "user_id", "required": true, "schema": { "format": "uuid", "title": "User Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatchUserRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminUserSummary" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Patch Admin User", "tags": [ "admin-users" ] } }, "/api/v1/admin/users/{user_id}/clear-bounce": { "post": { "description": "Resets `auth.users.email_bounced_at` and `email_bounce_type` to NULL. Caller MUST be an admin (is_admin=true on accounts row). The action is recorded in audit_logs.\n\nTIDY-9375 (F6 S5).", "operationId": "adminClearBounce", "parameters": [ { "in": "path", "name": "user_id", "required": true, "schema": { "title": "User Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClearBounceResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Clear a user's email bounce/complaint blocklist (admin)", "tags": [ "admin-email-blocklist", "admin-email-blocklist" ] } }, "/api/v1/admin/users/{user_id}/podcast-data-export": { "post": { "description": "Admin-initiated export of a user's podcast data (D71 scope).", "operationId": "adminExportUserPodcastData", "parameters": [ { "in": "path", "name": "user_id", "required": true, "schema": { "title": "User Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExportResult" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Admin Export User Podcast Data", "tags": [ "podcast", "podcast" ] } }, "/api/v1/admin/users/{user_id}/podcast-delete": { "post": { "description": "Case A (D68): remove the user from the (continuing) tenant and anonymize\ntheir podcast retention rows (usage logs, attribution, audit targets). The\ntenant's shared data and the corpus are untouched. Idempotent.", "operationId": "adminDeleteUserPodcastData", "parameters": [ { "in": "path", "name": "user_id", "required": true, "schema": { "title": "User Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeletionResult" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Admin Delete User Podcast Data", "tags": [ "podcast", "podcast" ] } }, "/api/v1/admin/webhook-health": { "get": { "description": "Return per-connection webhook health for all active push connections.\n\nSort: stale connections first, then most-recent failure.", "operationId": "adminWebhookHealth", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookHealthResponse" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Per-connection webhook health snapshot", "tags": [ "admin-webhook-health" ] } }, "/api/v1/admin/workforce-funnel": { "get": { "description": "Cross-tenant workforce journey health for the operator console (TIDY-18250 R40): hire conversion by step and chosen path, workshops online/offline by tenant, deploy failures by step, connections needing re-auth, time-to-first-completed-conversation (p50/p90), and health-check pass rate per harness/provider. Bounded windows only (7d / 30d). Admin-gated, platform plane.", "operationId": "getAdminWorkforceFunnel", "parameters": [ { "in": "query", "name": "window", "required": false, "schema": { "default": "30d", "enum": [ "7d", "30d" ], "title": "Window", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkforceFunnelResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Workforce hire funnel and journey health", "tags": [ "admin-workforce-funnel" ], "x-mcp-skip": true, "x-mcp-skip-reason": "Operator console aggregate (TIDY-18250); not agent-callable." } }, "/api/v1/admin/workspace-guest-policy": { "get": { "operationId": "getWorkspaceGuestPolicy", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceGuestPolicy" } } }, "description": "Successful Response" } }, "summary": "Read this workspace's guest policy", "tags": [ "guests" ] }, "put": { "operationId": "updateWorkspaceGuestPolicy", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateWorkspaceGuestPolicyRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceGuestPolicy" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Update this workspace's guest policy", "tags": [ "guests" ] } }, "/api/v1/agent-approvals/browser-configurations/{configuration_id}/authority": { "post": { "deprecated": true, "operationId": "approveBrowserEffectPolicy", "parameters": [ { "in": "path", "name": "configuration_id", "required": true, "schema": { "format": "uuid", "title": "Configuration Id", "type": "string" } } ], "responses": { "410": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrowserRunsRetiredProblem" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Approve browser effect policy (retired)", "tags": [ "agents" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Browser control transport and configured actions; harness tools are a separate contract." } }, "/api/v1/agent-control/commands": { "post": { "description": "Fan-out at creation; a stop on a terminal conversation pre-acks\n`already_completed`; duplicate stops are new commands whose targets ack\n`stop_already_idle` (idempotent at the harness).", "operationId": "createAgentControlCommand", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentControlCreateRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentControlCommandResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Issue a scoped steer/stop command to active agent conversations", "tags": [ "agents" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/agent-control/commands/{command_id}": { "get": { "description": "Command history is queryable: who stopped what, when, per-target outcome.", "operationId": "getAgentControlCommand", "parameters": [ { "in": "path", "name": "command_id", "required": true, "schema": { "title": "Command Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentControlCommandResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Per-target acknowledgement status for a control command", "tags": [ "agents" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/agent-credentials": { "get": { "operationId": "listAgentCredentials", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CredentialListResponse" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List Agent Credentials", "tags": [ "agents" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Credential custody is a first-party settings/runtime surface; secrets are never assistant-callable." } }, "/api/v1/agent-credentials/{credential_id}/grants": { "post": { "operationId": "createAgentCredentialGrant", "parameters": [ { "in": "path", "name": "credential_id", "required": true, "schema": { "format": "uuid", "title": "Credential Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CredentialGrantCreate" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CredentialGrant" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Create Agent Credential Grant", "tags": [ "agents" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Credential custody is a first-party settings/runtime surface; secrets are never assistant-callable." } }, "/api/v1/agent-credentials/{credential_id}/grants/{grant_id}": { "delete": { "operationId": "revokeAgentCredentialGrant", "parameters": [ { "in": "path", "name": "credential_id", "required": true, "schema": { "format": "uuid", "title": "Credential Id", "type": "string" } }, { "in": "path", "name": "grant_id", "required": true, "schema": { "format": "uuid", "title": "Grant Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevocationResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Revoke Agent Credential Grant", "tags": [ "agents" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Credential custody is a first-party settings/runtime surface; secrets are never assistant-callable." } }, "/api/v1/agent-ledger/anchor/resolve": { "get": { "description": "Jump-to-code navigation resolves here after line drift: exact\ncontent-hash match first, else the nearest surviving ancestor edit on the\nsame file before the original operation.", "operationId": "resolveAgentLedgerAnchor", "parameters": [ { "in": "query", "name": "session_id", "required": true, "schema": { "title": "Session Id", "type": "string" } }, { "description": "Workspace-relative path (D7).", "in": "query", "name": "file_path", "required": true, "schema": { "description": "Workspace-relative path (D7).", "title": "File Path", "type": "string" } }, { "description": "Content hash of the anchored text.", "in": "query", "name": "content_hash", "required": true, "schema": { "description": "Content hash of the anchored text.", "title": "Content Hash", "type": "string" } }, { "description": "Original anchor op (enables nearest-ancestor fallback).", "in": "query", "name": "operation_id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Original anchor op (enables nearest-ancestor fallback).", "title": "Operation Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentLedgerAnchorResolveResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Re-locate a D10 code anchor after drift (content hash → ancestor)", "tags": [ "agents" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/agent-ledger/events": { "post": { "description": "Batched, idempotent append. Invalid events reject the whole batch with\nper-index errors — capture gaps are surfaced by forwarders as lifecycle\nmarkers, never silently dropped.\n\nThis is THE operation-event ingest. The persist transaction NOTIFYs\n``tidy_agent_ledger`` on its own connection (S6, TIDY-18025), so rows and\nnotification become visible together at commit and EVERY api-service\nreplica — including this one — fans the persisted batch to its own SSE\nsubscribers from the durable rows. There is no local publish here any\nmore: two paths would double-deliver on the ingesting replica, and a\nprocess-local one could never reach a subscriber on another replica.", "operationId": "ingestAgentLedgerEvents", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentLedgerIngestRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentLedgerIngestResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Ingest a batch of captured operations (machine lane)", "tags": [ "agents" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/agent-ledger/fork": { "post": { "description": "Append-only fork: opens a fresh conversation stream whose first lifecycle\nop carries parent linkage back to the chosen source operation. The caller\nmust be able to see the source op (D8); history is never rewritten.", "operationId": "forkAgentLedgerLineage", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentLedgerForkRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentLedgerForkResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Fork a new lineage from a chosen operation (parent-linked)", "tags": [ "agents" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/agent-ledger/hotspots": { "get": { "description": "Same input → same output analysis over the recorded stream (D9): file\nchurn from edit ops, phase timing from TurnTelemetryV1 publications,\nfailure clusters from tool-call outcomes, conversation structure. Numbers are\ncomputed ONLY from captured evidence; ``complete:false`` surfaces partial\ncapture beside the counts — never presented as complete.", "operationId": "getAgentLedgerHotspots", "parameters": [ { "description": "Bounded scope: one conversation stream.", "in": "query", "name": "session_id", "required": true, "schema": { "description": "Bounded scope: one conversation stream.", "title": "Session Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentLedgerHotspotsResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Deterministic churn/timing/failure/structure hotspots for a conversation (F3-S3)", "tags": [ "agents" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/agent-ledger/integrity": { "get": { "description": "Recomputes every chain hash for the stream in insertion order.", "operationId": "verifyAgentLedgerIntegrity", "parameters": [ { "in": "query", "name": "session_id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Session Id" } }, { "in": "query", "name": "run_id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Run Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentLedgerIntegrityResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Verify a stream's hash chain (integrity gaps ≠ empty)", "tags": [ "agents" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/agent-ledger/query": { "get": { "description": "Replay/visual layers (S3-S5) read here. `complete:false` means partial\ncapture for the scope — never conflate it with a valid empty result.", "operationId": "queryAgentLedger", "parameters": [ { "in": "query", "name": "session_id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Session Id" } }, { "in": "query", "name": "run_id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Run Id" } }, { "in": "query", "name": "operation_id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Operation Id" } }, { "in": "query", "name": "event_id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Event Id" } }, { "in": "query", "name": "task_id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Task Id" } }, { "in": "query", "name": "work_item_id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Work Item Id" } }, { "in": "query", "name": "ve_id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Ve Id" } }, { "in": "query", "name": "principal_member_id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Principal Member Id" } }, { "in": "query", "name": "kind", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Kind" } }, { "description": "ISO 8601 UTC.", "in": "query", "name": "occurred_from", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO 8601 UTC.", "title": "Occurred From" } }, { "description": "ISO 8601 UTC.", "in": "query", "name": "occurred_to", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO 8601 UTC.", "title": "Occurred To" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 100, "maximum": 500, "minimum": 1, "title": "Limit", "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cursor" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentLedgerQueryResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Query the operation ledger (keyset-paged, D6 outcomes)", "tags": [ "agents" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/agent-ledger/tail": { "get": { "description": "Ascending keyset follow for watch consumers (TIDY-16678): pass back\nnext_cursor until it is null, then poll again later. Requires one bounded\nscope filter.", "operationId": "tailAgentLedger", "parameters": [ { "in": "query", "name": "session_id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Session Id" } }, { "in": "query", "name": "run_id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Run Id" } }, { "in": "query", "name": "ve_id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Ve Id" } }, { "in": "query", "name": "work_item_id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Work Item Id" } }, { "in": "query", "name": "task_id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Task Id" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "maximum": 200, "minimum": 1, "title": "Limit", "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cursor" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentLedgerQueryResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Tail the operation ledger after a durable cursor (watch lane)", "tags": [ "agents" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/agent-ledger/timeline": { "get": { "description": "Time travel over OPERATIONS: rewind pages backward from a chosen op,\nfast_forward steps forward toward the present, head returns the latest\nwindow. Rows are audience-filtered; completeness is not.", "operationId": "getAgentLedgerTimeline", "parameters": [ { "description": "Bounded scope: one conversation stream.", "in": "query", "name": "session_id", "required": true, "schema": { "description": "Bounded scope: one conversation stream.", "title": "Session Id", "type": "string" } }, { "description": "rewind | fast_forward | head", "in": "query", "name": "direction", "required": false, "schema": { "default": "head", "description": "rewind | fast_forward | head", "title": "Direction", "type": "string" } }, { "description": "Scrubber position: ULID of the position op.", "in": "query", "name": "position_operation_id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Scrubber position: ULID of the position op.", "title": "Position Operation Id" } }, { "description": "Scrubber position: ISO 8601 UTC instant.", "in": "query", "name": "position_occurred_at", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Scrubber position: ISO 8601 UTC instant.", "title": "Position Occurred At" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 100, "maximum": 500, "minimum": 1, "title": "Limit", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentLedgerTimelineResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Rewind / fast-forward window over one conversation stream (F3-S1)", "tags": [ "agents" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/agent-plans": { "post": { "operationId": "createAgentPlan", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePlanRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlanResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Create Agent Plan", "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/agent-plans/tasks/{task_id}": { "patch": { "operationId": "updateAgentPlanTask", "parameters": [ { "description": "Typed ID with prefix 'A'", "in": "path", "name": "task_id", "required": true, "schema": { "description": "Typed ID with prefix 'A'", "title": "Task Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateTaskRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentTaskResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Update Agent Plan Task", "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/agent-plans/tasks/{task_id}/resume": { "post": { "operationId": "resumeAgentPlanTask", "parameters": [ { "description": "Typed ID with prefix 'A'", "in": "path", "name": "task_id", "required": true, "schema": { "description": "Typed ID with prefix 'A'", "title": "Task Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResumeTaskRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResumeTaskResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Resume Agent Plan Task", "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/agent-plans/{plan_id}": { "get": { "operationId": "getAgentPlan", "parameters": [ { "in": "path", "name": "plan_id", "required": true, "schema": { "title": "Plan Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlanResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Agent Plan", "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/agent-sessions": { "get": { "description": "Read-time staleness: active conversations without a recent event flag stale.", "operationId": "listAgentSessions", "parameters": [ { "description": "Filter to one project UUID.", "in": "query", "name": "project", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter to one project UUID.", "title": "Project" } }, { "description": "Only non-terminal conversations.", "in": "query", "name": "active", "required": false, "schema": { "default": false, "description": "Only non-terminal conversations.", "title": "Active", "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentSessionListResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List agent conversations (envelope summary, heartbeat age, staleness)", "tags": [ "agents" ], "x-local-capability": "cloud", "x-mcp-skip": true }, "post": { "description": "Envelope-or-fail (D25): incomplete grounding → 422 envelope_incomplete.", "operationId": "registerAgentSession", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentSessionRegisterRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentSessionRegisterResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Register an agent conversation with its launch envelope", "tags": [ "agents" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/agent-sessions/{session_id}/control": { "get": { "description": "Short-poll delivery (documented choice: the simplest reliable primitive\nhere — the extension polls while a conversation is active; SKIP LOCKED marks\ndelivered exactly once). Acks arrive as `control_ack` events; S21 creates\ncommands and owns never-acked timeouts.", "operationId": "consumeAgentSessionControls", "parameters": [ { "in": "path", "name": "session_id", "required": true, "schema": { "title": "Session Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentControlListResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Consume pending control commands for a conversation (S20 harness poll)", "tags": [ "agents" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/agent-sessions/{session_id}/events": { "post": { "description": "Append-only; terminal kinds dedup; `assigned` maintains the Kanban chip.", "operationId": "ingestAgentSessionEvent", "parameters": [ { "in": "path", "name": "session_id", "required": true, "schema": { "title": "Session Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentSessionEventRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentSessionEventResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Ingest a coarse lifecycle event for an agent conversation", "tags": [ "agents" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/agent-skills/{slug}/archive/{sha256}": { "get": { "description": "A repo skill's archive (TIDY-20203 F2): exactly the published version's.\n\nAny other SHA-256 is refused, so a host can only ever download the bytes\nthe owner approved for what it installs, and only an employee that was\ngiven the skill gets them.", "operationId": "getAgentSkillArchive", "parameters": [ { "in": "path", "name": "slug", "required": true, "schema": { "title": "Slug", "type": "string" } }, { "in": "path", "name": "sha256", "required": true, "schema": { "title": "Sha256", "type": "string" } } ], "responses": { "200": { "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Get Agent Skill Archive", "tags": [ "agents", "agents" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Connector-facing published skill bundle serving." } }, "/api/v1/agent-skills/{slug}/manifest.json": { "get": { "description": "The published bundle's manifest: its file list and pinned version.\n\nTIDY-20203 F2: a repo skill's files are one archive. Its manifest names\nSKILL.md and adds ``archive`` — where to download it, and the size and\nSHA-256 the download must match.", "operationId": "getAgentSkillManifest", "parameters": [ { "in": "path", "name": "slug", "required": true, "schema": { "title": "Slug", "type": "string" } }, { "description": "The host installs a repo skill's archive. A repo skill's manifest is refused to a host that does not, which would install SKILL.md alone.", "in": "query", "name": "archives", "required": false, "schema": { "default": false, "description": "The host installs a repo skill's archive. A repo skill's manifest is refused to a host that does not, which would install SKILL.md alone.", "title": "Archives", "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Get Agent Skill Manifest", "tags": [ "agents", "agents" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Connector-facing published skill bundle serving." } }, "/api/v1/agent-skills/{slug}/{file_path}": { "get": { "description": "One bundle file, byte-identical to what the manifest names.\n\nPaths are matched against the bundle's own namespaces (``SKILL.md``,\n``SKILL.<os>.md``, ``references/*``, ``scripts/*``) — nothing here touches\na filesystem, so there is no path to escape.", "operationId": "getAgentSkillFile", "parameters": [ { "in": "path", "name": "slug", "required": true, "schema": { "title": "Slug", "type": "string" } }, { "in": "path", "name": "file_path", "required": true, "schema": { "title": "File Path", "type": "string" } } ], "responses": { "200": { "content": { "text/plain": { "schema": { "type": "string" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Get Agent Skill File", "tags": [ "agents", "agents" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Connector-facing published skill bundle serving." } }, "/api/v1/agent/events/liveness": { "get": { "operationId": "agentEventsLiveness", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentEventLivenessResponse" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Per-harness operation-event capture liveness", "tags": [ "agents" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/agent/events/stream": { "get": { "description": "Subscribe behind the SAME audience model as the durable ledger reads.\n\n``account_id`` authorizes here — it is never ignored: a non-operator\ncaller's subscription admits only events executed for them as principal\nor on task work items they can see through the canonical primitive\npredicate. Sibling members'/VEs' diff_chunk patch text never reaches a\ncaller the durable query would not show it to.", "operationId": "streamAgentEvents", "responses": { "200": { "content": { "text/event-stream": {} }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Live operation-event stream (SSE, D8-audience-gated)", "tags": [ "agents" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Server-Sent Events push channel for the running-turn view; consumed by the browser client, not an agent tool." } }, "/api/v1/agents/approvals": { "post": { "operationId": "requestAgentApproval", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentApprovalRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentApprovalResponse" } } }, "description": "Successful Response" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "conversation_required: the call is not part of a conversation." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Ask the owner to approve one exact call, without waiting", "tags": [ "agents", "Agents" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Interaction-rail plumbing; the tidy_ask_user / tidy_request_approval / tidy_questions / tidy_withdraw_question / tidy_answer_question MCP tools are the public surface." } }, "/api/v1/agents/backlogs/{employee}": { "get": { "operationId": "getEmployeeBacklog", "parameters": [ { "description": "The employee's slug, @mention handle, name or account id.", "in": "path", "name": "employee", "required": true, "schema": { "description": "The employee's slug, @mention handle, name or account id.", "maxLength": 200, "minLength": 1, "title": "Employee", "type": "string" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "maximum": 200, "minimum": 1, "title": "Limit", "type": "integer" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VeBacklogResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "An employee's backlog in the order its heartbeat works it", "tags": [ "agents", "Agents" ], "x-local-capability": "cloud" } }, "/api/v1/agents/backlogs/{employee}/order": { "post": { "operationId": "orderEmployeeBacklog", "parameters": [ { "description": "The employee's slug, @mention handle, name or account id.", "in": "path", "name": "employee", "required": true, "schema": { "description": "The employee's slug, @mention handle, name or account id.", "maxLength": 200, "minLength": 1, "title": "Employee", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VeBacklogOrderRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/VeBacklogResponse" }, { "$ref": "#/components/schemas/VeBacklogOrderReceipt" } ], "title": "Response Orderemployeebacklog" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Put items at the head of an employee's manual work order", "tags": [ "agents", "Agents" ], "x-local-capability": "cloud" } }, "/api/v1/agents/claim": { "post": { "operationId": "claimAgentConnector", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentClaimRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentClaimResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Claim a virtual employee local connector", "tags": [ "agents", "Agents" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Workspace admin provisioning/status API for browser UI and local connector setup." } }, "/api/v1/agents/claim-preflight": { "post": { "operationId": "preflightAgentConnectorClaim", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentClaimPreflightRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentClaimPreflightResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Preflight Agent Connector Claim", "tags": [ "agents", "Agents" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Workspace admin provisioning/status API for browser UI and local connector setup." } }, "/api/v1/agents/claim-v2": { "post": { "operationId": "claimAgentConnectorV2", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentClaimV2Request" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentClaimV2Response" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Claim Agent Connector V2", "tags": [ "agents", "Agents" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Workspace admin provisioning/status API for browser UI and local connector setup." } }, "/api/v1/agents/consumer-lease/accept-handoff": { "post": { "operationId": "acceptAgentConsumerHandoff", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HandoffTokenRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HandoffResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Accept Agent Consumer Handoff", "tags": [ "agents", "Agents" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Workspace admin provisioning/status API for browser UI and local connector setup." } }, "/api/v1/agents/consumer-lease/acquire": { "post": { "operationId": "acquireAgentConsumerLease", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConsumerLeaseAcquireRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConsumerLeaseAcquireResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Acquire Agent Consumer Lease", "tags": [ "agents", "Agents" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Workspace admin provisioning/status API for browser UI and local connector setup." } }, "/api/v1/agents/consumer-lease/handoff": { "post": { "operationId": "handoffAgentConsumerLease", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HandoffRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HandoffResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Handoff Agent Consumer Lease", "tags": [ "agents", "Agents" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Workspace admin provisioning/status API for browser UI and local connector setup." } }, "/api/v1/agents/consumer-lease/handoff-status": { "post": { "operationId": "getAgentConsumerHandoffStatus", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HandoffStatusRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HandoffResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Get Agent Consumer Handoff Status", "tags": [ "agents", "Agents" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Workspace admin provisioning/status API for browser UI and local connector setup." } }, "/api/v1/agents/consumer-lease/release": { "post": { "operationId": "releaseAgentConsumerLease", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConsumerLeaseReleaseRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperationStatusResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Release Agent Consumer Lease", "tags": [ "agents", "Agents" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Workspace admin provisioning/status API for browser UI and local connector setup." } }, "/api/v1/agents/consumer-lease/renew": { "post": { "operationId": "renewAgentConsumerLease", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConsumerLeaseRenewRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConsumerLeaseStatusResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Renew Agent Consumer Lease", "tags": [ "agents", "Agents" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Workspace admin provisioning/status API for browser UI and local connector setup." } }, "/api/v1/agents/consumer-lease/rollback-handoff": { "post": { "operationId": "rollbackAgentConsumerHandoff", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HandoffTokenRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HandoffResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Rollback Agent Consumer Handoff", "tags": [ "agents", "Agents" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Workspace admin provisioning/status API for browser UI and local connector setup." } }, "/api/v1/agents/consumer-lease/rollback-legacy": { "post": { "operationId": "rollbackLegacyAgentConsumer", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RollbackLegacyRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RollbackLegacyResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Rollback Legacy Agent Consumer", "tags": [ "agents", "Agents" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Workspace admin provisioning/status API for browser UI and local connector setup." } }, "/api/v1/agents/consumer-lease/status": { "get": { "operationId": "getAgentConsumerLeaseStatus", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConsumerLeaseStatusResponse" } } }, "description": "Successful Response" } }, "summary": "Get Agent Consumer Lease Status", "tags": [ "agents", "Agents" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Workspace admin provisioning/status API for browser UI and local connector setup." } }, "/api/v1/agents/credential-recovery/receipt": { "post": { "operationId": "exchangeAgentCredentialRecoveryReceipt", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CredentialRecoveryReceiptRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentClaimV2Response" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Exchange Agent Credential Recovery Receipt", "tags": [ "agents", "Agents" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Workspace admin provisioning/status API for browser UI and local connector setup." } }, "/api/v1/agents/credential-recovery/self": { "post": { "operationId": "recoverAgentCredentialSelf", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SelfCredentialRecoveryRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentClaimV2Response" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Recover Agent Credential Self", "tags": [ "agents", "Agents" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Workspace admin provisioning/status API for browser UI and local connector setup." } }, "/api/v1/agents/dev-run-sessions": { "get": { "description": "The owner's read of their VE's runs on a board item (newest-first) plus\neach run's lifecycle timeline and any open interaction prompt. Member-scoped\non the item: a member who cannot see the item reads no runs (R18 / R19).", "operationId": "listAgentDevRunSessions", "parameters": [ { "description": "Bare activity uuid of the task.", "in": "query", "name": "activity_id", "required": true, "schema": { "description": "Bare activity uuid of the task.", "title": "Activity Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DevRunSessionListResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Owner-facing dev-run conversation status for a board item", "tags": [ "agents", "Agents" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Owner-facing board-item session-status read + kill/retry control for the browser UI; the owner acts under their own web session." } }, "/api/v1/agents/dev-run-sessions/{run_id}/cancel": { "post": { "description": "Kill a run from the board item. Member-scoped on the item — a run the\ncaller cannot see 404s (a non-owner learns nothing). Marks the run\n``cancelled`` through the ledger (idempotent if already terminal).", "operationId": "cancelAgentDevRunSession", "parameters": [ { "description": "The run correlation token.", "in": "path", "name": "run_id", "required": true, "schema": { "description": "The run correlation token.", "title": "Run Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DevRunSessionResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Owner-facing kill: stop a dev-run conversation", "tags": [ "agents", "Agents" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Owner-facing board-item session-status read + kill/retry control for the browser UI; the owner acts under their own web session." } }, "/api/v1/agents/dev-run-sessions/{run_id}/events": { "get": { "description": "The full ordered lifecycle timeline the S4 run inspector renders\n(TIDY-15289 R3). Member-scoped on the board item — a run the caller cannot\nsee 404s (a non-owner learns nothing).", "operationId": "listAgentDevRunSessionEvents", "parameters": [ { "description": "The run correlation token.", "in": "path", "name": "run_id", "required": true, "schema": { "description": "The run correlation token.", "title": "Run Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DevRunSessionEventListResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Owner-facing run-events timeline for a dev-run conversation", "tags": [ "agents", "Agents" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Owner-facing board-item session-status read + kill/retry control for the browser UI; the owner acts under their own web session." } }, "/api/v1/agents/dev-run-sessions/{run_id}/retry": { "post": { "description": "Re-queue the run's task at the workspace's ready state (``todo``, or\nits own open state nearest the work), as a task-status write that moves\nthe board and fires automations. Member-scoped on the item — a run the\ncaller cannot see 404s. The run is returned as it ended.", "operationId": "retryAgentDevRunSession", "parameters": [ { "description": "The run correlation token.", "in": "path", "name": "run_id", "required": true, "schema": { "description": "The run correlation token.", "title": "Run Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DevRunSessionResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Owner-facing retry: re-queue a dev run's task", "tags": [ "agents", "Agents" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Owner-facing board-item session-status read + kill/retry control for the browser UI; the owner acts under their own web session." } }, "/api/v1/agents/dev-runs": { "get": { "description": "The supervision loop lists ``open_only=true`` on restart to resume in-flight\nruns from the ledger (durable state; in-memory is a cache, R9).", "operationId": "listAgentDevRuns", "parameters": [ { "description": "List a board item's runs newest-first.", "in": "query", "name": "activity_id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "List a board item's runs newest-first.", "title": "Activity Id" } }, { "description": "List only still-active runs — the orchestrator's restart resume source (R9).", "in": "query", "name": "open_only", "required": false, "schema": { "default": false, "description": "List only still-active runs — the orchestrator's restart resume source (R9).", "title": "Open Only", "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DevRunListResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List dev-runs (open runs to resume, or a board item's history)", "tags": [ "agents", "Agents" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Dev-orchestrator run-record ledger plumbing; the VE harness drives it directly under its runtime bearer." }, "post": { "description": "Record a dispatch: write the ve_dev_runs row + the dispatched event.\n\nEnforces one active run per board item (no double-dispatch, 409) and is\nidempotent on run_id. The caller is the dispatching VE (its runtime bearer).", "operationId": "createAgentDevRun", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DevRunCreateRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DevRunResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Emit a dev-orchestrator run record on dispatch", "tags": [ "agents", "Agents" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Dev-orchestrator run-record ledger plumbing; the VE harness drives it directly under its runtime bearer." } }, "/api/v1/agents/dev-runs/{run_id}": { "get": { "operationId": "getAgentDevRun", "parameters": [ { "description": "The run correlation token or run uuid.", "in": "path", "name": "run_id", "required": true, "schema": { "description": "The run correlation token or run uuid.", "title": "Run Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DevRunResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Read a dev-run record", "tags": [ "agents", "Agents" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Dev-orchestrator run-record ledger plumbing; the VE harness drives it directly under its runtime bearer." }, "patch": { "description": "Verify or transition a run. ``verify=true`` reads the board (the task's\nstatus and review tag + evidence comment, NEVER stdout) and marks\n``succeeded`` only if the board proves it (R10) — else returns\n``verified=false`` with a reason for the orchestrator to re-dispatch or\nescalate. Otherwise ``status`` transitions the run (idempotent; a true\nterminal wins).", "operationId": "updateAgentDevRun", "parameters": [ { "description": "The run correlation token.", "in": "path", "name": "run_id", "required": true, "schema": { "description": "The run correlation token.", "title": "Run Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DevRunUpdateRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DevRunResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Update a dev-run (verify from board ground truth, or mark status)", "tags": [ "agents", "Agents" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Dev-orchestrator run-record ledger plumbing; the VE harness drives it directly under its runtime bearer." } }, "/api/v1/agents/dev-runs/{run_id}/events": { "post": { "description": "Append a lifecycle event; any event registers progress and resets the\nwedge window (run-event progress is a liveness signal, DD7).", "operationId": "appendAgentDevRunEvent", "parameters": [ { "description": "The run correlation token.", "in": "path", "name": "run_id", "required": true, "schema": { "description": "The run correlation token.", "title": "Run Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DevRunEventRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DevRunResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Append a dev-run lifecycle event (progress signal)", "tags": [ "agents", "Agents" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Dev-orchestrator run-record ledger plumbing; the VE harness drives it directly under its runtime bearer." } }, "/api/v1/agents/employees/{employee}/harness-capabilities": { "get": { "operationId": "getEmployeeHarnessCapabilities", "parameters": [ { "description": "The employee's slug, @mention handle, name or account id.", "in": "path", "name": "employee", "required": true, "schema": { "description": "The employee's slug, @mention handle, name or account id.", "maxLength": 200, "minLength": 1, "title": "Employee", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmployeeHarnessCapabilitiesResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "What a named employee's harnesses can do", "tags": [ "agents", "Agents" ], "x-local-capability": "cloud" } }, "/api/v1/agents/employees/{employee}/standing-instructions": { "put": { "description": "Replace an employee's standing instructions, or append lines to them. For a workspace Owner/Admin, the employee's owner, or its direct manager on the team Org chart (a person or an employee). Never the employee itself. Pass based_on_sha256 from your read to refuse a write over a change you did not see. Audited, and shown on the employee's page as who changed them.", "operationId": "setEmployeeStandingInstructions", "parameters": [ { "description": "The employee's slug, @mention handle, name or account id.", "in": "path", "name": "employee", "required": true, "schema": { "description": "The employee's slug, @mention handle, name or account id.", "maxLength": 200, "minLength": 1, "title": "Employee", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmployeeStandingInstructionsChange" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmployeeConfigurationResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Set what an employee does on every wake", "tags": [ "agents", "Agents" ], "x-local-capability": "cloud" } }, "/api/v1/agents/employees/{employee}/work-policy": { "put": { "description": "For a workspace Owner/Admin, or the employee's direct manager on the team Org chart (a person or an employee). Never the employee itself. A status must be one of the workspace's task states; an unknown one is refused, naming them. Audited, and shown on the employee's page as who changed it.", "operationId": "setEmployeeWorkPolicy", "parameters": [ { "description": "The employee's slug, @mention handle, name or account id.", "in": "path", "name": "employee", "required": true, "schema": { "description": "The employee's slug, @mention handle, name or account id.", "maxLength": 200, "minLength": 1, "title": "Employee", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmployeeWorkPolicyChange" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmployeeConfigurationResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Set which states an employee works and how it orders them", "tags": [ "agents", "Agents" ], "x-local-capability": "cloud" } }, "/api/v1/agents/heartbeat": { "post": { "operationId": "heartbeatAgentConnector", "parameters": [ { "in": "header", "name": "X-Tidy-Installation-Id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tidy-Installation-Id" } }, { "in": "header", "name": "X-Tidy-Boot-Id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tidy-Boot-Id" } }, { "in": "header", "name": "X-Tidy-Consumer-Generation", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tidy-Consumer-Generation" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentHeartbeatRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentHeartbeatResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Report virtual employee connector heartbeat", "tags": [ "agents", "Agents" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Workspace admin provisioning/status API for browser UI and local connector setup." } }, "/api/v1/agents/installation-manifest": { "post": { "operationId": "registerAgentInstallationManifest", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InstallationManifestRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperationStatusResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Register Agent Installation Manifest", "tags": [ "agents", "Agents" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Workspace admin provisioning/status API for browser UI and local connector setup." } }, "/api/v1/agents/legacy-enrollment": { "post": { "operationId": "enrollLegacyAgentConnector", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyEnrollmentRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyEnrollmentResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Enroll Legacy Agent Connector", "tags": [ "agents", "Agents" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Workspace admin provisioning/status API for browser UI and local connector setup." } }, "/api/v1/agents/matrix/preflight": { "get": { "operationId": "preflightAgentMatrix", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MatrixPreflightResponse" } } }, "description": "Successful Response" } }, "summary": "Preflight Agent Matrix", "tags": [ "agents", "Agents" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Workspace admin provisioning/status API for browser UI and local connector setup." } }, "/api/v1/agents/matrix/room-keys/bootstrap": { "post": { "description": "Return self-scoped Matrix key-backup material for a virtual employee PAT.", "operationId": "bootstrapAgentMatrixRoomKeys", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentRoomKeysBootstrapResponse" } } }, "description": "Successful Response" } }, "summary": "Bootstrap Matrix room keys for the authenticated virtual employee", "tags": [ "matrix", "agents", "matrix" ], "x-mcp-skip": true } }, "/api/v1/agents/matrix/room-keys/bootstrap-v2": { "post": { "operationId": "bootstrapAgentMatrixRoomKeysV2", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentRoomKeysBootstrapV2Request" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentRoomKeysBootstrapV2Response" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Bootstrap Agent Matrix Room Keys V2", "tags": [ "matrix", "agents", "matrix" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/agents/memory/enrich": { "post": { "description": "Write a durable, agent-derived fact to the PRINCIPAL's shared substrate\n(owned by the principal, never the agent; ``link_source='agent'``). Gated by\nthe principal's active ``notes`` read_write delegation grant (403 otherwise)\nand the substrate boundary (read-private-write-shared → 422). On success the\nprincipal's recall cache is busted so the fact is immediately recallable.", "operationId": "enrichAgentMemory", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentMemoryEnrichRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentMemoryEnrichResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Contribute an agent-derived fact to the principal's substrate", "tags": [ "agents", "Agents" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Workspace admin provisioning/status API for browser UI and local connector setup." } }, "/api/v1/agents/memory/observations": { "get": { "description": "What ``memory_observe`` stored, newest first. Private to the agent: a\nnon-agent caller is 403 and no other agent's notes can match.", "operationId": "listAgentMemoryObservations", "parameters": [ { "in": "query", "name": "limit", "required": false, "schema": { "default": 20, "maximum": 50, "minimum": 1, "title": "Limit", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentMemoryObservationsResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List a virtual employee's own private observations", "tags": [ "agents", "Agents" ], "x-local-capability": "cloud" } }, "/api/v1/agents/memory/observe": { "post": { "description": "Persist one of the agent's own direct observations to its PRIVATE episodic\nstore (a ``notes`` row owned by the agent, ``note_kind='agent_episodic'``).\nEpisodic memory never reaches the principal's substrate nor any other agent;\nthe boundary owner is set by ``guard_episodic_write`` in memory-service. A\nnon-agent caller is rejected (403); a write failure surfaces (5xx).", "operationId": "observeAgentMemory", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentMemoryObserveRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentMemoryObserveResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Record a virtual employee's own episodic observation", "tags": [ "agents", "Agents" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Workspace admin provisioning/status API for browser UI and local connector setup." } }, "/api/v1/agents/memory/recall": { "post": { "operationId": "recallAgentMemoryContext", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentMemoryRecallRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentMemoryRecallResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Recall memory context for a virtual employee runtime", "tags": [ "agents", "Agents" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Workspace admin provisioning/status API for browser UI and local connector setup." } }, "/api/v1/agents/memory/search": { "post": { "description": "The agent's private observations and the principal's shared memory that\nmatch ``query`` — the read half of ``memory_observe`` / ``memory_enrich``.\nA non-agent caller is 403; a memory-service failure surfaces.", "operationId": "searchAgentMemory", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentMemorySearchRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentMemorySearchResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Search a virtual employee's own memory", "tags": [ "agents", "Agents" ], "x-local-capability": "cloud" } }, "/api/v1/agents/mentions/inbox": { "get": { "description": "The runtime polls this to consume its actionable rail (comment home-room\nalerts + chat highlights). Scoped to the caller's own agent account — an\nagent can never read another agent's mentions. Carries a resolver key\n(comment_id) + a non-secret snippet only; the runtime re-resolves the comment\nvia ``tidy://comments/{comment_id}`` under the mention grant (no parent-doc\nleak), acts, then acks.", "operationId": "listAgentMentionInbox", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActionableMentionInboxResponse" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List a virtual employee's un-acted actionable mentions", "tags": [ "agents", "Agents" ], "x-mcp-skip": true, "x-mcp-skip-reason": "Exposed to the runtime as the MCP resource tidy://agent/mentions (AgentMentionsResource), not a tool — the resource reads this endpoint." } }, "/api/v1/agents/mentions/{mention_id}/ack": { "post": { "description": "Mark a mention acted after the runtime replies / performs the request.\nIdempotent: a duplicate delivery + duplicate ack produces a SINGLE recorded\naction. A comment mention with no in-thread reply from the employee is a\n409 ``mention_reply_required`` naming the comment to reply on (TIDY-19325).", "operationId": "ackAgentMention", "parameters": [ { "description": "Actionable mention delivery id", "in": "path", "name": "mention_id", "required": true, "schema": { "description": "Actionable mention delivery id", "title": "Mention Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActionableMentionAckRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActionableMentionAckResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Acknowledge an actionable mention as acted", "tags": [ "agents", "Agents" ] } }, "/api/v1/agents/model-providers/catalog": { "get": { "operationId": "listModelProviderCatalog", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelProviderCatalogResponse" } } }, "description": "Successful Response" } }, "summary": "List Model Provider Catalog", "tags": [ "agents" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Credential custody is a first-party settings/runtime surface; secrets are never assistant-callable." } }, "/api/v1/agents/model-providers/connections": { "get": { "operationId": "listModelProviderConnections", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelProviderConnectionsResponse" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List Model Provider Connections", "tags": [ "agents" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Credential custody is a first-party settings/runtime surface; secrets are never assistant-callable." }, "post": { "operationId": "connectModelProvider", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelProviderConnectRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelProviderConnectionsResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Connect Model Provider", "tags": [ "agents" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Credential custody is a first-party settings/runtime surface; secrets are never assistant-callable." } }, "/api/v1/agents/model-providers/connections/{connection_id}": { "delete": { "operationId": "disconnectModelProvider", "parameters": [ { "in": "path", "name": "connection_id", "required": true, "schema": { "format": "uuid", "title": "Connection Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelProviderConnectionsResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Disconnect Model Provider", "tags": [ "agents" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Credential custody is a first-party settings/runtime surface; secrets are never assistant-callable." } }, "/api/v1/agents/model-providers/connections/{connection_id}/endpoint": { "put": { "description": "Move an existing connection to a different base URL (TIDY-18356).\n\nThe address is a property of the key, so this edits the connection and every\nemployee spending that key follows on its next turn. The key itself is never\nechoed and never travels in the path — only the endpoint does.", "operationId": "setModelProviderEndpoint", "parameters": [ { "in": "path", "name": "connection_id", "required": true, "schema": { "format": "uuid", "title": "Connection Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelProviderEndpointRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelProviderConnectionsResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Set Model Provider Endpoint", "tags": [ "agents" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Credential custody is a first-party settings/runtime surface; secrets are never assistant-callable." } }, "/api/v1/agents/model-providers/connections/{connection_id}/models": { "get": { "description": "List this connection's models; workshop LAN discovery refuses by name.", "operationId": "listConnectionModels", "parameters": [ { "in": "path", "name": "connection_id", "required": true, "schema": { "format": "uuid", "title": "Connection Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelProviderModelsResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List Connection Models", "tags": [ "agents" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Credential custody is a first-party settings/runtime surface; secrets are never assistant-callable." } }, "/api/v1/agents/model-providers/tidy-inference-models": { "get": { "description": "The lanes the keyless Tidy inference method may run on (TIDY-18662).\n\nRead before the employee exists, like the provider catalog: the wizard's\nkey step has to offer a real lane id, and the deployment's own router is\nthe only honest source for which lanes Tidy serves.", "operationId": "listTidyInferenceModels", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TidyInferenceModelsResponse" } } }, "description": "Successful Response" } }, "summary": "List Tidy Inference Models", "tags": [ "agents" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Credential custody is a first-party settings/runtime surface; secrets are never assistant-callable." } }, "/api/v1/agents/model-providers/{provider}/workshops/{workshop_id}/chat-sign-in-employees": { "get": { "description": "The employees on a workshop whose harness signs this provider in from\ntheir conversation (TIDY-19528). The browser hands the member to one of\nthem, where `/login` runs the sign-in; this route reads, and signs nothing\nin.", "operationId": "getModelProviderChatSignInEmployees", "parameters": [ { "in": "path", "name": "provider", "required": true, "schema": { "title": "Provider", "type": "string" } }, { "in": "path", "name": "workshop_id", "required": true, "schema": { "format": "uuid", "title": "Workshop Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatSignInEmployees" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Model Provider Chat Sign In Employees", "tags": [ "agents" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Credential custody is a first-party settings/runtime surface; secrets are never assistant-callable." } }, "/api/v1/agents/model-providers/{provider}/workshops/{workshop_id}/sign-in-target": { "get": { "description": "Which employee's connector runs this provider's sign-in on a workshop\n(TIDY-19270). The browser then drives the existing `harness.reauth` relay\nthrough it; this route reads, and signs nothing in.", "operationId": "getModelProviderWorkshopSignInTarget", "parameters": [ { "in": "path", "name": "provider", "required": true, "schema": { "title": "Provider", "type": "string" } }, { "in": "path", "name": "workshop_id", "required": true, "schema": { "format": "uuid", "title": "Workshop Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkshopSignInTarget" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Model Provider Workshop Sign In Target", "tags": [ "agents" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Credential custody is a first-party settings/runtime surface; secrets are never assistant-callable." } }, "/api/v1/agents/prompts": { "get": { "operationId": "listAgentPrompts", "parameters": [ { "description": "Only those still waiting.", "in": "query", "name": "open_only", "required": false, "schema": { "default": true, "description": "Only those still waiting.", "title": "Open Only", "type": "boolean" } }, { "description": "Only those asked in the conversation this call belongs to.", "in": "query", "name": "this_conversation", "required": false, "schema": { "default": false, "description": "Only those asked in the conversation this call belongs to.", "title": "This Conversation", "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentPromptListResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "The caller's own questions and approvals", "tags": [ "agents", "Agents" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Interaction-rail plumbing; the tidy_ask_user / tidy_request_approval / tidy_questions / tidy_withdraw_question / tidy_answer_question MCP tools are the public surface." }, "post": { "operationId": "createAgentPrompt", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentPromptCreateRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentPromptResponse" } } }, "description": "Successful Response" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "employee_not_found: no employee by that name the caller may reach." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "conversation_required: the call is not part of a conversation; question_recipient_unavailable: that person cannot be asked (not an active member, no chat yet, or the Tidy Assistant cannot post in their chat); employee_inactive: that employee is not active." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "kind=approval: refused; ask for one exact call through POST /agents/approvals." } }, "security": [ { "HTTPBearer": [] } ], "summary": "Ask a question: an employee from a conversation (the answer steers back into it), or a person from outside Tidy (the answer is read back from the prompt)", "tags": [ "agents", "Agents" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Interaction-rail plumbing; the tidy_ask_user / tidy_request_approval / tidy_questions / tidy_withdraw_question / tidy_answer_question MCP tools are the public surface." } }, "/api/v1/agents/prompts/conversation-move": { "post": { "operationId": "createAgentConversationMoveRequest", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentConversationMoveRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentConversationMoveResponse" } } }, "description": "Successful Response" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "No project by that id or exact name the conversation's person can see." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Several projects share that name, the project is archived, the conversation is already in it, or a move request already waits; conversation_required: the call is not part of a conversation." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "An employee asks its conversation's person to move the conversation into a project; the answer steers into the conversation their choice opened", "tags": [ "agents", "Agents" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Interaction-rail plumbing; the tidy_ask_user / tidy_request_approval / tidy_questions / tidy_withdraw_question / tidy_answer_question MCP tools are the public surface." } }, "/api/v1/agents/prompts/{prompt_id}": { "get": { "operationId": "getAgentPrompt", "parameters": [ { "in": "path", "name": "prompt_id", "required": true, "schema": { "title": "Prompt Id", "type": "string" } }, { "description": "Bounded wait seconds; returns on resolution or deadline. How a coding agent asking on a person's own token waits for its answer (TIDY-19705 F18): call again until it resolves. Bounded under the 60s per-call timeout common MCP clients use.", "in": "query", "name": "wait", "required": false, "schema": { "default": 0, "description": "Bounded wait seconds; returns on resolution or deadline. How a coding agent asking on a person's own token waits for its answer (TIDY-19705 F18): call again until it resolves. Bounded under the 60s per-call timeout common MCP clients use.", "maximum": 50, "minimum": 0, "title": "Wait", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentPromptStateResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Read a question or an approval", "tags": [ "agents", "Agents" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Interaction-rail plumbing; the tidy_ask_user / tidy_request_approval / tidy_questions / tidy_withdraw_question / tidy_answer_question MCP tools are the public surface." } }, "/api/v1/agents/prompts/{prompt_id}/answer": { "post": { "operationId": "answerAgentPrompt", "parameters": [ { "in": "path", "name": "prompt_id", "required": true, "schema": { "title": "Prompt Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentPromptAnswerRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentPromptAnswerResponse" } } }, "description": "Successful Response" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "No such question put to the caller." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "question_withdrawn: the asker took it back — stop; or it is already resolved." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Answer or decline a question another employee put to the caller", "tags": [ "agents", "Agents" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Interaction-rail plumbing; the tidy_ask_user / tidy_request_approval / tidy_questions / tidy_withdraw_question / tidy_answer_question MCP tools are the public surface." } }, "/api/v1/agents/prompts/{prompt_id}/withdraw": { "post": { "operationId": "withdrawAgentPrompt", "parameters": [ { "in": "path", "name": "prompt_id", "required": true, "schema": { "title": "Prompt Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentPromptStateResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Withdraw one of the caller's own open questions", "tags": [ "agents", "Agents" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Interaction-rail plumbing; the tidy_ask_user / tidy_request_approval / tidy_questions / tidy_withdraw_question / tidy_answer_question MCP tools are the public surface." } }, "/api/v1/agents/self/approval-grants": { "post": { "operationId": "recordAgentSelfApprovalGrant", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordGrantRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalGrant" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Record the reach a human chose on an approval prompt", "tags": [ "agents", "Agents" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Virtual-employee authorization surface for the settings UI and the local connector — never an assistant-callable tool." } }, "/api/v1/agents/self/approval-grants/check": { "post": { "operationId": "checkAgentSelfApprovalGrant", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckGrantRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckGrantResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Does a live grant cover this ask? (stamps the exercise)", "tags": [ "agents", "Agents" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Virtual-employee authorization surface for the settings UI and the local connector — never an assistant-callable tool." } }, "/api/v1/agents/self/approval-policy": { "get": { "operationId": "getAgentSelfApprovalPolicy", "parameters": [ { "description": "Include this conversation's layer and its conversation grants", "in": "query", "name": "conversation_id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Include this conversation's layer and its conversation grants", "title": "Conversation Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentSelfApprovalPolicyResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "The calling employee's composed policy, grants and standing-grant setting", "tags": [ "agents", "Agents" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Virtual-employee authorization surface for the settings UI and the local connector — never an assistant-callable tool." } }, "/api/v1/agents/self/command-policy/hits": { "post": { "operationId": "recordAgentSelfPolicyHit", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PolicyHitRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PolicyHitResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Record a command-policy hit with its rule id", "tags": [ "agents", "Agents" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Virtual-employee authorization surface for the settings UI and the local connector — never an assistant-callable tool." } }, "/api/v1/agents/self/command-policy/session-rules": { "post": { "operationId": "addAgentSelfSessionPolicyRule", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommandPolicyRuleRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommandPolicyRule" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Add a conversation-layer command-policy rule (tighten-only)", "tags": [ "agents", "Agents" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Virtual-employee authorization surface for the settings UI and the local connector — never an assistant-callable tool." } }, "/api/v1/agents/self/credentials/asks": { "post": { "operationId": "openAgentCredentialAsk", "parameters": [ { "in": "header", "name": "X-Tidy-Installation-Id", "required": false, "schema": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "X-Tidy-Installation-Id" } }, { "in": "header", "name": "X-Tidy-Boot-Id", "required": false, "schema": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "X-Tidy-Boot-Id" } }, { "in": "header", "name": "X-Tidy-Consumer-Generation", "required": false, "schema": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "X-Tidy-Consumer-Generation" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RuntimeAskCreate" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RuntimeAsk" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Open Agent Credential Ask", "tags": [ "agents" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Credential custody is a first-party settings/runtime surface; secrets are never assistant-callable." } }, "/api/v1/agents/self/credentials/asks/{ask_id}/finalize": { "post": { "operationId": "finalizeAgentCredentialAsk", "parameters": [ { "in": "path", "name": "ask_id", "required": true, "schema": { "format": "uuid", "title": "Ask Id", "type": "string" } }, { "in": "header", "name": "X-Tidy-Installation-Id", "required": false, "schema": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "X-Tidy-Installation-Id" } }, { "in": "header", "name": "X-Tidy-Boot-Id", "required": false, "schema": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "X-Tidy-Boot-Id" } }, { "in": "header", "name": "X-Tidy-Consumer-Generation", "required": false, "schema": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "X-Tidy-Consumer-Generation" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RuntimeAskResolution" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Finalize Agent Credential Ask", "tags": [ "agents" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Credential custody is a first-party settings/runtime surface; secrets are never assistant-callable." } }, "/api/v1/agents/self/credentials/broker/exercise": { "post": { "operationId": "exerciseAgentBrokerCredential", "parameters": [ { "in": "header", "name": "X-Tidy-Installation-Id", "required": false, "schema": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "X-Tidy-Installation-Id" } }, { "in": "header", "name": "X-Tidy-Boot-Id", "required": false, "schema": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "X-Tidy-Boot-Id" } }, { "in": "header", "name": "X-Tidy-Consumer-Generation", "required": false, "schema": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "X-Tidy-Consumer-Generation" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrokerExerciseRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrokerExerciseResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Exercise Agent Broker Credential", "tags": [ "agents" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Credential custody is a first-party settings/runtime surface; secrets are never assistant-callable." } }, "/api/v1/agents/self/credentials/materialize": { "post": { "operationId": "materializeAgentCredentials", "parameters": [ { "in": "header", "name": "X-Tidy-Installation-Id", "required": false, "schema": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "X-Tidy-Installation-Id" } }, { "in": "header", "name": "X-Tidy-Boot-Id", "required": false, "schema": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "X-Tidy-Boot-Id" } }, { "in": "header", "name": "X-Tidy-Consumer-Generation", "required": false, "schema": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "X-Tidy-Consumer-Generation" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MaterializeRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MaterializeResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Materialize Agent Credentials", "tags": [ "agents" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Credential custody is a first-party settings/runtime surface; secrets are never assistant-callable." } }, "/api/v1/agents/self/delegation": { "get": { "description": "The delegation the calling VE holds from its owner, and the one-click\nlink that grants the rest of what its runtime token can use (TIDY-19305).\n\nThe workshop connector reads this on the employee's first turn in a\nworkshop, so a fresh employee can ask for access once instead of finding\nout one 403 at a time. The runtime PAT is the identity, as for\n``/agents/self/persona``.", "operationId": "getAgentSelfDelegation", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentSelfDelegationResponse" } } }, "description": "Successful Response" } }, "summary": "Get Agent Self Delegation", "tags": [ "agents", "Agents" ], "x-local-capability": "cloud" } }, "/api/v1/agents/self/harness-credentials/materialize": { "post": { "operationId": "materializeVeHarnessCredentials", "parameters": [ { "in": "header", "name": "X-Tidy-Installation-Id", "required": false, "schema": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "X-Tidy-Installation-Id" } }, { "in": "header", "name": "X-Tidy-Boot-Id", "required": false, "schema": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "X-Tidy-Boot-Id" } }, { "in": "header", "name": "X-Tidy-Consumer-Generation", "required": false, "schema": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "X-Tidy-Consumer-Generation" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HarnessMaterializeRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HarnessMaterializeResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Materialize Ve Harness Credentials", "tags": [ "agents" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Credential custody is a first-party settings/runtime surface; secrets are never assistant-callable." } }, "/api/v1/agents/self/harness-usage/settle": { "post": { "description": "Receipt-bound unverified observation, NEVER a member credit debit.\nActive lease plus immutable execution and current job/turn eligibility\nfence identity. Provider reconciliation is required before any charge.", "operationId": "settleHarnessUsage", "parameters": [ { "in": "header", "name": "X-Tidy-Installation-Id", "required": false, "schema": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "X-Tidy-Installation-Id" } }, { "in": "header", "name": "X-Tidy-Boot-Id", "required": false, "schema": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "X-Tidy-Boot-Id" } }, { "in": "header", "name": "X-Tidy-Consumer-Generation", "required": false, "schema": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "X-Tidy-Consumer-Generation" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HarnessUsageRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HarnessUsageResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Settle Harness Usage", "tags": [ "agents" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Credential custody is a first-party settings/runtime surface; secrets are never assistant-callable." } }, "/api/v1/agents/self/host-fingerprints": { "post": { "description": "Record an SSH host key fingerprint (runtime endpoint for VE connector).", "operationId": "recordAgentHostFingerprint", "parameters": [ { "in": "header", "name": "X-Tidy-Installation-Id", "required": false, "schema": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "X-Tidy-Installation-Id" } }, { "in": "header", "name": "X-Tidy-Boot-Id", "required": false, "schema": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "X-Tidy-Boot-Id" } }, { "in": "header", "name": "X-Tidy-Consumer-Generation", "required": false, "schema": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "X-Tidy-Consumer-Generation" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordHostFingerprintRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MachineHostFingerprint" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Record Agent Host Fingerprint", "tags": [ "agents" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Credential custody is a first-party settings/runtime surface; secrets are never assistant-callable." } }, "/api/v1/agents/self/insights": { "put": { "description": "Replace the calling employee's insights — its own words about its own\nwork — on its contact, in the overlay of the person the turn is for\n(TIDY-20066 F7). They render on the employee's Insights tab.", "operationId": "putAgentSelfInsights", "parameters": [ { "in": "header", "name": "X-Tidy-Acting-Principal", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tidy-Acting-Principal" } }, { "in": "header", "name": "X-Internal-Service", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service" } }, { "in": "header", "name": "X-Internal-Service-Key", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service-Key" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentSelfInsightsRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentSelfInsightsResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Rewrite a virtual employee's own insights", "tags": [ "agents", "Agents" ], "x-local-capability": "cloud" } }, "/api/v1/agents/self/judge-tool-call": { "post": { "description": "TIDY-17535 (R21/D16): classify ONE call for the calling employee.\n\nRefused outright unless the employee's stored execution posture is\n`auto_allow_judgment` — the classifier is never a side door around a dial\nset narrower. Every failure escalates (never allows), and every verdict,\neither way, lands in the audit ledger with its confidence and model.", "operationId": "judgeAgentSelfToolCall", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JudgmentRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JudgmentResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "The borderline-call classifier behind the auto_allow_judgment posture", "tags": [ "agents", "Agents" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Virtual-employee authorization surface for the settings UI and the local connector — never an assistant-callable tool." } }, "/api/v1/agents/self/mcp-deployment": { "get": { "description": "The calling employee's desired deployment set for its workshop.", "operationId": "getAgentSelfMcpDeployment", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SelfMcpDeploymentResponse" } } }, "description": "Successful Response" } }, "summary": "Get Agent Self Mcp Deployment", "tags": [ "agents", "agents" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Connector-facing MCP deployment serving." } }, "/api/v1/agents/self/mcp-deployment/ack": { "post": { "description": "What the host did with one deployment sync pass, and — with a turn\ncredential — what that turn's audience actually listed from each server.", "operationId": "ackAgentSelfMcpDeployment", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SelfMcpDeploymentAck" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SelfMcpDeploymentAckResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Ack Agent Self Mcp Deployment", "tags": [ "agents", "agents" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Connector-facing MCP deployment serving." } }, "/api/v1/agents/self/mcp-deployment/materialize": { "post": { "description": "Retired as a source of values (TIDY-19557 F2b).\n\nIts values landed in the employee's shared harness environment, which every\nconversation's turn inherited. It now names every connection that carries\na secret in ``errors`` (``mcp_turn_delivery_required``), so a connector\nthat still calls it acks those rows loud-error until it updates.", "operationId": "materializeAgentSelfMcpDeployment", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SelfMcpDeploymentMaterializeResponse" } } }, "description": "Successful Response" } }, "summary": "Materialize Agent Self Mcp Deployment", "tags": [ "agents", "agents" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Connector-facing MCP deployment serving." } }, "/api/v1/agents/self/mcp-deployment/turn": { "post": { "description": "TIDY-19557 F2b — the MCP connections, lends and values one turn's\naudience may use: a person's own and the workspace's in their direct\nconversation, the workspace's alone in a room. The response goes into that\naudience's harness config for the turn and nowhere else.", "operationId": "materializeAgentTurnMcpDeployment", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SelfMcpTurnDeliveryRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SelfMcpTurnDeliveryResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Materialize Agent Turn Mcp Deployment", "tags": [ "agents", "agents" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Connector-facing MCP deployment serving." } }, "/api/v1/agents/self/persona": { "get": { "description": "The calling virtual employee's persona, manners and chosen skills.\n\nTIDY-16152 (S14) — the portable connector writes the persona and manners to\nthe harness's own instruction files at every daemon start. TIDY-16153 (S15)\ncarries the chosen skill slugs on the SAME response, because they have the\nsame identity, the same authorization and the same refresh cadence: the\nconnector then installs exactly that set into the harness's skill root and\nprunes what is no longer selected.\n\nThe runtime PAT is the identity: there is no account path parameter, so one\nVE can never read another's persona — or another's skills. A\nremoved/revoked employee is refused by `self_persona` before either is\nserved, so this never becomes a path that hands a revoked VE its skill list.\n\nThe response model keeps its name (`AgentSelfPersonaResponse`); renaming it\nwould churn both SDKs for nothing.", "operationId": "getAgentSelfPersona", "parameters": [ { "in": "query", "name": "runtime", "required": false, "schema": { "anyOf": [ { "maxLength": 64, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Runtime" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentSelfPersonaResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Get Agent Self Persona", "tags": [ "agents", "Agents" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Workspace admin provisioning/status API for browser UI and local connector setup." } }, "/api/v1/agents/self/plugin-binding-names": { "get": { "description": "TIDY-19802 — the catalogue binding names, for the employee's own\nconnector. The runtime PAT is the only identity; nothing about the\nemployee, its connections or its grants is read to answer it.", "operationId": "getAgentPluginBindingNames", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PluginBindingNamesResponse" } } }, "description": "Successful Response" } }, "summary": "Get Agent Plugin Binding Names", "tags": [ "agents" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Credential custody is a first-party settings/runtime surface; secrets are never assistant-callable." } }, "/api/v1/agents/self/plugin-grants": { "get": { "operationId": "listAgentPluginGrants", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmployeePluginGrantsResponse" } } }, "description": "Successful Response" } }, "summary": "The live plugin lends the calling employee holds", "tags": [ "access" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Lending is a first-party Access surface; grants and tokens are never assistant-callable." } }, "/api/v1/agents/self/plugins": { "get": { "operationId": "listAgentPlugins", "parameters": [ { "description": "Plugin ids (bare UUID or Q-<uuid>); any not lent to you is a 403 naming it.", "in": "query", "name": "ids", "required": false, "schema": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "description": "Plugin ids (bare UUID or Q-<uuid>); any not lent to you is a 403 naming it.", "title": "Ids" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentPluginsResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Setup manifests for the plugins the calling employee was lent", "tags": [ "access" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Lending is a first-party Access surface; grants and tokens are never assistant-callable." } }, "/api/v1/agents/self/plugins/{plugin_id}/token": { "post": { "operationId": "issueAgentPluginToken", "parameters": [ { "in": "path", "name": "plugin_id", "required": true, "schema": { "title": "Plugin Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RuntimeTokenResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "What a live shipment delivers to the employee's workshop", "tags": [ "access" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Lending is a first-party Access surface; grants and tokens are never assistant-callable." } }, "/api/v1/agents/self/revoke-runtime": { "post": { "operationId": "selfRevokeAgentRuntime", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SelfRevokeRuntimeRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SelfRevokeRuntimeResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Self Revoke Agent Runtime", "tags": [ "agents", "Agents" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Workspace admin provisioning/status API for browser UI and local connector setup." } }, "/api/v1/agents/self/sandbox-elevations": { "post": { "description": "An employee's turn on a workshop asks for exactly what a sandbox gate\nrefused. Only a turn credential can ask: the conversation, project and\nworkshop are read from it, never from the body.", "operationId": "requestSandboxElevation", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxElevationRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxElevation" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Ask the workshop's owner for sandbox access your turn was refused", "tags": [ "workshops" ], "x-local-capability": "cloud" } }, "/api/v1/agents/self/skill-bundle": { "get": { "description": "Everything the CALLING virtual employee should hold on disk.\n\nThe runtime PAT is the identity — there is no account path parameter, so one\nVE can never read another's bundle. Same shape as `/agents/self/persona`.", "operationId": "getAgentSelfSkillBundle", "parameters": [ { "in": "query", "name": "runtime", "required": false, "schema": { "anyOf": [ { "maxLength": 64, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Runtime" } }, { "description": "Serve every skill as its complete canonical file set (bundle_format='files'). Only for hosts that push whole bundles back.", "in": "query", "name": "bundle_files", "required": false, "schema": { "default": false, "description": "Serve every skill as its complete canonical file set (bundle_format='files'). Only for hosts that push whole bundles back.", "title": "Bundle Files", "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SelfSkillBundleResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Get Agent Self Skill Bundle", "tags": [ "skill-collections", "skill-collections" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Workspace administration of virtual-employee skill packs." } }, "/api/v1/agents/self/skill-bundle/ack": { "post": { "description": "What the host did with the bundle — the per-assignee sync state (R31).", "operationId": "ackAgentSelfSkillBundle", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SelfSkillBundleAck" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SelfSkillBundleAckResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Ack Agent Self Skill Bundle", "tags": [ "skill-collections", "skill-collections" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Workspace administration of virtual-employee skill packs." } }, "/api/v1/agents/self/skill-inventory": { "get": { "description": "What the CALLING virtual employee carries, and what its workshop holds.\n\nTIDY-19569 F5: how an employee confirms a skill it authored in its owner's\nDM reached it — the identity, version, route and delivery its owner's\nSkills view shows. That is the owner's view, so it is answered only for\nthe live credential of the owner's own DM turn (``resolve_skill_caller``,\nthe authority the skill reads themselves take) and read AS the owner: a\nturn for another person, a room, the home room or no turn at all is\nrefused, never answered as the employee — whose carried skills include\nits owner's private ones.", "operationId": "getAgentSelfSkillInventory", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmployeeSkillInventoryResponse" } } }, "description": "Successful Response" } }, "summary": "Get Agent Self Skill Inventory", "tags": [ "skill-collections", "skill-collections" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Workspace administration of virtual-employee skill packs." } }, "/api/v1/agents/self/skill-script-runs/{run_id}/claim": { "post": { "operationId": "claimSkillScriptRun", "parameters": [ { "in": "path", "name": "run_id", "required": true, "schema": { "format": "uuid", "title": "Run Id", "type": "string" } }, { "in": "header", "name": "X-Tidy-Installation-Id", "required": false, "schema": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "X-Tidy-Installation-Id" } }, { "in": "header", "name": "X-Tidy-Boot-Id", "required": false, "schema": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "X-Tidy-Boot-Id" } }, { "in": "header", "name": "X-Tidy-Consumer-Generation", "required": false, "schema": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "X-Tidy-Consumer-Generation" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkillScriptRunClaimRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkillScriptRunClaim" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Claim Skill Script Run", "tags": [ "agents" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "An employee's connector runs a rule's skill script with its runtime PAT; rules start runs through the run_skill_script verb, never a tool." } }, "/api/v1/agents/self/skill-script-runs/{run_id}/result": { "post": { "operationId": "reportSkillScriptRun", "parameters": [ { "in": "path", "name": "run_id", "required": true, "schema": { "format": "uuid", "title": "Run Id", "type": "string" } }, { "in": "header", "name": "X-Tidy-Installation-Id", "required": false, "schema": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "X-Tidy-Installation-Id" } }, { "in": "header", "name": "X-Tidy-Boot-Id", "required": false, "schema": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "X-Tidy-Boot-Id" } }, { "in": "header", "name": "X-Tidy-Consumer-Generation", "required": false, "schema": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "X-Tidy-Consumer-Generation" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkillScriptRunReport" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkillScriptRunReportAck" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Report Skill Script Run", "tags": [ "agents" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "An employee's connector runs a rule's skill script with its runtime PAT; rules start runs through the run_skill_script verb, never a tool." } }, "/api/v1/agents/self/work-orders/{work_order_id}/admission": { "post": { "deprecated": true, "description": "Retired with the work-order rail (TIDY-19869 W1): an employee gets work\nas an ordinary message. A connector older than that release still asks\nhere when a work order reaches it, so the route answers the named 410\ninstead of a 404 until every connector has updated.", "operationId": "admitAgentWorkOrder", "parameters": [ { "in": "path", "name": "work_order_id", "required": true, "schema": { "format": "uuid", "title": "Work Order Id", "type": "string" } } ], "responses": { "410": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkOrdersRetiredProblem" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Admit one work order (retired)", "tags": [ "agents", "Agents" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Workspace admin provisioning/status API for browser UI and local connector setup." } }, "/api/v1/agents/self/workshop-policy": { "get": { "description": "TIDY-19557 — the Docker setting of this employee's own enrolled workshop,\nread by its connector at turn time to arm (or withhold) the filtering Docker\nproxy. The runtime PAT is the identity; an employee on Tidy compute, or one\nwhose workshop is revoked, reads false.", "operationId": "getSelfWorkshopPolicy", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkshopPolicyResponse" } } }, "description": "Successful Response" } }, "summary": "Get Self Workshop Policy", "tags": [ "agents" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Credential custody is a first-party settings/runtime surface; secrets are never assistant-callable." } }, "/api/v1/agents/session-host-migrations/prepare": { "post": { "operationId": "prepareAgentSessionHostMigration", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionHostMigrationPrepareRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionHostMigrationResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Prepare Agent Session Host Migration", "tags": [ "agents", "Agents" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Workspace admin provisioning/status API for browser UI and local connector setup." } }, "/api/v1/agents/session-host-migrations/{receipt_id}": { "get": { "operationId": "getAgentSessionHostMigration", "parameters": [ { "in": "path", "name": "receipt_id", "required": true, "schema": { "format": "uuid", "title": "Receipt Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionHostMigrationResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Get Agent Session Host Migration", "tags": [ "agents", "Agents" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Workspace admin provisioning/status API for browser UI and local connector setup." } }, "/api/v1/agents/session-host-migrations/{receipt_id}/commit": { "post": { "operationId": "commitAgentSessionHostMigration", "parameters": [ { "in": "path", "name": "receipt_id", "required": true, "schema": { "format": "uuid", "title": "Receipt Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionHostMigrationActionRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionHostMigrationResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Commit Agent Session Host Migration", "tags": [ "agents", "Agents" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Workspace admin provisioning/status API for browser UI and local connector setup." } }, "/api/v1/agents/session-host-migrations/{receipt_id}/rollback": { "post": { "operationId": "rollbackAgentSessionHostMigration", "parameters": [ { "in": "path", "name": "receipt_id", "required": true, "schema": { "format": "uuid", "title": "Receipt Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionHostMigrationActionRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionHostMigrationResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Rollback Agent Session Host Migration", "tags": [ "agents", "Agents" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Workspace admin provisioning/status API for browser UI and local connector setup." } }, "/api/v1/agents/setup-descriptor": { "get": { "description": "Serve the hosted setup descriptor for Hermes / OpenClaw / Pi runtimes.\n\nEndpoint URLs, OAuth/MCP scopes, principal selection, memory-hook contract,\nand revocation behavior (TIDY-11135). When the caller is a provisioned\nvirtual employee, the descriptor is bound to that agent + its owner; a\ngeneric descriptor otherwise.", "operationId": "getAgentSetupDescriptor", "parameters": [ { "in": "query", "name": "runtime", "required": true, "schema": { "title": "Runtime", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentSetupDescriptorResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Fetch the external runtime setup descriptor", "tags": [ "agents", "Agents" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Workspace admin provisioning/status API for browser UI and local connector setup." } }, "/api/v1/agents/turn-credential": { "post": { "description": "TIDY-19435: the connector trades its runtime PAT for a credential bound\nto the human this turn is for, derived here from the room and sender (or,\nin the home room, the task behind the conversation). The harness uses it\nfor the turn's tool calls; the connector revokes it when the turn ends.\n\nTIDY-19869: with ``prepare`` (and the lease headers) the same call answers\nevery block the turn needs in ``prepared`` — one call per turn.", "operationId": "mintAgentTurnCredential", "parameters": [ { "in": "header", "name": "X-Tidy-Installation-Id", "required": false, "schema": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "X-Tidy-Installation-Id" } }, { "in": "header", "name": "X-Tidy-Boot-Id", "required": false, "schema": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "X-Tidy-Boot-Id" } }, { "in": "header", "name": "X-Tidy-Consumer-Generation", "required": false, "schema": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "X-Tidy-Consumer-Generation" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentTurnCredentialRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentTurnCredentialResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Mint the tool credential for one employee turn", "tags": [ "agents", "Agents" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Workspace admin provisioning/status API for browser UI and local connector setup." } }, "/api/v1/agents/turn-credential/colleague-messages": { "post": { "description": "TIDY-19561: what colleagues sent this employee that no conversation has\ntaken yet, for the connector to put ahead of the turn's prompt. Only a turn\nbound to the employee's owner gets them. Reading consumes nothing.", "operationId": "listAgentTurnColleagueMessages", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentTurnColleagueMessagesRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentTurnColleagueMessagesResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Unread colleague messages for an owner's turn", "tags": [ "agents", "Agents" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Workspace admin provisioning/status API for browser UI and local connector setup." } }, "/api/v1/agents/turn-credential/colleague-messages/read": { "post": { "description": "TIDY-19561: called once the harness ran the turn that carried them, so\na turn that never started leaves them unread for the next one.", "operationId": "markAgentTurnColleagueMessagesRead", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentTurnColleagueMessagesReadRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentTurnColleagueMessagesReadResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Mark the colleague messages a turn carried read", "tags": [ "agents", "Agents" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Workspace admin provisioning/status API for browser UI and local connector setup." } }, "/api/v1/agents/turn-credential/colleague-turn": { "post": { "description": "TIDY-19611: before it spends anything on a colleague's message that\n@mentions its employee, the connector asks here. The server reads the event\nas the employee, checks it is a colleague's in a project room everyone in\nwhich belongs to the project, and reserves the wake against the employee's\ncaps; the turn credential then opens only for an admitted event.", "operationId": "admitAgentColleagueTurn", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentColleagueTurnRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentColleagueTurnResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Admit one turn on a colleague's @mention in a project room", "tags": [ "agents", "Agents" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Workspace admin provisioning/status API for browser UI and local connector setup." } }, "/api/v1/agents/turn-credential/memory-cleared": { "post": { "description": "TIDY-19869 M5: the connector cleared the working memory of this turn's\nroom because a project was hidden from it, and calls this before the turn's\nharness starts. Every note the employee saved in the room before now stops\nbeing used, everywhere; none is deleted. Called with the runtime PAT that\nminted the turn. A failure is the connector's to fail the turn on.", "operationId": "withdrawAgentTurnClearedMemory", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentTurnMemoryClearedRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentTurnMemoryClearedResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Withdraw the saved notes of a room whose working memory was cleared", "tags": [ "agents", "Agents" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Workspace admin provisioning/status API for browser UI and local connector setup." } }, "/api/v1/agents/turn-credential/revoke": { "post": { "description": "Legacy ``{credential_id}`` answers ``revoked`` | ``not_live``. The prepare\nform (TIDY-19869) answers ``revoked`` | ``cancelled`` (a tombstone; nothing\nwas minted) | ``already_final``, and never ``not_live``.", "operationId": "revokeAgentTurnCredential", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentTurnCredentialRevokeRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperationStatusResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Revoke a settled turn's tool credential", "tags": [ "agents", "Agents" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Workspace admin provisioning/status API for browser UI and local connector setup." } }, "/api/v1/agents/turn-credential/sandbox-elevations": { "post": { "description": "Read by the employee's connector at the start of a Docker-on turn: the\nturn's filtering proxy then admits exactly these. The runtime PAT must be\nthe one that minted the turn credential.", "operationId": "listAgentTurnSandboxElevations", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentTurnSandboxElevationsRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentTurnSandboxElevationsResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "The sandbox approvals that reach one turn", "tags": [ "workshops" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "The employee's connector applies sandbox approvals at turn start." } }, "/api/v1/agents/turn-credential/sandbox-elevations/exercised": { "post": { "description": "Called before the turn credential is revoked: an \"Allow once\" is spent\nby the turn that used it; a standing approval counts an exercise.", "operationId": "recordAgentTurnSandboxElevationsExercised", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentTurnSandboxExercisedRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentTurnSandboxExercisedResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Record the sandbox approvals a turn's Docker filter used", "tags": [ "workshops" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "The employee's connector applies sandbox approvals at turn start." } }, "/api/v1/agents/{agent_account_id}/delete-identity": { "post": { "operationId": "deleteEmployeeIdentity", "parameters": [ { "in": "path", "name": "agent_account_id", "required": true, "schema": { "title": "Agent Account Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmployeeLifecycleResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Delete a retired employee's identity", "tags": [ "agents", "Agents" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/agents/{agent_account_id}/move": { "post": { "description": "Both directions. The settle gate refuses with the conversations still\nworking; `force` moves anyway and says in the response what it left.", "operationId": "moveEmployeeHost", "parameters": [ { "in": "path", "name": "agent_account_id", "required": true, "schema": { "title": "Agent Account Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmployeeMoveRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmployeeMoveResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Move an employee to a workshop or to Tidy compute", "tags": [ "agents", "Agents" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/agents/{agent_account_id}/move-targets": { "get": { "description": "The picker's whole content: the enrolled workshops, and Tidy compute.\n\nTidy compute is listed even when it cannot take the employee — with the\nreason. Hiding an option the user was told exists is how \"Move… does not\noffer Tidy compute\" becomes a support ticket instead of a sentence.", "operationId": "listEmployeeMoveTargets", "parameters": [ { "in": "path", "name": "agent_account_id", "required": true, "schema": { "title": "Agent Account Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmployeeMoveTargetsResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Where this employee could run", "tags": [ "agents", "Agents" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/agents/{agent_account_id}/pause": { "post": { "operationId": "pauseEmployee", "parameters": [ { "in": "path", "name": "agent_account_id", "required": true, "schema": { "title": "Agent Account Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmployeeLifecycleResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Pause an employee", "tags": [ "agents", "Agents" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/agents/{agent_account_id}/project-roots": { "get": { "operationId": "listAgentProjectRoots", "parameters": [ { "in": "path", "name": "agent_account_id", "required": true, "schema": { "title": "Agent Account Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentProjectRootListResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List a VE's project workspace roots", "tags": [ "agent-project-roots" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/agents/{agent_account_id}/project-roots/ensure": { "post": { "description": "Idempotent: an existing row keeps its stored root path; an error or\ndetached row resets to pending for a retry. Archived projects refuse.", "operationId": "ensureAgentProjectRoot", "parameters": [ { "in": "path", "name": "agent_account_id", "required": true, "schema": { "title": "Agent Account Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentProjectRootEnsureRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentProjectRootEnsureResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Ensure a VE's workspace root row for a project", "tags": [ "agent-project-roots" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/agents/{agent_account_id}/project-roots/{project_id}": { "put": { "description": "Only the agent itself may report — nothing else witnessed the host.", "operationId": "reportAgentProjectRoot", "parameters": [ { "in": "path", "name": "agent_account_id", "required": true, "schema": { "title": "Agent Account Id", "type": "string" } }, { "description": "Typed ID with prefix 'P'", "in": "path", "name": "project_id", "required": true, "schema": { "description": "Typed ID with prefix 'P'", "title": "Project Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentProjectRootReportRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentProjectRootResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Report the outcome of a workspace-root ensure from the VE host", "tags": [ "agent-project-roots" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/agents/{agent_account_id}/redeploy": { "post": { "description": "In place, on the employee's OWN box.\n\nDeliberately takes no workshop id: the box is read from the employee, so\n\"re-materialises on the same box\" cannot be broken by the caller. The\nroster-wide `redeploy-roster` on the workshop router is a different verb\nand keeps its own path. TIDY-20019 F3: the optional body can start the\nemployee with its own harness extensions off.", "operationId": "redeployEmployee", "parameters": [ { "in": "path", "name": "agent_account_id", "required": true, "schema": { "title": "Agent Account Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/EmployeeRedeployRequest" }, { "type": "null" } ], "title": "Body" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmployeeLifecycleResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Re-install an employee on the machine it already runs on", "tags": [ "agents", "Agents" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/agents/{agent_account_id}/resume": { "post": { "operationId": "resumeEmployee", "parameters": [ { "in": "path", "name": "agent_account_id", "required": true, "schema": { "title": "Agent Account Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmployeeLifecycleResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Resume a paused employee", "tags": [ "agents", "Agents" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/agents/{agent_account_id}/retire": { "post": { "operationId": "retireEmployee", "parameters": [ { "in": "path", "name": "agent_account_id", "required": true, "schema": { "title": "Agent Account Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmployeeLifecycleResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Retire an employee", "tags": [ "agents", "Agents" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/agents/{agent_id}/running-turn": { "get": { "operationId": "streamAgentRunningTurn", "parameters": [ { "description": "The employee's agent account UUID", "in": "path", "name": "agent_id", "required": true, "schema": { "description": "The employee's agent account UUID", "title": "Agent Id", "type": "string" } } ], "responses": { "200": { "content": { "text/event-stream": {} }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Live running-turn stream for one virtual employee (SSE)", "tags": [ "agents" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Server-Sent Events push channel for the read-only running-turn panel; consumed by the browser client, not an agent tool." } }, "/api/v1/agents/{employee_account_id}/harness-credentials": { "get": { "operationId": "listVeHarnessModelCredentials", "parameters": [ { "in": "path", "name": "employee_account_id", "required": true, "schema": { "format": "uuid", "title": "Employee Account Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HarnessCredentialAssignments" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List Ve Harness Model Credentials", "tags": [ "agents" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Credential custody is a first-party settings/runtime surface; secrets are never assistant-callable." } }, "/api/v1/agents/{employee_account_id}/harness-credentials/{runtime}": { "put": { "operationId": "setVeHarnessModelCredentials", "parameters": [ { "in": "path", "name": "employee_account_id", "required": true, "schema": { "format": "uuid", "title": "Employee Account Id", "type": "string" } }, { "in": "path", "name": "runtime", "required": true, "schema": { "title": "Runtime", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HarnessCredentialsSet" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HarnessCredentialAssignments" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/ProblemDetail" }, { "$ref": "#/components/schemas/LegacyValidationRefusal" } ], "title": "Response 422 Setveharnessmodelcredentials" } }, "application/problem+json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetail" }, { "$ref": "#/components/schemas/LegacyValidationRefusal" } ] } } }, "description": "A refused credential assignment (problem+json, or a legacy `{detail: [...]}` validation body from an older server — both typed). Names the specific `error_code`: e.g. `tidy_inference_model_not_published` (the persisted selection names a model the delivered key cannot serve, the alias is in `detail`), `tidy_inference_unconfigured`, `tidy_inference_unsupported_runtime`, or `model_source_missing` (a selected model no remaining source serves); native_box_login refusals carry `native_box_login_missing`. (TIDY-18662 F3/R4.) This command replaces the harness's whole source set with ONE source; `setVeHarnessModelSources` holds several (TIDY-19616)." } }, "security": [ { "HTTPBearer": [] } ], "summary": "Set Ve Harness Model Credentials", "tags": [ "agents" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Credential custody is a first-party settings/runtime surface; secrets are never assistant-callable." } }, "/api/v1/agents/{employee_account_id}/harness-credentials/{runtime}/sources": { "put": { "description": "Give a harness ALL its model sources at once (TIDY-19616): Tidy\ninference, its own sign-ins and any number of plugins, as far as the\nharness can tell their models apart (`source_capacity`).", "operationId": "setVeHarnessModelSources", "parameters": [ { "in": "path", "name": "employee_account_id", "required": true, "schema": { "format": "uuid", "title": "Employee Account Id", "type": "string" } }, { "in": "path", "name": "runtime", "required": true, "schema": { "title": "Runtime", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HarnessModelSourcesSet" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HarnessCredentialAssignments" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/ProblemDetail" }, { "$ref": "#/components/schemas/LegacyValidationRefusal" } ], "title": "Response 422 Setveharnessmodelsources" } }, "application/problem+json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetail" }, { "$ref": "#/components/schemas/LegacyValidationRefusal" } ] } } }, "description": "A refused source set (problem+json). `model_source_capacity` (this harness holds fewer sources; the message says how many), `model_source_namespace_conflict` (two plugins serve the same model names), `model_source_shadowed` (the harness is signed in to that provider itself), `model_source_missing` (a selected model no source in the set serves), `endpoint_workshop_mismatch` (a plugin restricted to another workshop), plus the single-source refusals. (TIDY-19616.)" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Set Ve Harness Model Sources", "tags": [ "agents" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Credential custody is a first-party settings/runtime surface; secrets are never assistant-callable." } }, "/api/v1/agents/{employee_account_id}/harnesses": { "get": { "operationId": "listEmployeeHarnesses", "parameters": [ { "in": "path", "name": "employee_account_id", "required": true, "schema": { "format": "uuid", "title": "Employee Account Id", "type": "string" } }, { "in": "query", "name": "profile_id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Profile Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmployeeHarnessListResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List Employee Harnesses", "tags": [ "agents" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Harness configuration is a first-party settings surface." } }, "/api/v1/agents/{employee_account_id}/harnesses/{runtime}": { "delete": { "operationId": "disarmEmployeeHarness", "parameters": [ { "in": "path", "name": "employee_account_id", "required": true, "schema": { "format": "uuid", "title": "Employee Account Id", "type": "string" } }, { "in": "path", "name": "runtime", "required": true, "schema": { "title": "Runtime", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DisarmHarnessResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Disarm Employee Harness", "tags": [ "agents" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Harness configuration is a first-party settings surface." }, "put": { "operationId": "armEmployeeHarness", "parameters": [ { "in": "path", "name": "employee_account_id", "required": true, "schema": { "format": "uuid", "title": "Employee Account Id", "type": "string" } }, { "in": "path", "name": "runtime", "required": true, "schema": { "title": "Runtime", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ArmHarnessRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ArmHarnessResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Arm Employee Harness", "tags": [ "agents" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Harness configuration is a first-party settings surface." } }, "/api/v1/agents/{employee_account_id}/harnesses/{runtime}/accounts": { "post": { "operationId": "addEmployeeHarnessAccount", "parameters": [ { "in": "path", "name": "employee_account_id", "required": true, "schema": { "format": "uuid", "title": "Employee Account Id", "type": "string" } }, { "in": "path", "name": "runtime", "required": true, "schema": { "title": "Runtime", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddHarnessAccountRequest" } } }, "required": true }, "responses": { "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HarnessAccountJobResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Add Employee Harness Account", "tags": [ "agents" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Harness configuration is a first-party settings surface." } }, "/api/v1/agents/{employee_account_id}/harnesses/{runtime}/accounts/{profile_id}/remedies": { "get": { "description": "The remedy contract for ONE harness account row (TIDY-18906, P14).\n\nThe registered usage-limits widget mounts in employee scope from the\nWorkforce Attention view, where no session detail exists — so the same\nserver-computed eligibility contract the session detail carries is served\nhere from the S5 account rows. Only `eligible` rows render; the execute\ndoors re-run the checks and refuse by name.", "operationId": "getEmployeeHarnessAccountRemedies", "parameters": [ { "in": "path", "name": "employee_account_id", "required": true, "schema": { "format": "uuid", "title": "Employee Account Id", "type": "string" } }, { "in": "path", "name": "runtime", "required": true, "schema": { "title": "Runtime", "type": "string" } }, { "in": "path", "name": "profile_id", "required": true, "schema": { "title": "Profile Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HarnessAccountRemediesResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Employee Harness Account Remedies", "tags": [ "agents" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Harness configuration is a first-party settings surface." } }, "/api/v1/agents/{employee_account_id}/harnesses/{runtime}/accounts/{profile_id}/sessions": { "get": { "description": "The conversations currently bound to one harness account (P15/F8).\n\nEmployee-scope remedies offer a per-session switch against THIS list; each\nrow carries its room id, which is what the per-session PATCH door takes.", "operationId": "listEmployeeHarnessAccountSessions", "parameters": [ { "in": "path", "name": "employee_account_id", "required": true, "schema": { "format": "uuid", "title": "Employee Account Id", "type": "string" } }, { "in": "path", "name": "runtime", "required": true, "schema": { "title": "Runtime", "type": "string" } }, { "in": "path", "name": "profile_id", "required": true, "schema": { "title": "Profile Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HarnessAccountSessionsResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List Employee Harness Account Sessions", "tags": [ "agents" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Harness configuration is a first-party settings surface." } }, "/api/v1/agents/{employee_account_id}/harnesses/{runtime}/models/refresh": { "post": { "description": "Ask the employee's workshop to list its model sources' models again\n(TIDY-19825). `model_listing_unavailable` when it is on no workshop.", "operationId": "refreshEmployeeHarnessModels", "parameters": [ { "in": "path", "name": "employee_account_id", "required": true, "schema": { "format": "uuid", "title": "Employee Account Id", "type": "string" } }, { "in": "path", "name": "runtime", "required": true, "schema": { "title": "Runtime", "type": "string" } } ], "responses": { "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HarnessModelListingResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Refresh Employee Harness Models", "tags": [ "agents" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Harness configuration is a first-party settings surface." } }, "/api/v1/agents/{employee_account_id}/harnesses/{runtime}/settings": { "put": { "description": "TIDY-20086 F8 — turn a harness's own settings on or off for one employee\n(Hermes's memory, cron jobs and Kanban). Its connector applies them from\nthe next heartbeat.", "operationId": "setEmployeeHarnessSettings", "parameters": [ { "in": "path", "name": "employee_account_id", "required": true, "schema": { "format": "uuid", "title": "Employee Account Id", "type": "string" } }, { "in": "path", "name": "runtime", "required": true, "schema": { "title": "Runtime", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HarnessSettingsUpdate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HarnessSettingsResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Set Employee Harness Settings", "tags": [ "agents" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Harness configuration is a first-party settings surface." } }, "/api/v1/agents/{employee_account_id}/harnesses/{runtime}/usage/refresh": { "post": { "operationId": "refreshEmployeeHarnessUsage", "parameters": [ { "in": "path", "name": "employee_account_id", "required": true, "schema": { "format": "uuid", "title": "Employee Account Id", "type": "string" } }, { "in": "path", "name": "runtime", "required": true, "schema": { "title": "Runtime", "type": "string" } }, { "in": "query", "name": "profile_id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Profile Id" } } ], "responses": { "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HarnessUsageRefreshResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Refresh Employee Harness Usage", "tags": [ "agents" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Harness configuration is a first-party settings surface." } }, "/api/v1/agents/{employee_account_id}/host-fingerprints": { "get": { "description": "Get recorded SSH host key fingerprints for a virtual employee.", "operationId": "getAgentHostFingerprints", "parameters": [ { "in": "path", "name": "employee_account_id", "required": true, "schema": { "format": "uuid", "title": "Employee Account Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MachineHostFingerprintsResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Agent Host Fingerprints", "tags": [ "agents" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Credential custody is a first-party settings/runtime surface; secrets are never assistant-callable." } }, "/api/v1/agents/{employee_account_id}/model-selection": { "get": { "operationId": "listVeModelSelection", "parameters": [ { "in": "path", "name": "employee_account_id", "required": true, "schema": { "format": "uuid", "title": "Employee Account Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelSelectionResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List Ve Model Selection", "tags": [ "agents" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Credential custody is a first-party settings/runtime surface; secrets are never assistant-callable." } }, "/api/v1/agents/{employee_account_id}/model-selection/{runtime}": { "put": { "operationId": "setVeModelSelection", "parameters": [ { "in": "path", "name": "employee_account_id", "required": true, "schema": { "format": "uuid", "title": "Employee Account Id", "type": "string" } }, { "in": "path", "name": "runtime", "required": true, "schema": { "title": "Runtime", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelSelectionSetRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelSelectionResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/ProblemDetail" }, { "$ref": "#/components/schemas/LegacyValidationRefusal" } ], "title": "Response 422 Setvemodelselection" } }, "application/problem+json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ProblemDetail" }, { "$ref": "#/components/schemas/LegacyValidationRefusal" } ] } } }, "description": "A refused model selection (problem+json, or a legacy `{detail: [...]}` validation body from an older server — both typed). For a `tidy_inference` employee the `error_code: tidy_inference_model_not_published` carries the refused alias in `detail` (and lists what the lane serves); `tidy_inference_catalogue_unavailable` means the lane list could not be read and the selection was refused rather than accepted unverified; `harness_credential_method_conflict` means the stored method set is mixed and must be cleared. Every other credential method keeps the host catalogue as its authority. (TIDY-18662 F3/R4.)" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Set Ve Model Selection", "tags": [ "agents" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Credential custody is a first-party settings/runtime surface; secrets are never assistant-callable." } }, "/api/v1/agents/{employee_account_id}/pty/tickets": { "post": { "description": "Mint a single-use PTY attach ticket into one employee's own context.\n\nThe employee home's Terminal tab (TIDY-19592): a shell its runtime spawns\nwith its harness homes and harness binaries, in its working directory, so\n`pi` there is the employee's pi. The response names the workshop the\nemployee is deployed on; the relay URL is that workshop's. Refuses when the\ncaller is neither the employee's owner nor a workspace Owner/Admin, when\nthe caller may not attach to the employee's workshop (the shell is that\nmachine's one OS account), or when the employee holds no live lease.\n\nA ``sign_in`` terminal (TIDY-19929) is refused ``sign_in_in_progress``\nwhen that harness is already being signed in on another device.", "operationId": "mintEmployeePtyTicket", "parameters": [ { "in": "path", "name": "employee_account_id", "required": true, "schema": { "format": "uuid", "title": "Employee Account Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/MintEmployeePtyTicketRequest" }, { "type": "null" } ], "title": "Body" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MintPtyTicketResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Mint Employee Pty Ticket", "tags": [ "workshops" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/agents/{employee_account_id}/usage": { "get": { "description": "The PRIVATE usage read — the requester must see the employee or 404 (F1).", "operationId": "getEmployeeUsageLimits", "parameters": [ { "in": "path", "name": "employee_account_id", "required": true, "schema": { "format": "uuid", "title": "Employee Account Id", "type": "string" } }, { "description": "The viewer's IANA timezone; the slice is cut in it.", "in": "query", "name": "tz", "required": true, "schema": { "description": "The viewer's IANA timezone; the slice is cut in it.", "title": "Tz", "type": "string" } }, { "in": "query", "name": "slice", "required": false, "schema": { "default": "today", "title": "Slice", "type": "string" } }, { "in": "query", "name": "runtime", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Runtime" } }, { "in": "query", "name": "profile_id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Profile Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageLimitsResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Employee Usage Limits", "tags": [ "agents" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Harness configuration is a first-party settings surface." } }, "/api/v1/agents/{employee_account_id}/usage/insights": { "get": { "operationId": "getEmployeeUsageInsights", "parameters": [ { "in": "path", "name": "employee_account_id", "required": true, "schema": { "format": "uuid", "title": "Employee Account Id", "type": "string" } }, { "description": "The viewer's IANA timezone; the slice is cut in it.", "in": "query", "name": "tz", "required": true, "schema": { "description": "The viewer's IANA timezone; the slice is cut in it.", "title": "Tz", "type": "string" } }, { "in": "query", "name": "slice", "required": false, "schema": { "default": "today", "title": "Slice", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageInsightsResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Employee Usage Insights", "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Usage insights are a first-party settings surface." } }, "/api/v1/ai/answer-qa": { "post": { "operationId": "answerChatQuestion", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnswerQuestionRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnswerQuestionResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Answer Question", "tags": [ "ai-chat" ] } }, "/api/v1/ai/assistant-call": { "post": { "description": "Request/response into the Tidy Assistant (tier 2) or an employee persona\n(tier 3), under the caller's identity and the employee's tool scope.\n\nSynchronous single turn with hard timeout + size caps — async orchestration\nis what the workflow itself is for.", "operationId": "aiAssistantCall", "parameters": [ { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssistantCallRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssistantCallResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Single-turn assistant / employee call (tiers 2-3)", "tags": [ "ai-primitives", "ai-primitives" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Workflow/sandbox AI primitive (tidy.ai.*); invoked from workflow scripts with the minted sandbox JWT, not a general MCP tool surface." } }, "/api/v1/ai/authoring/rewrite": { "post": { "description": "Rewrite the Soul (SOUL.md persona) or Manners (AGENTS.md behavioral\n contract) field of a virtual employee using the free LLM tier, primed\n with field-aware system context (AC4) and shaped by the chosen quick\n operation (rewrite / fix_grammar / shorten — AC2) plus an optional\n freeform instruction (AC3).\n\n Reuses the LiteLLM path and credit gate used by the email compose AI\n endpoints (AC7). Returns the rewritten field text only — no preamble,\n no code fences.\n\n Related: TIDY-11565", "operationId": "rewriteAuthoringText", "parameters": [ { "in": "header", "name": "X-Trace-Id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthoringRewriteRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthoringRewriteResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Rewrite a virtual-employee setup field with AI", "tags": [ "agents" ], "x-mcp-skip": true } }, "/api/v1/ai/compose-assist": { "post": { "operationId": "composeAssistChatMessage", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ComposeAssistRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ComposeAssistResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Compose Assist", "tags": [ "ai-chat" ] } }, "/api/v1/ai/employees": { "get": { "operationId": "listAIEmployees", "parameters": [ { "in": "query", "name": "enabled_only", "required": false, "schema": { "default": false, "title": "Enabled Only", "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/AIEmployeeResponse" }, "title": "Response Listaiemployees", "type": "array" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List Ai Employees", "tags": [ "ai-chat" ] }, "post": { "operationId": "createAIEmployee", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AIEmployeeRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AIEmployeeResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Create Ai Employee", "tags": [ "ai-chat" ] } }, "/api/v1/ai/employees/define": { "post": { "description": "Define a whole hosted employee in ONE transaction (TIDY-19500 F2).\n\nThe employee, its soul, manners and voice, model access, wake settings,\nobjectives, scheduled jobs, reporting line and bench-template planting all\nland together or not at all — a refusal of any part leaves no employee.\nLater edits go through each part's own endpoint.", "operationId": "defineAIEmployee", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmployeeDefinitionRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DefinedEmployeeResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Define Ai Employee", "tags": [ "ai-chat" ], "x-local-capability": "cloud" } }, "/api/v1/ai/employees/define-team": { "post": { "description": "Define a whole team of hosted employees in ONE transaction (TIDY-19500 F4).\n\nEach employee is defined exactly as ``/employees/define`` defines one, and\na teammate's ``reports_to.draft_key`` resolves to the account its manager\nwas given a moment earlier in the same transaction — so the team, its\nreporting lines and every part of every member land together or not at\nall. One approved card (D3/D12) is one call.", "operationId": "defineAIEmployeeTeam", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmployeeTeamDefinitionRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DefinedTeamResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Define Ai Employee Team", "tags": [ "ai-chat" ], "x-local-capability": "cloud" } }, "/api/v1/ai/employees/{employee_id}": { "delete": { "operationId": "deleteAIEmployee", "parameters": [ { "in": "path", "name": "employee_id", "required": true, "schema": { "format": "uuid", "title": "Employee Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_service__routers__ai_chat__OkResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Delete Ai Employee", "tags": [ "ai-chat" ] }, "put": { "operationId": "updateAIEmployee", "parameters": [ { "in": "path", "name": "employee_id", "required": true, "schema": { "format": "uuid", "title": "Employee Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AIEmployeePatch" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AIEmployeeResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Update Ai Employee", "tags": [ "ai-chat" ] } }, "/api/v1/ai/employees/{employee_id}/setup-checklist": { "get": { "description": "The employee's needs-setup checklist (D25) — its named MCP connections\nwith per-connection authorization state. Never blocks the employee: an\nunauthorized connection is flagged, its other tools still work.", "operationId": "getAIEmployeeSetupChecklist", "parameters": [ { "in": "path", "name": "employee_id", "required": true, "schema": { "format": "uuid", "title": "Employee Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmployeeSetupChecklistResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Ai Employee Setup Checklist", "tags": [ "ai-chat" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/ai/employees/{employee_id}/skills": { "get": { "description": "The per-employee skill assignments (R9). Empty => the employee loads the\nwhole visible tenant catalog (back-compat).", "operationId": "listAIEmployeeSkills", "parameters": [ { "in": "path", "name": "employee_id", "required": true, "schema": { "format": "uuid", "title": "Employee Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AIEmployeeSkillsResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List Ai Employee Skills", "tags": [ "ai-chat" ], "x-local-capability": "cloud", "x-mcp-skip": true }, "put": { "description": "Reconcile the employee's skill set to exactly ``skill_ids`` — only skills\nthat live in the tenant catalog are accepted (an unknown id is dropped, not\nan error).", "operationId": "setAIEmployeeSkills", "parameters": [ { "in": "path", "name": "employee_id", "required": true, "schema": { "format": "uuid", "title": "Employee Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AIEmployeeSkillsUpdate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AIEmployeeSkillsResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Set Ai Employee Skills", "tags": [ "ai-chat" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/ai/extract": { "post": { "description": "Run schema-validated extraction over ``body.items``.\n\nOne Instructor/LiteLLM call per item, bounded concurrency, per-item\nskip-and-continue. Consumption is gated on the credit pool (TIDY-12057):\n402 {code: pool_exhausted | checkpoint_required} when the account is out of\ncredits — do not retry within the run.", "operationId": "aiExtract", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiExtractRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiExtractResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Schema-validated structured LLM extraction over a batch of texts", "tags": [ "ai" ], "x-mcp-skip": true, "x-mcp-skip-reason": "Sandbox-script extraction primitive (workflow scripts call it with AUTH_TOKEN); agent surfaces have their own LLM lanes." } }, "/api/v1/ai/linkable-agents": { "get": { "description": "List the actors a connection can be granted to (TIDY-14147 / S5).\n\nUnions built-in AI Assistants (``ai_employees``, enabled + non-deleted) with\nvirtual employees (``agent_members`` that are lifecycle-usable: not removed,\nrevoked, or suspended). Carries no auth header or secret.", "operationId": "listLinkableAgents", "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/LinkableAgent" }, "title": "Response Listlinkableagents", "type": "array" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List Linkable Agents", "tags": [ "ai-chat" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/ai/room-policies": { "get": { "operationId": "listAIRoomPolicies", "parameters": [ { "in": "query", "name": "room_id", "required": true, "schema": { "minLength": 1, "title": "Room Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/RoomPolicyResponse" }, "title": "Response Listairoompolicies", "type": "array" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List Room Policies", "tags": [ "ai-chat" ] }, "post": { "operationId": "upsertAIRoomPolicy", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoomPolicyRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoomPolicyResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Upsert Room Policy", "tags": [ "ai-chat" ] } }, "/api/v1/ai/room-policies/{policy_id}": { "put": { "operationId": "updateAIRoomPolicy", "parameters": [ { "in": "path", "name": "policy_id", "required": true, "schema": { "format": "uuid", "title": "Policy Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoomPolicyPatch" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoomPolicyResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Update Room Policy", "tags": [ "ai-chat" ] } }, "/api/v1/ai/suggest-embed": { "post": { "operationId": "suggestChatEmbeds", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuggestEmbedRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuggestEmbedResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Suggest Embed", "tags": [ "ai-chat" ] } }, "/api/v1/ai/transform": { "post": { "description": "Transform ``input`` into a schema-valid object. Persists nothing.\n\nRoutes at the declared tier through the shared extraction engine; validates\nagainst the output schema with ONE in-call retry, then a loud 422 with the\nvalidator errors (malformed data never passes downstream).", "operationId": "aiTransform", "parameters": [ { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransformRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransformResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Schema-bound AI transform (tier 1)", "tags": [ "ai-primitives", "ai-primitives" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Workflow/sandbox AI primitive (tidy.ai.*); invoked from workflow scripts with the minted sandbox JWT, not a general MCP tool surface." } }, "/api/v1/analytics/badges": { "get": { "description": "Return earned and in-progress badges for the current user.", "operationId": "getBadges", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BadgesResponse" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Badges", "tags": [ "analytics" ] } }, "/api/v1/analytics/benchmarks": { "get": { "description": "Return all industry benchmark definitions.", "operationId": "getBenchmarks", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Getbenchmarks", "type": "object" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Benchmarks", "tags": [ "analytics" ] } }, "/api/v1/analytics/calendar/focus-time": { "get": { "description": "Return focus time metrics: total hours, daily average, blocks, best day.", "operationId": "getFocusTime", "parameters": [ { "description": "Time range preset", "in": "query", "name": "range", "required": false, "schema": { "default": "30d", "description": "Time range preset", "title": "Range", "type": "string" } }, { "description": "Start date for custom range", "in": "query", "name": "start", "required": false, "schema": { "anyOf": [ { "format": "date", "type": "string" }, { "type": "null" } ], "description": "Start date for custom range", "title": "Start" } }, { "description": "End date for custom range", "in": "query", "name": "end", "required": false, "schema": { "anyOf": [ { "format": "date", "type": "string" }, { "type": "null" } ], "description": "End date for custom range", "title": "End" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FocusTimeResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Focus Time", "tags": [ "analytics" ] } }, "/api/v1/analytics/calendar/meeting-quality": { "get": { "description": "Return meeting quality metrics: duration, size, recurring distributions.", "operationId": "getMeetingQuality", "parameters": [ { "description": "Time range preset", "in": "query", "name": "range", "required": false, "schema": { "default": "30d", "description": "Time range preset", "title": "Range", "type": "string" } }, { "description": "Start date for custom range", "in": "query", "name": "start", "required": false, "schema": { "anyOf": [ { "format": "date", "type": "string" }, { "type": "null" } ], "description": "Start date for custom range", "title": "Start" } }, { "description": "End date for custom range", "in": "query", "name": "end", "required": false, "schema": { "anyOf": [ { "format": "date", "type": "string" }, { "type": "null" } ], "description": "End date for custom range", "title": "End" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MeetingQualityResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Meeting Quality", "tags": [ "analytics" ] } }, "/api/v1/analytics/calendar/summary": { "get": { "description": "Return high-level calendar/meeting statistics for the time range.", "operationId": "getCalendarSummary", "parameters": [ { "description": "Time range preset", "in": "query", "name": "range", "required": false, "schema": { "default": "30d", "description": "Time range preset", "title": "Range", "type": "string" } }, { "description": "Start date for custom range", "in": "query", "name": "start", "required": false, "schema": { "anyOf": [ { "format": "date", "type": "string" }, { "type": "null" } ], "description": "Start date for custom range", "title": "Start" } }, { "description": "End date for custom range", "in": "query", "name": "end", "required": false, "schema": { "anyOf": [ { "format": "date", "type": "string" }, { "type": "null" } ], "description": "End date for custom range", "title": "End" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CalendarSummaryResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Calendar Summary", "tags": [ "analytics" ] } }, "/api/v1/analytics/calendar/volume": { "get": { "description": "Return time-series meeting volume data with size breakdown.", "operationId": "getCalendarVolume", "parameters": [ { "description": "Time range preset", "in": "query", "name": "range", "required": false, "schema": { "default": "30d", "description": "Time range preset", "title": "Range", "type": "string" } }, { "description": "Start date for custom range", "in": "query", "name": "start", "required": false, "schema": { "anyOf": [ { "format": "date", "type": "string" }, { "type": "null" } ], "description": "Start date for custom range", "title": "Start" } }, { "description": "End date for custom range", "in": "query", "name": "end", "required": false, "schema": { "anyOf": [ { "format": "date", "type": "string" }, { "type": "null" } ], "description": "End date for custom range", "title": "End" } }, { "description": "Grouping: day, week, or month", "in": "query", "name": "group_by", "required": false, "schema": { "default": "day", "description": "Grouping: day, week, or month", "title": "Group By", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/CalendarVolumePeriod" }, "title": "Response Getcalendarvolume", "type": "array" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Calendar Volume", "tags": [ "analytics" ] } }, "/api/v1/analytics/coaching/evaluate": { "post": { "description": "Evaluate user metrics against coaching rules and benchmarks.", "operationId": "evaluateCoaching", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CoachingEvaluateRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CoachingEvaluateResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Evaluate Coaching", "tags": [ "analytics" ] } }, "/api/v1/analytics/compute-daily": { "post": { "description": "Evaluate all streaks and badges for the calling user.", "operationId": "computeDaily", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ComputeDailyResponse" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Compute Daily", "tags": [ "analytics" ] } }, "/api/v1/analytics/defense/kpis": { "get": { "operationId": "getDefenseKpis", "parameters": [ { "in": "query", "name": "window", "required": false, "schema": { "default": "30d", "title": "Window", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DefenseKpiResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Defense-effectiveness KPIs (Λ + counterweight, τ, minutes saved, spend)", "tags": [ "analytics" ], "x-mcp-skip": true } }, "/api/v1/analytics/defense/leaderboard": { "get": { "operationId": "getDefenseLeaderboard", "parameters": [ { "in": "query", "name": "window", "required": false, "schema": { "default": "30d", "title": "Window", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LeaderboardResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Opt-in aggregate Λ/minutes-saved of other opted-in members", "tags": [ "analytics" ], "x-mcp-skip": true } }, "/api/v1/analytics/defense/leaderboard/opt-in": { "post": { "operationId": "setDefenseLeaderboardOptIn", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OptInRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Setdefenseleaderboardoptin", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Opt in/out of leaderboard-lite (default OFF, revocable)", "tags": [ "analytics" ], "x-mcp-skip": true } }, "/api/v1/analytics/email/behavior": { "get": { "description": "Return aggregated behavior metrics for the time range.", "operationId": "getEmailBehavior", "parameters": [ { "description": "Time range preset", "in": "query", "name": "range", "required": false, "schema": { "default": "30d", "description": "Time range preset", "title": "Range", "type": "string" } }, { "description": "Start date for custom range", "in": "query", "name": "start", "required": false, "schema": { "anyOf": [ { "format": "date", "type": "string" }, { "type": "null" } ], "description": "Start date for custom range", "title": "Start" } }, { "description": "End date for custom range", "in": "query", "name": "end", "required": false, "schema": { "anyOf": [ { "format": "date", "type": "string" }, { "type": "null" } ], "description": "End date for custom range", "title": "End" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailBehaviorResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Email Behavior", "tags": [ "analytics" ] } }, "/api/v1/analytics/email/categories": { "get": { "description": "Return category breakdown for received emails in the time range.", "operationId": "getEmailCategories", "parameters": [ { "description": "Time range preset", "in": "query", "name": "range", "required": false, "schema": { "default": "30d", "description": "Time range preset", "title": "Range", "type": "string" } }, { "description": "Start date for custom range", "in": "query", "name": "start", "required": false, "schema": { "anyOf": [ { "format": "date", "type": "string" }, { "type": "null" } ], "description": "Start date for custom range", "title": "Start" } }, { "description": "End date for custom range", "in": "query", "name": "end", "required": false, "schema": { "anyOf": [ { "format": "date", "type": "string" }, { "type": "null" } ], "description": "End date for custom range", "title": "End" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/EmailCategoryCount" }, "title": "Response Getemailcategories", "type": "array" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Email Categories", "tags": [ "analytics" ] } }, "/api/v1/analytics/email/contact-by-address": { "get": { "description": "Return bilateral analytics for an email address.\n\nResolves the address to a contact when one exists (then aggregates across\nall of that contact's addresses), otherwise computes analytics for the\nsingle address. Always returns a response — analytics are reported even\nwhen no contact record exists (newsletters, noreply senders, etc.).", "operationId": "getContactAnalyticsByAddress", "parameters": [ { "description": "Email address to analyze", "in": "query", "name": "address", "required": true, "schema": { "description": "Email address to analyze", "title": "Address", "type": "string" } }, { "description": "Time range preset", "in": "query", "name": "range", "required": false, "schema": { "default": "30d", "description": "Time range preset", "title": "Range", "type": "string" } }, { "description": "Start date for custom range", "in": "query", "name": "start", "required": false, "schema": { "anyOf": [ { "format": "date", "type": "string" }, { "type": "null" } ], "description": "Start date for custom range", "title": "Start" } }, { "description": "End date for custom range", "in": "query", "name": "end", "required": false, "schema": { "anyOf": [ { "format": "date", "type": "string" }, { "type": "null" } ], "description": "End date for custom range", "title": "End" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactAnalyticsResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Contact Analytics By Address", "tags": [ "analytics" ] } }, "/api/v1/analytics/email/contact/{contact_id}": { "get": { "description": "Return bilateral analytics for a specific contact.\n\nResolves all email addresses associated with the contact and aggregates\nanalytics across all of them. Returns data_quality=\"limited\" when total\nemail count is less than 5.", "operationId": "getContactAnalytics", "parameters": [ { "description": "Typed ID with prefix 'C'", "in": "path", "name": "contact_id", "required": true, "schema": { "description": "Typed ID with prefix 'C'", "title": "Contact Id", "type": "string" } }, { "description": "Time range preset", "in": "query", "name": "range", "required": false, "schema": { "default": "30d", "description": "Time range preset", "title": "Range", "type": "string" } }, { "description": "Start date for custom range", "in": "query", "name": "start", "required": false, "schema": { "anyOf": [ { "format": "date", "type": "string" }, { "type": "null" } ], "description": "Start date for custom range", "title": "Start" } }, { "description": "End date for custom range", "in": "query", "name": "end", "required": false, "schema": { "anyOf": [ { "format": "date", "type": "string" }, { "type": "null" } ], "description": "End date for custom range", "title": "End" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactAnalyticsResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Contact Analytics", "tags": [ "analytics" ] } }, "/api/v1/analytics/email/heatmap": { "get": { "description": "Return 7x24 activity heatmap grid.", "operationId": "getEmailHeatmap", "parameters": [ { "description": "Time range preset", "in": "query", "name": "range", "required": false, "schema": { "default": "30d", "description": "Time range preset", "title": "Range", "type": "string" } }, { "description": "Start date for custom range", "in": "query", "name": "start", "required": false, "schema": { "anyOf": [ { "format": "date", "type": "string" }, { "type": "null" } ], "description": "Start date for custom range", "title": "Start" } }, { "description": "End date for custom range", "in": "query", "name": "end", "required": false, "schema": { "anyOf": [ { "format": "date", "type": "string" }, { "type": "null" } ], "description": "End date for custom range", "title": "End" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/HeatmapCell" }, "title": "Response Getemailheatmap", "type": "array" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Email Heatmap", "tags": [ "analytics" ] } }, "/api/v1/analytics/email/inbox-composition": { "get": { "description": "Return inbox split composition for received emails.", "operationId": "getInboxComposition", "parameters": [ { "description": "Time range preset", "in": "query", "name": "range", "required": false, "schema": { "default": "30d", "description": "Time range preset", "title": "Range", "type": "string" } }, { "description": "Start date for custom range", "in": "query", "name": "start", "required": false, "schema": { "anyOf": [ { "format": "date", "type": "string" }, { "type": "null" } ], "description": "Start date for custom range", "title": "Start" } }, { "description": "End date for custom range", "in": "query", "name": "end", "required": false, "schema": { "anyOf": [ { "format": "date", "type": "string" }, { "type": "null" } ], "description": "End date for custom range", "title": "End" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/InboxCompositionSlice" }, "title": "Response Getinboxcomposition", "type": "array" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Inbox Composition", "tags": [ "analytics" ] } }, "/api/v1/analytics/email/response-times": { "get": { "description": "Return response time statistics and distributions.", "operationId": "getEmailResponseTimes", "parameters": [ { "description": "Time range preset", "in": "query", "name": "range", "required": false, "schema": { "default": "30d", "description": "Time range preset", "title": "Range", "type": "string" } }, { "description": "Start date for custom range", "in": "query", "name": "start", "required": false, "schema": { "anyOf": [ { "format": "date", "type": "string" }, { "type": "null" } ], "description": "Start date for custom range", "title": "Start" } }, { "description": "End date for custom range", "in": "query", "name": "end", "required": false, "schema": { "anyOf": [ { "format": "date", "type": "string" }, { "type": "null" } ], "description": "End date for custom range", "title": "End" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponseTimesResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Email Response Times", "tags": [ "analytics" ] } }, "/api/v1/analytics/email/summary": { "get": { "description": "Return high-level email statistics for the time range.", "operationId": "getEmailSummary", "parameters": [ { "description": "Time range preset", "in": "query", "name": "range", "required": false, "schema": { "default": "30d", "description": "Time range preset", "title": "Range", "type": "string" } }, { "description": "Start date for custom range", "in": "query", "name": "start", "required": false, "schema": { "anyOf": [ { "format": "date", "type": "string" }, { "type": "null" } ], "description": "Start date for custom range", "title": "Start" } }, { "description": "End date for custom range", "in": "query", "name": "end", "required": false, "schema": { "anyOf": [ { "format": "date", "type": "string" }, { "type": "null" } ], "description": "End date for custom range", "title": "End" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailSummaryResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Email Summary", "tags": [ "analytics" ] } }, "/api/v1/analytics/email/top-contacts": { "get": { "description": "Return ranked contacts by email frequency with trend indicator.", "operationId": "getTopContacts", "parameters": [ { "description": "Time range preset", "in": "query", "name": "range", "required": false, "schema": { "default": "30d", "description": "Time range preset", "title": "Range", "type": "string" } }, { "description": "Start date for custom range", "in": "query", "name": "start", "required": false, "schema": { "anyOf": [ { "format": "date", "type": "string" }, { "type": "null" } ], "description": "Start date for custom range", "title": "Start" } }, { "description": "End date for custom range", "in": "query", "name": "end", "required": false, "schema": { "anyOf": [ { "format": "date", "type": "string" }, { "type": "null" } ], "description": "End date for custom range", "title": "End" } }, { "description": "Max contacts to return", "in": "query", "name": "limit", "required": false, "schema": { "default": 20, "description": "Max contacts to return", "maximum": 100, "minimum": 1, "title": "Limit", "type": "integer" } }, { "description": "Filter: received, sent, or both", "in": "query", "name": "direction", "required": false, "schema": { "default": "both", "description": "Filter: received, sent, or both", "title": "Direction", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/TopContact" }, "title": "Response Gettopcontacts", "type": "array" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Top Contacts", "tags": [ "analytics" ] } }, "/api/v1/analytics/email/volume": { "get": { "description": "Return time-series volume data with category and split breakdowns.", "operationId": "getEmailVolume", "parameters": [ { "description": "Time range preset", "in": "query", "name": "range", "required": false, "schema": { "default": "30d", "description": "Time range preset", "title": "Range", "type": "string" } }, { "description": "Start date for custom range", "in": "query", "name": "start", "required": false, "schema": { "anyOf": [ { "format": "date", "type": "string" }, { "type": "null" } ], "description": "Start date for custom range", "title": "Start" } }, { "description": "End date for custom range", "in": "query", "name": "end", "required": false, "schema": { "anyOf": [ { "format": "date", "type": "string" }, { "type": "null" } ], "description": "End date for custom range", "title": "End" } }, { "description": "Grouping: day, week, or month", "in": "query", "name": "group_by", "required": false, "schema": { "default": "day", "description": "Grouping: day, week, or month", "title": "Group By", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/VolumePeriod" }, "title": "Response Getemailvolume", "type": "array" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Email Volume", "tags": [ "analytics" ] } }, "/api/v1/analytics/email/{email_id}/track-view": { "patch": { "description": "Record that the user opened this email for reading.\n\nWrites an event row to `email_view_events` and bumps the daily habits\ncounter. DOES NOT update `email_canonical` — that row carries the full\nsanitized HTML body (~300 KB) and is synced to every connected client\nvia PowerSync, so touching it on every email open forced a whole-row\nreplication round trip per click and pegged the client SQLite worker\nfor seconds at a time. Reopen metrics are now computed with COUNT()\nover the event log (see `behavior_queries.compute_reopen_metrics`).", "operationId": "trackEmailView", "parameters": [ { "in": "path", "name": "email_id", "required": true, "schema": { "format": "uuid", "title": "Email Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrackViewResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Track Email View", "tags": [ "analytics" ] } }, "/api/v1/analytics/export/csv": { "get": { "description": "Export analytics data as a downloadable CSV file.", "operationId": "exportCsv", "parameters": [ { "description": "Data category: email, calendar, tasks", "in": "query", "name": "category", "required": true, "schema": { "description": "Data category: email, calendar, tasks", "title": "Category", "type": "string" } }, { "description": "Specific dataset to export", "in": "query", "name": "subcategory", "required": true, "schema": { "description": "Specific dataset to export", "title": "Subcategory", "type": "string" } }, { "description": "Time range preset", "in": "query", "name": "range", "required": false, "schema": { "default": "30d", "description": "Time range preset", "title": "Range", "type": "string" } }, { "description": "Start date for custom range", "in": "query", "name": "start", "required": false, "schema": { "anyOf": [ { "format": "date", "type": "string" }, { "type": "null" } ], "description": "Start date for custom range", "title": "Start" } }, { "description": "End date for custom range", "in": "query", "name": "end", "required": false, "schema": { "anyOf": [ { "format": "date", "type": "string" }, { "type": "null" } ], "description": "End date for custom range", "title": "End" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Exportcsv", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Export Csv", "tags": [ "analytics", "analytics-export" ] } }, "/api/v1/analytics/export/email": { "post": { "description": "Send a formatted analytics summary email to the specified recipient.", "operationId": "exportEmail", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailExportRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailExportResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Export Email", "tags": [ "analytics", "analytics-export" ] } }, "/api/v1/analytics/gatekeeper/ledger": { "get": { "description": "Return the gatekeeper decision ledger for the caller's tenant (R6/D3).", "operationId": "getGatekeeperLedger", "parameters": [ { "description": "Trailing window in months incl. current", "in": "query", "name": "months", "required": false, "schema": { "default": 6, "description": "Trailing window in months incl. current", "maximum": 24, "minimum": 1, "title": "Months", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatekeeperLedgerResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Month-over-month gatekeeper + advisor decision ledger", "tags": [ "analytics" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/analytics/habits/log": { "post": { "description": "Record a behavioral event (inbox_open or session_end).", "operationId": "logHabitEvent", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HabitLogRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HabitLogResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Log Habit Event", "tags": [ "analytics" ] } }, "/api/v1/analytics/insights/correlations": { "get": { "description": "Return cross-domain correlations: email-to-task, meeting-to-task, overhead.", "operationId": "getCorrelations", "parameters": [ { "description": "Time range preset", "in": "query", "name": "range", "required": false, "schema": { "default": "90d", "description": "Time range preset", "title": "Range", "type": "string" } }, { "description": "Start date for custom range", "in": "query", "name": "start", "required": false, "schema": { "anyOf": [ { "format": "date", "type": "string" }, { "type": "null" } ], "description": "Start date for custom range", "title": "Start" } }, { "description": "End date for custom range", "in": "query", "name": "end", "required": false, "schema": { "anyOf": [ { "format": "date", "type": "string" }, { "type": "null" } ], "description": "End date for custom range", "title": "End" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CorrelationsResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Correlations", "tags": [ "analytics" ] } }, "/api/v1/analytics/insights/time-allocation": { "get": { "description": "Return time allocation breakdown: meeting, email, and focus hours.", "operationId": "getTimeAllocation", "parameters": [ { "description": "Time range preset", "in": "query", "name": "range", "required": false, "schema": { "default": "30d", "description": "Time range preset", "title": "Range", "type": "string" } }, { "description": "Start date for custom range", "in": "query", "name": "start", "required": false, "schema": { "anyOf": [ { "format": "date", "type": "string" }, { "type": "null" } ], "description": "Start date for custom range", "title": "Start" } }, { "description": "End date for custom range", "in": "query", "name": "end", "required": false, "schema": { "anyOf": [ { "format": "date", "type": "string" }, { "type": "null" } ], "description": "End date for custom range", "title": "End" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TimeAllocationResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Time Allocation", "tags": [ "analytics" ] } }, "/api/v1/analytics/narrative/anomalies": { "get": { "description": "List active (non-dismissed) anomaly alerts.", "operationId": "listAnomalies", "parameters": [ { "description": "Time range for anomalies (e.g. 30d, 90d)", "in": "query", "name": "range", "required": false, "schema": { "default": "30d", "description": "Time range for anomalies (e.g. 30d, 90d)", "title": "Range", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/AnomalyAlertItem" }, "title": "Response Listanomalies", "type": "array" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List Anomalies", "tags": [ "analytics" ] } }, "/api/v1/analytics/narrative/anomalies/{record_id}/dismiss": { "patch": { "description": "Dismiss an anomaly alert.", "operationId": "dismissAnomalyAlert", "parameters": [ { "in": "path", "name": "record_id", "required": true, "schema": { "title": "Record Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_service__routers__analytics__narrative__DismissResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Dismiss Anomaly Alert", "tags": [ "analytics" ] } }, "/api/v1/analytics/narrative/generate": { "post": { "description": "Generate a narrative digest for the given period via LLM.", "operationId": "generateDigest", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_service__routers__analytics__narrative__GenerateRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerateResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Generate Digest", "tags": [ "analytics" ] } }, "/api/v1/analytics/narrative/history": { "get": { "description": "List historical digest narratives, most recent first.", "operationId": "listDigestHistory", "parameters": [ { "in": "query", "name": "limit", "required": false, "schema": { "default": 12, "maximum": 100, "minimum": 1, "title": "Limit", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/DigestHistoryItem" }, "title": "Response Listdigesthistory", "type": "array" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List Digest History", "tags": [ "analytics" ] } }, "/api/v1/analytics/relationship/check": { "post": { "description": "Run relationship health check for the calling user.\n\nEvaluates all active relationship goals, detects engagement anomalies,\ngenerates alerts, sends notifications, and creates reminder activities\nfor severely overdue goals.", "operationId": "relationshipHealthCheck", "parameters": [ { "description": "When true, compute alerts without sending notifications, creating reminder tasks, or updating tracking fields.", "in": "query", "name": "preview", "required": false, "schema": { "default": false, "description": "When true, compute alerts without sending notifications, creating reminder tasks, or updating tracking fields.", "title": "Preview", "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthCheckResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Relationship Health Check", "tags": [ "analytics" ] } }, "/api/v1/analytics/relationship/goals": { "get": { "description": "List all contacts with active relationship goals and compliance status.", "operationId": "listGoals", "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/GoalListItem" }, "title": "Response Listgoals", "type": "array" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List Goals", "tags": [ "analytics" ] }, "post": { "description": "Set or update a relationship goal for a contact.", "operationId": "createOrUpdateGoal", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateGoalRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateGoalResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Create Or Update Goal", "tags": [ "analytics" ] } }, "/api/v1/analytics/relationship/goals/{contact_id}": { "delete": { "description": "Remove a relationship goal for a contact.", "operationId": "removeGoal", "parameters": [ { "in": "path", "name": "contact_id", "required": true, "schema": { "format": "uuid", "title": "Contact Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Removegoal", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Remove Goal", "tags": [ "analytics" ] }, "get": { "description": "Get goal detail and engagement history for a specific contact.", "operationId": "getGoalDetail", "parameters": [ { "in": "path", "name": "contact_id", "required": true, "schema": { "format": "uuid", "title": "Contact Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GoalDetailResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Goal Detail", "tags": [ "analytics" ] } }, "/api/v1/analytics/relationship/health": { "get": { "description": "Relationship health summary across all tracked contacts.", "operationId": "getHealthSummary", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthSummaryResponse" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Health Summary", "tags": [ "analytics" ] } }, "/api/v1/analytics/streaks": { "get": { "description": "Return active streaks for the current user.", "operationId": "getStreaks", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StreaksListResponse" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Streaks", "tags": [ "analytics" ] } }, "/api/v1/analytics/streaks/heatmap": { "get": { "description": "Return 365-day heatmap data for a specific streak type.", "operationId": "getStreakHeatmap", "parameters": [ { "description": "Streak type (e.g. inbox_zero)", "in": "query", "name": "type", "required": true, "schema": { "description": "Streak type (e.g. inbox_zero)", "title": "Type", "type": "string" } }, { "description": "Year for heatmap", "in": "query", "name": "year", "required": false, "schema": { "description": "Year for heatmap", "title": "Year", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HeatmapResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Streak Heatmap", "tags": [ "analytics" ] } }, "/api/v1/analytics/tasks/health": { "get": { "description": "Return task health metrics: overdue, stale, blocked, aging, per-project.", "operationId": "getTaskHealth", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskHealthResponse" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Task Health", "tags": [ "analytics" ] } }, "/api/v1/analytics/tasks/summary": { "get": { "description": "Return high-level task statistics for the time range.", "operationId": "getTaskSummary", "parameters": [ { "description": "Time range preset", "in": "query", "name": "range", "required": false, "schema": { "default": "30d", "description": "Time range preset", "title": "Range", "type": "string" } }, { "description": "Start date for custom range", "in": "query", "name": "start", "required": false, "schema": { "anyOf": [ { "format": "date", "type": "string" }, { "type": "null" } ], "description": "Start date for custom range", "title": "Start" } }, { "description": "End date for custom range", "in": "query", "name": "end", "required": false, "schema": { "anyOf": [ { "format": "date", "type": "string" }, { "type": "null" } ], "description": "End date for custom range", "title": "End" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskSummaryResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Task Summary", "tags": [ "analytics" ] } }, "/api/v1/analytics/tasks/velocity": { "get": { "description": "Return task velocity time-series: created, completed, net change per period.", "operationId": "getTaskVelocity", "parameters": [ { "description": "Time range preset", "in": "query", "name": "range", "required": false, "schema": { "default": "30d", "description": "Time range preset", "title": "Range", "type": "string" } }, { "description": "Start date for custom range", "in": "query", "name": "start", "required": false, "schema": { "anyOf": [ { "format": "date", "type": "string" }, { "type": "null" } ], "description": "Start date for custom range", "title": "Start" } }, { "description": "End date for custom range", "in": "query", "name": "end", "required": false, "schema": { "anyOf": [ { "format": "date", "type": "string" }, { "type": "null" } ], "description": "End date for custom range", "title": "End" } }, { "description": "Grouping: week or month", "in": "query", "name": "group_by", "required": false, "schema": { "default": "week", "description": "Grouping: week or month", "title": "Group By", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/TaskVelocityPeriod" }, "title": "Response Gettaskvelocity", "type": "array" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Task Velocity", "tags": [ "analytics" ] } }, "/api/v1/analytics/time/breakdown": { "get": { "description": "Allocation of tracked work time grouped DYNAMICALLY by `source_facet_type`\n(never a hardcoded enum — a new facet type appears as a new group).", "operationId": "getTimeAnalyticsBreakdown", "parameters": [ { "description": "Time range preset", "in": "query", "name": "range", "required": false, "schema": { "default": "30d", "description": "Time range preset", "title": "Range", "type": "string" } }, { "description": "Start date for custom range", "in": "query", "name": "start", "required": false, "schema": { "anyOf": [ { "format": "date", "type": "string" }, { "type": "null" } ], "description": "Start date for custom range", "title": "Start" } }, { "description": "End date for custom range", "in": "query", "name": "end", "required": false, "schema": { "anyOf": [ { "format": "date", "type": "string" }, { "type": "null" } ], "description": "End date for custom range", "title": "End" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/TimeBreakdownGroup" }, "title": "Response Gettimeanalyticsbreakdown", "type": "array" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Time Breakdown", "tags": [ "analytics" ] } }, "/api/v1/analytics/time/coaching": { "post": { "description": "Evaluate the canned, pattern-based time coaching rules against the\ncaller's computed metrics and return the triggered cards (why-it-matters /\ntry-this), mirroring the email insight engine.\n\nMetrics are computed server-side from `time_logs` (D5) — the caller never\nsupplies them, so the cards are grounded in real ledger data.", "operationId": "evaluateTimeCoaching", "parameters": [ { "description": "Time range preset", "in": "query", "name": "range", "required": false, "schema": { "default": "30d", "description": "Time range preset", "title": "Range", "type": "string" } }, { "description": "Start date for custom range", "in": "query", "name": "start", "required": false, "schema": { "anyOf": [ { "format": "date", "type": "string" }, { "type": "null" } ], "description": "Start date for custom range", "title": "Start" } }, { "description": "End date for custom range", "in": "query", "name": "end", "required": false, "schema": { "anyOf": [ { "format": "date", "type": "string" }, { "type": "null" } ], "description": "End date for custom range", "title": "End" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TimeCoachingResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Evaluate Time Coaching", "tags": [ "analytics" ] } }, "/api/v1/analytics/time/correlations": { "get": { "description": "Plan-vs-actual, focus-vs-task, and context-switching metrics derived from\n`time_logs`.", "operationId": "getTimeAnalyticsCorrelations", "parameters": [ { "description": "Time range preset", "in": "query", "name": "range", "required": false, "schema": { "default": "30d", "description": "Time range preset", "title": "Range", "type": "string" } }, { "description": "Start date for custom range", "in": "query", "name": "start", "required": false, "schema": { "anyOf": [ { "format": "date", "type": "string" }, { "type": "null" } ], "description": "Start date for custom range", "title": "Start" } }, { "description": "End date for custom range", "in": "query", "name": "end", "required": false, "schema": { "anyOf": [ { "format": "date", "type": "string" }, { "type": "null" } ], "description": "End date for custom range", "title": "End" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TimeCorrelationsResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Time Correlations", "tags": [ "analytics" ] } }, "/api/v1/analytics/time/heatmap": { "get": { "description": "Per-day focus buckets for a calendar year (GitHub-style heatmap). Reuses\nthe gamification `HeatmapDay` shape so S9 reuses the existing grid component.", "operationId": "getTimeAnalyticsHeatmap", "parameters": [ { "description": "Calendar year for the heatmap", "in": "query", "name": "year", "required": false, "schema": { "description": "Calendar year for the heatmap", "title": "Year", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TimeHeatmapResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Time Heatmap", "tags": [ "analytics" ] } }, "/api/v1/analytics/time/streaks": { "get": { "description": "Current + record tracking streak with forgiveness (freezes), computed\nfrom the ledger — no bespoke analytics store.", "operationId": "getTimeAnalyticsStreaks", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TimeStreakResponse" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Time Streaks", "tags": [ "analytics" ] } }, "/api/v1/analytics/time/summary": { "get": { "description": "Tracked-hours / session-count / avg-session / focus-% over the caller's\ncompleted work sessions, EXCLUDING `mode='break'` from work totals.", "operationId": "getTimeAnalyticsSummary", "parameters": [ { "description": "Time range preset (7d|30d|90d|ytd|1y|custom)", "in": "query", "name": "range", "required": false, "schema": { "default": "30d", "description": "Time range preset (7d|30d|90d|ytd|1y|custom)", "title": "Range", "type": "string" } }, { "description": "Start date for custom range", "in": "query", "name": "start", "required": false, "schema": { "anyOf": [ { "format": "date", "type": "string" }, { "type": "null" } ], "description": "Start date for custom range", "title": "Start" } }, { "description": "End date for custom range", "in": "query", "name": "end", "required": false, "schema": { "anyOf": [ { "format": "date", "type": "string" }, { "type": "null" } ], "description": "End date for custom range", "title": "End" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TimeSummaryResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Time Summary", "tags": [ "analytics" ] } }, "/api/v1/analytics/time/volume": { "get": { "description": "Tracked work time per period (the trend series). Excludes breaks.", "operationId": "getTimeAnalyticsVolume", "parameters": [ { "description": "Time range preset", "in": "query", "name": "range", "required": false, "schema": { "default": "30d", "description": "Time range preset", "title": "Range", "type": "string" } }, { "description": "Start date for custom range", "in": "query", "name": "start", "required": false, "schema": { "anyOf": [ { "format": "date", "type": "string" }, { "type": "null" } ], "description": "Start date for custom range", "title": "Start" } }, { "description": "End date for custom range", "in": "query", "name": "end", "required": false, "schema": { "anyOf": [ { "format": "date", "type": "string" }, { "type": "null" } ], "description": "End date for custom range", "title": "End" } }, { "description": "Grouping: day, week, or month", "in": "query", "name": "group_by", "required": false, "schema": { "default": "day", "description": "Grouping: day, week, or month", "title": "Group By", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/TimeVolumePeriod" }, "title": "Response Gettimeanalyticsvolume", "type": "array" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Time Volume", "tags": [ "analytics" ] } }, "/api/v1/analytics/wrapped": { "get": { "description": "Return aggregated Productivity Wrapped stats for the given period.", "operationId": "getWrapped", "parameters": [ { "description": "Period (Q1-2026 or 2026)", "in": "query", "name": "period", "required": false, "schema": { "default": "Q1-2026", "description": "Period (Q1-2026 or 2026)", "title": "Period", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WrappedResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Wrapped", "tags": [ "analytics" ] } }, "/api/v1/artifact-versions": { "get": { "description": "One artifact's version history, newest first.\n\nAuthorization is the underlying artifact's member-visible test — another\nmember's private artifact answers 403, and its version rows are further\nexcluded by the store's owner scope.", "operationId": "listArtifactVersions", "parameters": [ { "in": "query", "name": "artifact_type", "required": true, "schema": { "maxLength": 32, "minLength": 1, "title": "Artifact Type", "type": "string" } }, { "in": "query", "name": "artifact_id", "required": true, "schema": { "maxLength": 64, "minLength": 1, "title": "Artifact Id", "type": "string" } }, { "description": "'snapshot' to include bodies", "in": "query", "name": "include", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "'snapshot' to include bodies", "title": "Include" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 200, "maximum": 500, "minimum": 1, "title": "Limit", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ArtifactVersionList" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List Artifact Versions", "tags": [ "artifact-versions", "artifact-versions" ], "x-local-capability": "local", "x-mcp-skip": true, "x-mcp-skip-reason": "Builder version-history substrate: the web/desktop history sidecar reads metadata local-first and fetches snapshots for diff/restore. Not an agent capability." }, "post": { "description": "Record a version for an artifact the caller can edit.\n\n``trigger='manual'`` (a named checkpoint) is always accepted.\n``save``/``restore`` are accepted only for a local-first artifact type\n(``CLIENT_SAVE_PATH_TYPES``), whose commit the client owns; for a\nserver-saved type they are rejected, because there the version belongs\ninside the save transaction and a client row could neither be trusted nor\nkept consistent with it.", "operationId": "createArtifactVersion", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ArtifactVersionCreateRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ArtifactVersion" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Create Artifact Version", "tags": [ "artifact-versions", "artifact-versions" ], "x-local-capability": "outbox", "x-mcp-skip": true, "x-mcp-skip-reason": "Named checkpoints are a builder-UI affordance on the member's own editing session; not an agent capability." } }, "/api/v1/assistant/invoke": { "post": { "operationId": "invokeAssistantFromMcp", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssistantInvokeRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssistantInvokeResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Invoke the Tidy assistant from an MCP client", "tags": [ "assistant" ] } }, "/api/v1/assistant/turn": { "post": { "operationId": "assistantTurn", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssistantTurnRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssistantTurnResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Ask the Tidy assistant a knowledge-graph-grounded question", "tags": [ "assistant" ] } }, "/api/v1/asyncapi.json": { "get": { "description": "Returns the committed AsyncAPI 3.0 spec (webhooks, SSE, MCP notifications). F0 stubs one example event; F4 populates the full catalog. Canonical per D19.", "operationId": "getAsyncapiSpec", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Getasyncapispec", "type": "object" } } }, "description": "Successful Response" } }, "summary": "Public AsyncAPI 3.0 specification for event-driven surfaces", "tags": [ "meta", "meta" ] } }, "/api/v1/attachments": { "post": { "description": "Upload a file to the attachments bucket for use in TipTap/rich-text content. Max 25MB. Returns a /api/v1/storage/attachments/* URL that can be embedded in note bodies — the proxy enforces auth + RLS at read time (TIDY-5478). Pass `target_id` (the note, journal or comment the file will be embedded in) to make it readable by everyone who can see that document; the caller must be able to edit it (TIDY-19215; comments: TIDY-20218, author-only).", "operationId": "uploadRichTextAttachment", "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/Body_uploadRichTextAttachment" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttachmentResponse" } } }, "description": "Successful Response" }, "404": { "description": "target_id names no note/journal the caller can edit, or no comment the caller authored" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Upload a rich-text attachment", "tags": [ "attachments" ] } }, "/api/v1/attachments/{email_canonical_id}/{filename}/content": { "get": { "description": "Resolve the attachment locator from email_canonical.attachments and stream bytes through AttachmentBytesService. Accepts user JWT or internal service headers. Returns typed error bodies so the viewer can render explicit banners.", "operationId": "getAttachmentContent", "parameters": [ { "description": "Original attachment filename", "in": "path", "name": "filename", "required": true, "schema": { "description": "Original attachment filename", "title": "Filename", "type": "string" } }, { "description": "Typed ID with prefix 'E'", "in": "path", "name": "email_canonical_id", "required": true, "schema": { "description": "Typed ID with prefix 'E'", "title": "Email Canonical Id", "type": "string" } }, { "description": "Inline (preview) vs attachment download", "in": "query", "name": "inline", "required": false, "schema": { "default": true, "description": "Inline (preview) vs attachment download", "title": "Inline", "type": "boolean" } }, { "description": "Selects one of several attachments sharing this filename: the locator's provider attachment_id, or its storage_path. Omitted, the first attachment of that name is returned.", "in": "query", "name": "part", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Selects one of several attachments sharing this filename: the locator's provider attachment_id, or its storage_path. Omitted, the first attachment of that name is returned.", "title": "Part" } }, { "in": "header", "name": "X-Internal-Service", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service" } }, { "in": "header", "name": "X-Internal-Service-Key", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service-Key" } }, { "in": "header", "name": "X-Trace-Id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Getattachmentcontent", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Stream attachment bytes by email + filename", "tags": [ "emails" ] } }, "/api/v1/attachments/{email_canonical_id}/{filename}/process": { "post": { "description": "Parse and extract ONE email attachment through the docling + extraction pipeline. Canonical markdown is written back for the file viewer and any extracted entities land as pending-review items on the email. Returns 202 with the pipeline trace id. Idempotent on double-submit.", "operationId": "processEmailAttachment", "parameters": [ { "description": "Original attachment filename", "in": "path", "name": "filename", "required": true, "schema": { "description": "Original attachment filename", "title": "Filename", "type": "string" } }, { "description": "Typed ID with prefix 'E'", "in": "path", "name": "email_canonical_id", "required": true, "schema": { "description": "Typed ID with prefix 'E'", "title": "Email Canonical Id", "type": "string" } } ], "responses": { "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProcessAttachmentResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Process one email attachment on demand", "tags": [ "emails" ], "x-mcp-skip": true, "x-mcp-skip-reason": "UI-triggered pipeline dispatch (process an email attachment). Not a data CRUD surface — extracted content arrives via the normal pipeline and the file viewer reads it locally." } }, "/api/v1/attention-channels/health": { "get": { "description": "Both fan-out channels, always — a channel with no row is healthy.", "operationId": "getAttentionChannelHealth", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChannelHealthResponse" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Delivery health of the caller's SMS and email attention channels", "tags": [ "notifications", "notifications" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/attribution/events": { "post": { "description": "Public, rate-limited, validated. event_type is always 'touch' — the\nclient cannot assert conversions. A payload carrying no anonymous_id AND no\nutm_source is junk (a bare pageview with nothing to attribute) and is\ndropped with 422 rather than written.", "operationId": "recordAttributionTouch", "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TouchResponse" } } }, "description": "Successful Response" } }, "summary": "Record a first-party marketing touch (public)", "tags": [ "attribution", "attribution" ], "x-mcp-skip": true } }, "/api/v1/audit": { "get": { "operationId": "listAuditEntries", "parameters": [ { "in": "query", "name": "actor_type", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Actor Type" } }, { "in": "query", "name": "action", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Action" } }, { "in": "query", "name": "resource_type", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Resource Type" } }, { "in": "query", "name": "mcp_session_id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Mcp Session Id" } }, { "in": "query", "name": "date_from", "required": false, "schema": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Date From" } }, { "in": "query", "name": "date_to", "required": false, "schema": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Date To" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "maximum": 500, "minimum": 1, "title": "Limit", "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cursor" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_service__routers__audit__AuditListResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "List Audit", "tags": [ "audit", "audit" ] } }, "/api/v1/audit/export": { "post": { "operationId": "startAuditExport", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExportRequest" } } }, "required": true }, "responses": { "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExportJobResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Start Export", "tags": [ "audit-export", "audit-export" ] } }, "/api/v1/audit/export/{job_id}/download": { "get": { "description": "Redirect to the 7-day signed URL.\n\nWe do NOT stream the file through api-service — the signed URL is\ndirectly usable by clients (no Authorization header needed) for the\nfull 7-day TTL, so this endpoint just hands the browser/curl client\nthe URL and steps out of the way.", "operationId": "downloadAuditExport", "parameters": [ { "in": "path", "name": "job_id", "required": true, "schema": { "format": "uuid", "title": "Job Id", "type": "string" } } ], "responses": { "307": { "description": "Redirect to the signed storage URL (valid 7 days)." }, "404": { "description": "Job not found." }, "409": { "description": "Job not yet complete." }, "410": { "description": "Download URL has expired (>7 days)." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Export Job Download", "tags": [ "audit-export", "audit-export" ] } }, "/api/v1/audit/export/{job_id}/status": { "get": { "operationId": "getAuditExportStatus", "parameters": [ { "in": "path", "name": "job_id", "required": true, "schema": { "format": "uuid", "title": "Job Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExportJobStatusResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Export Job Status", "tags": [ "audit-export", "audit-export" ] } }, "/api/v1/audit/integrity/{anchor_date}": { "get": { "operationId": "getAuditIntegrityAnchor", "parameters": [ { "in": "path", "name": "anchor_date", "required": true, "schema": { "format": "date", "title": "Anchor Date", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrityResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Get Integrity", "tags": [ "audit-integrity", "audit-integrity" ] } }, "/api/v1/audit/{entry_id}": { "get": { "operationId": "getAuditEntry", "parameters": [ { "in": "path", "name": "entry_id", "required": true, "schema": { "format": "uuid", "title": "Entry Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuditEntryResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Get Audit Entry", "tags": [ "audit", "audit" ] } }, "/api/v1/auth/capture-lead": { "post": { "description": "Capture a signup lead (capture-before-block). No auth required.\n\nTIDY-12623 (R15/R16, D5): the single unified capture path for BOTH the\nemail-form no-code block and the OAuth-return block (the OAuth callback,\nTIDY-12618, POSTs here with source 'app-direct oauth'). TIDY-16884 moved it\nonto the CRM pack — `waitlist_funnel.capture_waitlist_lead`:\n\n * upserts the local `signup_leads` mirror ON CONFLICT (email) — so the\n two app-direct paths DEDUPE onto one row instead of erroring or\n double-inserting, and\n * captures the lead onto the workspace's lead facet through the pack's\n own declarative mapping, from which an `event_subscriptions` row\n delivers it to the corporate n8n `marketing_contacts` store under the\n canonical bounded retry schedule, so an n8n outage never silently\n drops a lead.\n\n`normalize_source` collapses every app-direct spelling onto the canonical\n`app_direct_signup` tag (marketing_site passes through), so the local row\nand the captured lead converge regardless of which surface captured it.", "operationId": "captureLead", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaptureLeadRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Capturelead", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Capture Lead", "tags": [ "growth" ] } }, "/api/v1/auth/cleanup-half-created-user": { "post": { "description": "Lets a user who mistyped their email at signup delete the unverified record so they can re-sign up with the correct address. Requires the user to be currently unverified — returns 409 if email_confirmed_at IS NOT NULL.", "operationId": "authCleanupHalfCreatedUser", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CleanupResponse" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Delete the current (unverified) user — for typo recovery", "tags": [ "auth-verification", "auth-verification-proxy" ] } }, "/api/v1/auth/domain-check": { "get": { "description": "Public endpoint (no auth required). Checks whether a domain has auto-join\n enabled by any tenant. Returns minimal info to avoid leaking tenant details.\n\n Used by the signup flow to detect if a user can auto-join an existing team.\n\n Related: TIDY-A-344 Section 4.1", "operationId": "domainCheck", "parameters": [ { "description": "Email domain to check (e.g. 'heirloomforge.com')", "in": "query", "name": "domain", "required": true, "schema": { "description": "Email domain to check (e.g. 'heirloomforge.com')", "title": "Domain", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DomainCheckResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Check domain auto-join availability", "tags": [ "domain-check" ] } }, "/api/v1/auth/domain-join": { "post": { "description": "Authenticated endpoint. Extracts the user's email domain from their account\n and joins them to a tenant that has auto-join enabled for that domain.\n\n Creates a person_account_memberships entry with role='Member'.\n\n Related: TIDY-A-344 Section 4.2", "operationId": "domainJoin", "parameters": [ { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DomainJoinResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Join tenant via domain auto-join", "tags": [ "domain-check" ] } }, "/api/v1/auth/guest/landing": { "get": { "operationId": "guestMagicLinkLanding", "parameters": [ { "in": "query", "name": "token", "required": true, "schema": { "maxLength": 128, "minLength": 32, "title": "Token", "type": "string" } } ], "responses": { "200": { "content": { "text/html": { "schema": { "type": "string" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Guest magic-link landing", "tags": [ "auth" ] } }, "/api/v1/auth/hooks/password-verification": { "post": { "description": "GoTrue calls this Standard-Webhooks-signed hook on every password verification. Failed attempts are tracked per account in Redis; after the configured threshold the account is locked and even a correct password is refused until the lock expires or a completed password reset or change establishes a new password scope. Requesting a reset email, following its link without setting a password, and email-link or Google sign-ins do not end the password lockout. F3 S2 / TIDY-12926; TIDY-19869.", "operationId": "handlePasswordVerificationHook", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Handlepasswordverificationhook", "type": "object" } } }, "description": "Successful Response" } }, "summary": "GoTrue password-verification attempt hook (account lockout)", "tags": [ "auth-hooks" ], "x-mcp-skip": true } }, "/api/v1/auth/hooks/signup": { "post": { "description": "Webhook endpoint triggered by Supabase Auth on user signup completion.\n\n Supabase sends this webhook when:\n 1. User completes signup form with email + password\n 2. Email verification completes (if enabled)\n 3. Account created in auth.users table\n\n Request Body (from Supabase):\n {\n \"user\": {\n \"id\": \"11111111-1111-1111-1111-111111111111\",\n \"email\": \"parent@example.com\",\n \"email_confirmed_at\": \"2025-11-08T14:30:22.123Z\"\n },\n \"type\": \"user.signup\"\n }\n\n Processing:\n 1. Extract account_id from event.user.id\n 2. Check if invitation token provided (query param or form field)\n 3. If no invitation: Create new tenant, user is owner\n 4. If invitation: Associate user with existing tenant as member\n 5. Log operation with account_id, tenant_id, trace context\n\n Response (200 OK):\n {\n \"status\": \"success\",\n \"action\": \"tenant_created|account_associated\",\n \"tenant_id\": \"a1b2c3d4-e5f6-4789-abcd-ef1234567890\"\n }\n\n Error Responses:\n - 400 Bad Request: Invalid request body\n - 401 Unauthorized: Invalid webhook signature\n - 500 Internal Server Error: Tenant creation/association failed\n\n Related: FR-010, AC-001, AC-002, KCC-1117, T027", "operationId": "handleSignupWebhook", "parameters": [ { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } }, { "in": "header", "name": "X-Webhook-Signature", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Webhook-Signature" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Handlesignupwebhook", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Supabase Auth signup webhook", "tags": [ "auth-hooks" ] } }, "/api/v1/auth/human-check": { "post": { "description": "TIDY-20213 F2. An account that signed up through Google or Microsoft never passed the signup form's Turnstile widget; it passes this one before /tenants/provision will create its workspace. Bootstrap surface: accepts the Supabase session bearer, like /tenants/provision. Refuses a throwaway mailbox (422 disposable_email), a failed challenge (403 human_check_failed), and a client address or network over its daily new-account budget (429 new_account_limit_*). Idempotent.", "operationId": "passSignupHumanCheck", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HumanCheckRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HumanCheckResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Record a new account's human check before its workspace is created", "tags": [ "provisioning" ], "x-mcp-skip": true } }, "/api/v1/auth/introspect": { "post": { "description": "RFC 7662 token introspection. Two auth modes accepted:\n\n1. `X-Internal-Service-Key` header — internal callers can introspect any token.\n2. `Authorization: Bearer X` where the body's `token` field equals X — RFC 7662 §2.1 client self-introspection. Lets a client check whether its own access token is currently valid without consuming the refresh.\n\nInactive/expired/revoked tokens return HTTP 200 with `{\"active\": false}`. Auth failures return 401.", "operationId": "introspectToken", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntrospectRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntrospectResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Introspect Endpoint", "tags": [ "oauth" ] } }, "/api/v1/auth/logout": { "post": { "description": "Log out the current user session.\n\n This endpoint:\n 1. Revokes the authenticated refresh family, access tokens and recent-auth grant\n 2. Records logout in the audit log\n 3. Returns 204 No Content on success\n\n Clients also clear their local session cookies.\n\n Related: 011-auth-user-onboarding Feature", "operationId": "logout", "parameters": [ { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Log out user", "tags": [ "auth" ] } }, "/api/v1/auth/me": { "get": { "description": "Returns the signed-in account and tenant represented by the current Tidy session. Chrome extension callers may authenticate with the tidy_access cookie using credentials: include.", "operationId": "getAuthMe", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthMeResponse" } } }, "description": "Successful Response" } }, "summary": "Get browser session account state", "tags": [ "auth" ] } }, "/api/v1/auth/refresh-after-verify": { "post": { "description": "Re-runs /auth/session/exchange to mint a fresh Tidy bearer whose `verified` claim reflects the current `auth.users.email_confirmed_at`. Used by the `/auth/callback` magic-link flow after the verification click flips the user's email_confirmed_at. The verify-otp path (see S6) re-mints inline; this endpoint is the escape hatch for flows that complete out-of-band.\n\nOn the pre-verification allowlist (require_verified bypasses this path) so a verified=false bearer can call it. Rate-limited per minute to absorb retries without becoming a brute-force surface.", "operationId": "refreshAfterVerify", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RefreshAfterVerifyRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExchangeSessionResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Re-exchange after email verification — picks up new email_confirmed_at", "tags": [ "auth" ] } }, "/api/v1/auth/resend-verification": { "post": { "description": "Bearer-optional (TIDY-17663). With a pre-verification bearer the TIDY-17444 subject/email binding applies; without one the address is the only input and the response is uniform whether or not it names an unconfirmed account. Rate limits: 1 per 22s, 10 per 24h per address. Returns 410 if the address is blocklisted (hard bounce or complaint).", "operationId": "authResendVerification", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResendVerificationRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResendOkResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Resend signup verification email", "tags": [ "auth-verification", "auth-verification-proxy" ] } }, "/api/v1/auth/resume-decision": { "post": { "description": "Server-to-server audit sink for the web resume route's branch decision: operator → platform chain; customer/invite/onboarding → the caller's tenant chain. A customer session cannot mint the operator branch — that requires a tenantless typ=admin bearer. Pre-verification and tenantless invite bearers still audit on the platform plane.", "operationId": "recordResumeDecision", "parameters": [ { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResumeDecisionRequest" } } }, "required": true }, "responses": { "204": { "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Record an /auth/resume branch decision (TIDY-17596)", "tags": [ "auth" ], "x-mcp-skip": true, "x-mcp-skip-reason": "Auth-lifecycle audit sink driven by the web server resume route; never agent-callable." } }, "/api/v1/auth/resume-verification": { "post": { "description": "Login recovery: unconfirmed + correct password → bootstrap cookie.", "operationId": "authResumeVerification", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResumeVerificationRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignupResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Re-issue the pre-verification bootstrap for an unconfirmed account", "tags": [ "auth-verification", "auth-verification-proxy" ] } }, "/api/v1/auth/revoke": { "post": { "description": "RFC 7009: revoke access, refresh, PAT, or service account token.\n\nAccepts form-encoded (spec-compliant) or JSON body.\nAlways returns 200, even if the token doesn't exist.", "operationId": "revokeToken", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_service__routers__oauth_admin__RevokeResponse" } } }, "description": "Successful Response" } }, "summary": "Revoke Endpoint", "tags": [ "oauth" ] } }, "/api/v1/auth/scopes": { "get": { "description": "The complete scope catalog + bundles, generated from the canonical enum. Consent screens and PAT-creation UIs render from this — never from a hand-maintained list.", "operationId": "getScopeCatalog", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScopeCatalogResponse" } } }, "description": "Successful Response" } }, "summary": "Canonical OAuth scope catalog", "tags": [ "auth" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/auth/service/exchange": { "post": { "description": "Mint a 5-minute ``typ=delegated`` ES256 bearer for the named user.\n\nCaller authenticates with SA credentials via Basic auth. See module\ndocstring for the full auth model.", "operationId": "serviceAccountDelegatedExchange", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExchangeRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExchangeResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Service Account Delegated Exchange", "tags": [ "auth", "auth" ] } }, "/api/v1/auth/session": { "get": { "description": "Get information about the current authenticated session.\n\n Returns:\n {\n \"account_id\": \"uuid\",\n \"is_authenticated\": true\n }\n\n Useful for debugging authentication issues.", "operationId": "getSessionInfo", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Getsessioninfo", "type": "object" } } }, "description": "Successful Response" } }, "summary": "Get current session info", "tags": [ "auth" ] } }, "/api/v1/auth/session/exchange": { "post": { "description": "Server-side bridge. Validates the Supabase session JWT with explicit issuer + audience + exp checks (JWKS when configured; HS256 fallback otherwise — never the signature-only legacy helper). On success, mints a Tidy-native access + refresh token pair bound to `resource` (RFC 8707). Used by `hooks.server.ts` on first request after sign-in so every subsequent browser request carries a Tidy JWT with full tenant_id, typ=session, env=prod claims and hooks into revocation + family rotation.\n\nScopes on the returned Tidy JWT are drawn from the F0 scope catalog bundle for the user's tenant role. Capability-based authorization (create_pat, admin_members, etc.) is enforced by require_capability() per endpoint — they are never embedded in the `scope` claim.", "operationId": "exchangeSupabaseSession", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExchangeSessionRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExchangeSessionResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Exchange Supabase session JWT for Tidy JWT (TIDY-7238)", "tags": [ "auth" ] } }, "/api/v1/auth/sign-in-event": { "post": { "description": "Log a sign-in event for the audit trail.\n\n This endpoint should be called after successful authentication to record\n the sign-in in the audit log. It captures:\n - Authentication provider (google, azure, email)\n - Success/failure status\n - IP address and user agent (from request headers)\n\n Also used to log failed sign-in attempts for security monitoring.\n\n Related: 011-auth-user-onboarding T031", "operationId": "logSignInEvent", "parameters": [ { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignInEventRequest" } } }, "required": true }, "responses": { "204": { "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Log sign-in event", "tags": [ "auth" ] } }, "/api/v1/auth/signup": { "post": { "description": "Tidy-owned signup endpoint. Calls GoTrue `POST /auth/v1/signup` (NOT the admin endpoint). With `GOTRUE_MAILER_AUTOCONFIRM=false` this creates an unconfirmed `auth.users` row and fires the `send_email_hook`, which the notification service uses to dispatch the verification OTP / magic-link.\n\nReturns a limited Tidy bearer (`verified=false`) so the verify page can call the pre-verification allowlist endpoints (resend-verification, verify-otp, cleanup-half-created-user) without re-authenticating. Tenantless signups receive the access-only `tidy_access` + `tidy_expires_at` cookies; accounts that already have a tenant also receive `tidy_refresh`.\n\nThe hard-wall middleware (TIDY-9373) gates protected `/api/v1/*` paths on `verified=true`, so an unverified bearer cannot reach any application route until `/auth/verify-otp` succeeds.\n\nRate limits: 5 signups per email per 24h, 10 signups per IP per 1h.", "operationId": "authSignup", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignupRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignupResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Sign up a new user via GoTrue's standard signup endpoint", "tags": [ "auth-verification", "auth-verification-proxy" ] } }, "/api/v1/auth/step-up/challenges": { "post": { "operationId": "createStepUpChallenge", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChallengeRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChallengeResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Create Challenge", "tags": [ "auth-step-up" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/auth/step-up/challenges/{challenge_id}/email-otp/send": { "post": { "operationId": "sendStepUpEmailOtp", "parameters": [ { "in": "path", "name": "challenge_id", "required": true, "schema": { "format": "uuid", "title": "Challenge Id", "type": "string" } } ], "responses": { "202": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Send Otp", "tags": [ "auth-step-up" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/auth/step-up/challenges/{challenge_id}/provider/start": { "post": { "operationId": "startStepUpProvider", "parameters": [ { "in": "path", "name": "challenge_id", "required": true, "schema": { "format": "uuid", "title": "Challenge Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Provider Start", "tags": [ "auth-step-up" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/auth/step-up/challenges/{challenge_id}/verify": { "post": { "operationId": "verifyStepUpChallenge", "parameters": [ { "in": "path", "name": "challenge_id", "required": true, "schema": { "format": "uuid", "title": "Challenge Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifyRequest" } } }, "required": true }, "responses": { "204": { "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Verify", "tags": [ "auth-step-up" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/auth/step-up/factors": { "get": { "operationId": "getStepUpFactors", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FactorsResponse" } } }, "description": "Successful Response" } }, "summary": "Factors", "tags": [ "auth-step-up" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/auth/validate-invite": { "post": { "description": "Validate an invite code without redeeming it. No auth required.", "operationId": "validateInvite", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidateInviteRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Validateinvite", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Validate Invite", "tags": [ "growth" ] } }, "/api/v1/auth/verify-otp": { "post": { "description": "Calls GoTrue's /verify on success and re-runs the Supabase→Tidy exchange to mint a fresh bearer whose `verified` claim reflects the now-flipped email_confirmed_at. Per-code wrong-attempt limit: 10 wrong codes then the GoTrue token is invalidated.\n\nBearer-optional (TIDY-17663). A pre-verification bearer keeps the TIDY-17444 subject/email binding; without one the OTP is the sole authority — the sign-in and cold-browser cases that can never hold a signup bootstrap token — bounded by a per-address hourly budget.", "operationId": "authVerifyOtp", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifyOtpRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifyOtpResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Verify the OTP and mint a verified=true Tidy bearer", "tags": [ "auth-verification", "auth-verification-proxy" ] } }, "/api/v1/automations": { "get": { "description": "R19/R20/R23 tenant list: actor, run/failure counts, status +\npaused_reason per rule, plus the tenant metering summary (used/ceiling/\nautomations_paused — the pause-on-exceed banner state). Members see\ntheir own rules; tenant admins see every rule and its actor (D9).", "operationId": "listAutomationRules", "parameters": [ { "in": "query", "name": "limit", "required": false, "schema": { "default": 200, "maximum": 500, "minimum": 1, "title": "Limit", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutomationRuleListResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List automation rules (member: own rules; tenant admin: all) + tenant usage", "tags": [ "automations", "automations" ], "x-local-capability": "local" }, "post": { "operationId": "createAutomationRule", "parameters": [ { "in": "header", "name": "X-Tidy-Acting-Principal", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tidy-Acting-Principal" } }, { "in": "header", "name": "X-Internal-Service", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service" } }, { "in": "header", "name": "X-Internal-Service-Key", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service-Key" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutomationRuleCreate" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutomationRuleResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Create an automation rule", "tags": [ "automations", "automations" ], "x-local-capability": "outbox" } }, "/api/v1/automations/assignees": { "get": { "description": "The assignee vocabulary for action params (TIDY-16717 / S2, R5).\n\nDeliberately NOT the workspace member list: that surface is admin-gated\nand human-shaped, so an agent member was invisible to a rule author and\n\"assign to CSR-1\" was not expressible at all. This returns both kinds from\none query, labelled, so the builder can offer an agent and the executor\naccepts exactly what was offered.", "operationId": "listAutomationAssignees", "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/AutomationAssignee" }, "title": "Response Listautomationassignees", "type": "array" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Principals an automation may assign work to — humans AND agents", "tags": [ "automations", "automations" ], "x-local-capability": "local", "x-mcp-skip": true, "x-mcp-skip-reason": "UI-shaped read; the automation_* MCP tools cover the rule/run surface." } }, "/api/v1/automations/assistant-asks/{continuation_id}/response": { "post": { "operationId": "ask_response_callback_api_v1_automations_assistant_asks__continuation_id__response_post", "parameters": [ { "in": "path", "name": "continuation_id", "required": true, "schema": { "title": "Continuation Id", "type": "string" } }, { "in": "header", "name": "X-Internal-Service-Key", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service-Key" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AskResponseCallback" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AskCallbackResult" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Ask Response Callback", "tags": [ "automations", "automations" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/automations/email-trigger-preview": { "post": { "description": "Replay an unsaved email trigger + conditions over the caller's recent\nmail (TIDY-16717 / S2, R5) — \"this rule would have matched 12 messages\nthis week\", shown before the rule is enabled.\n\nRead-only by construction: it runs the SAME predicate as the live lane\n(``email_context.trigger_matches_email`` plus the canonical condition\nengine) over the same snapshot shape, so the number is trustworthy rather\nthan a second approximation of the rule. An evaluation fault surfaces as a\n5xx — never a fabricated zero, which would read as \"safe\".", "operationId": "previewAutomationEmailTrigger", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailTriggerPreviewRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailTriggerPreviewResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Count the messages an email rule would have matched (R5)", "tags": [ "automations", "automations" ], "x-local-capability": "local", "x-mcp-skip": true, "x-mcp-skip-reason": "UI-shaped read; the automation_* MCP tools cover the rule/run surface." } }, "/api/v1/automations/runs": { "get": { "description": "TIDY-14803 (S14): the assistant's cross-rule verification surface —\nruns on every rule the caller may read, without naming a rule. Per-rule\nhistory stays on ``/{rule_id}/runs``.", "operationId": "listVisibleAutomationRuns", "parameters": [ { "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "maximum": 200, "minimum": 1, "title": "Limit", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/AutomationRunResponse" }, "title": "Response Listvisibleautomationruns", "type": "array" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Run history across every visible rule (newest first, bounded) — R19/S14", "tags": [ "automations", "automations" ], "x-local-capability": "local" } }, "/api/v1/automations/runs/{run_id}/retry-parked-step": { "post": { "description": "TIDY-18242 (R48): the Retry behind the ``employee_offline_for_step``\nattention item.\n\nAn Ask-employee step whose employee was offline PARKED — the run stayed\nrunning, its inbox row went needs-you, and an attention item named the\nemployee and the step. This re-executes the chain from THAT action, with\neverything before it carried in verbatim: the parked step never ran, so\nnothing repeats and nothing is skipped. Still offline is ``parked_again``\nwith the same item left open, never a silent failure.\n\nAuthorization is the run's own: the run owner, the rule's creator or its\nactor. A caller outside that set gets 404 rather than a 403 that would\nconfirm the run exists.", "operationId": "retryParkedAutomationStep", "parameters": [ { "in": "path", "name": "run_id", "required": true, "schema": { "title": "Run Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetryParkedStepResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Retry an Ask-employee step parked on an offline employee (R48)", "tags": [ "automations", "automations" ], "x-local-capability": "outbox", "x-mcp-skip": true, "x-mcp-skip-reason": "Inbox attention-item action (Retry a parked step); the automation_* MCP tools cover the rule/run surface." } }, "/api/v1/automations/system-events": { "get": { "description": "The sentence builder's \"When something happens in Tidy…\" category:\nthe curated set from the event dispatcher's constant.\n\n``email.received`` used to appear here disabled with its D7 hold. That\nhold is lifted (TIDY-16717 / S2): email is now its own trigger KIND with a\ncondition vocabulary, so it is authored through the email trigger chips\nrather than as an opaque system event, and it no longer belongs in this\ncatalog at all.\n\nTIDY-17345 (S6, D4): the SCM entries are OMITTED entirely for a tenant\nwith no source-control provider connected — not rendered disabled. A held\nevent (the D7 shape) is one Tidy has decided not to offer yet and every\ntenant sees the same answer; this one is a capability the tenant simply\ndoes not have, and advertising it would be the \"no-GitHub\" copy failure.", "operationId": "listAutomationSystemEvents", "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/SystemEventCatalogEntry" }, "title": "Response Listautomationsystemevents", "type": "array" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Curated system-event trigger catalog (R8) + held entries (D7)", "tags": [ "automations", "automations" ], "x-local-capability": "local", "x-mcp-skip": true, "x-mcp-skip-reason": "UI-shaped read; the automation_* MCP tools cover the rule/run surface." } }, "/api/v1/automations/triggers": { "get": { "description": "List the caller's chat-triggerable automations for a room.\n\nRead-only. Scoped by three-tier visibility (own + shared + global) on the\ncanonical ``workflow_scripts`` plus room membership (the room must belong to\nor be shared with the caller's tenant). Only enabled workflows are returned.", "operationId": "listChatTriggers", "parameters": [ { "description": "Trigger surface. Only 'chat' is supported.", "in": "query", "name": "surface", "required": true, "schema": { "const": "chat", "description": "Trigger surface. Only 'chat' is supported.", "title": "Surface", "type": "string" } }, { "description": "Matrix room_id for scoping.", "in": "query", "name": "room_id", "required": true, "schema": { "description": "Matrix room_id for scoping.", "maxLength": 256, "minLength": 1, "title": "Room Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatTriggerRegistryResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List Chat Triggers", "tags": [ "automations" ], "x-mcp-skip": true, "x-mcp-skip-reason": "Composer slash-menu discovery contract; not a user-data tool." } }, "/api/v1/automations/usage": { "get": { "operationId": "getAutomationUsage", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutomationUsageSummary" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Tenant automation metering summary (used/ceiling/paused) — R23", "tags": [ "automations", "automations" ], "x-local-capability": "local", "x-mcp-skip": true, "x-mcp-skip-reason": "UI-shaped read; the automation_* MCP tools cover the rule/run surface." } }, "/api/v1/automations/{rule_id}": { "delete": { "operationId": "deleteAutomationRule", "parameters": [ { "in": "path", "name": "rule_id", "required": true, "schema": { "title": "Rule Id", "type": "string" } }, { "in": "header", "name": "X-Tidy-Acting-Principal", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tidy-Acting-Principal" } }, { "in": "header", "name": "X-Internal-Service", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service" } }, { "in": "header", "name": "X-Internal-Service-Key", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service-Key" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Delete an automation rule (creator or tenant admin)", "tags": [ "automations", "automations" ], "x-local-capability": "outbox" }, "get": { "operationId": "getAutomationRule", "parameters": [ { "in": "path", "name": "rule_id", "required": true, "schema": { "title": "Rule Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutomationRuleResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get one automation rule by id", "tags": [ "automations", "automations" ], "x-local-capability": "local" }, "patch": { "operationId": "updateAutomationRule", "parameters": [ { "in": "path", "name": "rule_id", "required": true, "schema": { "title": "Rule Id", "type": "string" } }, { "in": "header", "name": "X-Tidy-Acting-Principal", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tidy-Acting-Principal" } }, { "in": "header", "name": "X-Internal-Service", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service" } }, { "in": "header", "name": "X-Internal-Service-Key", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service-Key" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutomationRuleUpdate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutomationRuleResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Update an automation rule (creator or tenant admin)", "tags": [ "automations", "automations" ], "x-local-capability": "outbox" } }, "/api/v1/automations/{rule_id}/runs": { "get": { "operationId": "listAutomationRuns", "parameters": [ { "in": "path", "name": "rule_id", "required": true, "schema": { "title": "Rule Id", "type": "string" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "maximum": 200, "minimum": 1, "title": "Limit", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/AutomationRunResponse" }, "title": "Response Listautomationruns", "type": "array" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Per-rule run history (newest first, bounded) — R19", "tags": [ "automations", "automations" ], "x-local-capability": "local" } }, "/api/v1/avatars/describe": { "post": { "operationId": "describeAvatar", "parameters": [ { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AvatarDescribeRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AvatarDescribeResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Turn a description into an avatar draft", "tags": [ "avatars", "Avatars" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Avatar-creator UI flow: the draft is shown for human review in the editor, never saved — not an agent workflow." } }, "/api/v1/avatars/portraits": { "get": { "description": "The last five accepted portraits for the entity (R4), plus the caller's\nown undecided ones.\n\nEntity-scoped for the accepted history: a portrait accepted onto a shared\ncontact belongs to the contact, so any member who can see the contact can\nsee and re-select it. Account-scoped for ``undecided``: a preview is a\nverdict its spender has not given yet — it is how a paid-for preview the\ntransport lost stays reachable (the honest-quota rule), not something to\noffer another member for acceptance.", "operationId": "listAvatarPortraits", "parameters": [ { "description": "contact | organization | record", "in": "query", "name": "entity_type", "required": true, "schema": { "description": "contact | organization | record", "title": "Entity Type", "type": "string" } }, { "description": "Typed ID (C-/O-/R-) or bare UUID", "in": "query", "name": "entity_id", "required": true, "schema": { "description": "Typed ID (C-/O-/R-) or bare UUID", "title": "Entity Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PortraitHistoryResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "An entity's retained portraits, newest first", "tags": [ "Avatar Portraits" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Avatar-creator UI flow with a per-click cloud image spend — not an agent workflow." }, "post": { "description": "One generation, one attempt — recorded now, produced in the background.\n\nReturns **202** with the pending ledger row in milliseconds; the 70-90s\nprovider call runs in a worker and the client polls\n``GET /api/v1/avatars/portraits/{id}`` (TIDY-15949 bounce — a synchronous\nrequest of provider length dies at the edge's read timeout while the server\nfinishes and spends anyway). Nothing is attached yet (R1), and nothing is\nspent unless the poll lands on ``succeeded``.", "operationId": "generateAvatarPortrait", "parameters": [ { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneratePortraitRequest" } } }, "required": true }, "responses": { "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneratePortraitResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Start generating an avatar portrait preview", "tags": [ "Avatar Portraits" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Avatar-creator UI flow with a per-click cloud image spend — not an agent workflow." } }, "/api/v1/avatars/portraits/options": { "get": { "description": "The generate panel's one call on open.\n\nPresets come from the substrate tuple rather than a second list on the\nclient: a preset that exists in the UI and not in the prompt composer is a\n500 waiting to be picked.", "operationId": "getAvatarPortraitOptions", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PortraitOptionsResponse" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Style presets and the caller's remaining portrait quota", "tags": [ "Avatar Portraits" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Avatar-creator UI flow with a per-click cloud image spend — not an agent workflow." } }, "/api/v1/avatars/portraits/{generation_id}": { "get": { "description": "The submit's other half: the client polls this until the row settles.\n\nScoped to the account that submitted (a generation id is a probe — another\nmember's id is a 404, never a 403). The quota rides along so the panel's\ncount comes from the ledger the moment the outcome lands, which is what\nmakes the \"did/did not use one of today's portraits\" sentence provable\ninstead of guessed from the transport (the bounce's false copy).", "operationId": "getAvatarPortrait", "parameters": [ { "in": "path", "name": "generation_id", "required": true, "schema": { "title": "Generation Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PortraitStatusResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Poll one generation until its outcome is terminal", "tags": [ "Avatar Portraits" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Avatar-creator UI flow with a per-click cloud image spend — not an agent workflow." } }, "/api/v1/avatars/portraits/{generation_id}/accept": { "post": { "description": "Promote the preview onto the entity, then enforce the last-5 bound (R2/R3).\n\nThe entity's ``avatar_schema`` is not read and not written on this path —\nthe portrait is an added option, not a replacement.", "operationId": "acceptAvatarPortrait", "parameters": [ { "in": "path", "name": "generation_id", "required": true, "schema": { "title": "Generation Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcceptPortraitResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Attach a portrait to its entity as a selectable photo option", "tags": [ "Avatar Portraits" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Avatar-creator UI flow with a per-click cloud image spend — not an agent workflow." } }, "/api/v1/avatars/portraits/{generation_id}/reject": { "post": { "description": "Drop the preview's bytes now instead of waiting for the 24h sweep.\n\nThe provenance row survives with ``rejected_at`` set, and the quota stays\nspent: the image WAS produced (decision 2).", "operationId": "rejectAvatarPortrait", "parameters": [ { "in": "path", "name": "generation_id", "required": true, "schema": { "title": "Generation Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RejectPortraitResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Discard a portrait preview", "tags": [ "Avatar Portraits" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Avatar-creator UI flow with a per-click cloud image spend — not an agent workflow." } }, "/api/v1/batch-runs": { "get": { "description": "The caller's runs, newest first — what the monitoring surface lists.\nA tenant admin sees the tenant's, matching the single-run read.", "operationId": "listBatchRuns", "parameters": [ { "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "maximum": 200, "minimum": 1, "title": "Limit", "type": "integer" } }, { "in": "query", "name": "offset", "required": false, "schema": { "default": 0, "minimum": 0, "title": "Offset", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchRunListResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List Batch Runs", "tags": [ "batch-runs" ], "x-local-capability": "cloud", "x-mcp-skip": true }, "post": { "description": "Create an idle run. The view and the actions are validated NOW — an\nunrunnable run is refused at authoring time, not discovered mid-drain.", "operationId": "createBatchRun", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchRunCreate" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchRunResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Create Batch Run", "tags": [ "batch-runs" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/batch-runs/preflight": { "get": { "description": "How many items a view resolves to right now, under the CALLER's\nvisibility — the count the author reviews before creating a run. An empty\naudience answers 0 rather than an error; a run over it completes with\nnothing done.", "operationId": "preflightBatchRun", "parameters": [ { "description": "Typed ID with prefix 'W' (or bare UUID during deprecation)", "in": "query", "name": "saved_view_id", "required": true, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Typed ID with prefix 'W' (or bare UUID during deprecation)", "title": "Saved View Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchRunPreflightResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Preflight Batch Run", "tags": [ "batch-runs" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/batch-runs/{run_id}": { "get": { "description": "Progress + counts. A stalled run shows it (``stalled_count``) rather\nthan looking silently dead.", "operationId": "getBatchRun", "parameters": [ { "description": "batch_runs.id", "in": "path", "name": "run_id", "required": true, "schema": { "description": "batch_runs.id", "title": "Run Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchRunResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Batch Run", "tags": [ "batch-runs" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/batch-runs/{run_id}/items": { "get": { "description": "The per-item ledger — ``?state=failed`` is the failure list.", "operationId": "listBatchRunItems", "parameters": [ { "description": "batch_runs.id", "in": "path", "name": "run_id", "required": true, "schema": { "description": "batch_runs.id", "title": "Run Id", "type": "string" } }, { "description": "Filter by item state (e.g. failed).", "in": "query", "name": "state", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by item state (e.g. failed).", "title": "State" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 100, "maximum": 500, "minimum": 1, "title": "Limit", "type": "integer" } }, { "in": "query", "name": "offset", "required": false, "schema": { "default": 0, "minimum": 0, "title": "Offset", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchRunItemsResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List Batch Run Items", "tags": [ "batch-runs" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/batch-runs/{run_id}/retry": { "post": { "description": "Re-queue ONLY the failed items and put the run back to ``running``.\nSucceeded and skipped items are never re-executed (AC5).", "operationId": "retryBatchRun", "parameters": [ { "description": "batch_runs.id", "in": "path", "name": "run_id", "required": true, "schema": { "description": "batch_runs.id", "title": "Run Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchRunResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Retry Batch Run", "tags": [ "batch-runs" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/batch-runs/{run_id}/start": { "post": { "description": "Start the run: the audience materializes and the drain picks it up.\n\nThe tenant's automation metering gate applies — a tenant at its monthly\nceiling cannot start a run that would spend past it.", "operationId": "startBatchRun", "parameters": [ { "description": "batch_runs.id", "in": "path", "name": "run_id", "required": true, "schema": { "description": "batch_runs.id", "title": "Run Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchRunResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Start Batch Run", "tags": [ "batch-runs" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/batch-runs/{run_id}/stop": { "post": { "description": "Stop the run. The drain re-checks the run's state before EVERY item, so\nthe acknowledgment is followed by no further side effects; items claimed\nbut not executed go straight back to ``pending``.", "operationId": "stopBatchRun", "parameters": [ { "description": "batch_runs.id", "in": "path", "name": "run_id", "required": true, "schema": { "description": "batch_runs.id", "title": "Run Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchRunResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Stop Batch Run", "tags": [ "batch-runs" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/beta/invite/redeem": { "post": { "description": "Validate invite code, resolve tester Gmail, add to internal-testers Group.\n\nSee module docstring for the schema contract and idempotency rules.", "operationId": "redeemBetaInvite", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BetaInviteRedeemRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BetaInviteRedeemResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Redeem Beta Invite", "tags": [ "beta-invite", "beta-invite" ] } }, "/api/v1/billing/addons/inboxes": { "post": { "description": "Set the total authorized add-on inboxes for the account.\n\nIncrease prorates; decrease uses no refund proration and is blocked (409) when\nmore inboxes are connected than the new allowance would permit.", "operationId": "setInboxAddons", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InboxAddonRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InboxAddonResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Set Inbox Addons", "tags": [ "billing", "billing" ], "x-mcp-skip": true } }, "/api/v1/billing/addons/inboxes/quote": { "get": { "description": "Quote add-on inboxes from Stripe; nothing is charged.\n\nWith a subscription, an increase previews the prorated charge Stripe adds\nto the next invoice; the owner confirms it before ``POST …/addons/inboxes``.\nWithout one, the quote is the plan line and the add-on line one Checkout\nwould carry.", "operationId": "quoteInboxAddons", "parameters": [ { "description": "Total add-on inboxes to quote.", "in": "query", "name": "quantity", "required": true, "schema": { "description": "Total add-on inboxes to quote.", "minimum": 0, "title": "Quantity", "type": "integer" } }, { "description": "Without a subscription: the plan the Checkout carries.", "in": "query", "name": "plan_id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Without a subscription: the plan the Checkout carries.", "title": "Plan Id" } }, { "description": "Without a subscription: the plan's billing interval.", "in": "query", "name": "billing_interval", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Without a subscription: the plan's billing interval.", "title": "Billing Interval" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InboxAddonQuoteResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Quote Inbox Addons", "tags": [ "billing", "billing" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/billing/cancel-scheduled-subscription": { "post": { "description": "Atomically replace a pending downgrade with period-end cancellation.\n\nThe portal cannot cancel while a schedule manages the subscription. We\nchange that schedule's sole phase to end in cancellation, rather than\nrelease it before a second, fallible Stripe mutation.", "operationId": "cancelScheduledSubscription", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelScheduledSubscriptionResponse" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Cancel Scheduled Subscription", "tags": [ "billing" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/billing/change-plan": { "post": { "description": "Change the current subscription's plan and interval.\n\nPlan changes happen in the app (owner decision 8, TIDY-19279); the Customer\nPortal keeps card updates, cancellation and invoice history. An upgrade\ntakes effect now with proration; a downgrade at period end\n(``takes_effect_at``). Choosing the current plan again drops a pending\ndowngrade. A refusal from Stripe is a typed 409 (stale link, rejected\nchange) or 502 (Stripe unavailable).", "operationId": "changePlan", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_service__routers__billing_stripe__ChangePlanRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangePlanResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Change Plan", "tags": [ "billing" ] } }, "/api/v1/billing/checkout-session": { "post": { "operationId": "createCheckoutSession", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutSessionRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutSessionResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Create Checkout Session", "tags": [ "billing" ] } }, "/api/v1/billing/checkout-session/{session_id}/sync": { "post": { "description": "Synchronously apply a completed settings Checkout Session.\n\nHosted Checkout redirects the browser back before the webhook path is\nguaranteed to run in local/dev environments. The return URL contains the\nsession id, so settings billing verifies it with Stripe and applies the\nsame domain update as the webhook consumer before rendering subscription\nstate.", "operationId": "syncCheckoutSession", "parameters": [ { "in": "path", "name": "session_id", "required": true, "schema": { "title": "Session Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Sync Checkout Session", "tags": [ "billing" ] } }, "/api/v1/billing/credits": { "get": { "description": "Current-period credit usage from the F3 credit ledger (TIDY-12057).\n\nAllocated = positive inflow (grants + top-ups) this period; remaining = the\nsigned pool balance; used = allocated − remaining. Per-feature and per-user\nbreakdowns aggregate the period's debits (the legacy per-action credit\nschema is retired).", "operationId": "getBillingCredits", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditsResponse" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Credits", "tags": [ "billing" ] } }, "/api/v1/billing/invoices": { "get": { "operationId": "getBillingInvoices", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoicesResponse" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Invoices", "tags": [ "billing" ] } }, "/api/v1/billing/portal-session": { "post": { "operationId": "createPortalSession", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PortalSessionResponse" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Create Portal Session", "tags": [ "billing" ] } }, "/api/v1/billing/resume-subscription": { "post": { "description": "Undo cancellation without recreating a superseded plan change.", "operationId": "resumeSubscription", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelScheduledSubscriptionResponse" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Resume Subscription", "tags": [ "billing" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/billing/seats": { "get": { "description": "List team members, pending invitations, and the seats they sit in.", "operationId": "listSeats", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListSeatsResponse" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List Seats", "tags": [ "billing-seats" ] }, "post": { "description": "Buy a seat at ``tier`` and send ``email`` an invitation into it.\n\nThe seat is charged first, in the transaction that records it: a declined\ncard (409 ``seat_payment_declined``) or any Stripe refusal leaves no seat\nand sends nothing. Once paid, the invitation goes out; if its email cannot\nbe delivered the seat stays paid and open (``invitation_sent`` false) to\ninvite into again.", "operationId": "buySeat", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SeatPurchaseRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SeatPurchaseResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Buy Seat", "tags": [ "billing-seats" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/billing/seats/quote": { "get": { "description": "Quote one more seat at ``tier`` from Stripe; nothing is charged.\n\nThe seat is charged now for the rest of the current billing period,\nprorated (monthly or annual), and then renews with the subscription.", "operationId": "quoteSeat", "parameters": [ { "description": "The tier of the seat to buy.", "in": "query", "name": "tier", "required": true, "schema": { "description": "The tier of the seat to buy.", "enum": [ "core", "plus", "max" ], "title": "Tier", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SeatQuoteResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Quote Seat", "tags": [ "billing-seats" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/billing/seats/{seat_id}/invitation": { "post": { "description": "Invite someone into a vacant seat. The seat is already paid: nothing is\ncharged. An Owner, Admin or Member may invite (the member invite rule).", "operationId": "inviteIntoSeat", "parameters": [ { "in": "path", "name": "seat_id", "required": true, "schema": { "format": "uuid", "title": "Seat Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SeatInviteRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SeatItem" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Invite Into Seat", "tags": [ "billing-seats" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/billing/seats/{seat_id}/remove": { "post": { "description": "Remove a vacant seat (or one holding a pending invitation, which is\nrevoked with it). The billing event: Stripe's quantity drops now, with no\nrefund for the period already paid. An occupied seat is refused (409):\nremove its member first.", "operationId": "removeBoughtSeat", "parameters": [ { "in": "path", "name": "seat_id", "required": true, "schema": { "format": "uuid", "title": "Seat Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SeatRemovalResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Remove Bought Seat", "tags": [ "billing-seats" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/billing/seats/{user_id}": { "delete": { "description": "Remove a member AND the seat they sit in (the billing event).\n\nKept for clients from before seats could be managed one by one\n(TIDY-19981); new clients remove the member, then the seat\n(``POST /billing/seats/{seat_id}/remove``).", "operationId": "removeSeat", "parameters": [ { "in": "path", "name": "user_id", "required": true, "schema": { "format": "uuid", "title": "User Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RemoveSeatResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Remove Seat", "tags": [ "billing-seats" ] } }, "/api/v1/billing/subscription": { "get": { "operationId": "getSubscription", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionResponse" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Subscription", "tags": [ "billing" ] } }, "/api/v1/billing/tiers": { "get": { "description": "Return the plan-tier ladder in feature order with the price Checkout charges.\n\nAnonymous pricing reads the deployment's Stripe mirror; for a workspace\nCheckout's tenant plane selects the same cached catalog used here.", "operationId": "listPublicBillingTiers", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlanTiersResponse" } } }, "description": "Successful Response" } }, "summary": "List the Core/Plus/Max plan-tier ladder", "tags": [ "billing", "billing" ], "x-mcp-skip": true } }, "/api/v1/billing/trial-eligibility": { "get": { "description": "Check if the current user is eligible for a free trial.", "operationId": "checkTrialEligibility", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Checktrialeligibility", "type": "object" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Check Trial Eligibility", "tags": [ "growth" ] } }, "/api/v1/booking-pages/me": { "delete": { "operationId": "deleteMyBookingPage", "responses": { "204": { "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Delete My Booking Page", "tags": [ "booking-pages", "booking-pages" ], "x-local-capability": "cloud", "x-mcp-skip": true }, "get": { "operationId": "getMyBookingPage", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingPageResponse" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get My Booking Page", "tags": [ "booking-pages", "booking-pages" ], "x-local-capability": "cloud", "x-mcp-skip": true }, "put": { "operationId": "upsertMyBookingPage", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingPageUpsert" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingPageResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Upsert My Booking Page", "tags": [ "booking-pages", "booking-pages" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/booking-pages/me/bookings": { "get": { "operationId": "listMyBookings", "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/BookingSummary" }, "title": "Response Listmybookings", "type": "array" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List My Bookings", "tags": [ "booking-pages", "booking-pages" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/browser-accounts": { "get": { "description": "The browsing accounts the caller may run, so an employee's browser tools go\nfrom an account's name to the id a session opens on (TIDY-19316).", "operationId": "listRunnableBrowserAccounts", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunnableBrowserAccountsResponse" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List Runnable Browser Accounts", "tags": [ "browser-accounts" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Browser control transport and configured actions; harness tools are a separate contract." }, "post": { "operationId": "createBrowserAccount", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrowserAccountCreateRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrowserAccountResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Create Browser Account", "tags": [ "browser-accounts" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Browser control transport and configured actions; harness tools are a separate contract." } }, "/api/v1/browser-accounts/{browser_account_id}/egress": { "delete": { "description": "Back to the workshop's own network — the owner only. Ends its open sessions.", "operationId": "clearBrowserAccountEgress", "parameters": [ { "in": "path", "name": "browser_account_id", "required": true, "schema": { "format": "uuid", "title": "Browser Account Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrowserAccountEgressResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Clear Browser Account Egress", "tags": [ "browser-accounts" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Browser control transport and configured actions; harness tools are a separate contract." }, "put": { "description": "Give the account its own network — the owner only. Ends its open sessions.", "operationId": "setBrowserAccountEgress", "parameters": [ { "in": "path", "name": "browser_account_id", "required": true, "schema": { "format": "uuid", "title": "Browser Account Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrowserAccountEgressRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrowserAccountEgressResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Set Browser Account Egress", "tags": [ "browser-accounts" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Browser control transport and configured actions; harness tools are a separate contract." } }, "/api/v1/browser-accounts/{browser_account_id}/egress-device": { "put": { "description": "Browse through one of the owner's own computers (TIDY-18934 F13) — the\nowner only, to a computer of theirs with the setting on. Ends open sessions.", "operationId": "setBrowserAccountEgressDevice", "parameters": [ { "in": "path", "name": "browser_account_id", "required": true, "schema": { "format": "uuid", "title": "Browser Account Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrowserAccountEgressDeviceRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrowserAccountEgressResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Set Browser Account Egress Device", "tags": [ "browser-accounts" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Browser control transport and configured actions; harness tools are a separate contract." } }, "/api/v1/browser-accounts/{browser_account_id}/policy": { "post": { "description": "Change the account's site policy or start page — the scope owner only (D17).", "operationId": "updateBrowserAccountPolicy", "parameters": [ { "in": "path", "name": "browser_account_id", "required": true, "schema": { "format": "uuid", "title": "Browser Account Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrowserAccountPolicyRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrowserAccountPolicyResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Update Browser Account Policy", "tags": [ "browser-accounts" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Browser control transport and configured actions; harness tools are a separate contract." } }, "/api/v1/browser-accounts/{browser_account_id}/sessions": { "get": { "description": "The account's last 50 sessions with who drove each and when (TIDY-18718 / D24):\nthe owner or a ``watch``-right member; anyone else is refused ``account_forbidden``.", "operationId": "listBrowserAccountSessions", "parameters": [ { "in": "path", "name": "browser_account_id", "required": true, "schema": { "format": "uuid", "title": "Browser Account Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrowserSessionHistoryResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List Browser Account Sessions", "tags": [ "browser-accounts" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Browser control transport and configured actions; harness tools are a separate contract." }, "post": { "operationId": "createBrowserSession", "parameters": [ { "in": "path", "name": "browser_account_id", "required": true, "schema": { "format": "uuid", "title": "Browser Account Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrowserSessionCreateRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrowserSessionResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Create Browser Session", "tags": [ "browser-accounts" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Browser control transport and configured actions; harness tools are a separate contract." } }, "/api/v1/browser-runs": { "post": { "deprecated": true, "operationId": "beginBrowserRun", "responses": { "410": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrowserRunsRetiredProblem" } } }, "description": "Successful Response" } }, "summary": "Begin browser run (retired)", "tags": [ "browser-runs" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Browser control transport and configured actions; harness tools are a separate contract." } }, "/api/v1/browser-runs/scheduled": { "post": { "deprecated": true, "operationId": "beginScheduledBrowserRun", "responses": { "410": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrowserRunsRetiredProblem" } } }, "description": "Successful Response" } }, "summary": "Begin scheduled browser run (retired)", "tags": [ "browser-runs" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Browser control transport and configured actions; harness tools are a separate contract." } }, "/api/v1/browser-runs/{run_id}/cancel": { "post": { "deprecated": true, "operationId": "cancelBrowserRun", "parameters": [ { "in": "path", "name": "run_id", "required": true, "schema": { "format": "uuid", "title": "Run Id", "type": "string" } } ], "responses": { "410": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrowserRunsRetiredProblem" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Cancel browser run (retired)", "tags": [ "browser-runs" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Browser control transport and configured actions; harness tools are a separate contract." } }, "/api/v1/browser-runs/{run_id}/checks": { "post": { "deprecated": true, "operationId": "resolveBrowserRunChecks", "parameters": [ { "in": "path", "name": "run_id", "required": true, "schema": { "format": "uuid", "title": "Run Id", "type": "string" } } ], "responses": { "410": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrowserRunsRetiredProblem" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Resolve browser run checks (retired)", "tags": [ "browser-runs" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Browser control transport and configured actions; harness tools are a separate contract." } }, "/api/v1/browser-runs/{run_id}/claim": { "post": { "deprecated": true, "operationId": "claimBrowserRun", "parameters": [ { "in": "path", "name": "run_id", "required": true, "schema": { "format": "uuid", "title": "Run Id", "type": "string" } } ], "responses": { "410": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrowserRunsRetiredProblem" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Claim browser run (retired)", "tags": [ "browser-runs" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Browser control transport and configured actions; harness tools are a separate contract." } }, "/api/v1/browser-runs/{run_id}/effect-contracts": { "post": { "deprecated": true, "operationId": "resolveBrowserEffectContracts", "parameters": [ { "in": "path", "name": "run_id", "required": true, "schema": { "format": "uuid", "title": "Run Id", "type": "string" } } ], "responses": { "410": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrowserRunsRetiredProblem" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Resolve browser effect contracts (retired)", "tags": [ "browser-runs" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Browser control transport and configured actions; harness tools are a separate contract." } }, "/api/v1/browser-runs/{run_id}/effect-reconcile": { "post": { "deprecated": true, "operationId": "resolveBrowserEffectReconciliation", "parameters": [ { "in": "path", "name": "run_id", "required": true, "schema": { "format": "uuid", "title": "Run Id", "type": "string" } } ], "responses": { "410": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrowserRunsRetiredProblem" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Resolve browser effect reconciliation (retired)", "tags": [ "browser-runs" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Browser control transport and configured actions; harness tools are a separate contract." } }, "/api/v1/browser-runs/{run_id}/effect-result": { "post": { "deprecated": true, "operationId": "recordBrowserEffectResult", "parameters": [ { "in": "path", "name": "run_id", "required": true, "schema": { "format": "uuid", "title": "Run Id", "type": "string" } } ], "responses": { "410": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrowserRunsRetiredProblem" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Record browser effect result (retired)", "tags": [ "browser-runs" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Browser control transport and configured actions; harness tools are a separate contract." } }, "/api/v1/browser-runs/{run_id}/evidence": { "delete": { "deprecated": true, "operationId": "deleteBrowserRunEvidence", "parameters": [ { "in": "path", "name": "run_id", "required": true, "schema": { "format": "uuid", "title": "Run Id", "type": "string" } } ], "responses": { "410": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrowserRunsRetiredProblem" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Delete browser run evidence (retired)", "tags": [ "browser-runs" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Browser control transport and configured actions; harness tools are a separate contract." }, "get": { "deprecated": true, "operationId": "getBrowserRunEvidence", "parameters": [ { "in": "path", "name": "run_id", "required": true, "schema": { "format": "uuid", "title": "Run Id", "type": "string" } } ], "responses": { "410": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrowserRunsRetiredProblem" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Get browser run evidence (retired)", "tags": [ "browser-runs" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Browser control transport and configured actions; harness tools are a separate contract." }, "post": { "deprecated": true, "operationId": "captureBrowserRunEvidence", "parameters": [ { "in": "path", "name": "run_id", "required": true, "schema": { "format": "uuid", "title": "Run Id", "type": "string" } } ], "responses": { "410": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrowserRunsRetiredProblem" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Capture browser run evidence (retired)", "tags": [ "browser-runs" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Browser control transport and configured actions; harness tools are a separate contract." } }, "/api/v1/browser-runs/{run_id}/prepare": { "post": { "deprecated": true, "operationId": "prepareBrowserRun", "parameters": [ { "in": "path", "name": "run_id", "required": true, "schema": { "format": "uuid", "title": "Run Id", "type": "string" } } ], "responses": { "410": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrowserRunsRetiredProblem" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Prepare browser run (retired)", "tags": [ "browser-runs" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Browser control transport and configured actions; harness tools are a separate contract." } }, "/api/v1/browser-runs/{run_id}/reconcile": { "post": { "deprecated": true, "operationId": "reconcileBrowserRun", "parameters": [ { "in": "path", "name": "run_id", "required": true, "schema": { "format": "uuid", "title": "Run Id", "type": "string" } } ], "responses": { "410": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrowserRunsRetiredProblem" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Reconcile browser run (retired)", "tags": [ "browser-runs" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Browser control transport and configured actions; harness tools are a separate contract." } }, "/api/v1/browser-runs/{run_id}/result": { "post": { "deprecated": true, "operationId": "recordBrowserRunCheckedResult", "parameters": [ { "in": "path", "name": "run_id", "required": true, "schema": { "format": "uuid", "title": "Run Id", "type": "string" } } ], "responses": { "410": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrowserRunsRetiredProblem" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Record browser run checked result (retired)", "tags": [ "browser-runs" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Browser control transport and configured actions; harness tools are a separate contract." } }, "/api/v1/browser-runs/{run_id}/resume": { "post": { "deprecated": true, "operationId": "resumeBrowserRun", "parameters": [ { "in": "path", "name": "run_id", "required": true, "schema": { "format": "uuid", "title": "Run Id", "type": "string" } } ], "responses": { "410": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrowserRunsRetiredProblem" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Resume browser run (retired)", "tags": [ "browser-runs" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Browser control transport and configured actions; harness tools are a separate contract." } }, "/api/v1/browser-runs/{run_id}/status": { "post": { "deprecated": true, "operationId": "reportBrowserRunStatus", "parameters": [ { "in": "path", "name": "run_id", "required": true, "schema": { "format": "uuid", "title": "Run Id", "type": "string" } } ], "responses": { "410": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrowserRunsRetiredProblem" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Report browser run status (retired)", "tags": [ "browser-runs" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Browser control transport and configured actions; harness tools are a separate contract." } }, "/api/v1/browser-sessions/{session_id}": { "delete": { "operationId": "closeBrowserSession", "parameters": [ { "in": "path", "name": "session_id", "required": true, "schema": { "format": "uuid", "title": "Session Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrowserSessionClosedResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Close Browser Session", "tags": [ "browser-sessions" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Browser control transport and configured actions; harness tools are a separate contract." } }, "/api/v1/browser-sessions/{session_id}/authority": { "post": { "operationId": "refreshBrowserSessionAuthority", "parameters": [ { "in": "path", "name": "session_id", "required": true, "schema": { "format": "uuid", "title": "Session Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrowserAuthorityRefreshRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrowserAuthorityResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Refresh Browser Session Authority", "tags": [ "browser-sessions" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Browser control transport and configured actions; harness tools are a separate contract." } }, "/api/v1/browser-sessions/{session_id}/egress": { "post": { "description": "The egress URL for one session, to that session's own controller.", "operationId": "readBrowserSessionEgress", "parameters": [ { "in": "path", "name": "session_id", "required": true, "schema": { "format": "uuid", "title": "Session Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrowserSessionEgressRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrowserSessionEgressResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Read Browser Session Egress", "tags": [ "browser-accounts" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Browser control transport and configured actions; harness tools are a separate contract." } }, "/api/v1/browser-sessions/{session_id}/file-transfer": { "post": { "operationId": "authorizeBrowserSessionFileTransfer", "parameters": [ { "in": "path", "name": "session_id", "required": true, "schema": { "format": "uuid", "title": "Session Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrowserSessionFileTransferRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrowserAuthorityResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Authorize Session File Transfer", "tags": [ "browser-controller" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Browser control transport and configured actions; harness tools are a separate contract." } }, "/api/v1/browser-sessions/{session_id}/mode": { "post": { "operationId": "requestBrowserSessionMode", "parameters": [ { "in": "path", "name": "session_id", "required": true, "schema": { "format": "uuid", "title": "Session Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrowserModeRequest" } } }, "required": true }, "responses": { "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrowserModeResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Request Browser Session Mode", "tags": [ "browser-sessions" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Browser control transport and configured actions; harness tools are a separate contract." } }, "/api/v1/browser-sessions/{session_id}/tickets": { "post": { "operationId": "mintBrowserSessionTicket", "parameters": [ { "in": "path", "name": "session_id", "required": true, "schema": { "format": "uuid", "title": "Session Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrowserTicketRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrowserTicketResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Mint Browser Session Ticket", "tags": [ "browser-sessions" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Browser control transport and configured actions; harness tools are a separate contract." } }, "/api/v1/browser-sessions/{session_id}/tickets/redeem": { "post": { "operationId": "redeemBrowserSessionTicket", "parameters": [ { "in": "path", "name": "session_id", "required": true, "schema": { "format": "uuid", "title": "Session Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrowserTicketRedeemRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrowserAuthorityResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Redeem Browser Session Ticket", "tags": [ "browser-sessions" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Browser control transport and configured actions; harness tools are a separate contract." } }, "/api/v1/browser-teach-sessions/{session_id}/demonstrations/{demonstration_id}/handoff": { "get": { "description": "The recipient, the words and the storyboard of a demonstration the caller taught.", "operationId": "getBrowserDemonstrationHandoff", "parameters": [ { "in": "path", "name": "session_id", "required": true, "schema": { "format": "uuid", "title": "Session Id", "type": "string" } }, { "in": "path", "name": "demonstration_id", "required": true, "schema": { "format": "uuid", "title": "Demonstration Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrowserDemonstrationHandoffResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Demonstration Handoff", "tags": [ "browser-controller" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "The teacher's own client sends the hand-off as their end-to-end encrypted chat message; no agent can send it for them." } }, "/api/v1/browser-teach-sessions/{session_id}/save": { "post": { "operationId": "saveBrowserDemonstration", "parameters": [ { "in": "path", "name": "session_id", "required": true, "schema": { "format": "uuid", "title": "Session Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrowserTeachingSaveRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrowserDemonstrationSaveResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Save Browser Demonstration", "tags": [ "browser-controller" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Browser control transport and configured actions; harness tools are a separate contract." } }, "/api/v1/browser-trails": { "post": { "description": "File one turn's browser trail. Idempotent on ``trail_id``: a retry answers 200.", "operationId": "uploadBrowserTrail", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrowserTrailUploadRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrowserTrailUploadResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Upload Browser Trail", "tags": [ "browser-trails" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Sent once per turn by the workshop connector, never by a tool." } }, "/api/v1/browser/evidence-policy": { "get": { "deprecated": true, "operationId": "getBrowserEvidencePolicy", "responses": { "410": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrowserRunsRetiredProblem" } } }, "description": "Successful Response" } }, "summary": "Get browser evidence policy (retired)", "tags": [ "browser-evidence" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Browser control transport and configured actions; harness tools are a separate contract." } }, "/api/v1/bundles": { "get": { "operationId": "listBundles", "parameters": [ { "description": "Filter by lifecycle status.", "in": "query", "name": "status", "required": false, "schema": { "anyOf": [ { "enum": [ "active", "saved", "archived" ], "type": "string" }, { "type": "null" } ], "description": "Filter by lifecycle status.", "title": "Status" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/BundleResponse" }, "title": "Response Listbundles", "type": "array" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List the caller's bundles", "tags": [ "bundles" ], "x-local-capability": "cloud", "x-mcp-skip": true }, "post": { "description": "Create a bundle and make it the active one.\n\nA new bundle IS the tray, so it archives whatever was active before — the\nsame one-active-per-owner invariant reopen enforces (R8), applied here so a\nplain create cannot leave the owner with two.", "operationId": "createBundle", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateBundleRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActivatedBundleResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Create a bundle", "tags": [ "bundles" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/bundles/from-project/{project_id}": { "post": { "description": "Materialize a transient bundle from a project's direct children.\n\nThis is the reason saved bundles can stay thin (D21): the commonest repeat\ncase is \"generate from the thing I already organized\", and answering it off\nthe project means the user never has to maintain a second named set that\nshadows it. The result is an ORDINARY active bundle — unnamed, trimmable,\ngenerated from once and then discarded or saved like any other.\n\nThe project is added as a container item and expanded by the same depth-1\nresolution every container add uses; there is no second expansion rule here\nto drift from that one.", "operationId": "createBundleFromProject", "parameters": [ { "description": "Typed ID with prefix 'P'", "in": "path", "name": "project_id", "required": true, "schema": { "description": "Typed ID with prefix 'P'", "title": "Project Id", "type": "string" } } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActivatedBundleResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Generate from this project — materialize a bundle from its members", "tags": [ "bundles" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/bundles/open-for-facet": { "post": { "description": "Focus, bind, rebind (confirmed) or create — decided under an owner lock.\n\nThis is the ONLY safe way for a `+` on an output type to reach the tray. The\ngeneric create above archives whatever was active, which is correct for an\nexplicit \"new bundle\" and catastrophic for \"open my podcast bundle\": the\nsources another device collected two minutes ago would be archived out from\nunder it. Every branch here either writes one column or writes nothing, and\nno branch touches an item.", "operationId": "openBundleForFacet", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenBundleForFacetRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenBundleForFacetResponse" } } }, "description": "Successful Response" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "`bundle_rebind_confirmation_required` — the active bundle is bound to a DIFFERENT output type; re-send with `confirm_rebind` and the exact id + revision from `current`. Or `active_bundle_changed` — the active bundle is not the one the caller observed; refresh and ask again. Both carry the caller's current active bundle summary (or null) in `current`." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Open (or bind) the active bundle for an output type", "tags": [ "bundles" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/bundles/{bundle_id}": { "delete": { "operationId": "deleteBundle", "parameters": [ { "description": "Bundle id", "in": "path", "name": "bundle_id", "required": true, "schema": { "description": "Bundle id", "format": "uuid", "title": "Bundle Id", "type": "string" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Discard a bundle", "tags": [ "bundles" ], "x-local-capability": "cloud", "x-mcp-skip": true }, "get": { "operationId": "getBundle", "parameters": [ { "description": "Bundle id", "in": "path", "name": "bundle_id", "required": true, "schema": { "description": "Bundle id", "format": "uuid", "title": "Bundle Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BundleDetailResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Read a bundle with its resolved items", "tags": [ "bundles" ], "x-local-capability": "cloud", "x-mcp-skip": true }, "patch": { "operationId": "updateBundle", "parameters": [ { "description": "Bundle id", "in": "path", "name": "bundle_id", "required": true, "schema": { "description": "Bundle id", "format": "uuid", "title": "Bundle Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateBundleRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BundleResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Rename, set instructions, rebind the output type, or save a bundle", "tags": [ "bundles" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/bundles/{bundle_id}/chat": { "post": { "description": "Answer from the bundle's sources with citations, or refuse.\n\nThe answer draws only on what is in the bundle AND still visible to the\ncaller. A question the sources do not cover is refused rather than answered\nfrom general knowledge (D12), and an answer whose claims cannot be tied\nback to a source is refused rather than returned uncited.", "operationId": "chatWithBundle", "parameters": [ { "description": "Bundle id", "in": "path", "name": "bundle_id", "required": true, "schema": { "description": "Bundle id", "format": "uuid", "title": "Bundle Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Ask a question grounded in a bundle's sources", "tags": [ "bundles" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/bundles/{bundle_id}/chat/messages": { "get": { "description": "Read a bundle conversation's turns.\n\n`conversation_id` is OPTIONAL (TIDY-15850). It used to be required, which\nmade history unreachable for the only client that really needed it: the id\nis minted server-side and returned WITH the answer, so a client that missed\nthe answer never learned the id, and the completed turn it was owed stayed\ninvisible forever. Omitting the parameter resolves the bundle's most recent\nconversation instead, and the response echoes which one that was so the\ncaller can thread its follow-ups onto it.\n\nAccess is the bundle's own owner scope (`repo.get_bundle` matches\n`tenant_id` AND `owner_id`). That is deliberately STRICTER than the\nmember-visible predicate: a bundle is private to its owner, so widening to\nthe shared/global branch would expose another member's conversation.", "operationId": "listBundleChatMessages", "parameters": [ { "description": "Bundle id", "in": "path", "name": "bundle_id", "required": true, "schema": { "description": "Bundle id", "format": "uuid", "title": "Bundle Id", "type": "string" } }, { "description": "The conversation to read. OMIT IT to read the bundle's most recent conversation — which is what a client that never received an answer must do, since the id only arrives with the answer.", "in": "query", "name": "conversation_id", "required": false, "schema": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "description": "The conversation to read. OMIT IT to read the bundle's most recent conversation — which is what a client that never received an answer must do, since the id only arrives with the answer.", "title": "Conversation Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatHistoryResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Read a bundle conversation's turns", "tags": [ "bundles" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/bundles/{bundle_id}/chat/messages/{message_id}/citation-click": { "post": { "description": "Citation click-through, the other half of R22's observability.\n\nThe marker is resolved against the STORED citations of that message, so a\nclick can only ever be recorded against a source the answer actually cited.", "operationId": "recordBundleCitationClick", "parameters": [ { "description": "Bundle id", "in": "path", "name": "bundle_id", "required": true, "schema": { "description": "Bundle id", "format": "uuid", "title": "Bundle Id", "type": "string" } }, { "description": "Chat message id", "in": "path", "name": "message_id", "required": true, "schema": { "description": "Chat message id", "format": "uuid", "title": "Message Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CitationClickRequest" } } }, "required": true }, "responses": { "204": { "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Record that a citation was opened", "tags": [ "bundles" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/bundles/{bundle_id}/estimate": { "post": { "description": "What this generation would cost, and who would be billed.\n\nRead-only and side-effect free — it creates no job and spends nothing. The\nfigure comes from the SAME code the submission cap enforces against, so the\nnumber shown here and the number enforced there cannot drift.", "operationId": "estimateGenerationCost", "parameters": [ { "description": "Bundle id", "in": "path", "name": "bundle_id", "required": true, "schema": { "description": "Bundle id", "format": "uuid", "title": "Bundle Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EstimateRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerationEstimateResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Estimate what generating from this bundle would cost", "tags": [ "generation" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/bundles/{bundle_id}/generate": { "post": { "description": "Queue a generation, or refuse with the precondition that blocks it.\n\n202 with a queued job means a producer will pick it up; the job row (and\nthis endpoint's siblings) carry it from there. Every refusal is a named\nerror — `sources_processing`, `bundle_over_cap`, `bundle_empty`,\n`not_a_generated_type`, `modality_unavailable`, `tier_not_enabled` — so the\nclient can tell the user which single thing to fix.", "operationId": "generateFromBundle", "parameters": [ { "description": "Bundle id", "in": "path", "name": "bundle_id", "required": true, "schema": { "description": "Bundle id", "format": "uuid", "title": "Bundle Id", "type": "string" } }, { "in": "header", "name": "x-internal-service", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service" } }, { "in": "header", "name": "x-internal-service-key", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service-Key" } }, { "in": "header", "name": "x-tenant-id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tenant-Id" } }, { "in": "header", "name": "x-account-id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Account-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_service__routers__generation__GenerateRequest" } } }, "required": true }, "responses": { "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerationJobResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Generate an output from a bundle", "tags": [ "generation" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/bundles/{bundle_id}/generation-preview": { "get": { "description": "Resolve the bundle's bound output type against its stored override.", "operationId": "previewBundleGeneration", "parameters": [ { "description": "Bundle id", "in": "path", "name": "bundle_id", "required": true, "schema": { "description": "Bundle id", "format": "uuid", "title": "Bundle Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerationPreviewResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Preview how this bundle's instruction override will be applied", "tags": [ "bundles" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/bundles/{bundle_id}/history": { "get": { "description": "The bundle's generation history, newest first (R8).\n\nFailed and cancelled runs are part of the history — \"I tried this twice and\nit broke both times\" is exactly what the panel has to be able to show.", "operationId": "listBundleGenerationHistory", "parameters": [ { "description": "Bundle id", "in": "path", "name": "bundle_id", "required": true, "schema": { "description": "Bundle id", "format": "uuid", "title": "Bundle Id", "type": "string" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "maximum": 200, "minimum": 1, "title": "Limit", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerationJobListResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Every output ever generated from this bundle", "tags": [ "generation" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/bundles/{bundle_id}/items": { "post": { "description": "Add one source.\n\nReturns 201 with the created item, or **200 with the existing item and\n``duplicate: true``** when this primitive is already in the bundle. A 409\nwould make the client treat a benign no-op as an error (R1).\n\nAn ``external`` URL is created in ``processing`` and resolved by the\nhandler its host selects: a YouTube link by the transcript chain\n(TIDY-15704), anything else by the existing crawl path (TIDY-15703).\nEither way the chip appears at once and resolves to a titled source, or to\na NAMED failure — never to a silently empty one.", "operationId": "addBundleItem", "parameters": [ { "description": "Bundle id", "in": "path", "name": "bundle_id", "required": true, "schema": { "description": "Bundle id", "format": "uuid", "title": "Bundle Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddItemRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddItemResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Add a source to a bundle", "tags": [ "bundles" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/bundles/{bundle_id}/items/bulk": { "post": { "description": "Add every selected primitive, reporting each id's outcome.\n\nResolution is BY TYPED ID against the server's own visibility — the client\nnever needs the row locally, so a selection made on a server-driven list\nthat PowerSync has not delivered yet adds fine (R2 failure mode).\n\nOutcomes are per id and all three are ordinary: added, already in the\nbundle (``duplicate``, not an error — R1), or a named failure. Hitting the\nitem or token cap mid-selection stops the run and reports the remainder as\nfailures rather than silently trimming the selection: a bundle that quietly\nholds three of the five sources the user picked produces a generation that\nquietly used less than they asked for.", "operationId": "bulkAddBundleItems", "parameters": [ { "description": "Bundle id", "in": "path", "name": "bundle_id", "required": true, "schema": { "description": "Bundle id", "format": "uuid", "title": "Bundle Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkAddItemsRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkAddItemsResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Add a whole selection to a bundle in one request", "tags": [ "bundles" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/bundles/{bundle_id}/items/reorder": { "post": { "description": "Apply the full ordering in a single UPDATE.\n\nThe submitted list must name exactly the items currently in the bundle —\na partial list would silently leave the unnamed items at stale positions,\nwhich reads to the user as \"the drag didn't stick\".", "operationId": "reorderBundleItems", "parameters": [ { "description": "Bundle id", "in": "path", "name": "bundle_id", "required": true, "schema": { "description": "Bundle id", "format": "uuid", "title": "Bundle Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReorderItemsRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BundleDetailResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Apply a full item ordering", "tags": [ "bundles" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/bundles/{bundle_id}/items/{item_id}": { "delete": { "operationId": "removeBundleItem", "parameters": [ { "description": "Bundle id", "in": "path", "name": "bundle_id", "required": true, "schema": { "description": "Bundle id", "format": "uuid", "title": "Bundle Id", "type": "string" } }, { "description": "Bundle item id", "in": "path", "name": "item_id", "required": true, "schema": { "description": "Bundle item id", "format": "uuid", "title": "Item Id", "type": "string" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Remove an item from a bundle", "tags": [ "bundles" ], "x-local-capability": "cloud", "x-mcp-skip": true }, "patch": { "description": "A scope note tells the model what this source is *for* (\"use only the\nappendix tables\") — it is the difference between a pile of sources and a\ndeliberate instruction (R6).\n\n``excluded`` deselects a source — typically one child of a container the\nuser does not want. The row stays (no silent drops) but leaves the size\nindicator immediately, which is what makes the aggregate trustworthy enough\nto trim an over-cap bundle against.", "operationId": "updateBundleItem", "parameters": [ { "description": "Bundle id", "in": "path", "name": "bundle_id", "required": true, "schema": { "description": "Bundle id", "format": "uuid", "title": "Bundle Id", "type": "string" } }, { "description": "Bundle item id", "in": "path", "name": "item_id", "required": true, "schema": { "description": "Bundle item id", "format": "uuid", "title": "Item Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateItemRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BundleItemResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Set an item's scope note, position, or deselect it", "tags": [ "bundles" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/bundles/{bundle_id}/items/{item_id}/confirm-transcription": { "post": { "description": "The user's \"yes, transcribe it\" for media over the duration cap.\n\nR5 names transcription of long media as the dominant cost, so a recording\npast the cap is HELD rather than transcribed: the chip carries its duration\nand the estimate, and nothing is spent until this endpoint is called. Only\nan item actually holding for that answer is accepted — confirming anything\nelse is a 409, not a second way to kick off a transcription.\n\nAbove the documented hard ceiling there is no confirmation: the item\nalready failed ``media_too_long`` with its duration named, and re-running\nintake will refuse it again.", "operationId": "confirmBundleItemTranscription", "parameters": [ { "description": "Bundle id", "in": "path", "name": "bundle_id", "required": true, "schema": { "description": "Bundle id", "format": "uuid", "title": "Bundle Id", "type": "string" } }, { "description": "Bundle item id", "in": "path", "name": "item_id", "required": true, "schema": { "description": "Bundle item id", "format": "uuid", "title": "Item Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BundleItemResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Transcribe a recording that was held for confirmation", "tags": [ "bundles" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/bundles/{bundle_id}/reopen": { "post": { "description": "Reopen a saved bundle as the active tray.\n\nRe-resolution is not a refresh button the client can forget to press: six\nweeks of drift is exactly the state a saved bundle comes back in, and\ngenerating from stale membership is the silent-drop failure R1 forbids.", "operationId": "reopenBundle", "parameters": [ { "description": "Bundle id", "in": "path", "name": "bundle_id", "required": true, "schema": { "description": "Bundle id", "format": "uuid", "title": "Bundle Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActivatedBundleResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Make a saved bundle the active one and re-resolve it", "tags": [ "bundles" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/bundles/{bundle_id}/resolve": { "post": { "description": "Re-run resolution over every item and return the reviewable working set.\n\nEvery source is re-checked against the caller's CURRENT visibility — access\nlost since the add makes the item ``unavailable`` / ``access_denied``, not\nabsent — and every container is re-expanded to depth 1. Nothing is dropped:\nan item that cannot contribute keeps its row, its last-known title, and a\nnamed ``failure_code`` so the tray can say WHICH source fell out and why.", "operationId": "resolveBundle", "parameters": [ { "description": "Bundle id", "in": "path", "name": "bundle_id", "required": true, "schema": { "description": "Bundle id", "format": "uuid", "title": "Bundle Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BundleDetailResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Re-resolve a bundle against the caller's current visibility", "tags": [ "bundles" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/byo-inference": { "get": { "operationId": "getByoInferenceConfig", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ByoConfigsResponse" } } }, "description": "Successful Response" } }, "summary": "Get Byo Inference Config", "tags": [ "byo-inference", "byo-inference" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Tenant-admin settings surface (S5 web UI); not an agent tool." } }, "/api/v1/byo-inference/{capability}": { "put": { "operationId": "putByoInferenceConfig", "parameters": [ { "in": "path", "name": "capability", "required": true, "schema": { "enum": [ "text", "image", "tts", "stt", "video", "embedding" ], "title": "Capability", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ByoConfigPutRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ByoCapabilityConfigResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Put Byo Inference Config", "tags": [ "byo-inference", "byo-inference" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Tenant-admin settings surface (S5 web UI); not an agent tool." } }, "/api/v1/byo-inference/{capability}/test": { "post": { "operationId": "testByoInferenceConfig", "parameters": [ { "in": "path", "name": "capability", "required": true, "schema": { "enum": [ "text", "image", "tts", "stt", "video", "embedding" ], "title": "Capability", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ByoTestResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Test Byo Inference Config", "tags": [ "byo-inference", "byo-inference" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Tenant-admin settings surface (S5 web UI); not an agent tool." } }, "/api/v1/calendar/collections": { "get": { "description": "List calendar collections (calendars) for the tenant.\n\nTIDY-5994: When writable=true, returns only collections linked to a\nwrite-enabled calendar_source_configs entry (provider calendars that\naccept outbound event pushes).", "operationId": "listCollections", "parameters": [ { "description": "Include hidden collections", "in": "query", "name": "include_hidden", "required": false, "schema": { "default": false, "description": "Include hidden collections", "title": "Include Hidden", "type": "boolean" } }, { "description": "Filter to writable provider collections only", "in": "query", "name": "writable", "required": false, "schema": { "default": false, "description": "Filter to writable provider collections only", "title": "Writable", "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/CalendarCollection" }, "title": "Response Listcollections", "type": "array" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List calendar collections", "tags": [ "calendar", "Calendar Collections" ] }, "post": { "description": "Create new calendar collection (calendar).", "operationId": "createCollection", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CalendarCollectionCreate" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CalendarCollection" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Create calendar collection", "tags": [ "calendar", "Calendar Collections" ] } }, "/api/v1/calendar/collections/custom": { "post": { "description": "Create a custom calendar source collection.\n\nCustom collections are user-defined, source_type='custom', and may define\nboth a default facet slug and an alternate date pivot field.", "operationId": "createCustomCollection", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomCalendarCollectionCreate" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CalendarCollection" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Create custom calendar source", "tags": [ "calendar", "Calendar Collections" ] } }, "/api/v1/calendar/collections/{collection_id}": { "delete": { "description": "Soft delete calendar collection (must be empty).", "operationId": "deleteCollection", "parameters": [ { "in": "path", "name": "collection_id", "required": true, "schema": { "title": "Collection Id", "type": "string" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Delete calendar collection", "tags": [ "calendar", "Calendar Collections" ] }, "get": { "description": "Get single calendar collection by ID.", "operationId": "getCollection", "parameters": [ { "in": "path", "name": "collection_id", "required": true, "schema": { "title": "Collection Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CalendarCollection" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get collection by ID", "tags": [ "calendar", "Calendar Collections" ] }, "put": { "description": "Update existing calendar collection.", "operationId": "updateCollection", "parameters": [ { "in": "path", "name": "collection_id", "required": true, "schema": { "title": "Collection Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CalendarCollectionUpdate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CalendarCollection" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Update calendar collection", "tags": [ "calendar", "Calendar Collections" ] } }, "/api/v1/calendar/conflicts": { "get": { "description": "Every conflict currently waiting on this member, from BOTH homes.\n\nA blocked change to an existing event and a blocked create are one question\nto the member — \"what is Tidy waiting on me for\" — so they arrive as one\nlist. Entries and their resolution proposals are published exactly as\npersisted, including the truncation and horizon fields: a caller that\nrendered a bounded check as a clean one would be asserting something the\nevaluator refused to assert (R108, R110).", "operationId": "listCalendarConflictCards", "parameters": [ { "description": "Cards to return, oldest first.", "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "description": "Cards to return, oldest first.", "maximum": 50, "minimum": 1, "title": "Limit", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConflictCardListResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List open calendar conflict cards", "tags": [ "calendar" ], "x-local-capability": "cloud" } }, "/api/v1/calendar/conflicts/pending-creates/{pending_create_id}/apply": { "post": { "description": "Answer a blocked create by picking one of its own resolution proposals.\n\nThe proposal's EXACT range is re-evaluated under the current calendar and\nonly a complete, non-conflicting verdict lets the canonical create path run\n— which puts the write through the conflict ward like any other create. A\nrefusal writes NOTHING, so the card and its proposals stay exactly as they\nwere and the member can pick again.", "operationId": "applyCalendarPendingCreateResolution", "parameters": [ { "description": "The calendar_pending_create_conflicts row id.", "in": "path", "name": "pending_create_id", "required": true, "schema": { "description": "The calendar_pending_create_conflicts row id.", "title": "Pending Create Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PendingCreateApplyRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PendingCreateApplyResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Create a blocked event at one of its proposed times", "tags": [ "calendar" ], "x-local-capability": "cloud" } }, "/api/v1/calendar/conflicts/{card_id}": { "get": { "description": "One card by id — an event id, or a blocked create's row id.", "operationId": "getCalendarConflictCard", "parameters": [ { "description": "Typed ID with prefix 'V'", "in": "path", "name": "card_id", "required": true, "schema": { "description": "Typed ID with prefix 'V'", "title": "Card Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConflictCard" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Read one calendar conflict card", "tags": [ "calendar" ], "x-local-capability": "cloud" } }, "/api/v1/calendar/conflicts/{card_id}/acknowledge": { "post": { "description": "The member looked at the overlap and judged it acceptable.\n\nNothing is withdrawn and nothing on the calendar changes: the entry keeps\nits place on the card and stays enumerable from the event (P4). What\nchanges is that it now carries who said it was fine, when, and how — so the\nsurfaces whose job is to interrupt stop counting it.", "operationId": "acknowledgeCalendarConflict", "parameters": [ { "description": "Typed ID with prefix 'V'", "in": "path", "name": "card_id", "required": true, "schema": { "description": "Typed ID with prefix 'V'", "title": "Card Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConflictAcknowledgeRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConflictAcknowledgeResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Record \"Conflict's OK\" on a conflict card", "tags": [ "calendar" ], "x-local-capability": "cloud" } }, "/api/v1/calendar/conflicts/{card_id}/priority-features": { "get": { "description": "Everything the priority model needs, assembled from persisted rows.\n\nPer involved event: role (organizer/attendee/solo), attendee count,\nstanding-series flag, hours until start, and severity — plus the F9\ncomparator's deterministic verdict for each pairing (which event yields,\nthe 48h move-veto, or an honest tie). Pure assembly, no LLM (TIDY-16596,\nD-features-server-side): the calendar-conflict-manager skill consumes this\nevidence instead of re-deriving facts.", "operationId": "getCalendarConflictPriorityFeatures", "parameters": [ { "description": "Typed ID with prefix 'V'", "in": "path", "name": "card_id", "required": true, "schema": { "description": "Typed ID with prefix 'V'", "title": "Card Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConflictPriorityFeaturesResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Deterministic priority evidence for one conflict card", "tags": [ "calendar" ], "x-local-capability": "cloud" } }, "/api/v1/calendar/conflicts/{card_id}/unacknowledge": { "post": { "description": "Undo — the conflict goes back to demanding attention.\n\nThe acknowledgment leaves the annotation entirely; that a member once said\nit was fine stays answerable from ``calendar_conflict_source_history``.", "operationId": "unacknowledgeCalendarConflict", "parameters": [ { "description": "Typed ID with prefix 'V'", "in": "path", "name": "card_id", "required": true, "schema": { "description": "Typed ID with prefix 'V'", "title": "Card Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConflictAcknowledgeRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConflictAcknowledgeResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Reverse a conflict acknowledgment", "tags": [ "calendar" ], "x-local-capability": "cloud" } }, "/api/v1/calendar/conflicts/{source_proposal_id}/dismiss": { "post": { "description": "Withdraw one entry without applying anything.\n\nRETIRED as a member-facing action (TIDY-16593, D-dismiss-retired). \"Dismiss\"\nreads as avoiding the decision rather than making one, and it HID the\nconflict; the affirmative, reversible answer is `/acknowledge` above. Web no\nlonger calls this route — it remains only so a client shipped before the\nchange is not left without a working button.\n\nDismissal is an answer, not a deletion: the withdrawal is appended to\n``calendar_conflict_source_history`` before the entry leaves the card, so\n\"this was raised and the member said no\" stays answerable. Idempotent — an\nentry already gone reports the current version rather than 404ing.", "operationId": "dismissCalendarConflict", "parameters": [ { "description": "The conflict entry's source_proposal_id.", "in": "path", "name": "source_proposal_id", "required": true, "schema": { "description": "The conflict entry's source_proposal_id.", "title": "Source Proposal Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConflictDismissRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConflictDismissResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Dismiss one conflict entry", "tags": [ "calendar" ], "x-local-capability": "cloud" } }, "/api/v1/calendar/events": { "get": { "description": "List calendar events with optional filters.\n\n**Search (KCC-3659):** Uses PostgreSQL full-text search on summary (highest weight),\ndescription, and location fields. Search terms are combined with AND semantics.", "operationId": "listEvents", "parameters": [ { "in": "query", "name": "start_date", "required": false, "schema": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Start Date" } }, { "in": "query", "name": "end_date", "required": false, "schema": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "End Date" } }, { "description": "Date-only lower bound (YYYY-MM-DD): from the start of that day in your timezone — an employee's owner's. Instead of start_date.", "in": "query", "name": "start_day", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Date-only lower bound (YYYY-MM-DD): from the start of that day in your timezone — an employee's owner's. Instead of start_date.", "title": "Start Day" } }, { "description": "Date-only upper bound (YYYY-MM-DD): through the end of that day in your timezone — an employee's owner's. Instead of end_date.", "in": "query", "name": "end_day", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Date-only upper bound (YYYY-MM-DD): through the end of that day in your timezone — an employee's owner's. Instead of end_date.", "title": "End Day" } }, { "in": "query", "name": "event_type", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Event Type" } }, { "in": "query", "name": "location", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Location" } }, { "description": "Comma-separated approval states to list: approved, pending_review, rejected, cancelled. `approved,pending_review` is what the calendar shows — the events on it and the ones awaiting the member's approval.", "in": "query", "name": "approval_status", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": "approved", "description": "Comma-separated approval states to list: approved, pending_review, rejected, cancelled. `approved,pending_review` is what the calendar shows — the events on it and the ones awaiting the member's approval.", "title": "Approval Status" } }, { "description": "Full-text search on summary, description, location", "in": "query", "name": "search", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Full-text search on summary, description, location", "title": "Search" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 100, "maximum": 5000, "minimum": 1, "title": "Limit", "type": "integer" } }, { "in": "query", "name": "offset", "required": false, "schema": { "default": 0, "minimum": 0, "title": "Offset", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Listevents", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List calendar events", "tags": [ "calendar" ] }, "post": { "description": "Create new calendar event.\n\nTIDY-5994: If collection_id resolves to a write-enabled provider collection,\nthe event is also pushed to the provider and external linkage is established.\n\nTIDY-11426 / S1: OBO-aware. A delegated create (``X-Tidy-On-Behalf-Of``\nnaming a principal with an active ``read_write`` calendar grant) attributes\n``owner_id`` to the principal and writes a ``delegation.obo_write`` audit\nrow in the same transaction as the event create. Without an active grant the\nswap falls back to the caller, the event is owned by the caller, and NO\ndelegation audit row is written. The owner-attribution path (D3) also fixes\nthe manual ``owner_id=NULL`` orphan. An omitted ``visibility`` follows the\nevent's container: shared in a shared calendar or project, otherwise\nprivate to the owner (TIDY-20003/20007).", "operationId": "createEvent", "parameters": [ { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CalendarEventCreate" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CalendarEvent" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Create calendar event", "tags": [ "calendar" ] } }, "/api/v1/calendar/events/alternatives": { "post": { "description": "Propose at most five conflict-free times for a candidate event.\n\nSuggestions only — this endpoint writes nothing and never reschedules\n(R109). Ranking is deterministic and the search is bounded, so the same\nrequest returns the same five proposals; ``alternatives_truncated`` says\nwhether more existed beyond them. A proposal generated from a partially\nevaluated series carries ``not_evaluated_beyond`` and has to clear\n``/events/alternatives/recheck`` before it can be applied (R110).", "operationId": "generateEventAlternatives", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AlternativesRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AlternativesResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Suggest alternative times for a conflicting event", "tags": [ "calendar" ], "x-local-capability": "cloud" } }, "/api/v1/calendar/events/alternatives/recheck": { "post": { "description": "The gate an alternative has to pass before it may be written.\n\nA proposal is a snapshot of a past evaluation, and a truncated evaluation\nadmits it could not see the whole series. So acceptance re-evaluates THIS\nproposal's exact range under the current watermark: a conflict, a truncation\nor a range mismatch returns ``apply_allowed=false`` with the reason, and the\nmutation must not proceed (R109, R110).", "operationId": "recheckEventAlternative", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AlternativeRecheckRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AlternativeRecheckResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Re-check one proposed alternative before applying it", "tags": [ "calendar" ], "x-local-capability": "cloud" } }, "/api/v1/calendar/events/batch": { "post": { "description": "Create multiple events in a single request.", "operationId": "batchCreateEvents", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchCreateRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchCreateResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Batch create events", "tags": [ "calendar" ] } }, "/api/v1/calendar/events/bulk-review": { "post": { "description": "Approve or reject many pending calendar_events in one request (TIDY-13541).\n\nPer-item processing — one item's failure does not roll back others. Each\nitem routes through the same shared ``review_calendar_event`` service\nfunction the single endpoints use, so behavior is identical, and each uses\neach member's own default destination. A non-visible or foreign-tenant id\nlands in ``failed[]`` with an error string; the remaining items still\nsucceed. Already-reviewed but visible events are idempotent successes\n(mirrors the single-endpoint semantics).\n\nThis handler opens NO outer transaction (TIDY-17980): every item gets its\nown connection, so an item's conflict-runner transaction commits or rolls\nback entirely on its own before the next item is attempted. ``results``\ncarries exactly one ordered, typed outcome per submitted id.", "operationId": "bulkReviewCalendarEvents", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkEventReviewRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkEventReviewResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Bulk approve or reject calendar events pending review", "tags": [ "calendar" ] } }, "/api/v1/calendar/events/check-conflicts": { "post": { "description": "Check for time conflicts with existing events.\n\nWraps the same shared evaluator (`kcc_common.calendar.conflicts`) that every\nmutation path runs before it writes, so a preview here and the ward that\nactually blocks a write can never disagree. The original overlap contract is\npreserved verbatim; the extended kinds, recurrence expansion and truncation\nreporting are additive (TIDY-15403).", "operationId": "checkConflicts", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConflictCheckRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConflictCheckResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Check for conflicting events", "tags": [ "calendar" ] } }, "/api/v1/calendar/events/{event_id}": { "delete": { "description": "Soft delete calendar event.\n\nTIDY-20052: a virtual employee's delete of an event that has not ended and\nstarts within 48 hours answers 409 until its owner approves it on a card,\nwhile the member's Calendar setting asks for that (default on).\n\nTIDY-5994: If the event has external linkage (synced from provider),\nthe delete is also pushed to the provider.\n\nTIDY-11426 / S1: OBO-aware. The member-visible predicate runs under\n``write_ctx.caller_param_account_id`` (delegator when granted, else caller),\nand a delegated delete writes one ``delegation.obo_write`` audit row.", "operationId": "deleteEvent", "parameters": [ { "description": "Typed ID with prefix 'V'", "in": "path", "name": "event_id", "required": true, "schema": { "description": "Typed ID with prefix 'V'", "title": "Event Id", "type": "string" } }, { "description": "Email source to send cancellation from", "in": "query", "name": "email_source_id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Email source to send cancellation from", "title": "Email Source Id" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Delete calendar event", "tags": [ "calendar" ] }, "get": { "description": "Get single calendar event by ID.", "operationId": "getEvent", "parameters": [ { "description": "Typed ID with prefix 'V'", "in": "path", "name": "event_id", "required": true, "schema": { "description": "Typed ID with prefix 'V'", "title": "Event Id", "type": "string" } }, { "description": "Include source mapping details for reconciliation diagnostics", "in": "query", "name": "include_source_mappings", "required": false, "schema": { "default": true, "description": "Include source mapping details for reconciliation diagnostics", "title": "Include Source Mappings", "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CalendarEvent" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get event by ID", "tags": [ "calendar" ] }, "patch": { "description": "PATCH endpoint — partial update; mirrors PUT and is the surface\nthe frontend VisibilityToggle calls (TIDY-10113).\n\nTIDY-11426 / S1: OBO-aware (same contract as PUT). The member-visible\npredicate runs under ``write_ctx.caller_param_account_id``.\n\nTIDY-11427 / S2: ``scope`` selects the recurring-series edit semantics.\n``scope='all'`` keeps the existing whole-series behavior; ``scope='this'``\nand ``scope='future'`` route through ``calendar_recurrence_ops`` and require\n``occurrence_start``.", "operationId": "updateEventPatch", "parameters": [ { "description": "Typed ID with prefix 'V'", "in": "path", "name": "event_id", "required": true, "schema": { "description": "Typed ID with prefix 'V'", "title": "Event Id", "type": "string" } }, { "description": "Send ICS UPDATE to attendees when notification-worthy fields change. Defaults false (TIDY-17470): a field save never emails attendees; the organizer must confirm via Send updates.", "in": "query", "name": "notify_attendees", "required": false, "schema": { "default": false, "description": "Send ICS UPDATE to attendees when notification-worthy fields change. Defaults false (TIDY-17470): a field save never emails attendees; the organizer must confirm via Send updates.", "title": "Notify Attendees", "type": "boolean" } }, { "description": "Email source to send notifications from", "in": "query", "name": "email_source_id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Email source to send notifications from", "title": "Email Source Id" } }, { "description": "Recurring-series edit scope (TIDY-11427): 'all' edits the whole series (default), 'this' edits only the occurrence at occurrence_start, 'future' edits this and all later occurrences.", "in": "query", "name": "scope", "required": false, "schema": { "default": "all", "description": "Recurring-series edit scope (TIDY-11427): 'all' edits the whole series (default), 'this' edits only the occurrence at occurrence_start, 'future' edits this and all later occurrences.", "pattern": "^(this|all|future)$", "title": "Scope", "type": "string" } }, { "description": "The original UTC start of the occurrence being edited. Required when scope != 'all' on a recurring event.", "in": "query", "name": "occurrence_start", "required": false, "schema": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "The original UTC start of the occurrence being edited. Required when scope != 'all' on a recurring event.", "title": "Occurrence Start" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CalendarEventUpdate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CalendarEvent" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Partially update calendar event", "tags": [ "calendar" ] }, "put": { "description": "Update existing calendar event.\n\nTIDY-11426 / S1: OBO-aware. The member-visible predicate runs under\n``write_ctx.caller_param_account_id`` — the delegator when an active\n``read_write`` calendar grant exists, else the caller (no leak). A delegated\nupdate writes one ``delegation.obo_write`` audit row.", "operationId": "updateEvent", "parameters": [ { "description": "Typed ID with prefix 'V'", "in": "path", "name": "event_id", "required": true, "schema": { "description": "Typed ID with prefix 'V'", "title": "Event Id", "type": "string" } }, { "description": "Send ICS UPDATE to attendees when notification-worthy fields change. Defaults false (TIDY-17470): a field save never emails attendees; the organizer must confirm via Send updates.", "in": "query", "name": "notify_attendees", "required": false, "schema": { "default": false, "description": "Send ICS UPDATE to attendees when notification-worthy fields change. Defaults false (TIDY-17470): a field save never emails attendees; the organizer must confirm via Send updates.", "title": "Notify Attendees", "type": "boolean" } }, { "description": "Email source to send notifications from", "in": "query", "name": "email_source_id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Email source to send notifications from", "title": "Email Source Id" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CalendarEventUpdate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CalendarEvent" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Update calendar event", "tags": [ "calendar" ] } }, "/api/v1/calendar/events/{event_id}/approve": { "post": { "description": "Approve a calendar_events row that is pending review.\n\nNo body — the one-click default — approves onto the member's configured\ndefault calendar (or preserves a destination the event was deliberately\nstaged for). An optional\n``{\"destination\": {\"field\": \"collection_id\", \"value\": \"<uuid>\"}}`` body is\nApprove to…: that calendar for this event only, without changing the\nmember's default (TIDY-17980).\n\nDestination, event_status, requires_review, the related pending\ncalendar_notifications and the durable provider-delivery action commit\ntogether or not at all. Only operates on events currently in status\n'pending' or 'pending_review' and not soft-deleted; an already-approved\nevent keeps its first committed destination.", "operationId": "approveCalendarEvent", "parameters": [ { "description": "Typed ID with prefix 'V'", "in": "path", "name": "event_id", "required": true, "schema": { "description": "Typed ID with prefix 'V'", "title": "Event Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/ApprovalApproveRequest" }, { "type": "null" } ], "title": "Body" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Approvecalendarevent", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Approve a calendar event pending review", "tags": [ "calendar" ] } }, "/api/v1/calendar/events/{event_id}/attachments": { "get": { "operationId": "listEventAttachments", "parameters": [ { "description": "Typed ID with prefix 'V'", "in": "path", "name": "event_id", "required": true, "schema": { "description": "Typed ID with prefix 'V'", "title": "Event Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventAttachmentListResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List attachments on a calendar event", "tags": [ "calendar", "Calendar Event Files" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Event file-attachment surface; agents use calendar endpoints." }, "post": { "operationId": "uploadEventAttachment", "parameters": [ { "description": "Typed ID with prefix 'V'", "in": "path", "name": "event_id", "required": true, "schema": { "description": "Typed ID with prefix 'V'", "title": "Event Id", "type": "string" } } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/Body_uploadEventAttachment" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventAttachmentUploadResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Upload an attachment to a calendar event", "tags": [ "calendar", "Calendar Event Files" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Multipart file upload; agents use calendar endpoints." } }, "/api/v1/calendar/events/{event_id}/attachments/from-object": { "post": { "operationId": "attachObjectToEvent", "parameters": [ { "description": "Typed ID with prefix 'V'", "in": "path", "name": "event_id", "required": true, "schema": { "description": "Typed ID with prefix 'V'", "title": "Event Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttachFromObjectRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventAttachmentUploadResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Attach a serialized Tidy object (.eml/.ics) to a calendar event", "tags": [ "calendar", "Calendar Event Files" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Server-side object serialization + attach; agents use calendar endpoints." } }, "/api/v1/calendar/events/{event_id}/attachments/{attachment_id}": { "delete": { "operationId": "removeEventAttachment", "parameters": [ { "in": "path", "name": "attachment_id", "required": true, "schema": { "title": "Attachment Id", "type": "string" } }, { "description": "Typed ID with prefix 'V'", "in": "path", "name": "event_id", "required": true, "schema": { "description": "Typed ID with prefix 'V'", "title": "Event Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventAttachmentRemoveResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Remove an attachment from a calendar event", "tags": [ "calendar", "Calendar Event Files" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Event file-attachment surface; agents use calendar endpoints." } }, "/api/v1/calendar/events/{event_id}/attendees": { "get": { "description": "List attendees for an event.", "operationId": "listAttendees", "parameters": [ { "description": "Typed ID with prefix 'V'", "in": "path", "name": "event_id", "required": true, "schema": { "description": "Typed ID with prefix 'V'", "title": "Event Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/CalendarAttendee" }, "title": "Response Listattendees", "type": "array" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List attendees", "tags": [ "calendar-attendees", "Calendar Attendees" ] }, "post": { "description": "Add attendee to an event and auto-link contact when email match exists.", "operationId": "addAttendee", "parameters": [ { "description": "Typed ID with prefix 'V'", "in": "path", "name": "event_id", "required": true, "schema": { "description": "Typed ID with prefix 'V'", "title": "Event Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddAttendeeRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CalendarAttendee" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Add attendee", "tags": [ "calendar-attendees", "Calendar Attendees" ] } }, "/api/v1/calendar/events/{event_id}/attendees/send-invites": { "post": { "description": "Send ICS REQUEST messages to all or a subset of event attendees.", "operationId": "sendInvites", "parameters": [ { "description": "Typed ID with prefix 'V'", "in": "path", "name": "event_id", "required": true, "schema": { "description": "Typed ID with prefix 'V'", "title": "Event Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendInvitesRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendInvitesResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Send invites to event attendees", "tags": [ "calendar-attendees", "Calendar Attendees" ] } }, "/api/v1/calendar/events/{event_id}/attendees/send-updates": { "post": { "description": "Send an \"Updated:\" ICS REQUEST with an incremented SEQUENCE (TIDY-14317).\n\nOnly sends when the caller's tenant organizes the event; skip reasons come\nback in `reason` instead of erroring so the UI can toast them.", "operationId": "sendEventUpdates", "parameters": [ { "description": "Typed ID with prefix 'V'", "in": "path", "name": "event_id", "required": true, "schema": { "description": "Typed ID with prefix 'V'", "title": "Event Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/SendUpdatesRequest" }, { "type": "null" } ], "title": "Payload" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendUpdatesResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Send an updated invite (bumped SEQUENCE) to all attendees", "tags": [ "calendar-attendees", "Calendar Attendees" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Explicit user-facing send action on the event page; outbound invite email is never an ambient agent workflow (same posture as sendInvites)." } }, "/api/v1/calendar/events/{event_id}/attendees/{attendee_id}": { "delete": { "description": "Delete attendee from an event.", "operationId": "deleteAttendee", "parameters": [ { "in": "path", "name": "attendee_id", "required": true, "schema": { "format": "uuid", "title": "Attendee Id", "type": "string" } }, { "description": "Typed ID with prefix 'V'", "in": "path", "name": "event_id", "required": true, "schema": { "description": "Typed ID with prefix 'V'", "title": "Event Id", "type": "string" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Delete attendee", "tags": [ "calendar-attendees", "Calendar Attendees" ] } }, "/api/v1/calendar/events/{event_id}/change-pending/approve": { "post": { "description": "Apply the stamped ``change_pending.proposed_state`` to the event and\nclear the annotation. Idempotent — a no-op when no annotation is present.\n\nRouted through the conflict ward (TIDY-15853): ``proposed_state`` may carry\na new ``dtstart``/``dtend``, so accepting one moves the event to a time\nnothing has evaluated. The candidate is built from the PROPOSED range, and a\nrefusal applies nothing — the annotation stays stamped and the member can\ndismiss it or resolve the conflict card instead.", "operationId": "approveCalendarEventChangePending", "parameters": [ { "description": "Typed ID with prefix 'V'", "in": "path", "name": "event_id", "required": true, "schema": { "description": "Typed ID with prefix 'V'", "title": "Event Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Approvecalendareventchangepending", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Approve a pending update on a calendar event", "tags": [ "calendar" ] } }, "/api/v1/calendar/events/{event_id}/change-pending/dismiss": { "post": { "description": "Clear the ``change_pending`` annotation WITHOUT applying it. Idempotent.", "operationId": "dismissCalendarEventChangePending", "parameters": [ { "description": "Typed ID with prefix 'V'", "in": "path", "name": "event_id", "required": true, "schema": { "description": "Typed ID with prefix 'V'", "title": "Event Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Dismisscalendareventchangepending", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Dismiss a pending update on a calendar event", "tags": [ "calendar" ] } }, "/api/v1/calendar/events/{event_id}/channel": { "get": { "operationId": "getMeetingChannel", "parameters": [ { "description": "Typed ID with prefix 'V'", "in": "path", "name": "event_id", "required": true, "schema": { "description": "Typed ID with prefix 'V'", "title": "Event Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MeetingChannel" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "The channel a meeting owns", "tags": [ "calendar-attendees", "Calendar Attendees" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/calendar/events/{event_id}/conflicts/{source_key}/apply": { "post": { "description": "Move the event to a proposed time, but only on a fresh, clean re-check.\n\nThe proposal is a snapshot of an evaluation that has since aged, so this\nre-evaluates its EXACT range under the current watermark and refuses on\nanything short of a complete, non-conflicting verdict (R110). A refusal\nwrites NOTHING — the card, its proposals and the source's watermark are\nuntouched, which is what makes it retryable rather than a dead end.\n\nIdempotent: a replayed apply reports ``already_resolved`` instead of moving\nthe event a second time.", "operationId": "applyCalendarConflictResolution", "parameters": [ { "description": "The conflict entry's source_proposal_id — or, during the compatibility window, the legacy source_email_id it was filed under.", "in": "path", "name": "source_key", "required": true, "schema": { "description": "The conflict entry's source_proposal_id — or, during the compatibility window, the legacy source_email_id it was filed under.", "title": "Source Key", "type": "string" } }, { "description": "Typed ID with prefix 'V'", "in": "path", "name": "event_id", "required": true, "schema": { "description": "Typed ID with prefix 'V'", "title": "Event Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConflictResolutionApplyRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConflictResolutionApplyResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Apply one resolution proposal from a conflict entry", "tags": [ "calendar" ], "x-local-capability": "cloud" } }, "/api/v1/calendar/events/{event_id}/exceptions": { "post": { "description": "Skip or reschedule a single occurrence of a recurring series (TIDY-11427).\n\n``skip`` adds the occurrence to the parent's EXDATE (no row). ``reschedule``\nadds the EXDATE and creates a standalone override event at the new time\n(``recurrence_id`` = the original occurrence start). Idempotent: repeating a\nskip does not duplicate the EXDATE entry; re-rescheduling updates the\nexisting override. An ``occurrence_start`` that is not an instance of the\nRRULE returns 422 and writes nothing.\n\nOBO-aware: the member-visible predicate runs under\n``write_ctx.caller_param_account_id`` (delegator when granted, else caller);\na delegated exception writes one ``delegation.obo_write`` audit row.", "operationId": "createCalendarException", "parameters": [ { "description": "Typed ID with prefix 'V'", "in": "path", "name": "event_id", "required": true, "schema": { "description": "Typed ID with prefix 'V'", "title": "Event Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CalendarExceptionCreate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExceptionResult" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Create a single-occurrence exception (skip / reschedule)", "tags": [ "calendar" ] } }, "/api/v1/calendar/events/{event_id}/history": { "get": { "description": "Fetch server-authored edit history for a calendar event.", "operationId": "getCalendarEventHistory", "parameters": [ { "description": "Typed ID with prefix 'V'", "in": "path", "name": "event_id", "required": true, "schema": { "description": "Typed ID with prefix 'V'", "title": "Event Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Getcalendareventhistory", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get calendar event edit history", "tags": [ "calendar" ] } }, "/api/v1/calendar/events/{event_id}/history/{change_set_id}/restore": { "post": { "description": "Restore a prior calendar event edit batch with notifications off by default.", "operationId": "restoreCalendarEventChangeSet", "parameters": [ { "in": "path", "name": "change_set_id", "required": true, "schema": { "title": "Change Set Id", "type": "string" } }, { "description": "Typed ID with prefix 'V'", "in": "path", "name": "event_id", "required": true, "schema": { "description": "Typed ID with prefix 'V'", "title": "Event Id", "type": "string" } }, { "description": "Send ICS UPDATE after restore. Defaults false so restore never silently notifies attendees.", "in": "query", "name": "notify_attendees", "required": false, "schema": { "default": false, "description": "Send ICS UPDATE after restore. Defaults false so restore never silently notifies attendees.", "title": "Notify Attendees", "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CalendarEvent" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Restore a calendar event change set", "tags": [ "calendar" ] } }, "/api/v1/calendar/events/{event_id}/ics": { "get": { "description": "Returns a standards-valid RFC 5545 VCALENDAR/VEVENT (text/calendar).", "operationId": "downloadEventIcs", "parameters": [ { "description": "Typed ID with prefix 'V'", "in": "path", "name": "event_id", "required": true, "schema": { "description": "Typed ID with prefix 'V'", "title": "Event Id", "type": "string" } } ], "responses": { "200": { "content": { "text/calendar": {} }, "description": "Single-event .ics" }, "404": { "description": "Event not found or not visible to the caller" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Download a single event as .ics", "tags": [ "calendar", "Calendar Event Files" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Binary .ics download; agents read event data via the calendar endpoints." } }, "/api/v1/calendar/events/{event_id}/messages": { "get": { "description": "Return chronological email/reply thread and linked activity primitives.\n\nTIDY-8945 (S8): the response field formerly named ``commitments`` is\nnow ``linked_activities`` — the underlying data has always come from\nthe activities table. Each id is emitted as typed ``A-<uuid>``.", "operationId": "getEventMessages", "parameters": [ { "description": "Typed ID with prefix 'V'", "in": "path", "name": "event_id", "required": true, "schema": { "description": "Typed ID with prefix 'V'", "title": "Event Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Geteventmessages", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get event-linked message thread", "tags": [ "calendar" ] } }, "/api/v1/calendar/events/{event_id}/negotiation-history": { "get": { "description": "Every hop (sent → reply → counter → settled/surfaced) oldest-first.\n\nReads the conflict source-history record that never evicts, so the trail\nstays addressable after the conflict cleared and the event settled (F3).", "operationId": "getNegotiationHistory", "parameters": [ { "description": "Typed ID with prefix 'V'", "in": "path", "name": "event_id", "required": true, "schema": { "description": "Typed ID with prefix 'V'", "title": "Event Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NegotiationHistoryResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "The async-negotiation hop trail recorded against an event", "tags": [ "Calendar Negotiations", "Calendar Negotiations" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/calendar/events/{event_id}/negotiation/cancel": { "post": { "description": "The member takes over: waiting continuations stop, and the\ncounterparty's next reply lands in plain triage like any other email.", "operationId": "cancelNegotiation", "parameters": [ { "description": "Typed ID with prefix 'V'", "in": "path", "name": "event_id", "required": true, "schema": { "description": "Typed ID with prefix 'V'", "title": "Event Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NegotiationCancelResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Stop Tidy's negotiation on this event", "tags": [ "Calendar Negotiations", "Calendar Negotiations" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/calendar/events/{event_id}/reject": { "post": { "description": "Reject a calendar_events row that is pending review.\n\nSets event_status='rejected', soft-deletes the row (deleted_at=NOW()),\nand marks related pending calendar_notifications as 'actioned'. Only\noperates on events in status 'pending' or 'pending_review'.", "operationId": "rejectCalendarEvent", "parameters": [ { "description": "Typed ID with prefix 'V'", "in": "path", "name": "event_id", "required": true, "schema": { "description": "Typed ID with prefix 'V'", "title": "Event Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Rejectcalendarevent", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Reject a calendar event pending review", "tags": [ "calendar" ] } }, "/api/v1/calendar/events/{event_id}/schedule": { "post": { "description": "Write scheduling state on a calendar_events row via semantic verbs.\n\nDispatches to CalendarEventWriter.schedule_to_week / schedule_to_day\n/ schedule_to_time / unschedule. Returns ``{changed, state}``.\n\n- ``to_week``: payload ``{monday_date: YYYY-MM-DD}``. Best-effort\n fallback — events don't have a native week state; stored as\n all-day on the target Monday.\n- ``to_day``: payload ``{date: YYYY-MM-DD, all_day?: true}``.\n ``all_day=False`` is rejected (use ``to_time``).\n- ``to_time``: payload ``{datetime: canonical UTC ISO}``. Rejects\n naive datetimes per the Tidy Time Standard.\n- ``unschedule``: returns 400 — events have no unplanned state.", "operationId": "scheduleCalendarEvent", "parameters": [ { "description": "Typed ID with prefix 'V'", "in": "path", "name": "event_id", "required": true, "schema": { "description": "Typed ID with prefix 'V'", "title": "Event Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_service__routers__calendar_schedule__ScheduleRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScheduleResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Assign calendar event to week/day/time (TIDY-7074)", "tags": [ "calendar-schedule" ] } }, "/api/v1/calendar/events/{event_id}/scheduling-role": { "get": { "description": "Resolved through the member alias index, never a raw address compare.\n\nAn invitation addressed to one of the member's send-as aliases still\nbelongs to them; comparing `organizer_email` to one configured mailbox\nmakes them a stranger on their own invite.", "operationId": "getEventSchedulingRole", "parameters": [ { "description": "Typed ID with prefix 'V'", "in": "path", "name": "event_id", "required": true, "schema": { "description": "Typed ID with prefix 'V'", "title": "Event Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SchedulingRoleResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Whether the caller organizes or merely attends this event", "tags": [ "Calendar Negotiations", "Calendar Negotiations" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/calendar/events/{event_id}/wiki-links/sync": { "post": { "description": "DELETE-then-INSERT replaces all `linked_references` rows sourced from\n wiki-link sync for the event's private Notes body (Yjs), with the provided\n set. The shared Calendar Description is synced separately on event update.\n\n `source_container_type` is `event` (collab room kind). `source_note_id`\n stays NULL.", "operationId": "syncEventWikiLinks", "parameters": [ { "description": "Event UUID", "in": "path", "name": "event_id", "required": true, "schema": { "description": "Event UUID", "title": "Event Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WikiLinkSyncRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WikiLinkSyncResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Atomically replace wiki-link rows for a calendar event", "tags": [ "links" ], "x-local-capability": "outbox", "x-mcp-skip": true } }, "/api/v1/calendar/feed": { "get": { "description": "Get or create an ICS calendar feed URL for the tenant during onboarding.", "operationId": "getOnboardingCalendarFeed", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CalendarFeedResponse" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get calendar feed URL for onboarding", "tags": [ "calendar", "Calendar Feed" ] } }, "/api/v1/calendar/ical/{subscription_token}": { "get": { "description": "Generate iCalendar (.ics) feed for subscription (PUBLIC, no auth required).\n\nThis endpoint is publicly accessible to allow calendar apps to subscribe.\nAuthentication is via the unique subscription_token (secret URL).", "operationId": "getIcalFeed", "parameters": [ { "in": "path", "name": "subscription_token", "required": true, "schema": { "title": "Subscription Token", "type": "string" } } ], "responses": { "200": { "content": { "text/plain": { "schema": { "type": "string" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Get Ical Feed", "tags": [ "calendar", "Calendar Subscriptions" ] } }, "/api/v1/calendar/meeting-agents": { "get": { "operationId": "listMeetingAgentCandidates", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MeetingAgentCandidates" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Virtual employees that can be invited to a meeting", "tags": [ "calendar-attendees", "Calendar Attendees" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/calendar/negotiations/{negotiation_id}/close": { "post": { "description": "Terminal hop + stop any still-waiting continuation of the negotiation.\n\nThe manual-settle race ends here with outcome='closed' and a note — the\ncontinuation resumed, found the event already resolved, and closes without\nmutating anything (R4.4 edge case).", "operationId": "closeNegotiation", "parameters": [ { "in": "path", "name": "negotiation_id", "required": true, "schema": { "format": "uuid", "title": "Negotiation Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CloseNegotiationRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Closenegotiation", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Close a negotiation (settled / surfaced / closed with a note)", "tags": [ "Calendar Negotiations", "Calendar Negotiations" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/calendar/notifications": { "get": { "description": "List visible calendar notifications ordered by pending-first, then newest first.", "operationId": "listCalendarNotifications", "parameters": [ { "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "maximum": 200, "minimum": 1, "title": "Limit", "type": "integer" } }, { "in": "query", "name": "offset", "required": false, "schema": { "default": 0, "minimum": 0, "title": "Offset", "type": "integer" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CalendarNotificationListResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List calendar notifications", "tags": [ "calendar", "Calendar Notifications", "Calendar Notifications" ] } }, "/api/v1/calendar/notifications/bulk-approve": { "post": { "description": "Approve every pending calendar_events row tied to an approvable pending\nnotification (types extracted_event / invite). Marks those notifications\nas 'actioned'. Non-approvable notification types (rsvp_response,\ntime_proposal, cancellation) are not touched and are reported under\nskipped_by_type.\n\nThe per-type approve semantics are intentionally narrow for bulk:\ninvites are NOT auto-replied via SMTP (that stays opt-in through the\nper-item respond flow) — we only flip the event_status to 'approved'\nso the event lands on the calendar. Users who want to send RSVP\nreplies use the per-item Accept/Decline controls.\n\nPer item, not one transaction (TIDY-15855). Every approve routes through\nthe shared ``review_calendar_event``, so this endpoint gets what the single\nand bulk-review endpoints already had: the conflict ward, and the\nmember-visible predicate. Previously it was one tenant-wide UPDATE, which\nboth bypassed the ward — bulk-approving a stack of extracted events\nstraight into overlaps — and let any member approve another member's\nprivate pending event. An event the ward refuses is counted in\n``conflicted`` and keeps its notification pending, so the card stays\nreachable from the inbox.", "operationId": "bulkApproveCalendarNotifications", "parameters": [ { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CalendarNotificationBulkApproveResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Approve all pending approvable calendar notifications", "tags": [ "calendar", "Calendar Notifications", "Calendar Notifications" ] } }, "/api/v1/calendar/notifications/bulk-dismiss": { "post": { "description": "Mark every pending calendar_notifications row for the tenant as\n'actioned' (a.k.a. \"dismissed from the inbox\"). This matches the\nsingle-row dismiss endpoint's terminal state so the Done tab shows\nwhat the user cleared.\n\nRuns in a single transaction — partial failures roll back. Idempotent:\nre-running when nothing is pending returns dismissed=0.", "operationId": "bulkDismissCalendarNotifications", "parameters": [ { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CalendarNotificationBulkDismissResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Dismiss all pending calendar notifications", "tags": [ "calendar", "Calendar Notifications", "Calendar Notifications" ] } }, "/api/v1/calendar/notifications/{notification_id}/action": { "post": { "description": "Mark a visible notification as actioned. Idempotent for terminal rows.", "operationId": "actionCalendarNotification", "parameters": [ { "in": "path", "name": "notification_id", "required": true, "schema": { "format": "uuid", "title": "Notification Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CalendarNotificationDismissResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Mark calendar notification as actioned", "tags": [ "calendar", "Calendar Notifications", "Calendar Notifications" ] } }, "/api/v1/calendar/notifications/{notification_id}/dismiss": { "post": { "description": "Dismiss a visible notification. Idempotent for terminal rows.", "operationId": "dismissCalendarNotification", "parameters": [ { "in": "path", "name": "notification_id", "required": true, "schema": { "format": "uuid", "title": "Notification Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CalendarNotificationDismissResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Dismiss calendar notification", "tags": [ "calendar", "Calendar Notifications", "Calendar Notifications" ] } }, "/api/v1/calendar/notifications/{notification_id}/read": { "post": { "description": "Mark a visible notification as read without changing its visibility window.", "operationId": "readCalendarNotification", "parameters": [ { "in": "path", "name": "notification_id", "required": true, "schema": { "format": "uuid", "title": "Notification Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CalendarNotificationDismissResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Mark calendar notification as read", "tags": [ "calendar", "Calendar Notifications", "Calendar Notifications" ] } }, "/api/v1/calendar/pending-events": { "get": { "description": "List pending events requiring review.", "operationId": "listPendingEvents", "parameters": [ { "in": "query", "name": "review_status", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Review Status" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 100, "maximum": 1000, "minimum": 1, "title": "Limit", "type": "integer" } }, { "in": "query", "name": "offset", "required": false, "schema": { "default": 0, "minimum": 0, "title": "Offset", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Listpendingevents", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List pending events", "tags": [ "calendar" ] }, "post": { "description": "Create new pending event for review.", "operationId": "createPendingEvent", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PendingEventCreate" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PendingEvent" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Create pending event", "tags": [ "calendar" ] } }, "/api/v1/calendar/pending-events/{pending_event_id}": { "get": { "description": "Get single pending event by ID.", "operationId": "getPendingEvent", "parameters": [ { "in": "path", "name": "pending_event_id", "required": true, "schema": { "title": "Pending Event Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PendingEvent" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get pending event", "tags": [ "calendar" ] }, "put": { "description": "Update pending event before approval.", "operationId": "updatePendingEvent", "parameters": [ { "in": "path", "name": "pending_event_id", "required": true, "schema": { "title": "Pending Event Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PendingEventUpdate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PendingEvent" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Update pending event", "tags": [ "calendar" ] } }, "/api/v1/calendar/pending-events/{pending_event_id}/approve": { "post": { "description": "Approve pending event and create actual calendar event.", "operationId": "approvePendingEvent", "parameters": [ { "in": "path", "name": "pending_event_id", "required": true, "schema": { "title": "Pending Event Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CalendarEvent" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Approve pending event", "tags": [ "calendar" ] } }, "/api/v1/calendar/pending-events/{pending_event_id}/reject": { "post": { "description": "Reject pending event.", "operationId": "rejectPendingEvent", "parameters": [ { "in": "path", "name": "pending_event_id", "required": true, "schema": { "title": "Pending Event Id", "type": "string" } }, { "in": "query", "name": "notes", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Notes" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Reject pending event", "tags": [ "calendar" ] } }, "/api/v1/calendar/source-configs/{config_id}": { "patch": { "description": "Patch the user's color/label override for a calendar source.\n\nBoth fields are optional — pass only the field(s) you want to change.\nEmpty string for `display_name` clears the override (falls back to\nprovider-supplied calendar_name in the UI).\n\nThe UPDATE includes IS DISTINCT FROM guards so identical writes are\nno-ops at the WAL level.", "operationId": "patchCalendarSourceConfig", "parameters": [ { "in": "path", "name": "config_id", "required": true, "schema": { "title": "Config Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CalendarSourceConfigPatch" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Patchcalendarsourceconfig", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Update calendar source config (color + display name)", "tags": [ "calendar", "Calendar Collections" ] } }, "/api/v1/calendar/sources/health": { "get": { "description": "Returns per-source connection health for the current tenant.", "operationId": "getCalendarSourcesHealth", "parameters": [ { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CalendarSourcesHealthListResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List calendar source health", "tags": [ "calendar-health" ] } }, "/api/v1/calendar/subscriptions": { "get": { "description": "List calendar subscriptions for tenant.", "operationId": "listSubscriptions", "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/CalendarSubscription" }, "title": "Response Listsubscriptions", "type": "array" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List Subscriptions", "tags": [ "calendar", "Calendar Subscriptions" ] }, "post": { "description": "Create new calendar subscription.", "operationId": "createSubscription", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CalendarSubscriptionCreate" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CalendarSubscription" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Create Subscription", "tags": [ "calendar", "Calendar Subscriptions" ] } }, "/api/v1/calendar/subscriptions/{subscription_id}": { "delete": { "description": "Soft delete subscription.", "operationId": "deleteSubscription", "parameters": [ { "in": "path", "name": "subscription_id", "required": true, "schema": { "title": "Subscription Id", "type": "string" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Delete Subscription", "tags": [ "calendar", "Calendar Subscriptions" ] }, "get": { "description": "Get single subscription by ID.", "operationId": "getSubscription2", "parameters": [ { "in": "path", "name": "subscription_id", "required": true, "schema": { "title": "Subscription Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CalendarSubscription" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Subscription", "tags": [ "calendar", "Calendar Subscriptions" ] }, "put": { "description": "Update calendar subscription.", "operationId": "updateSubscription", "parameters": [ { "in": "path", "name": "subscription_id", "required": true, "schema": { "title": "Subscription Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CalendarSubscriptionUpdate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CalendarSubscription" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Update Subscription", "tags": [ "calendar", "Calendar Subscriptions" ] } }, "/api/v1/calendar/unified/events": { "get": { "description": "List unified calendar events with RRULE expansion.\n\nExpands recurring events into individual instances for the date range.", "operationId": "listUnifiedEvents", "parameters": [ { "description": "Filter by collection", "in": "query", "name": "collection_id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by collection", "title": "Collection Id" } }, { "in": "query", "name": "start_date", "required": false, "schema": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Start Date" } }, { "in": "query", "name": "end_date", "required": false, "schema": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "End Date" } }, { "description": "Filter by status", "in": "query", "name": "event_status", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by status", "title": "Event Status" } }, { "description": "Filter by type", "in": "query", "name": "event_type", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by type", "title": "Event Type" } }, { "description": "Include cancelled events", "in": "query", "name": "include_cancelled", "required": false, "schema": { "default": false, "description": "Include cancelled events", "title": "Include Cancelled", "type": "boolean" } }, { "description": "Expand recurring events", "in": "query", "name": "expand_recurring", "required": false, "schema": { "default": true, "description": "Expand recurring events", "title": "Expand Recurring", "type": "boolean" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 100, "maximum": 1000, "minimum": 1, "title": "Limit", "type": "integer" } }, { "in": "query", "name": "offset", "required": false, "schema": { "default": 0, "minimum": 0, "title": "Offset", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Listunifiedevents", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List unified calendar events", "tags": [ "calendar", "Calendar Collections" ] }, "post": { "description": "Create a new unified calendar event.\n\nLow-confidence events are set to 'pending' for review. An overlap is no\nlonger recorded that way (TIDY-15853): the conflict ward evaluates the\ncandidate under lock before anything is written, and a refusal returns a\ntyped 409 carrying the pending card instead of a half-real 'pending' row.", "operationId": "createUnifiedEvent", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnifiedCalendarEventCreate" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnifiedCalendarEvent" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Create unified calendar event", "tags": [ "calendar", "Calendar Collections" ] } }, "/api/v1/calendar/unified/events/{event_id}": { "delete": { "description": "Soft delete unified calendar event.", "operationId": "deleteUnifiedEvent", "parameters": [ { "description": "Typed ID with prefix 'V'", "in": "path", "name": "event_id", "required": true, "schema": { "description": "Typed ID with prefix 'V'", "title": "Event Id", "type": "string" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Delete unified calendar event", "tags": [ "calendar", "Calendar Collections" ] }, "get": { "description": "Get single unified calendar event by ID.", "operationId": "getUnifiedEvent", "parameters": [ { "description": "Typed ID with prefix 'V'", "in": "path", "name": "event_id", "required": true, "schema": { "description": "Typed ID with prefix 'V'", "title": "Event Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnifiedCalendarEvent" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get unified event by ID", "tags": [ "calendar", "Calendar Collections" ] }, "put": { "description": "Update existing unified calendar event.", "operationId": "updateUnifiedEvent", "parameters": [ { "description": "Typed ID with prefix 'V'", "in": "path", "name": "event_id", "required": true, "schema": { "description": "Typed ID with prefix 'V'", "title": "Event Id", "type": "string" } }, { "description": "Send ICS UPDATE to attendees when notification-worthy fields change. Defaults false (TIDY-17470): a field save never emails attendees.", "in": "query", "name": "notify_attendees", "required": false, "schema": { "default": false, "description": "Send ICS UPDATE to attendees when notification-worthy fields change. Defaults false (TIDY-17470): a field save never emails attendees.", "title": "Notify Attendees", "type": "boolean" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnifiedCalendarEventUpdate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnifiedCalendarEvent" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Update unified calendar event", "tags": [ "calendar", "Calendar Collections" ] } }, "/api/v1/calendar/unified/events/{event_id}/approve": { "post": { "description": "Approve a pending unified calendar event.", "operationId": "approveUnifiedEvent", "parameters": [ { "description": "Typed ID with prefix 'V'", "in": "path", "name": "event_id", "required": true, "schema": { "description": "Typed ID with prefix 'V'", "title": "Event Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventApprovalResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Approve pending event", "tags": [ "calendar", "Calendar Collections" ] } }, "/api/v1/calendar/unified/events/{event_id}/cancel": { "post": { "description": "Cancel a unified calendar event (set status to cancelled).", "operationId": "cancelUnifiedEvent", "parameters": [ { "description": "Typed ID with prefix 'V'", "in": "path", "name": "event_id", "required": true, "schema": { "description": "Typed ID with prefix 'V'", "title": "Event Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventApprovalResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Cancel calendar event", "tags": [ "calendar", "Calendar Collections" ] } }, "/api/v1/calendar/unified/events/{event_id}/reject": { "post": { "description": "Reject a pending unified calendar event.", "operationId": "rejectUnifiedEvent", "parameters": [ { "description": "Typed ID with prefix 'V'", "in": "path", "name": "event_id", "required": true, "schema": { "description": "Typed ID with prefix 'V'", "title": "Event Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/EventRejectRequest" }, { "type": "null" } ], "title": "Reject Request" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventApprovalResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Reject pending event", "tags": [ "calendar", "Calendar Collections" ] } }, "/api/v1/campaign-settings": { "get": { "operationId": "getCampaignSettings", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CampaignSettingsResponse" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Campaign Settings", "tags": [ "campaign-settings" ], "x-local-capability": "cloud", "x-mcp-skip": true }, "put": { "operationId": "putCampaignSettings", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CampaignSettingsBody" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CampaignSettingsResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Put Campaign Settings", "tags": [ "campaign-settings" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/campaigns/render/test": { "post": { "operationId": "renderCampaignTest", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CampaignTestRenderRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CampaignTestRenderResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Full campaign render for one sample recipient (test-send lane)", "tags": [ "campaigns" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Campaign editor render surface; the campaign MCP tooling lands with the send orchestration story." } }, "/api/v1/campaigns/render/validate": { "post": { "operationId": "validateCampaignTemplate", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CampaignDocRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CampaignValidateResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Save-time campaign template validation (per-block reasons)", "tags": [ "campaigns" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Campaign editor render surface; the campaign MCP tooling lands with the send orchestration story." } }, "/api/v1/campaigns/{campaign_id}/cancel": { "post": { "description": "Cancel: scheduled → draft; sending/paused → remaining rows cancelled.", "operationId": "cancelCampaign", "parameters": [ { "description": "records.id of the campaign", "in": "path", "name": "campaign_id", "required": true, "schema": { "description": "records.id of the campaign", "title": "Campaign Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CampaignActionResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Cancel Campaign", "tags": [ "campaigns" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/campaigns/{campaign_id}/pause": { "post": { "operationId": "pauseCampaign", "parameters": [ { "description": "records.id of the campaign", "in": "path", "name": "campaign_id", "required": true, "schema": { "description": "records.id of the campaign", "title": "Campaign Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CampaignActionResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Pause Campaign", "tags": [ "campaigns" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/campaigns/{campaign_id}/preflight": { "post": { "description": "Resolve the audience NOW and return the R10 counts.\n\nThe optional body carries the client's known-local properties — field\nauthoring is local-first, so a preflight fired right after a write must\nnot read the stale stored bag (the write-behind race, TIDY-14685).", "operationId": "preflightCampaign", "parameters": [ { "description": "records.id of the campaign", "in": "path", "name": "campaign_id", "required": true, "schema": { "description": "records.id of the campaign", "title": "Campaign Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/PreflightRequest" }, { "type": "null" } ], "title": "Body" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PreflightResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Preflight Campaign", "tags": [ "campaigns" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/campaigns/{campaign_id}/progress": { "get": { "description": "Live send progress — the client surface over campaign_recipients (R19).", "operationId": "getCampaignProgress", "parameters": [ { "description": "records.id of the campaign", "in": "path", "name": "campaign_id", "required": true, "schema": { "description": "records.id of the campaign", "title": "Campaign Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProgressResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Campaign Progress", "tags": [ "campaigns" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/campaigns/{campaign_id}/recipients/{recipient_id}/resolve-uncertain": { "post": { "description": "The explicit operator decision on an uncertain row (gate F3).\n\n``retry`` is deliberate and logged — it MAY deliver a duplicate email.\n``skip`` counts the row out (cancelled).", "operationId": "resolveUncertainRecipient", "parameters": [ { "description": "records.id of the campaign", "in": "path", "name": "campaign_id", "required": true, "schema": { "description": "records.id of the campaign", "title": "Campaign Id", "type": "string" } }, { "in": "path", "name": "recipient_id", "required": true, "schema": { "title": "Recipient Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UncertainResolveRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UncertainResolveResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Resolve Uncertain Recipient", "tags": [ "campaigns" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/campaigns/{campaign_id}/resume": { "post": { "description": "Resume a paused campaign.\n\nWith a snapshot: re-queue ONLY retrying/queued rows (sent/uncertain rows\nimmune) and dispatch. Without one (paused at fire): re-fire — preflight\nre-runs, identity/connection re-validate (R11).", "operationId": "resumeCampaign", "parameters": [ { "description": "records.id of the campaign", "in": "path", "name": "campaign_id", "required": true, "schema": { "description": "records.id of the campaign", "title": "Campaign Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CampaignActionResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Resume Campaign", "tags": [ "campaigns" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/campaigns/{campaign_id}/schedule": { "post": { "description": "Schedule the campaign; the durable due-campaign scan fires it (F5).", "operationId": "scheduleCampaign", "parameters": [ { "description": "records.id of the campaign", "in": "path", "name": "campaign_id", "required": true, "schema": { "description": "records.id of the campaign", "title": "Campaign Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_service__models__campaigns__ScheduleRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CampaignActionResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Schedule Campaign", "tags": [ "campaigns" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/campaigns/{campaign_id}/send": { "post": { "description": "Send now: preflight, snapshot, dispatch (R10/R11).", "operationId": "sendCampaign", "parameters": [ { "description": "records.id of the campaign", "in": "path", "name": "campaign_id", "required": true, "schema": { "description": "records.id of the campaign", "title": "Campaign Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendNowResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Send Campaign", "tags": [ "campaigns" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/campaigns/{campaign_id}/test-send": { "post": { "description": "Render the FULL resolved email and send it to the author (R9).\n\nStamps ``test_sent_at`` on success — the gate send/schedule check.", "operationId": "testSendCampaign", "parameters": [ { "description": "records.id of the campaign", "in": "path", "name": "campaign_id", "required": true, "schema": { "description": "records.id of the campaign", "title": "Campaign Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TestSendResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Test Send Campaign", "tags": [ "campaigns" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/capture": { "post": { "operationId": "captureRow", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaptureRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaptureResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Capture", "tags": [ "capture" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/captures": { "get": { "operationId": "listVoiceCaptures", "parameters": [ { "in": "query", "name": "status", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Status" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "maximum": 200, "minimum": 1, "title": "Limit", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoiceCaptureListResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List the caller's recent voice captures", "tags": [ "captures", "captures" ], "x-mcp-skip": true } }, "/api/v1/captures/voice": { "post": { "description": "Store the audio, insert the capture row, publish ``capture.materialize``.\n\nReturns 202 with the new capture id on first upload. A replay of the same\n``client_capture_id`` (the watch draining its offline queue) returns 200\nwith the existing capture id and creates no duplicate row / note / message.", "operationId": "createVoiceCapture", "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/Body_createVoiceCapture" } } }, "required": true }, "responses": { "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoiceCaptureCreateResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Upload a voice capture for async materialization", "tags": [ "captures", "captures" ], "x-mcp-skip": true } }, "/api/v1/captures/{capture_id}": { "get": { "operationId": "getVoiceCapture", "parameters": [ { "in": "path", "name": "capture_id", "required": true, "schema": { "title": "Capture Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoiceCaptureResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get a voice capture's status/detail", "tags": [ "captures", "captures" ], "x-mcp-skip": true } }, "/api/v1/cards/{card_id}/detail": { "get": { "description": "Get detailed information for a specific feed card.\n\n Returns the full card content (body not truncated) and optionally\n related cards for display in a detail modal.\n\n Path Parameters:\n card_id: The card ID in format {cardType}_{sourceId}\n e.g., \"event_a1b2c3d4-...\" or \"recipe_weather_abc123\"\n\n Response:\n {\n \"card\": {\n \"id\": \"event_a1b2c3d4-...\",\n \"cardType\": \"event\",\n \"sourceId\": \"a1b2c3d4-...\",\n \"title\": \"School Picture Day\",\n \"subtitle\": \"Lincoln Elementary\",\n \"body\": \"Full content...\",\n ...\n },\n \"relatedCards\": []\n }\n\n Error Responses:\n - 400 Bad Request: Invalid card ID format\n - 401 Unauthorized: Missing or invalid JWT token\n - 404 Not Found: Card not found or no tenant associated with account\n - 500 Internal Server Error: Database operation failed\n\n Related: Android App v1 - Data-driven click actions", "operationId": "getCardDetail", "parameters": [ { "in": "path", "name": "card_id", "required": true, "schema": { "title": "Card Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CardDetailResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get card detail", "tags": [ "feed" ] } }, "/api/v1/channel-pickup": { "get": { "operationId": "listChannelPickupSettings", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChannelPickupSettings" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Per-channel default employee and offline policy", "tags": [ "channel-ingress", "team" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/channel-pickup/{channel}": { "put": { "description": "Validated, audited, and refusing to store an unhonourable policy.\n\nA failover target must itself be available-CLASS — a hosted employee, or a\nworkshop employee that is enrolled somewhere. Pointing failover at an\nemployee that can never answer is a queue with extra steps, and saying so\nat save time beats discovering it at 3am.", "operationId": "setChannelPickupSetting", "parameters": [ { "in": "path", "name": "channel", "required": true, "schema": { "enum": [ "sms", "web", "android", "whatsapp" ], "title": "Channel", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChannelPickupUpdate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChannelPickupSetting" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Set a channel's default employee and offline policy", "tags": [ "channel-ingress", "team" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/chat/conversations": { "get": { "description": "Recent joined rooms, most-recent-active first (watch conversation list).", "operationId": "listChatConversations", "parameters": [ { "in": "query", "name": "limit", "required": false, "schema": { "default": 20, "maximum": 100, "minimum": 1, "title": "Limit", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationsResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List the caller's recent chat conversations", "tags": [ "chat-relay", "chat-relay" ], "x-mcp-skip": true } }, "/api/v1/chat/conversations/{room_id}/messages": { "get": { "description": "Newest-last page of a room's messages with an opaque ``next_from`` token.\n\nRuns under the caller's Matrix token behind a relay-side membership guard\n— a room the caller has not joined returns 403 (no cross-member leakage,\nno room-existence oracle; real Tuwunel would 200 an unjoined read).", "operationId": "listChatMessages", "parameters": [ { "in": "path", "name": "room_id", "required": true, "schema": { "title": "Room Id", "type": "string" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 30, "maximum": 100, "minimum": 1, "title": "Limit", "type": "integer" } }, { "in": "query", "name": "from", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "From" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessagesResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Page a conversation's timeline messages", "tags": [ "chat-relay", "chat-relay" ] }, "post": { "description": "Send under the caller's relay device; encrypted rooms never downgrade.", "operationId": "sendChatMessage", "parameters": [ { "in": "path", "name": "room_id", "required": true, "schema": { "title": "Room Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendMessageRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendMessageResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Send a message to a conversation (idempotent)", "tags": [ "chat-relay", "chat-relay" ] } }, "/api/v1/chat/dm": { "post": { "description": "Return a stable ``room_id`` for a 1:1 DM, creating it on first call.", "operationId": "resolveChatDm", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_service__routers__chat_relay__CreateDmRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_service__routers__chat_relay__CreateDmResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Resolve-or-create a DM with a member or the assistant", "tags": [ "chat-relay", "chat-relay" ], "x-mcp-skip": true } }, "/api/v1/chat/dms/{room_id}/encryption/enable": { "post": { "operationId": "enableDmEncryption", "parameters": [ { "in": "path", "name": "room_id", "required": true, "schema": { "title": "Room Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DmEncryptionEnableRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DmEncryptionResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Enable E2EE for a DM after disclosure acknowledgement", "tags": [ "chat-encryption" ] } }, "/api/v1/chat/dms/{room_id}/encryption/status": { "get": { "operationId": "getDmEncryptionStatus", "parameters": [ { "in": "path", "name": "room_id", "required": true, "schema": { "title": "Room Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DmEncryptionResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Load per-DM encryption status", "tags": [ "chat-encryption" ] } }, "/api/v1/chat/keyword-alerts": { "get": { "description": "Return every keyword alert owned by the calling account.", "operationId": "listKeywordAlerts", "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/KeywordAlertResponse" }, "title": "Response Listkeywordalerts", "type": "array" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List the caller's chat keyword alerts", "tags": [ "chat-keyword-alerts", "chat-keyword-alerts" ] }, "post": { "description": "Create a keyword alert. 409 if the caller already has that keyword.", "operationId": "createKeywordAlert", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateKeywordAlertRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KeywordAlertResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Create a chat keyword alert for the caller", "tags": [ "chat-keyword-alerts", "chat-keyword-alerts" ] } }, "/api/v1/chat/keyword-alerts/{alert_id}": { "delete": { "description": "Delete the caller's keyword alert. 404 if it isn't theirs.", "operationId": "deleteKeywordAlert", "parameters": [ { "in": "path", "name": "alert_id", "required": true, "schema": { "format": "uuid", "title": "Alert Id", "type": "string" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Delete a chat keyword alert owned by the caller", "tags": [ "chat-keyword-alerts", "chat-keyword-alerts" ] }, "patch": { "description": "Patch keyword and/or enabled. 404 if the alert isn't the caller's.", "operationId": "patchKeywordAlert", "parameters": [ { "in": "path", "name": "alert_id", "required": true, "schema": { "format": "uuid", "title": "Alert Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatchKeywordAlertRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KeywordAlertResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Update a chat keyword alert owned by the caller", "tags": [ "chat-keyword-alerts", "chat-keyword-alerts" ] } }, "/api/v1/chat/member-messages": { "post": { "description": "An employee working in a person's conversation reaches them there (TIDY-20074\nF7); every other message is the DM send, as ``/dm`` and the send route make it.", "operationId": "sendChatMemberMessage", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemberMessageRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemberMessageResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Message a member: in the conversation the call comes from when it is theirs, else in the caller's DM with them (idempotent)", "tags": [ "chat-relay", "chat-relay" ], "x-local-capability": "cloud" } }, "/api/v1/chat/rooms/{room_id}/messages/{event_id}/unfurl": { "post": { "description": "Fire-and-forget endpoint. The frontend extracts URLs from the body of a message it has just sent and POSTs them here. The api-service schedules a background task that fetches OpenGraph metadata, caches per tenant, and posts a Matrix m.replace event attaching the rendered preview cards. Returns 202 within ~100 ms regardless of fetch latency.", "operationId": "enqueueChatMessageUnfurl", "parameters": [ { "in": "path", "name": "room_id", "required": true, "schema": { "title": "Room Id", "type": "string" } }, { "in": "path", "name": "event_id", "required": true, "schema": { "title": "Event Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnfurlEnqueueRequest" } } }, "required": true }, "responses": { "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnfurlAcceptedResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Schedule link-unfurl for a just-sent Matrix message", "tags": [ "chat-unfurl" ], "x-mcp-skip": true } }, "/api/v1/chat/rooms/{room_id}/summarize": { "post": { "operationId": "summarizeChatRoom", "parameters": [ { "in": "path", "name": "room_id", "required": true, "schema": { "title": "Room Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SummarizeRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatSummaryResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Generate an AI summary of a chat room since the user was last here", "tags": [ "chat-summarization", "chat-summarization" ] } }, "/api/v1/chat/summaries/{summary_id}/promote": { "post": { "operationId": "promoteChatSummary", "parameters": [ { "in": "path", "name": "summary_id", "required": true, "schema": { "format": "uuid", "title": "Summary Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_service__routers__chat_summarization__PromoteRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PromoteResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Promote a transient chat summary to a permanent note", "tags": [ "chat-summarization", "chat-summarization" ] } }, "/api/v1/collages/{note_id}/share-image": { "get": { "description": "Stream the share PNG (watermarked unless the caller disabled it, D9).", "operationId": "getCollageShareImage", "parameters": [ { "description": "Typed ID with prefix 'N'", "in": "path", "name": "note_id", "required": true, "schema": { "description": "Typed ID with prefix 'N'", "title": "Note Id", "type": "string" } } ], "responses": { "200": { "content": { "image/png": {} }, "description": "Composed snapshot PNG" }, "404": { "description": "Collage not found / not visible" }, "409": { "description": "Snapshot not composed yet" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Composed collage snapshot for sharing", "tags": [ "collages", "collages" ], "x-mcp-skip": true, "x-mcp-skip-reason": "Binary image download for the OS share sheet; not an agent tool." } }, "/api/v1/comments": { "get": { "description": "Return threaded comments for a primitive, sorted by created_at DESC.\n\nExcludes soft-deleted comments. Replies are nested under their root.\nResolved comments stay queryable here (D18 — resolution never deletes);\npass ``status=resolved`` for the resolved-history view.", "operationId": "listComments", "parameters": [ { "description": "Parent entity type", "in": "query", "name": "parent_type", "required": true, "schema": { "description": "Parent entity type", "title": "Parent Type", "type": "string" } }, { "description": "Parent entity ID (typed or bare UUID)", "in": "query", "name": "parent_id", "required": true, "schema": { "description": "Parent entity ID (typed or bare UUID)", "title": "Parent Id", "type": "string" } }, { "description": "Filter by lifecycle status ('open' or 'resolved') — TIDY-14992", "in": "query", "name": "status", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by lifecycle status ('open' or 'resolved') — TIDY-14992", "title": "Status" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "additionalProperties": true, "type": "object" }, "title": "Response Listcomments", "type": "array" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List comments for a primitive", "tags": [ "comments" ] }, "post": { "description": "Create a comment on any primitive.\n\nDerives plain_text from ProseMirror JSON content.\nIf thread_root_id is set (reply), creates linked_references rows.\n\nTIDY-18990: the comment is EMBEDDED at the end of the parent's body by\ndefault (see :func:`_resolve_body_placement` for the three cases that turn\nthat off), and always carries a ``comment_on`` edge to its parent written\nby the ``comments_link_parent`` trigger. The response adds\n``embedded`` / ``link_id`` — and ``embed_error`` when the row landed but\nthe body mutation did not.\n\n``request`` and ``principal_claim`` are here for the embed step: the\ncoordinator derives the granted token scopes from the request and the\nacting principal from the same verified claim the canonical content-edits\nroute binds, so the version-history entry names the employee or agent\nmember that commented rather than the human whose bearer carried the\ninternal call.\n\nA client-supplied ``id`` UPSERTS. When it lands on a row that already\nexists and would change it, this route is a comment MUTATION and answers\nto the same gates ``PATCH`` does — 403 ``not_author`` / ``forbidden``\n(:func:`_authorize_comment_upsert`). A resend that changes nothing stays\nthe idempotent retry PowerSync relies on. That gate is applied INSIDE the\nwriting transaction, under a per-id advisory lock\n(``services/comment_locks.py``), so two POSTs racing on one fresh id cannot\nboth decide there is nothing to authorize and let the loser overwrite the\nwinner.", "operationId": "createComment", "parameters": [ { "in": "header", "name": "X-Tidy-Acting-Principal", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tidy-Acting-Principal" } }, { "in": "header", "name": "X-Internal-Service", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service" } }, { "in": "header", "name": "X-Internal-Service-Key", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service-Key" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommentCreate" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Createcomment", "type": "object" } } }, "description": "Successful Response" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Refused. `code: not_author` — only the author may change a comment's text, and deleting someone else's needs edit access to the primitive its thread hangs on. `code: forbidden` — the caller reaches this comment only through an @mention, which grants reading the thread and replying, never mutating it. Neither is retryable." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Create a comment", "tags": [ "comments" ] } }, "/api/v1/comments/mentions": { "get": { "description": "Return comments where the caller is @mentioned, newest first.\n\nData source for S6's Chat Comments section. Each row carries anchor_text,\nthe thread root, and the parent route — WITHOUT requiring parent access and\nWITHOUT serializing the parent body (Decision A / R7).\n\ntidy-mention-grant-justified: this read deliberately bypasses\n``primitive_visible_predicate`` on the parent because the caller is\n@mentioned. We never select the parent primitive's body — only comment\nfields + anchor + parent route metadata.", "operationId": "listMentionedComments", "parameters": [ { "description": "ISO timestamp; return comments created after this", "in": "query", "name": "since", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO timestamp; return comments created after this", "title": "Since" } }, { "description": "Max comments to return", "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "description": "Max comments to return", "maximum": 200, "minimum": 1, "title": "Limit", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/MentionedCommentResponse" }, "title": "Response Listmentionedcomments", "type": "array" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List comments where the caller is @mentioned", "tags": [ "comments" ] } }, "/api/v1/comments/resolve-bulk": { "post": { "description": "Bulk resolve (the summarize-then-resolve agent flow). Explicit partials.", "operationId": "resolveCommentsBulk", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommentResolveBulkRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommentResolveBulkResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Resolve multiple comments with per-id outcomes", "tags": [ "comments" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/comments/{comment_id}": { "delete": { "description": "Soft-delete a comment by setting deleted_at. Replies are NOT cascaded.\n\nAuthorization (TIDY-18988): the author, or a member with EDIT access to the\nprimitive the thread hangs on — the document's owner cleaning up their own\npage is the case this second branch exists for. A member who can only READ\nthat primitive (a named read scope on a record, say) gets 403\n``not_author``; an @mentioned principal gets 403 like every other comment\nmutation.\n\nThe path param accepts the canonical typed comment ID (``M-<uuid>``) or a\nbare UUID.", "operationId": "deleteComment", "parameters": [ { "in": "path", "name": "comment_id", "required": true, "schema": { "title": "Comment Id", "type": "string" } } ], "responses": { "204": { "description": "Successful Response" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Refused. `code: not_author` — only the author may change a comment's text, and deleting someone else's needs edit access to the primitive its thread hangs on. `code: forbidden` — the caller reaches this comment only through an @mention, which grants reading the thread and replying, never mutating it. Neither is retryable." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Soft-delete a comment", "tags": [ "comments" ] }, "get": { "description": "Return a single comment + its thread + anchor metadata.\n\nAuthorize if the caller can access the parent primitive (its own view, or a\ndelegation grant from the parent's owner — TIDY-19325) OR is @mentioned in\nthe comment/thread (mention-grant, Decision A / R7). NEVER serialize the\nparent primitive's body — only comment rows + anchor + parent route.\n\nWhen access is mention-grant only, the returned thread is scoped to the\nmentioned thread (root + replies). A deleted comment 404s; a caller who is\nneither mentioned nor parent-authorized gets 403 (fail closed).\n\nThe path param accepts the canonical typed comment ID (``M-<uuid>``) or a\nbare UUID; both forms resolve to the same row.", "operationId": "getComment", "parameters": [ { "in": "path", "name": "comment_id", "required": true, "schema": { "title": "Comment Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommentThreadResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get a single comment + thread (mention-grant aware)", "tags": [ "comments" ] }, "patch": { "description": "Update a comment's content, status, or facets.\n\nRe-derives plain_text if content is updated.\n\nAuthorization (TIDY-18988), in two layers:\n\n* Every field needs access to the primitive the thread hangs on. An\n @mention alone is not enough — that grant is read-thread + reply\n (``_authorize_comment_mutation``).\n* ``content`` on top of that is the AUTHOR's alone: 403 ``not_author`` for\n anyone else. Rewriting what someone else said is not a permission a\n co-member has, and this is the boundary every client is held to — the\n web's own edits upload through this same route. ``status``, ``facets``\n and ``facet_data`` stay co-member writable: a colleague may resolve or\n retype a comment without rewriting its words.\n\nThe path param accepts the canonical typed comment ID (``M-<uuid>``) or a\nbare UUID.", "operationId": "updateComment", "parameters": [ { "in": "path", "name": "comment_id", "required": true, "schema": { "title": "Comment Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommentUpdate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Updatecomment", "type": "object" } } }, "description": "Successful Response" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Refused. `code: not_author` — only the author may change a comment's text, and deleting someone else's needs edit access to the primitive its thread hangs on. `code: forbidden` — the caller reaches this comment only through an @mention, which grants reading the thread and replying, never mutating it. Neither is retryable." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Update a comment", "tags": [ "comments" ] } }, "/api/v1/comments/{comment_id}/reopen": { "post": { "description": "Return a resolved comment to the active margin / default reads.", "operationId": "reopenComment", "parameters": [ { "in": "path", "name": "comment_id", "required": true, "schema": { "title": "Comment Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommentResolutionResponse" } } }, "description": "Successful Response" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Refused. `code: forbidden` — the caller reaches this comment only through an @mention, which grants reading the thread and replying to it, never resolving or reopening it. Not retryable." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "`code: not_resolved` — the comment was never resolved, so there is nothing to reopen. Not retryable." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Reopen a resolved comment into active context", "tags": [ "comments" ], "x-local-capability": "cloud" } }, "/api/v1/comments/{comment_id}/resolve": { "post": { "description": "Set status=resolved with the actor/timestamp audit pair. Idempotent.", "operationId": "resolveComment", "parameters": [ { "in": "path", "name": "comment_id", "required": true, "schema": { "title": "Comment Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommentResolutionResponse" } } }, "description": "Successful Response" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Refused. `code: forbidden` — the caller reaches this comment only through an @mention, which grants reading the thread and replying to it, never resolving or reopening it. Not retryable." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Resolve a comment out of active context (never deletes)", "tags": [ "comments" ], "x-local-capability": "cloud" } }, "/api/v1/comments/{comment_id}/thread-mute": { "post": { "description": "Set the caller's per-thread mute for a comment thread (TIDY-11596).\n\nThe caller passes any comment id in the thread (``M-<uuid>``); the thread\nROOT is resolved and the caller's mute flag is set on it. ``muted=true`` stops\nfurther reply notifications for that thread for this human; ``muted=false``\nresubscribes. Agents ignore mute (always subscribed) — this is the per-human\ncontrol. Authorization mirrors the thread read: parent access OR mention\ngrant (R6) — a caller who can't see the thread can't mute it (404). This is a\nCOMMENT-surface control; nothing routes into chat.", "operationId": "setCommentThreadMute", "parameters": [ { "in": "path", "name": "comment_id", "required": true, "schema": { "title": "Comment Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ThreadMuteRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ThreadMuteResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Mute/unmute reply notifications for a comment thread", "tags": [ "comments" ], "x-mcp-skip": true, "x-mcp-skip-reason": "Per-HUMAN comment-thread mute UX (TIDY-11596). Agents ignore mute (always subscribed for running context), so there is no agent-facing tool — this is a web/notification-surface control only." } }, "/api/v1/consent": { "get": { "description": "List all parental consent records for the current tenant.\n\n Returns pending, granted, revoked, and expired consents.\n Filter by status to see specific records.\n\n Related: 011-auth-user-onboarding T098", "operationId": "listConsents", "parameters": [ { "in": "query", "name": "status", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Status" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "maximum": 100, "minimum": 1, "title": "Limit", "type": "integer" } }, { "in": "query", "name": "offset", "required": false, "schema": { "default": 0, "minimum": 0, "title": "Offset", "type": "integer" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConsentListResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List parental consents", "tags": [ "security" ] } }, "/api/v1/consent/{consent_id}": { "delete": { "description": "Revoke parental consent.\n\n Only the parent who created the consent request can revoke it.\n Triggers cascade deletion of child-related data per COPPA requirements.\n\n Related: 011-auth-user-onboarding T100, T104", "operationId": "revokeConsent", "parameters": [ { "in": "path", "name": "consent_id", "required": true, "schema": { "title": "Consent Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ParentalConsentRevoke" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ParentalConsentResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Revoke parental consent", "tags": [ "security" ] }, "post": { "description": "Grant consent for a pending parental consent request.\n\n Only the parent who created the consent request can grant it.\n Captures IP address and user agent for audit purposes.\n\n Related: 011-auth-user-onboarding T099", "operationId": "grantConsent", "parameters": [ { "in": "path", "name": "consent_id", "required": true, "schema": { "title": "Consent Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } }, { "in": "header", "name": "X-Forwarded-For", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Forwarded-For" } }, { "in": "header", "name": "User-Agent", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "User-Agent" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ParentalConsentGrant" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ParentalConsentResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Grant parental consent", "tags": [ "security" ] } }, "/api/v1/consent/{consent_id}/renew": { "post": { "description": "Renew an expiring or expired parental consent.\n\n Extends the consent for another year with updated scope.\n\n Related: 011-auth-user-onboarding T105", "operationId": "renewConsent", "parameters": [ { "in": "path", "name": "consent_id", "required": true, "schema": { "title": "Consent Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } }, { "in": "header", "name": "X-Forwarded-For", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Forwarded-For" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ParentalConsentGrant" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ParentalConsentResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Renew parental consent", "tags": [ "security" ] } }, "/api/v1/contact-intelligence/resolve": { "post": { "description": "Resolve selected or email-derived text into contact and organization recommendations.", "operationId": "resolveContactIntelligence", "parameters": [ { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactIntelligenceResolveRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactIntelligenceResolveResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Resolve extracted contact data into safe recommendations", "tags": [ "contact-intelligence", "Contact Intelligence" ] } }, "/api/v1/contacts": { "get": { "description": "List contacts for authenticated user's tenant with optional filtering.\n\nTIDY-10690 / S3 — OBO: when ``X-Tidy-On-Behalf-Of`` names a principal with\nan active ``contacts`` read grant, the member-visible predicate runs under\nthe delegator (``effective.caller_param_account_id``). With no active grant\nit falls back to the caller's own id, so an ungranted call never leaks the\nprincipal's private contacts.", "operationId": "listContacts", "parameters": [ { "in": "query", "name": "role", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Role" } }, { "description": "TIDY-7640: filter by linked organization UUID(s). Repeatable. Replaces the legacy free-text 'organization' query parameter.", "in": "query", "name": "organization_id", "required": false, "schema": { "default": [], "description": "TIDY-7640: filter by linked organization UUID(s). Repeatable. Replaces the legacy free-text 'organization' query parameter.", "items": { "type": "string" }, "title": "Organization Id", "type": "array" } }, { "in": "query", "name": "relation_type", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Relation Type" } }, { "description": "Visibility filter. Defaults to promoted-only. Use 'all' to include approved and pending contacts while excluding rejected contacts.", "in": "query", "name": "visibility", "required": false, "schema": { "anyOf": [ { "pattern": "^(promoted|shadow|pending_review|rejected|all)$", "type": "string" }, { "type": "null" } ], "description": "Visibility filter. Defaults to promoted-only. Use 'all' to include approved and pending contacts while excluding rejected contacts.", "title": "Visibility" } }, { "description": "Ownership scope for the primary contacts list.", "in": "query", "name": "scope", "required": false, "schema": { "anyOf": [ { "pattern": "^(all|mine|shared|global)$", "type": "string" }, { "type": "null" } ], "description": "Ownership scope for the primary contacts list.", "title": "Scope" } }, { "in": "query", "name": "search", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Search" } }, { "description": "Filter by starred status", "in": "query", "name": "starred", "required": false, "schema": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Filter by starred status", "title": "Starred" } }, { "description": "Filter by source type (imported, extracted, manual)", "in": "query", "name": "source_type", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by source type (imported, extracted, manual)", "title": "Source Type" } }, { "description": "Filter by exact tag membership (repeatable)", "in": "query", "name": "tag", "required": false, "schema": { "default": [], "description": "Filter by exact tag membership (repeatable)", "items": { "type": "string" }, "title": "Tag", "type": "array" } }, { "description": "Filter by address book UUID", "in": "query", "name": "address_book", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by address book UUID", "title": "Address Book" } }, { "description": "TIDY-16721: filter to contacts carrying this applied facet (e.g. `crm_lead`). Narrows the member-visible result set; it never widens it.", "in": "query", "name": "facet_slug", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "TIDY-16721: filter to contacts carrying this applied facet (e.g. `crm_lead`). Narrows the member-visible result set; it never widens it.", "title": "Facet Slug" } }, { "description": "TIDY-18527: order before paging. Omitted: best search match first, then most recently updated.", "in": "query", "name": "sort", "required": false, "schema": { "anyOf": [ { "pattern": "^(name_asc|name_desc|created_desc|created_asc|updated_desc)$", "type": "string" }, { "type": "null" } ], "description": "TIDY-18527: order before paging. Omitted: best search match first, then most recently updated.", "title": "Sort" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 100, "maximum": 1000, "minimum": 1, "title": "Limit", "type": "integer" } }, { "in": "query", "name": "offset", "required": false, "schema": { "default": 0, "minimum": 0, "title": "Offset", "type": "integer" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Listcontacts", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List contacts with filtering", "tags": [ "contacts", "Contacts" ] }, "post": { "description": "Create a new contact for the authenticated user's tenant.\n\nTIDY-10690 / S3 — OBO write: a delegated create requires a ``read_write``\n``contacts`` grant (``need_write=True``). With only a ``read`` grant (or no\ngrant) the swap falls back to the caller, so the contact is owned by the\ncaller — a read-only delegation can never write into the principal's data.", "operationId": "createContact", "parameters": [ { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactCreate" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Create new contact", "tags": [ "contacts", "Contacts" ] } }, "/api/v1/contacts/duplicates": { "get": { "description": "Find potential duplicate contacts using tiered matching.", "operationId": "getDuplicates", "parameters": [ { "in": "query", "name": "limit", "required": false, "schema": { "default": 100, "maximum": 500, "minimum": 1, "title": "Limit", "type": "integer" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DuplicatesResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get potential duplicate contact pairs", "tags": [ "contacts", "Contact Merge" ] } }, "/api/v1/contacts/duplicates/dismiss": { "post": { "description": "Mark a duplicate pair as not duplicates so it won't appear in future scans.", "operationId": "dismissDuplicatePair", "parameters": [ { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DismissRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Dismissduplicatepair", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Dismiss a duplicate pair as not duplicates", "tags": [ "contacts", "Contact Merge" ] } }, "/api/v1/contacts/duplicates/dismissed": { "get": { "description": "Get all pairs that have been dismissed as not duplicates.", "operationId": "getDismissedPairs", "parameters": [ { "in": "query", "name": "limit", "required": false, "schema": { "default": 100, "maximum": 500, "minimum": 1, "title": "Limit", "type": "integer" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DismissedListResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get dismissed duplicate pairs", "tags": [ "contacts", "Contact Merge" ] } }, "/api/v1/contacts/duplicates/dismissed/{dismissal_id}": { "delete": { "description": "Remove a dismissal so the pair will appear again in duplicate scans.", "operationId": "restoreDismissedPair", "parameters": [ { "in": "path", "name": "dismissal_id", "required": true, "schema": { "title": "Dismissal Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Restoredismissedpair", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Restore a dismissed pair (reconsider for merging)", "tags": [ "contacts", "Contact Merge" ] } }, "/api/v1/contacts/enrichment/gravatar-refresh": { "post": { "description": "Queue every contact with an email and no real photo for enrichment.\n\nTargets:\n - Contacts with no photo_url / photo_source at all (initials only)\n - Contacts with a locally-generated placeholder source\n ('gravatar_identicon' legacy or 'generated'), in case a real\n Google People photo became available since the last run.\n\nLeaves alone: contacts with 'manual', 'device_sync', or\n'google_people' sources. The rate-limited enrichment worker drains the\nqueue in the background. (Gravatar removed for privacy — TIDY-10525;\nthe route path/operation_id are unchanged to preserve the FE contract.)", "operationId": "refreshGravatars", "parameters": [ { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GravatarRefreshResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Refresh photos for all contacts lacking a real photo", "tags": [ "contacts", "contact-enrichment", "Contact Enrichment" ] } }, "/api/v1/contacts/filters/organizations": { "get": { "description": "Get list of organizations from the organizations table for filter dropdown.", "operationId": "getFilterOrganizations", "parameters": [ { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/api_service__models__contact__OrganizationSummary" }, "title": "Response Getfilterorganizations", "type": "array" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get unique organizations for filter dropdown", "tags": [ "contacts", "Contacts" ] } }, "/api/v1/contacts/filters/roles": { "get": { "description": "Get list of unique roles across all contacts for filter dropdown.", "operationId": "getFilterRoles", "parameters": [ { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "type": "string" }, "title": "Response Getfilterroles", "type": "array" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get unique roles for filter dropdown", "tags": [ "contacts", "Contacts" ] } }, "/api/v1/contacts/groups": { "get": { "description": "List the contact groups the caller may see, with member counts.", "operationId": "listGroups", "parameters": [ { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupListResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List contact groups", "tags": [ "contacts", "contact-groups", "Contact Groups" ] }, "post": { "description": "Create a new contact group, private to its creator unless shared.", "operationId": "createGroup", "parameters": [ { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupCreate" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Create contact group", "tags": [ "contacts", "contact-groups", "Contact Groups" ] } }, "/api/v1/contacts/groups/{group_id}": { "delete": { "description": "Soft-delete a contact group (sets deleted_at).\n\nMembers (contacts and organizations) are never deleted — soft-deleting the\ngroup leaves every member row and every entity intact (R10, D14).", "operationId": "deleteGroup", "parameters": [ { "in": "path", "name": "group_id", "required": true, "schema": { "format": "uuid", "title": "Group Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Soft-delete contact group", "tags": [ "contacts", "contact-groups", "Contact Groups" ] }, "get": { "description": "Get a single group with its (contact + organization) member list.", "operationId": "getGroup", "parameters": [ { "in": "path", "name": "group_id", "required": true, "schema": { "format": "uuid", "title": "Group Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get contact group with members", "tags": [ "contacts", "contact-groups", "Contact Groups" ] }, "put": { "description": "Update group name, description, team wear (R19) and/or who sees it.", "operationId": "updateGroup", "parameters": [ { "in": "path", "name": "group_id", "required": true, "schema": { "format": "uuid", "title": "Group Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupUpdate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Update contact group", "tags": [ "contacts", "contact-groups", "Contact Groups" ] } }, "/api/v1/contacts/groups/{group_id}/emails": { "get": { "description": "Resolve a mixed group to send-time addresses (R22, R21).\n\nContacts resolve via their canonical primary email; organizations via the\ngeneric → primary-contact → unaddressable tiers. Any member with no\nresolvable address is returned in ``unaddressable`` — never silently dropped.", "operationId": "getGroupEmails", "parameters": [ { "in": "path", "name": "group_id", "required": true, "schema": { "format": "uuid", "title": "Group Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupEmailsResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Resolve group to email addresses", "tags": [ "contacts", "contact-groups", "Contact Groups" ] } }, "/api/v1/contacts/groups/{group_id}/members": { "post": { "description": "Add contacts and/or organizations to a manual group (R22).", "operationId": "addMembers", "parameters": [ { "in": "path", "name": "group_id", "required": true, "schema": { "format": "uuid", "title": "Group Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupMemberAdd" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Add members to group", "tags": [ "contacts", "contact-groups", "Contact Groups" ] } }, "/api/v1/contacts/groups/{group_id}/members/organizations/{organization_id}": { "delete": { "description": "Remove a single organization from a manual group (the org is untouched).", "operationId": "removeGroupOrganizationMember", "parameters": [ { "in": "path", "name": "group_id", "required": true, "schema": { "format": "uuid", "title": "Group Id", "type": "string" } }, { "description": "Typed ID with prefix 'O'", "in": "path", "name": "organization_id", "required": true, "schema": { "description": "Typed ID with prefix 'O'", "title": "Organization Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Remove an organization member from group", "tags": [ "contacts", "contact-groups", "Contact Groups" ], "x-local-capability": "outbox", "x-mcp-skip": true, "x-mcp-skip-reason": "Group membership management UI flow — rows are local-first synced." } }, "/api/v1/contacts/groups/{group_id}/members/{contact_id}": { "delete": { "description": "Remove a single contact from a group.", "operationId": "removeMember", "parameters": [ { "in": "path", "name": "group_id", "required": true, "schema": { "format": "uuid", "title": "Group Id", "type": "string" } }, { "in": "path", "name": "contact_id", "required": true, "schema": { "format": "uuid", "title": "Contact Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Remove member from group", "tags": [ "contacts", "contact-groups", "Contact Groups" ] } }, "/api/v1/contacts/groups/{group_id}/promote": { "post": { "description": "One-way promote a manual group to an organization (R10, D14).\n\nCreates an ``approved`` organization owned by the caller (name/description\ncarried), links contact members to it, parents organization members whose\n``parent_organization_id`` is currently NULL (others reported as skipped),\nthen soft-deletes the group. Smart groups cannot be promoted (400).\nPromoting an already-deleted/missing group is a 404.", "operationId": "promoteGroup", "parameters": [ { "in": "path", "name": "group_id", "required": true, "schema": { "format": "uuid", "title": "Group Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PromoteGroupResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Promote a manual group to an organization", "tags": [ "contacts", "contact-groups", "Contact Groups" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "One-way group→org promotion; a server-side multi-step transaction." } }, "/api/v1/contacts/merge": { "post": { "description": "Execute an atomic contact merge operation.", "operationId": "executeMerge", "parameters": [ { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_service__models__contact_merge__MergeRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MergeResult" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Execute contact merge", "tags": [ "contacts", "Contact Merge" ] } }, "/api/v1/contacts/merge/batch": { "post": { "description": "Execute multiple contact merges in a single batch operation.", "operationId": "executeBatchMerge", "parameters": [ { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchMergeRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchMergeResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Execute batch contact merge", "tags": [ "contacts", "Contact Merge" ] } }, "/api/v1/contacts/merge/detect-clusters": { "post": { "description": "Analyze selected contacts and group them into clusters of likely duplicates.\n\n``scope='owner'`` (default) is the per-owner candidate query and is open to\nany member. ``scope='cross_member'`` (TIDY-10524 / S11) spans other members'\nshared / account / global contacts and is restricted to the account owner /\ntenant admin — a non-admin member gets 403.", "operationId": "detectClusters", "parameters": [ { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClusterDetectionRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClusterDetectionResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Detect clusters among selected contacts", "tags": [ "contacts", "Contact Merge" ] } }, "/api/v1/contacts/merge/preview": { "post": { "description": "Generate a preview of what the merged contact would look like.", "operationId": "previewMerge", "parameters": [ { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MergePreviewRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MergePreview" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Preview merge result before execution", "tags": [ "contacts", "Contact Merge" ] } }, "/api/v1/contacts/merge/{audit_id}/retry-graph-sync": { "post": { "description": "Re-run Postgres graph hygiene for a merge whose sync previously failed.", "operationId": "retryContactMergeGraphSync", "parameters": [ { "in": "path", "name": "audit_id", "required": true, "schema": { "title": "Audit Id", "type": "string" } } ], "responses": { "202": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Retrycontactmergegraphsync", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Retry Contact Merge Graph Sync", "tags": [ "contacts", "contact-merge-graph-sync" ] } }, "/api/v1/contacts/merge/{merge_audit_id}/undo": { "post": { "description": "Reverse a contact merge using its ``contact_merge_audit`` record (S10).\n\nUn-soft-deletes the loser (clears ``deleted_at`` + ``merged_into``), restores\nthe survivor's pre-merge field values, reverses the cascade row moves, and\nrecomputes both contacts' selected photo. Idempotent + tenant-scoped:\nundoing an already-undone merge is a safe no-op.", "operationId": "undoMerge", "parameters": [ { "in": "path", "name": "merge_audit_id", "required": true, "schema": { "title": "Merge Audit Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MergeUndoResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Undo a contact merge (true restore from the audit snapshot)", "tags": [ "contacts", "Contact Merge" ] } }, "/api/v1/contacts/pending-review": { "get": { "description": "Get contacts with visibility='pending_review' awaiting user approval.\n\n KCC-3223: Shadow Contact Promotion System\n Returns contacts that have accumulated enough evidence to suggest they\n may be important, but haven't been auto-promoted.\n\n Query Parameters:\n limit: Max results (default 50, max 200)\n offset: Pagination offset\n\n Response:\n {\n \"contacts\": [...],\n \"total_count\": 15\n }\n\n Related: KCC-3223, migration 236_shadow_contacts.sql", "operationId": "getPendingReviewContacts", "parameters": [ { "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "maximum": 200, "minimum": 1, "title": "Limit", "type": "integer" } }, { "in": "query", "name": "offset", "required": false, "schema": { "default": 0, "minimum": 0, "title": "Offset", "type": "integer" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Getpendingreviewcontacts", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get contacts pending review for promotion", "tags": [ "contacts", "Contact Promotion" ] } }, "/api/v1/contacts/photos/hydrate-thumbnails": { "post": { "description": "Backfill the inline base64 ``photo_thumbnail`` for every contact in the\n tenant that has a photo but no inline thumbnail derivative.\n\n Local-first contract (TIDY-10636 S1): contact avatars render from the\n synced ``photo_thumbnail`` with zero network. Contacts whose photo was\n stored only as a bare storage path lacked that derivative, forcing a\n per-render signed-URL fetch storm. This endpoint materializes the\n derivative once; it then syncs DOWN with the contact row.\n\n Bounded per call (max 500 contacts). The client re-invokes while\n ``pending`` > 0. Idempotent — already-hydrated contacts are skipped by\n the writer's IS DISTINCT FROM guard.\n\n Response: { \"hydrated\": int, \"skipped\": int, \"pending\": int }", "operationId": "hydrateContactPhotoThumbnails", "parameters": [ { "in": "query", "name": "limit", "required": false, "schema": { "default": 500, "maximum": 500, "minimum": 1, "title": "Limit", "type": "integer" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HydratePhotoThumbnailsResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Hydrate inline thumbnails for local-first contact avatars", "tags": [ "contacts", "Contact Photos" ], "x-mcp-skip": true } }, "/api/v1/contacts/recent": { "get": { "description": "Return up to ``limit`` recently active contacts for the tenant.\n\n\"Recency\" = ``GREATEST(contacts.updated_at,\ncontact_promotion_scores.last_interaction_at)`` (D-S3-1). Tenants\nthat have never interacted with a contact still see it ordered by\n``updated_at`` thanks to the ``COALESCE`` in the left join.", "operationId": "listRecentContacts", "parameters": [ { "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "maximum": 200, "minimum": 1, "title": "Limit", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_service__routers__contacts__recent__RecentContactsResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "List recent contacts for the extension primitive cache", "tags": [ "contacts", "Contacts" ] } }, "/api/v1/contacts/settings": { "get": { "description": "Retrieve contact settings for the authenticated user.\n\nReturns defaults if no settings have been saved yet.", "operationId": "getContactSettings", "parameters": [ { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactSettingsResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get contact module settings for the current user", "tags": [ "contacts", "contact-settings", "Contact Settings" ] }, "patch": { "description": "Partially update contact settings.\n\nOnly fields provided in the body are updated; omitted fields keep their\ncurrent values. Creates a user_preferences row if one does not exist.", "operationId": "updateContactSettings", "parameters": [ { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactSettingsPayload" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactSettingsResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Update contact module settings", "tags": [ "contacts", "contact-settings", "Contact Settings" ] } }, "/api/v1/contacts/smart-groups": { "get": { "description": "List read-only smart groups for the tenant.", "operationId": "getSummaries", "parameters": [ { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SmartGroupListResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List smart contact groups", "tags": [ "contacts", "contact-smart-groups", "Smart Groups" ] }, "post": { "description": "Create a smart group from a whitelisted rule. Membership is materialized\nbefore the response returns; capped at 20 custom groups per tenant (409).", "operationId": "createSmartGroup", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSmartGroupRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomSmartGroupResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Create a user-defined smart group", "tags": [ "contacts", "contact-smart-groups", "Smart Groups" ] } }, "/api/v1/contacts/smart-groups/recompute": { "post": { "description": "Trigger a full smart-group recomputation for the tenant.", "operationId": "recompute", "parameters": [ { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SmartGroupListResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Recompute smart-group memberships", "tags": [ "contacts", "contact-smart-groups", "Smart Groups" ] } }, "/api/v1/contacts/smart-groups/{group_id}": { "delete": { "description": "Soft-delete a custom smart group and drop its membership rows. System\ngroups reject deletion (403).", "operationId": "deleteSmartGroup", "parameters": [ { "in": "path", "name": "group_id", "required": true, "schema": { "format": "uuid", "title": "Group Id", "type": "string" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Delete a user-defined smart group", "tags": [ "contacts", "contact-smart-groups", "Smart Groups" ] }, "put": { "description": "Edit a custom smart group's name/description/rule. System groups reject\nedits (403). A rule change re-materializes membership.", "operationId": "updateSmartGroup", "parameters": [ { "in": "path", "name": "group_id", "required": true, "schema": { "format": "uuid", "title": "Group Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSmartGroupRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomSmartGroupResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Update a user-defined smart group", "tags": [ "contacts", "contact-smart-groups", "Smart Groups" ] } }, "/api/v1/contacts/smart-groups/{group_id}/recompute": { "post": { "description": "Recompute membership for a single smart group (TIDY-13840). Fired after a\ngroup-style save so the styled group's wear materializes promptly instead of\nwaiting for the 6h scheduler. 404 if the id is not a live smart group.", "operationId": "recomputeGroup", "parameters": [ { "in": "path", "name": "group_id", "required": true, "schema": { "format": "uuid", "title": "Group Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SmartGroupListResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Recompute one smart group's membership", "tags": [ "contacts", "contact-smart-groups", "Smart Groups" ], "x-mcp-skip": true } }, "/api/v1/contacts/smart-groups/{group_type}/members": { "get": { "description": "Return the contacts belonging to a smart group.", "operationId": "getMembers", "parameters": [ { "in": "path", "name": "group_type", "required": true, "schema": { "title": "Group Type", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SmartGroupMembersResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get smart-group members", "tags": [ "contacts", "contact-smart-groups", "Smart Groups" ] } }, "/api/v1/contacts/sync": { "post": { "description": "Sync contacts from mobile device address book with KCC contacts.", "operationId": "syncContacts", "parameters": [ { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactSyncRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactSyncResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Sync device contacts", "tags": [ "contacts", "Contacts" ] } }, "/api/v1/contacts/sync/carddav": { "post": { "description": "Sync one specific connection or all CardDAV-capable connections.\n\nRuns connections SERIALLY (per TIDY-6640 D13) — CardDAV servers\nrate-limit per account, and serial execution matches the hourly\nscheduler pattern.", "operationId": "triggerCarddavSync", "parameters": [ { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/CardDAVBatchSyncRequest" }, { "type": "null" } ], "title": "Body" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/CardDAVConnectionSyncResult" }, "title": "Response Triggercarddavsync", "type": "array" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Trigger CardDAV contact sync for one or all connections", "tags": [ "contacts", "contact-sync", "Contact Sync" ] } }, "/api/v1/contacts/sync/google": { "post": { "description": "Trigger a one-way inbound sync from Google Contacts.\n\nRequires the caller's Google account connected for Contacts. A named\nconnection syncs that account only (TIDY-19604 F12).\nAdds new contacts, merges empty fields on existing contacts,\nand respects field locks.", "operationId": "triggerGoogleSync", "parameters": [ { "in": "query", "name": "connection_id", "required": false, "schema": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Connection Id" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GoogleSyncResult" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Trigger Google Contacts sync", "tags": [ "contacts", "contact-sync", "Contact Sync" ] } }, "/api/v1/contacts/sync/google-directory": { "post": { "description": "Trigger a one-way inbound sync from Google Workspace domain directory.\n\nFetches contacts from the organization's shared directory (domain\ncontacts and profiles). Only available for Google Workspace accounts;\nconsumer Google accounts will return 0 results.\n\nRequires an active Google calendar source (for OAuth tokens).", "operationId": "triggerDirectorySync", "parameters": [ { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GoogleSyncResult" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Trigger Google Workspace directory sync", "tags": [ "contacts", "contact-sync", "Contact Sync" ] } }, "/api/v1/contacts/sync/google/connections": { "get": { "description": "Return one row per active Google connection so the Contacts Sync UI\ncan render an account card per Google account (TIDY-8379).", "operationId": "getGoogleContactConnections", "parameters": [ { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/GoogleConnectionStatus" }, "title": "Response Getgooglecontactconnections", "type": "array" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Per-Google-connection contact sync status", "tags": [ "contacts", "contact-sync", "Contact Sync" ] } }, "/api/v1/contacts/sync/status": { "get": { "description": "Get sync status including last-sync timestamps and contact counts\nfor each configured sync source.", "operationId": "getContactSyncStatus", "parameters": [ { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_service__routers__contacts__sync__SyncStatusResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get contact sync status", "tags": [ "contacts", "contact-sync", "Contact Sync" ] } }, "/api/v1/contacts/vcard/bulk": { "post": { "description": "Generate and return a combined vCard 4.0 file for multiple contacts.", "operationId": "bulkVcardExport", "parameters": [ { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkVCardRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Bulkvcardexport", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Download vCard for multiple contacts", "tags": [ "contacts", "contact-vcard", "Contacts" ] } }, "/api/v1/contacts/vip": { "get": { "description": "Get VIP contacts (phone-synced) sorted by recent email activity.\n\nVIP contacts are identified by:\n- source_type = 'imported' (phone sync)\n- OR 'phone_sync' in contact_source array\n\nSorted by most recent email activity (sent_at DESC).", "operationId": "getVipContacts", "parameters": [ { "in": "query", "name": "limit", "required": false, "schema": { "default": 10, "maximum": 50, "minimum": 1, "title": "Limit", "type": "integer" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Getvipcontacts", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get VIP contacts sorted by recent email activity", "tags": [ "contacts", "Contacts" ] } }, "/api/v1/contacts/{contact_id}": { "delete": { "description": "Soft delete contact (sets deleted_at timestamp).", "operationId": "deleteContact", "parameters": [ { "description": "Typed ID with prefix 'C'", "in": "path", "name": "contact_id", "required": true, "schema": { "description": "Typed ID with prefix 'C'", "title": "Contact Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Delete contact", "tags": [ "contacts", "Contacts" ] }, "get": { "description": "Get contact details by ID.\n\nReads as the caller, or as the row's owner under that owner's ``contacts``\ndelegation grant — the same caller the list ran as. A 404 says whether\nthe id does not exist (``not_found``) or exists in this workspace but is\nnot visible to the caller (``not_visible``).", "operationId": "getContact", "parameters": [ { "description": "Typed ID with prefix 'C'", "in": "path", "name": "contact_id", "required": true, "schema": { "description": "Typed ID with prefix 'C'", "title": "Contact Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get contact details", "tags": [ "contacts", "Contacts" ] }, "patch": { "description": "Update contact fields using PATCH (partial update).", "operationId": "updateContactPatch", "parameters": [ { "description": "Typed ID with prefix 'C'", "in": "path", "name": "contact_id", "required": true, "schema": { "description": "Typed ID with prefix 'C'", "title": "Contact Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactUpdate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Update contact (partial update)", "tags": [ "contacts", "Contacts" ] }, "put": { "description": "Update contact fields using PUT (full resource replace).", "operationId": "updateContactPut", "parameters": [ { "description": "Typed ID with prefix 'C'", "in": "path", "name": "contact_id", "required": true, "schema": { "description": "Typed ID with prefix 'C'", "title": "Contact Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactUpdate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Update contact (full replace)", "tags": [ "contacts", "Contacts" ] } }, "/api/v1/contacts/{contact_id}/aliases": { "post": { "description": "Create a manual alias for a contact (source='manual').", "operationId": "createContactAlias", "parameters": [ { "in": "path", "name": "contact_id", "required": true, "schema": { "title": "Contact Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactAliasCreate" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactAliasResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Create Contact Alias", "tags": [ "contacts", "contact-aliases" ] } }, "/api/v1/contacts/{contact_id}/aliases/{alias_id}": { "delete": { "description": "Remove a contact alias.\n\nAliases with ``source='merge'`` are immutable for traceability and\nreturn 409. Manual + extraction-derived aliases delete normally.", "operationId": "deleteContactAlias", "parameters": [ { "in": "path", "name": "contact_id", "required": true, "schema": { "title": "Contact Id", "type": "string" } }, { "in": "path", "name": "alias_id", "required": true, "schema": { "title": "Alias Id", "type": "string" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Delete Contact Alias", "tags": [ "contacts", "contact-aliases" ] } }, "/api/v1/contacts/{contact_id}/approve": { "post": { "description": "Approve a contact flagged for review. Sets requires_review=false.", "operationId": "approveContact", "parameters": [ { "in": "path", "name": "contact_id", "required": true, "schema": { "title": "Contact Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Approve contact", "tags": [ "contacts", "Contacts" ] } }, "/api/v1/contacts/{contact_id}/audit": { "get": { "description": "Return recent audit_log rows for a contact, newest first.", "operationId": "getContactAuditLog", "parameters": [ { "in": "path", "name": "contact_id", "required": true, "schema": { "title": "Contact Id", "type": "string" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "maximum": 200, "minimum": 1, "title": "Limit", "type": "integer" } }, { "description": "Opaque cursor from prior page.", "in": "query", "name": "before", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Opaque cursor from prior page.", "title": "Before" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuditLogListResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Contact Audit Log", "tags": [ "contacts", "contact-audit" ] } }, "/api/v1/contacts/{contact_id}/avatar/convert": { "post": { "operationId": "convertContactPhotoToAvatar", "parameters": [ { "in": "path", "name": "contact_id", "required": true, "schema": { "title": "Contact Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AvatarConvertResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Convert a contact's photo into an avatar schema", "tags": [ "contacts", "Contacts" ], "x-mcp-skip": true, "x-mcp-skip-reason": "Avatar-creator UI flow: schema is pre-loaded for human review in the creator, never auto-saved — not an agent workflow." } }, "/api/v1/contacts/{contact_id}/avatar/select": { "put": { "description": "Select the contact's custom avatar (``avatar_schema``) as the displayed\n representation. Flips the single display discriminator\n ``contacts.photo_source`` to ``'custom_avatar'`` and clears any sticky\n photo selection so the avatar is the sole selected candidate. Photos\n remain the restore source — ``photo_url`` is untouched, so choosing a real\n photo afterwards repoints the display back to that photo.\n\n Returns 400 when the contact has no custom avatar to select.\n\n Response:\n {\n \"success\": true,\n \"avatar_selected\": true\n }\n\n Related: TIDY-13143 Custom Avatar Selection", "operationId": "selectContactCustomAvatar", "parameters": [ { "description": "Typed ID with prefix 'C'", "in": "path", "name": "contact_id", "required": true, "schema": { "description": "Typed ID with prefix 'C'", "title": "Contact Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Selectcontactcustomavatar", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Select the contact's custom avatar as the displayed representation", "tags": [ "contacts", "Contact Photos" ], "x-mcp-skip": true, "x-mcp-skip-reason": "Avatar/photo management UI flow — not an agent workflow." } }, "/api/v1/contacts/{contact_id}/convert-to-organization": { "post": { "description": "Convert a pending-review contact into an organization.", "operationId": "convertContact", "parameters": [ { "in": "path", "name": "contact_id", "required": true, "schema": { "title": "Contact Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityConversionResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Convert contact to organization", "tags": [ "contacts", "Contacts" ] } }, "/api/v1/contacts/{contact_id}/enrichment-metadata": { "get": { "description": "Return the v2 enrichment metadata for a contact.", "operationId": "getEnrichmentMetadata", "parameters": [ { "in": "path", "name": "contact_id", "required": true, "schema": { "title": "Contact Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnrichmentMetadataResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get enrichment metadata for a contact", "tags": [ "contacts", "contact-enrichment", "Contact Enrichment" ] } }, "/api/v1/contacts/{contact_id}/feedback": { "post": { "description": "Record thumbs feedback on a contact (TIDY-7557 R28).\n\nIdempotent flip: posting up then down updates the same row's thumb to\n-1 rather than inserting a duplicate.", "operationId": "setContactFeedback", "parameters": [ { "in": "path", "name": "contact_id", "required": true, "schema": { "title": "Contact Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactFeedbackRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactFeedbackResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Set Contact Feedback", "tags": [ "contacts", "contact-feedback" ] } }, "/api/v1/contacts/{contact_id}/field-locks": { "get": { "description": "Return field locks for a contact.", "operationId": "getFieldLocks", "parameters": [ { "in": "path", "name": "contact_id", "required": true, "schema": { "title": "Contact Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FieldLocksResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get field locks for a contact", "tags": [ "contacts", "contact-enrichment", "Contact Enrichment" ] } }, "/api/v1/contacts/{contact_id}/field-locks/{field_name}": { "delete": { "description": "Unlock a field so enrichment can update it again.", "operationId": "unlockField", "parameters": [ { "in": "path", "name": "contact_id", "required": true, "schema": { "title": "Contact Id", "type": "string" } }, { "in": "path", "name": "field_name", "required": true, "schema": { "title": "Field Name", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FieldLocksResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Unlock a field on a contact", "tags": [ "contacts", "contact-enrichment", "Contact Enrichment" ] }, "post": { "description": "Lock a field to prevent enrichment from overwriting it.", "operationId": "lockField", "parameters": [ { "in": "path", "name": "contact_id", "required": true, "schema": { "title": "Contact Id", "type": "string" } }, { "in": "path", "name": "field_name", "required": true, "schema": { "title": "Field Name", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FieldLocksResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Lock a field on a contact", "tags": [ "contacts", "contact-enrichment", "Contact Enrichment" ] } }, "/api/v1/contacts/{contact_id}/files": { "get": { "description": "Return every attachment from emails where the contact is a participant.\n\nIncludes historical emails not present in the local-first sync window.", "operationId": "listContactFiles", "parameters": [ { "description": "Typed ID with prefix 'C'", "in": "path", "name": "contact_id", "required": true, "schema": { "description": "Typed ID with prefix 'C'", "title": "Contact Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactFilesResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Aggregate email attachments exchanged with a contact", "tags": [ "contacts", "Contacts" ] } }, "/api/v1/contacts/{contact_id}/follow-ups": { "get": { "description": "Return open follow-up flags for a contact, newest first.", "operationId": "listContactFollowUps", "parameters": [ { "in": "path", "name": "contact_id", "required": true, "schema": { "format": "uuid", "title": "Contact Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactFollowUpsResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List a contact's open follow-ups", "tags": [ "contacts", "contacts" ] } }, "/api/v1/contacts/{contact_id}/history": { "get": { "description": "Get edit history entries for a single contact.", "operationId": "getContactHistory", "parameters": [ { "description": "Typed ID with prefix 'C'", "in": "path", "name": "contact_id", "required": true, "schema": { "description": "Typed ID with prefix 'C'", "title": "Contact Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactEditHistoryResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get contact edit history", "tags": [ "contacts", "Contacts" ] } }, "/api/v1/contacts/{contact_id}/history/{change_set_id}/restore": { "post": { "description": "Restore a prior contact edit batch using the stored old values.", "operationId": "restoreContactChangeSet", "parameters": [ { "in": "path", "name": "change_set_id", "required": true, "schema": { "title": "Change Set Id", "type": "string" } }, { "description": "Typed ID with prefix 'C'", "in": "path", "name": "contact_id", "required": true, "schema": { "description": "Typed ID with prefix 'C'", "title": "Contact Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Restore a contact change set", "tags": [ "contacts", "Contacts" ] } }, "/api/v1/contacts/{contact_id}/photo-from-face": { "post": { "description": "Promote a recognized face crop to the contact's profile photo (R36).\n\nCaller must see both the face's photo and the contact. Crops the face region\nserver-side (generous padding) from the ORIGINAL and routes it through the\nEXISTING contact_photos upload flow (source='manual', is_selected=true) —\nthe approval gate for contacts is untouched.\n\nTIDY-15490 — OBO write: the face is the subject, so authorization rides a\nread_write ``photos`` grant (no second contacts grant); both visibility\nchecks run under the resolved caller. Audit-before-act (R7).", "operationId": "contactPhotoFromFace", "parameters": [ { "in": "path", "name": "contact_id", "required": true, "schema": { "format": "uuid", "title": "Contact Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PhotoFromFaceRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PhotoFromFaceResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Contact Photo From Face", "tags": [ "photo-faces", "photo-faces" ], "x-mcp-skip": true, "x-mcp-skip-reason": "Face-recognition UI surface (overlays/markers/people rail); not an agent tool." } }, "/api/v1/contacts/{contact_id}/photos": { "get": { "description": "Get all available photos for a contact from all sources.\n\n Returns photos from: manual upload, device sync, Google People API,\n and locally-generated initials avatars. Photos marked as deleted are\n excluded. (Gravatar was removed for privacy — TIDY-10525.)\n\n Response:\n {\n \"photos\": [\n {\n \"id\": \"photo-uuid\",\n \"source\": \"google_people\",\n \"storage_path\": \"tenant/contacts/contact-id/google_people/...\",\n \"thumbnail_path\": \"..._thumb.jpg\",\n \"is_selected\": true,\n \"created_at\": \"2026-01-12T...\"\n }\n ],\n \"selected_source\": \"google_people\",\n \"photo_url\": \"...\"\n }\n\n Related: KCC-3163 Contact Photo Enrichment", "operationId": "listContactPhotos", "parameters": [ { "description": "Typed ID with prefix 'C'", "in": "path", "name": "contact_id", "required": true, "schema": { "description": "Typed ID with prefix 'C'", "title": "Contact Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Listcontactphotos", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List photos for a contact", "tags": [ "contacts", "Contact Photos" ] }, "post": { "description": "Upload a manual photo for a contact.\n\n Accepts: jpg, png, webp images up to 5MB.\n Images are resized and stored with thumbnails.\n Manual photos have highest priority and become the displayed photo.\n\n Request: multipart/form-data with 'file' field\n\n Response:\n {\n \"id\": \"photo-uuid\",\n \"source\": \"manual\",\n \"storage_path\": \"...\",\n \"thumbnail_path\": \"...\",\n \"is_selected\": true\n }\n\n Related: KCC-3163 Contact Photo Enrichment, US-6 Manual Photo Upload", "operationId": "uploadContactPhoto", "parameters": [ { "description": "Typed ID with prefix 'C'", "in": "path", "name": "contact_id", "required": true, "schema": { "description": "Typed ID with prefix 'C'", "title": "Contact Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/Body_uploadContactPhoto" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Uploadcontactphoto", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Upload a photo for a contact", "tags": [ "contacts", "Contact Photos" ] } }, "/api/v1/contacts/{contact_id}/photos/animated-avatar": { "post": { "description": "Upload the vector avatar's idle loop, rendered to an animated GIF by the\n editor, as one more profile photo for the contact and select it as the\n displayed photo. Earlier animated avatars stay in the profile photos, so\n switching back is the normal photo selection.\n\n Accepts: an animated GIF (at least two frames) up to 2 MB, multipart\n field 'file'. The first frame becomes the inline thumbnail — what\n reduced-motion readers and first paint show.\n\n Related: TIDY-19211", "operationId": "saveAnimatedAvatarPhoto", "parameters": [ { "description": "Typed ID with prefix 'C'", "in": "path", "name": "contact_id", "required": true, "schema": { "description": "Typed ID with prefix 'C'", "title": "Contact Id", "type": "string" } } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/Body_saveAnimatedAvatarPhoto" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SaveAnimatedAvatarResponse" } } }, "description": "Successful Response" }, "400": { "description": "Not an animated GIF, or too large." }, "404": { "description": "Contact not found." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Save the contact's animated avatar as a profile photo", "tags": [ "contacts", "Contact Photos" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/contacts/{contact_id}/photos/{photo_id}": { "delete": { "description": "Logically delete a photo from a contact.\n\n The photo is marked as deleted but preserved in the system.\n This prevents the photo from being re-synced from the same source.\n If the deleted photo was selected, falls back to priority order.\n\n Response:\n {\n \"success\": true,\n \"message\": \"Photo deleted\"\n }\n\n Related: KCC-3163 Contact Photo Enrichment, US-7 Photo Management", "operationId": "deleteContactPhoto", "parameters": [ { "in": "path", "name": "photo_id", "required": true, "schema": { "title": "Photo Id", "type": "string" } }, { "description": "Typed ID with prefix 'C'", "in": "path", "name": "contact_id", "required": true, "schema": { "description": "Typed ID with prefix 'C'", "title": "Contact Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Deletecontactphoto", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Delete a photo (logical delete)", "tags": [ "contacts", "Contact Photos" ] } }, "/api/v1/contacts/{contact_id}/photos/{photo_id}/select": { "put": { "description": "Select a specific photo to be the displayed photo for this contact.\n\n Overrides the default priority order (Manual > Device > Google > Generated).\n The selected photo becomes the contact's photo_url.\n\n Response:\n {\n \"success\": true,\n \"photo_id\": \"...\",\n \"photo_url\": \"...\"\n }\n\n Related: KCC-3163 Contact Photo Enrichment, US-7 Photo Management", "operationId": "selectContactPhoto", "parameters": [ { "in": "path", "name": "photo_id", "required": true, "schema": { "title": "Photo Id", "type": "string" } }, { "description": "Typed ID with prefix 'C'", "in": "path", "name": "contact_id", "required": true, "schema": { "description": "Typed ID with prefix 'C'", "title": "Contact Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Selectcontactphoto", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Select a photo as the primary display photo", "tags": [ "contacts", "Contact Photos" ] } }, "/api/v1/contacts/{contact_id}/profile-links": { "get": { "description": "Return all profile links for a contact.", "operationId": "getProfileLinks", "parameters": [ { "in": "path", "name": "contact_id", "required": true, "schema": { "title": "Contact Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProfileLinksResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get profile links for a contact", "tags": [ "contacts", "contact-enrichment", "Contact Enrichment" ] }, "post": { "description": "Add a new profile link to a contact's profile_links array.", "operationId": "addProfileLink", "parameters": [ { "in": "path", "name": "contact_id", "required": true, "schema": { "title": "Contact Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProfileLinkCreate" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProfileLinksResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Add a profile link to a contact", "tags": [ "contacts", "contact-enrichment", "Contact Enrichment" ] } }, "/api/v1/contacts/{contact_id}/profile-links/{index}": { "delete": { "description": "Remove a profile link at the given index.", "operationId": "removeProfileLink", "parameters": [ { "in": "path", "name": "contact_id", "required": true, "schema": { "title": "Contact Id", "type": "string" } }, { "in": "path", "name": "index", "required": true, "schema": { "title": "Index", "type": "integer" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProfileLinksResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Remove a profile link by index", "tags": [ "contacts", "contact-enrichment", "Contact Enrichment" ] } }, "/api/v1/contacts/{contact_id}/promote": { "post": { "description": "Promote a contact from shadow/pending_review to 'promoted' visibility.\n\n KCC-3223: Shadow Contact Promotion System\n Promoted contacts are included in VIP matching for signal-aware extraction.\n\n Response: Updated contact with visibility='promoted'\n\n Error Responses:\n - 401 Unauthorized: Missing or invalid JWT token\n - 404 Not Found: Contact does not exist or does not belong to your tenant\n - 500 Internal Server Error: Database operation failed\n\n Related: KCC-3223, migration 236_shadow_contacts.sql", "operationId": "promoteContactVisibility", "parameters": [ { "in": "path", "name": "contact_id", "required": true, "schema": { "title": "Contact Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Promote a contact to full visibility", "tags": [ "contacts", "Contact Promotion" ] } }, "/api/v1/contacts/{contact_id}/provenance/seen": { "post": { "description": "Stamp ``seen_by[account_id]=now()`` on all the contact's provenance rows.", "operationId": "markContactProvenanceSeen", "parameters": [ { "description": "Typed ID with prefix 'C'", "in": "path", "name": "contact_id", "required": true, "schema": { "description": "Typed ID with prefix 'C'", "title": "Contact Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProvenanceSeenResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Mark a contact's field-provenance highlights seen", "tags": [ "contacts", "Contacts" ], "x-mcp-skip": true } }, "/api/v1/contacts/{contact_id}/reject": { "post": { "description": "Reject a visible contact through the shared review decision writer.", "operationId": "rejectContact", "parameters": [ { "in": "path", "name": "contact_id", "required": true, "schema": { "title": "Contact Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Rejectcontact", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Reject contact", "tags": [ "contacts", "Contacts" ] } }, "/api/v1/contacts/{contact_id}/reject-promotion": { "post": { "description": "Reject a contact, setting visibility='rejected'.\n\n KCC-3223: Shadow Contact Promotion System\n Rejected contacts are hidden from VIP matching and won't appear in\n the pending review queue again.\n\n Response: {\"message\": \"Contact rejected\", \"id\": \"...\"}\n\n Error Responses:\n - 401 Unauthorized: Missing or invalid JWT token\n - 404 Not Found: Contact does not exist or does not belong to your tenant\n - 500 Internal Server Error: Database operation failed\n\n Related: KCC-3223, migration 236_shadow_contacts.sql", "operationId": "rejectContactPromotion", "parameters": [ { "in": "path", "name": "contact_id", "required": true, "schema": { "title": "Contact Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Rejectcontactpromotion", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Reject a contact from promotion", "tags": [ "contacts", "Contact Promotion" ] } }, "/api/v1/contacts/{contact_id}/reports-to": { "put": { "description": "Place the contact under ``manager_contact_id`` on the org chart, or pass null to move them to the top. The line is written in an organization the two already share (the workspace's team organization first), otherwise in the team organization, which either person joins if they are not in it. A move changes only this organization's line, preserving every other organization. Pass organization_id to choose it explicitly, or team_organization=true for the workspace team. Existing alias memberships retain their subtree. A private non-directory card on the team chart is flagged (``private_on_team_chart``, ``manager_private_on_team_chart``): only its owner sees it there. Directory identities (workspace members and virtual employees) remain visible to every co-member regardless of their stored visibility tier. Every placement needs a workspace owner or admin, or someone who answers for the employee being placed (403 ``org_chart_not_allowed``); a manager who reports to the person returns 422 ``hierarchy_cycle``.", "operationId": "setContactReportsTo", "parameters": [ { "description": "Typed ID with prefix 'C'", "in": "path", "name": "contact_id", "required": true, "schema": { "description": "Typed ID with prefix 'C'", "title": "Contact Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactReportsToUpdate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactReportsToResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Set who a person reports to", "tags": [ "organizations", "Organizations" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Org chart drag-and-drop UI flow — membership rows are local-first synced." } }, "/api/v1/contacts/{contact_id}/star": { "post": { "description": "Star a contact to mark it as VIP.", "operationId": "starContact", "parameters": [ { "description": "Typed ID with prefix 'C'", "in": "path", "name": "contact_id", "required": true, "schema": { "description": "Typed ID with prefix 'C'", "title": "Contact Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Star a contact (mark as VIP)", "tags": [ "contacts", "Contacts" ] } }, "/api/v1/contacts/{contact_id}/unstar": { "post": { "description": "Unstar a contact to remove VIP status.", "operationId": "unstarContact", "parameters": [ { "description": "Typed ID with prefix 'C'", "in": "path", "name": "contact_id", "required": true, "schema": { "description": "Typed ID with prefix 'C'", "title": "Contact Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Unstar a contact (remove VIP status)", "tags": [ "contacts", "Contacts" ] } }, "/api/v1/contacts/{contact_id}/vcard": { "get": { "description": "Generate and return a vCard 4.0 file for a single contact.", "operationId": "getContactVcard", "parameters": [ { "in": "path", "name": "contact_id", "required": true, "schema": { "title": "Contact Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Getcontactvcard", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Download single contact vCard", "tags": [ "contacts", "contact-vcard", "Contacts" ] } }, "/api/v1/conversation-channels/departures/finish": { "post": { "operationId": "finishConversationChannelDeparture", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FinishDepartureRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FinishDepartureResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Finish an employee's departure from a conversation channel once its turn is published", "tags": [ "agents" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "The connector's publication step, on the employee's runtime PAT." } }, "/api/v1/conversation-channels/leave": { "post": { "description": "The employee whose turn credential names a conversation in a channel it\nwas invited into leaves it (TIDY-20074 F12); anything else is refused.", "operationId": "leaveConversationChannel", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LeaveConversationChannelRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationChannelDepartureResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Leave the conversation channel this turn is in, once its reply is posted, and carry on", "tags": [ "agents" ], "x-local-capability": "cloud" } }, "/api/v1/conversation-channels/{room_id}/invites": { "post": { "operationId": "inviteToConversationChannel", "parameters": [ { "in": "path", "name": "room_id", "required": true, "schema": { "maxLength": 255, "minLength": 3, "title": "Room Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InviteToConversationChannelRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationChannelResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Invite the people @mentioned into a channel opened from a conversation", "tags": [ "agents" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "A person's chat composer action; employees invite nobody." } }, "/api/v1/conversations/search": { "get": { "description": "One result per conversation, best hit first, with per-hit lane honesty\n(``matched_in``: message / title / chat / item_link) and item bindings.", "operationId": "searchConversations", "parameters": [ { "description": "Full-text query (websearch syntax).", "in": "query", "name": "q", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Full-text query (websearch syntax).", "title": "Q" } }, { "description": "Narrow to one employee's conversations — an agent member id, the agent's account id, or `assistant` for the built-in Tidy Assistant. Ignored for agent callers (they are always scoped to their own history).", "in": "query", "name": "employee", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Narrow to one employee's conversations — an agent member id, the agent's account id, or `assistant` for the built-in Tidy Assistant. Ignored for agent callers (they are always scoped to their own history).", "title": "Employee" } }, { "description": "Typed item id (`A-<uuid>`, `N-<uuid>`, …). Restricts results to conversations bound to the item through its assignment episodes.", "in": "query", "name": "item_ref", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Typed item id (`A-<uuid>`, `N-<uuid>`, …). Restricts results to conversations bound to the item through its assignment episodes.", "title": "Item Ref" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 20, "maximum": 50, "minimum": 1, "title": "Limit", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationSearchResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Full-text search over the caller's conversation history", "tags": [ "agents" ], "x-local-capability": "cloud" } }, "/api/v1/conversations/{conversation_id}/browser-trails": { "get": { "description": "The browser trail of one turn, for a person who may read the conversation.\n\nPictures are listed only of a browser the caller may watch.", "operationId": "listBrowserTrails", "parameters": [ { "in": "path", "name": "conversation_id", "required": true, "schema": { "format": "uuid", "title": "Conversation Id", "type": "string" } }, { "in": "query", "name": "turn_ref", "required": true, "schema": { "maxLength": 512, "minLength": 1, "title": "Turn Ref", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrowserTrailsResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List Browser Trails", "tags": [ "browser-trails" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "The pictures and steps behind a turn's Show work; the employee already has its own turn, and readers open it in the conversation." } }, "/api/v1/conversations/{conversation_id}/browser-trails/{trail_id}/pictures/{index}": { "get": { "description": "One masked picture of a trail, authorized on every read.", "operationId": "getBrowserTrailPicture", "parameters": [ { "in": "path", "name": "conversation_id", "required": true, "schema": { "format": "uuid", "title": "Conversation Id", "type": "string" } }, { "in": "path", "name": "trail_id", "required": true, "schema": { "format": "uuid", "title": "Trail Id", "type": "string" } }, { "in": "path", "name": "index", "required": true, "schema": { "exclusiveMaximum": 16, "minimum": 0, "title": "Index", "type": "integer" } } ], "responses": { "200": { "content": { "image/jpeg": { "schema": { "format": "binary", "type": "string" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Browser Trail Picture", "tags": [ "browser-trails" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "The pictures and steps behind a turn's Show work; the employee already has its own turn, and readers open it in the conversation." } }, "/api/v1/conversations/{conversation_id}/channel": { "post": { "operationId": "openConversationChannel", "parameters": [ { "in": "path", "name": "conversation_id", "required": true, "schema": { "maxLength": 36, "minLength": 36, "title": "Conversation Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenConversationChannelRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationChannelResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Move a conversation with an employee into a new channel with the people @mentioned", "tags": [ "agents" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "A person's chat composer action; employees invite nobody." } }, "/api/v1/conversations/{conversation_id}/harness-frames/export": { "post": { "description": "Copy one employee conversation's raw harness-frame log (TIDY-19927)\nfrom the workshop that runs it into the caller's files, private to them.\n\nThe employee's owner, or a workspace Owner/Admin, who may attach to that\nworkshop. `capture_hours` switches the conversation's capture on as well,\nfrom its next turn; what was recorded so far is exported now.", "operationId": "exportConversationHarnessFrames", "parameters": [ { "in": "path", "name": "conversation_id", "required": true, "schema": { "format": "uuid", "title": "Conversation Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HarnessFramesExportRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SnapshotResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Export Conversation Harness Frames", "tags": [ "project-roots" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/conversations/{conversation_id}/transcript": { "get": { "description": "Oldest first. A conversation the caller may not read — missing, another\nmember's, or never shared with this employee — is one 404\n``session_not_shared_with_employee``; it never reveals which.", "operationId": "getConversationTranscript", "parameters": [ { "in": "path", "name": "conversation_id", "required": true, "schema": { "format": "uuid", "title": "Conversation Id", "type": "string" } }, { "description": "Only the messages in THIS conversation that match (full-text or substring).", "in": "query", "name": "q", "required": false, "schema": { "anyOf": [ { "maxLength": 500, "type": "string" }, { "type": "null" } ], "description": "Only the messages in THIS conversation that match (full-text or substring).", "title": "Q" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 1000, "maximum": 1000, "minimum": 1, "title": "Limit", "type": "integer" } }, { "in": "query", "name": "offset", "required": false, "schema": { "default": 0, "minimum": 0, "title": "Offset", "type": "integer" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionTranscriptResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Read one conversation's transcript (yours, or one shared with you)", "tags": [ "agents" ], "x-local-capability": "cloud" } }, "/api/v1/convert/check-duplicate": { "post": { "operationId": "convertCheckDuplicate", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConvertCheckDuplicateRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConvertCheckDuplicateResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Check whether a note with this import_file_hash already exists", "tags": [ "convert", "convert" ] } }, "/api/v1/convert/docx": { "post": { "operationId": "convertDocx", "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/Body_convertDocx" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConvertDocxResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Convert a .docx file to a Tidy note", "tags": [ "convert", "convert" ] } }, "/api/v1/convert/health": { "get": { "operationId": "convertHealth", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConvertHealthResponse" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "doc-service pool + echo-worker liveness probe", "tags": [ "convert", "convert" ] } }, "/api/v1/convert/pptx": { "post": { "operationId": "convertPptx", "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/Body_convertPptx" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConvertPptxResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Convert a .pptx file to a Tidy note (text extraction)", "tags": [ "convert", "convert" ] } }, "/api/v1/convert/xlsx": { "post": { "operationId": "convertXlsx", "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/Body_convertXlsx" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConvertXlsxResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Convert an .xlsx file to a Tidy spreadsheet note", "tags": [ "convert", "convert" ] } }, "/api/v1/credits/balance": { "get": { "description": "Pooled credit balance for the caller's account + the caller's ration.", "operationId": "getCreditBalance", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditBalanceResponse" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Credit Balance", "tags": [ "credits", "credits" ], "x-mcp-skip": true } }, "/api/v1/credits/caps": { "put": { "description": "Owner sets or clears a per-user hard cap (D13). Only an explicit null clears it.\n\nTwo things this deliberately does NOT do (TIDY-15867):\n\n**A cap of 0 is not a clear.** It previously was (`<= 0` meant \"remove\"),\nwhich made zero unusable as what it plainly reads as — this member may draw\nnothing this period. Absence is `null`; zero is a number the owner typed.\n\n**Clearing NULLs the column instead of deleting the row.** The same row\ncarries `provider_cap_micros`, so dropping it silently cleared a BYO\nprovider cap the caller never touched.", "operationId": "updateCreditUserCap", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserCapRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserCapResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Update Credit User Cap", "tags": [ "credits", "credits" ], "x-mcp-skip": true } }, "/api/v1/credits/consent": { "post": { "description": "An account owner approves a member's past-checkpoint continue. Audited.", "operationId": "mintCreditConsent", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OwnerConsentRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OwnerConsentResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Mint Owner Consent", "tags": [ "credits", "credits" ], "x-mcp-skip": true } }, "/api/v1/credits/settings": { "put": { "description": "Owner upserts the account's credit controls (D13). Only the supplied\nfields change; a NULL checkpoint_pct clears the override to the config\ndefault.", "operationId": "updateCreditControls", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OwnerControlsRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OwnerControlsResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Update Credit Controls", "tags": [ "credits", "credits" ], "x-mcp-skip": true } }, "/api/v1/credits/topup": { "post": { "operationId": "createCreditTopup", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TopupRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TopupResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Create Credit Topup", "tags": [ "credits", "credits" ], "x-mcp-skip": true } }, "/api/v1/credits/usage": { "get": { "description": "One-shot usage snapshot for the meter/chip/settings surface. Fetched on\nsurface open and after consent/top-up events — never polled.", "operationId": "getCreditUsage", "parameters": [ { "description": "Set to 'users' for the owner-only per-user rollup", "in": "query", "name": "rollup", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Set to 'users' for the owner-only per-user rollup", "title": "Rollup" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditUsageResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Credit Usage", "tags": [ "credits", "credits" ], "x-mcp-skip": true } }, "/api/v1/crm/access-keys/issue": { "post": { "description": "One key per member: a re-ask returns the key they already hold.\n\nAn exhausted pool is a 409, not a substitute code — the agent tells the\nmember it cannot issue right now and escalates to the Manager. Mirroring\nthe issued key onto a lead record is the caller's follow-up through\n``POST /api/v1/crm/lead-capture`` with the tenant's own lead facet — the\nplatform holds no lead vocabulary (TIDY-16774).", "operationId": "crmIssueAccessKey", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccessKeyIssueRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccessKeyIssueResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Issue this Discord member's beta key (idempotent per handle)", "tags": [ "crm-access-keys" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/crm/access-keys/stock": { "get": { "operationId": "crmAccessKeyStock", "parameters": [ { "in": "query", "name": "prefix", "required": false, "schema": { "default": "DISCORD", "maxLength": 32, "minLength": 1, "title": "Prefix", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccessKeyStockResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Stock level of the beta-key pool", "tags": [ "crm-access-keys" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/crm/access-keys/unredeemed": { "get": { "description": "The friendly-follow-up queue (R17): who has a key and never used it.", "operationId": "crmUnredeemedAccessKeys", "parameters": [ { "in": "query", "name": "older_than_days", "required": false, "schema": { "default": 7, "maximum": 365, "minimum": 1, "title": "Older Than Days", "type": "integer" } }, { "in": "query", "name": "prefix", "required": false, "schema": { "default": "DISCORD", "maxLength": 32, "minLength": 1, "title": "Prefix", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccessKeyUnredeemedResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Keys issued but never redeemed, older than N days", "tags": [ "crm-access-keys" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/crm/lead-capture": { "post": { "deprecated": true, "description": "DEPRECATED (TIDY-16813) — use POST /api/v1/capture, which captures onto any facet with any match key. This door is a thin delegation to that implementation with target_table='contacts' and match_field='email'; its behaviour, including its error contract, is unchanged. It keeps serving while installed pack workflows still call it (TIDY-16882 / D3); removal conditions are posted on TIDY-16805.", "operationId": "captureCrmLead", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LeadCaptureRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LeadCaptureResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Capture Crm Lead", "tags": [ "crm" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/crm/leads/forget": { "post": { "deprecated": true, "description": "DEPRECATED (TIDY-16882) — compose the same erasure from POST /api/v1/crm/suppressions and the primitive delete surface. Still serving, unchanged, until a full release-train cycle passes with no deprecation log.", "operationId": "crmForgetLead", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForgetLeadRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForgetLeadResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Forget a lead: erase record + enrichment, suppress the address", "tags": [ "crm-compliance" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/crm/leads/{contact_id}/customer-link": { "delete": { "description": "Remove a lead's customer link, with member audit.", "operationId": "unlinkCrmLeadCustomer", "parameters": [ { "in": "path", "name": "contact_id", "required": true, "schema": { "title": "Contact Id", "type": "string" } }, { "description": "The contact facet whose pipeline this contact belongs to (e.g. the tenant's installed lead facet). Required: the caller resolves it from the tenant's own facet definitions — the platform holds no default pipeline vocabulary (TIDY-16775).", "in": "query", "name": "facet_slug", "required": true, "schema": { "description": "The contact facet whose pipeline this contact belongs to (e.g. the tenant's installed lead facet). Required: the caller resolves it from the tenant's own facet definitions — the platform holds no default pipeline vocabulary (TIDY-16775).", "minLength": 1, "title": "Facet Slug", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerLinkResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Unlink Customer", "tags": [ "crm" ], "x-local-capability": "cloud", "x-mcp-skip": true }, "put": { "description": "Manually join a lead to a Tidy account, with member audit.", "operationId": "linkCrmLeadCustomer", "parameters": [ { "in": "path", "name": "contact_id", "required": true, "schema": { "title": "Contact Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerLinkRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerLinkResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Link Customer", "tags": [ "crm" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/crm/proposal-acceptance-metrics": { "get": { "description": "How the tenant's CRM proposals are being decided, and why v1 still asks.\n\nThe rollup is refreshed for this tenant before it is read. That is a\nprojection recompute, not an accumulation — replaying it over unchanged\nproposals produces the same counters — so a read is always current without\nwaiting for the hourly sweep.\n\n``automation_promotion`` reports the promotion gate's verdict alongside the\nnumbers, so the surface that shows an acceptance rate also shows that the\nrate grants nothing: v1 has no auto-approval contract to satisfy.", "operationId": "getCrmProposalAcceptanceMetrics", "parameters": [ { "in": "query", "name": "since", "required": false, "schema": { "anyOf": [ { "format": "date", "type": "string" }, { "type": "null" } ], "title": "Since" } }, { "in": "query", "name": "until", "required": false, "schema": { "anyOf": [ { "format": "date", "type": "string" }, { "type": "null" } ], "title": "Until" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcceptanceMetricsResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Crm Proposal Acceptance Metrics", "tags": [ "crm-proposals" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/crm/proposal-suppressions": { "get": { "description": "The caller's own mutes, newest decision first.\n\nReversed and lapsed rows are included by default — a mute you want to\nreverse has to be findable, and the reversal history is what makes the\ndecision auditable. Another member's mutes are never visible here.", "operationId": "listCrmProposalSuppressions", "parameters": [ { "in": "query", "name": "active_only", "required": false, "schema": { "default": false, "title": "Active Only", "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuppressionListResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List Crm Proposal Suppressions", "tags": [ "crm-proposals" ], "x-local-capability": "cloud", "x-mcp-skip": true }, "post": { "description": "Mute a scope with no proposal in hand — or re-arm one already reversed.\n\nIdempotent: re-muting a scope lands on the same row with the same id rather\nthan minting a second policy for the same decision.", "operationId": "createCrmProposalSuppression", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuppressionCreateRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuppressionRecordModel" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Create Crm Proposal Suppression", "tags": [ "crm-proposals" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/crm/proposal-suppressions/{suppression_id}": { "delete": { "description": "Re-enable a muted scope. The row stays as history, deactivated.", "operationId": "releaseCrmProposalSuppression", "parameters": [ { "in": "path", "name": "suppression_id", "required": true, "schema": { "title": "Suppression Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuppressionReleaseResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Release Crm Proposal Suppression", "tags": [ "crm-proposals" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/crm/proposals/{proposal_id}/approve": { "post": { "description": "Approve a pending proposal: link contact↔organization and mint the mapping.", "operationId": "approveCrmProposal", "parameters": [ { "in": "path", "name": "proposal_id", "required": true, "schema": { "title": "Proposal Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProposalApproveRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProposalApproveResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Approve Crm Proposal", "tags": [ "crm-proposals" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/crm/proposals/{proposal_id}/suppress": { "post": { "description": "Mute the scope and (by default) dismiss this proposal as ``rejected``.", "operationId": "suppressCrmProposal", "parameters": [ { "in": "path", "name": "proposal_id", "required": true, "schema": { "title": "Proposal Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProposalSuppressRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProposalSuppressResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Suppress Crm Proposal", "tags": [ "crm-proposals" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/crm/suppression-check": { "get": { "deprecated": true, "description": "DEPRECATED (TIDY-16882) — use GET /api/v1/crm/suppressions, the keyset-paginated registry that answers the same question for every address at once. Still serving, unchanged, until a full release-train cycle passes with no deprecation log.", "operationId": "crmSuppressionCheck", "parameters": [ { "in": "query", "name": "email", "required": true, "schema": { "maxLength": 320, "minLength": 3, "title": "Email", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuppressionCheckResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Preflight: may this address be emailed?", "tags": [ "crm-compliance" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/crm/suppressions": { "get": { "description": "The tenant's suppression registry, keyset-paginated by address.\n\nThe read half of the one suppression module (TIDY-16833 / R2): a reconcile —\nthe platform module today, a signed-HTTP workflow next — diffs the provider's\naccount-suppression list against this. Owner/Admin only: the registry is the\ntenant's compliance state, and it is a list of addresses the tenant mailed.", "operationId": "listCrmSuppressions", "parameters": [ { "description": "Opaque page cursor from the previous response's next_cursor.", "in": "query", "name": "cursor", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Opaque page cursor from the previous response's next_cursor.", "title": "Cursor" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 200, "maximum": 1000, "minimum": 1, "title": "Limit", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CrmSuppressionListResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List Suppressions", "tags": [ "crm-suppressions" ], "x-local-capability": "cloud", "x-mcp-skip": true }, "post": { "description": "Manually suppress an address: suppression + consent + audit rows.", "operationId": "suppressCrmContact", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManualSuppressRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManualSuppressResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Suppress Contact", "tags": [ "crm-suppressions" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/crm/suppressions/remove": { "post": { "description": "Lift a suppression — the audited member resubscribe path (R13).", "operationId": "unsuppressCrmContact", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManualUnsuppressRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManualUnsuppressResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Unsuppress Contact", "tags": [ "crm-suppressions" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/crm/unsubscribe-link": { "post": { "deprecated": true, "description": "DEPRECATED (TIDY-16882) — a send now resolves its link from the tenant's designated unsubscribe publication (TIDY-16835). Still serving, unchanged, until a full release-train cycle passes with no deprecation log.", "operationId": "crmMintUnsubscribeLink", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnsubscribeLinkRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnsubscribeLinkResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Mint the RFC 8058 unsubscribe link for an agent 1:1 send", "tags": [ "crm-compliance" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/cross-account/audit": { "get": { "operationId": "listAudit", "parameters": [ { "in": "query", "name": "action", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Action" } }, { "in": "query", "name": "target_account_id", "required": false, "schema": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Target Account Id" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "maximum": 200, "minimum": 1, "title": "Limit", "type": "integer" } }, { "in": "query", "name": "offset", "required": false, "schema": { "default": 0, "minimum": 0, "title": "Offset", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_service__routers__cross_account__AuditListResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Cross-account audit log", "tags": [ "cross-account" ] } }, "/api/v1/cross-account/permissions": { "get": { "operationId": "listPermissions", "parameters": [ { "in": "query", "name": "status", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Status" } }, { "in": "query", "name": "target_account_id", "required": false, "schema": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Target Account Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/PermissionResponse" }, "title": "Response Listpermissions", "type": "array" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List cross-account permissions", "tags": [ "cross-account" ] }, "post": { "operationId": "createPermission", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PermissionCreateRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PermissionResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Request cross-account permission", "tags": [ "cross-account" ] } }, "/api/v1/cross-account/permissions/{permission_id}": { "delete": { "operationId": "revokePermission", "parameters": [ { "in": "path", "name": "permission_id", "required": true, "schema": { "format": "uuid", "title": "Permission Id", "type": "string" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Revoke cross-account permission", "tags": [ "cross-account" ] } }, "/api/v1/cross-account/permissions/{permission_id}/approve": { "post": { "operationId": "approvePermission", "parameters": [ { "in": "path", "name": "permission_id", "required": true, "schema": { "format": "uuid", "title": "Permission Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PermissionResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Approve cross-account permission", "tags": [ "cross-account" ] } }, "/api/v1/database-facets": { "post": { "description": "Create a canonical Database facet row, idempotent on client ids.", "operationId": "createDatabaseFacet", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatabaseFacetCreateRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatabaseFacetResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Create a Database facet record", "tags": [ "database-facets", "database-facets" ], "x-mcp-skip": true, "x-mcp-skip-reason": "Editor Database facet persistence API; MCP has no Database facet tool yet." } }, "/api/v1/database-facets/auto-name": { "get": { "description": "Return the same auto-title used by create when title is null.", "operationId": "getDatabaseFacetAutoName", "parameters": [ { "description": "Facet slugs included in the query", "in": "query", "name": "query_facets[]", "required": false, "schema": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "description": "Facet slugs included in the query", "title": "Query Facets[]" } }, { "description": "JSON-encoded Database filter object", "in": "query", "name": "filters", "required": false, "schema": { "default": "{}", "description": "JSON-encoded Database filter object", "title": "Filters", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatabaseFacetAutoNameResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Auto-name a Database facet query", "tags": [ "database-facets", "database-facets" ], "x-mcp-skip": true, "x-mcp-skip-reason": "Editor Database facet persistence API; MCP has no Database facet tool yet." } }, "/api/v1/database-facets/saved-views": { "post": { "description": "Create/upsert a saved database view in the canonical form (D16/D17).\n\nValidates layout against the facet's view mappings and filter properties\nagainst the facet schema (loud 422s), authors a database-facet record\nparented to the project page + a project-scoped pin, idempotent by\n(project, title). A project the caller cannot see is a 404 (R50). Returns\n``action='created'|'updated'``.", "operationId": "createSavedDatabaseView", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SavedViewCreateRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SavedViewCreateResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Author a saved database view (project, note, or workspace container)", "tags": [ "database-facets", "database-facets" ] } }, "/api/v1/database-facets/{database_facet_id}": { "delete": { "description": "Delete a saved view you may edit (TIDY-19456).\n\nTakes its database node out of the note it was authored into, removes your\nsaved-views nav pins of it, then soft-deletes the row. A view you cannot\nedit is a 404 and stays as it was.", "operationId": "deleteDatabaseFacet", "parameters": [ { "in": "path", "name": "database_facet_id", "required": true, "schema": { "format": "uuid", "title": "Database Facet Id", "type": "string" } }, { "description": "Your own UUID for this delete. A retry with the same id replays the first result; the same id naming a different view is refused (operation_input_drift).", "in": "query", "name": "operation_id", "required": false, "schema": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "description": "Your own UUID for this delete. A retry with the same id replays the first result; the same id naming a different view is refused (operation_input_drift).", "title": "Operation Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SavedViewDeleteResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Delete a saved database view", "tags": [ "database-facets", "database-facets" ], "x-local-capability": "cloud" }, "get": { "description": "Return a visible canonical Database facet row.", "operationId": "getDatabaseFacet", "parameters": [ { "in": "path", "name": "database_facet_id", "required": true, "schema": { "format": "uuid", "title": "Database Facet Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatabaseFacetResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get a Database facet record", "tags": [ "database-facets", "database-facets" ], "x-mcp-skip": true, "x-mcp-skip-reason": "Editor Database facet persistence API; MCP has no Database facet tool yet." }, "patch": { "description": "Update the canonical Database facet row without editing embeds.", "operationId": "updateDatabaseFacet", "parameters": [ { "in": "path", "name": "database_facet_id", "required": true, "schema": { "format": "uuid", "title": "Database Facet Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatabaseFacetUpdateRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatabaseFacetResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Patch a Database facet record", "tags": [ "database-facets", "database-facets" ], "x-mcp-skip": true, "x-mcp-skip-reason": "Editor Database facet persistence API; MCP has no Database facet tool yet." } }, "/api/v1/database-facets/{database_facet_id}/rows": { "get": { "description": "Resolve an embedded database view to ``{columns, rows}`` (TIDY-14037 / S4).\n\nRuns under the caller's member-visible predicate. Used by the report-export\nlane to flatten a query embed into a static table; a not-visible/missing\nfacet 404s so the export fails loud rather than shipping an empty section.", "operationId": "getDatabaseFacetRows", "parameters": [ { "in": "path", "name": "database_facet_id", "required": true, "schema": { "format": "uuid", "title": "Database Facet Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatabaseFacetRowsResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Resolve a Database facet view to a static table", "tags": [ "database-facets", "database-facets" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Editor Database facet persistence API; MCP has no Database facet tool yet." } }, "/api/v1/database-facets/{database_facet_id}/usage": { "get": { "description": "Where a view you can see is used, across the whole workspace (TIDY-19705 F9).\n\nLists the notes, journals, tasks, templates, forms, charts, dashboards, facet\ntemplates, workstations and nav pins you can open that embed, name or pin\nit; every other place is counted in ``hidden_places`` and never described.\n``in_use`` is false only when nothing anywhere uses it.", "operationId": "getDatabaseViewUsage", "parameters": [ { "in": "path", "name": "database_facet_id", "required": true, "schema": { "format": "uuid", "title": "Database Facet Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatabaseViewUsageResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Where a saved database view is used", "tags": [ "database-facets", "database-facets" ], "x-local-capability": "cloud" } }, "/api/v1/defense/emails/{email_id}/journey": { "get": { "description": "Return the email's ordered defense events. 404 if the caller does not own\nthe email (or it has no journey).", "operationId": "getEmailDefenseJourney", "parameters": [ { "in": "path", "name": "email_id", "required": true, "schema": { "title": "Email Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/DefenseEventResponse" }, "title": "Response Getemaildefensejourney", "type": "array" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Ordered per-gate defense journey for an email", "tags": [ "defense", "defense" ], "x-mcp-skip": true } }, "/api/v1/defense/find-email": { "get": { "description": "Search the caller's mail across delivered, done, quarantined, blocked, and\nscreened states — the \"I never got the email from X\" audit.", "operationId": "findDefenseEmail", "parameters": [ { "description": "Sender address/domain substring", "in": "query", "name": "sender", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Sender address/domain substring", "title": "Sender" } }, { "description": "Subject contains", "in": "query", "name": "subject", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Subject contains", "title": "Subject" } }, { "in": "query", "name": "window_days", "required": false, "schema": { "default": 30, "maximum": 90, "minimum": 1, "title": "Window Days", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FindEmailResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Find email across ALL dispositions with the firing rule attached", "tags": [ "defense", "defense" ], "x-mcp-skip": true } }, "/api/v1/defense/journey-state": { "get": { "description": "Return the derived journey stage, founded pack set, and counts.", "operationId": "getDefenseJourneyState", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JourneyStateResponse" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Defense growth-journey state for the caller's tenant", "tags": [ "defense", "defense" ], "x-mcp-skip": true } }, "/api/v1/defense/journey/daily": { "get": { "description": "Return the caller's defense events for the given UTC day, paginated —\nthe Layer 3 replay feed.", "operationId": "getDailyDefenseJourney", "parameters": [ { "description": "YYYY-MM-DD (UTC); defaults to today", "in": "query", "name": "date", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "YYYY-MM-DD (UTC); defaults to today", "title": "Date" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 500, "maximum": 2000, "minimum": 1, "title": "Limit", "type": "integer" } }, { "in": "query", "name": "offset", "required": false, "schema": { "default": 0, "minimum": 0, "title": "Offset", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/DefenseEventResponse" }, "title": "Response Getdailydefensejourney", "type": "array" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "The caller's defense events for a day (paginated)", "tags": [ "defense", "defense" ], "x-mcp-skip": true } }, "/api/v1/defense/replay": { "get": { "description": "Assemble the caller's email defense journeys for one local day — the\nLayer 3 replay feed. Owner-scoped: only the caller's own journeys are\nreturned. Day boundaries use the caller's preferred tz (or the `tz`\noverride) per the canonical time rules.", "operationId": "getDefenseReplay", "parameters": [ { "description": "YYYY-MM-DD; defaults to today in the resolved tz", "in": "query", "name": "day", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "YYYY-MM-DD; defaults to today in the resolved tz", "title": "Day" } }, { "description": "IANA tz override for day boundaries", "in": "query", "name": "tz", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "IANA tz override for day boundaries", "title": "Tz" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DefenseReplayResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Assembled day-replay feed of the caller's email defense journeys", "tags": [ "defense", "defense" ], "x-mcp-skip": true } }, "/api/v1/defense/replay/artifacts": { "get": { "description": "The Harvest-breakdown tab's itemized lists for one local day — documents,\nattachments, contacts, and calendar events across the caller's owner-scoped\njourney email set, each row carrying email_id + sender to link back to its\njourney. One batch per type (no per-email N+1). Owner-scoped; day boundaries\nuse the caller's preferred tz (or the `tz` override).", "operationId": "getDefenseReplayDayArtifacts", "parameters": [ { "description": "YYYY-MM-DD; defaults to today in the resolved tz", "in": "query", "name": "day", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "YYYY-MM-DD; defaults to today in the resolved tz", "title": "Day" } }, { "description": "IANA tz override for day boundaries", "in": "query", "name": "tz", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "IANA tz override for day boundaries", "title": "Tz" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DefenseReplayDayArtifactsResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "The day's itemized harvest lists across the caller's journey emails", "tags": [ "defense", "defense" ], "x-mcp-skip": true } }, "/api/v1/defense/replay/emails/{email_id}/artifacts": { "get": { "description": "The openable rows behind an email's harvest counters. Owner-scoped: 404\nif the caller does not own a defense journey for the email.", "operationId": "getDefenseReplayEmailArtifacts", "parameters": [ { "in": "path", "name": "email_id", "required": true, "schema": { "title": "Email Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DefenseReplayArtifactsResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Itemized harvest artifacts (documents, attachments, contacts, events) for one journey email", "tags": [ "defense", "defense" ], "x-mcp-skip": true } }, "/api/v1/defense/replay/emails/{email_id}/artifacts/documents/{document_id}/content": { "get": { "description": "The canonical markdown for one harvest reference row. Owner-scoped: 404 if\nthe caller does not own the email's journey or the document is not attributed\nto that email.", "operationId": "getDefenseReplayDocumentContent", "parameters": [ { "in": "path", "name": "email_id", "required": true, "schema": { "title": "Email Id", "type": "string" } }, { "in": "path", "name": "document_id", "required": true, "schema": { "title": "Document Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReplayDocumentContentResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Canonical markdown for one harvested document/url of a journey email", "tags": [ "defense", "defense" ], "x-mcp-skip": true } }, "/api/v1/defense/replay/memories": { "get": { "description": "The memory rows the caller's emails deposited into the graph for one\nlocal day — the linked_references provenance edges resolved to their\ntarget display names. Owner-scoped over the same journey email set as the\nreplay feed; day boundaries use the caller's preferred tz (or the `tz`\noverride) per the canonical time rules.", "operationId": "getDefenseReplayMemories", "parameters": [ { "description": "YYYY-MM-DD; defaults to today in the resolved tz", "in": "query", "name": "day", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "YYYY-MM-DD; defaults to today in the resolved tz", "title": "Day" } }, { "description": "IANA tz override for day boundaries", "in": "query", "name": "tz", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "IANA tz override for day boundaries", "title": "Tz" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DefenseReplayMemoriesResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Displayable memories the caller's emails deposited into the graph for a day", "tags": [ "defense", "defense" ], "x-mcp-skip": true } }, "/api/v1/defense/replay/town": { "get": { "description": "The persistent town population as of one local day — pending contacts\n(residents) and email-harvested calendar events (bulletin board), each on a\n30-day trailing window. Owner-scoped. HONEST LIMITATION: pending_contacts is\ncurrent-pending ∩ created-in-window; a contact approved after the selected\nday can't be reconstructed as pending-at-that-time (no status history). Day\nboundaries use the caller's preferred tz (or the `tz` override).", "operationId": "getDefenseReplayTown", "parameters": [ { "description": "YYYY-MM-DD; defaults to today in the resolved tz", "in": "query", "name": "day", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "YYYY-MM-DD; defaults to today in the resolved tz", "title": "Day" } }, { "description": "IANA tz override for day boundaries", "in": "query", "name": "tz", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "IANA tz override for day boundaries", "title": "Tz" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DefenseReplayTownResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "The caller's town population (pending contacts + harvested events) as of a day", "tags": [ "defense", "defense" ], "x-mcp-skip": true } }, "/api/v1/defense/rules": { "get": { "description": "List rules under the member-visible predicate (own + tenant/global packs).", "operationId": "listDefenseRules", "parameters": [ { "in": "query", "name": "class", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Class" } }, { "in": "query", "name": "provenance", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Provenance" } }, { "in": "query", "name": "enabled", "required": false, "schema": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Enabled" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/DefenseRuleResponse" }, "title": "Response Listdefenserules", "type": "array" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List defense rules visible to the member", "tags": [ "defense", "defense" ], "x-mcp-skip": true }, "post": { "description": "Create a rule. Match is validated by the Pydantic contract (regex safety\nincluded). Workflow-family rules require a bound handler reference. A\ndelegatee drafting for another member lands a disabled proposal (R12).", "operationId": "createDefenseRule", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DefenseRuleCreate" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DefenseRuleResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Create a defense rule", "tags": [ "defense", "defense" ], "x-mcp-skip": true } }, "/api/v1/defense/rules/preview": { "post": { "description": "Report what ``body.match`` would have matched over the caller's history\nplus whether their own engagement contradicts muting it.", "operationId": "previewDefenseRule", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PreviewRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PreviewResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Backtest a defense rule match against history", "tags": [ "defense", "defense" ] } }, "/api/v1/defense/rules/{rule_id}": { "delete": { "description": "Soft-delete a rule the caller owns (or a tenant/global pack rule).", "operationId": "deleteDefenseRule", "parameters": [ { "in": "path", "name": "rule_id", "required": true, "schema": { "title": "Rule Id", "type": "string" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Soft-delete a defense rule", "tags": [ "defense", "defense" ], "x-mcp-skip": true }, "get": { "description": "Fetch one rule under the member-visible predicate. Drafts ARE fetchable\nby id (TIDY-13697) — the @tidy defense tools and the draft tab read the row\nthe user is working on; only the LIST surface hides drafts.", "operationId": "getDefenseRule", "parameters": [ { "in": "path", "name": "rule_id", "required": true, "schema": { "title": "Rule Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DefenseRuleResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get one defense rule by id", "tags": [ "defense", "defense" ] }, "patch": { "description": "Partially update a rule the caller owns (or a tenant/global pack rule).", "operationId": "updateDefenseRule", "parameters": [ { "in": "path", "name": "rule_id", "required": true, "schema": { "title": "Rule Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DefenseRuleUpdate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DefenseRuleResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Update a defense rule", "tags": [ "defense", "defense" ] } }, "/api/v1/defense/rules/{rule_id}/apply-retroactive": { "post": { "description": "Bulk-archive the emails a suppress/route-away rule matches so the inbox is\nclean immediately. Idempotent — a second run archives 0 new rows.", "operationId": "applyDefenseRuleRetroactive", "parameters": [ { "in": "path", "name": "rule_id", "required": true, "schema": { "title": "Rule Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetroApplyResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Retroactively archive existing matches of a suppress rule", "tags": [ "defense", "defense" ], "x-mcp-skip": true } }, "/api/v1/defense/rules/{rule_id}/confirm": { "post": { "description": "Adopt a militia rule: clear its TTL (permanent), stamp confirmed_at, and\nkeep provenance='ai_learned' so its Watchtower history/reason is preserved.", "operationId": "confirmDefenseRule", "parameters": [ { "in": "path", "name": "rule_id", "required": true, "schema": { "title": "Rule Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DefenseRuleResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Confirm an AI-learned (Watchtower) rule — make it permanent", "tags": [ "defense", "defense" ], "x-mcp-skip": true } }, "/api/v1/defense/rules/{rule_id}/dismiss": { "post": { "description": "Tear down a militia rule. Dismissal is a durable NEGATIVE, not a mere\ndelete: in ONE transaction the rule is soft-deleted AND an ``is_exception``\nrule with the SAME match is written so the militia writer refuses to\nre-learn the covered match (Negative AC — silent re-learning designed out).", "operationId": "dismissDefenseRule", "parameters": [ { "in": "path", "name": "rule_id", "required": true, "schema": { "title": "Rule Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DefenseRuleResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Dismiss an AI-learned rule — soft-delete + write a durable exception", "tags": [ "defense", "defense" ], "x-mcp-skip": true } }, "/api/v1/defense/rules/{rule_id}/health": { "get": { "description": "Return the rule's health score, band, trend, and the evidence trail.", "operationId": "getDefenseRuleHealth", "parameters": [ { "in": "path", "name": "rule_id", "required": true, "schema": { "format": "uuid", "title": "Rule Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RuleHealthResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Rule health score + evidence trail", "tags": [ "defense", "defense" ], "x-mcp-skip": true } }, "/api/v1/defense/seed": { "post": { "description": "Return a rule proposal for the moment, or none when nothing to offer /\nthe (moment, match-key) is currently suppressed. Never persists a rule.", "operationId": "seedDefenseRule", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SeedRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SeedProposalResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get a pre-configured defense-rule proposal for a correction moment", "tags": [ "defense", "defense" ], "x-mcp-skip": true } }, "/api/v1/defense/seed/decline": { "post": { "description": "Record a decline; suppress the (moment, match-key) for 30 days after two.", "operationId": "declineDefenseSeed", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SeedDeclineRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SeedDeclineResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Record a declined seed proposal (frequency cap)", "tags": [ "defense", "defense" ], "x-mcp-skip": true } }, "/api/v1/defense/suggestions": { "get": { "operationId": "listDefenseSuggestions", "parameters": [ { "in": "query", "name": "status", "required": false, "schema": { "default": "pending", "title": "Status", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/SuggestionResponse" }, "title": "Response Listdefensesuggestions", "type": "array" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List defense suggestions (owner-scoped) with freshness tier", "tags": [ "defense", "defense" ], "x-mcp-skip": true } }, "/api/v1/defense/suggestions/accept-batch": { "post": { "description": "Approve-all for a monthly-review batch. Iterates the batch's pending rows\nthrough the SAME single-accept core. Idempotent: a second call finds no\npending rows and accepts 0.", "operationId": "acceptDefenseSuggestionBatch", "parameters": [ { "in": "query", "name": "surface", "required": false, "schema": { "default": "monthly_review", "title": "Surface", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcceptBatchRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcceptBatchResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Accept every pending suggestion in a monthly-review batch", "tags": [ "defense", "defense" ], "x-mcp-skip": true } }, "/api/v1/defense/suggestions/{suggestion_id}/accept": { "post": { "operationId": "acceptDefenseSuggestion", "parameters": [ { "in": "path", "name": "suggestion_id", "required": true, "schema": { "format": "uuid", "title": "Suggestion Id", "type": "string" } }, { "in": "query", "name": "surface", "required": false, "schema": { "default": "analytics", "title": "Surface", "type": "string" } }, { "description": "Deploy-from-draft (TIDY-14666 R7a): promote this EDITED draft rule (provenance='draft', caller-owned) instead of creating the original proposal. Additive — omitted keeps the create-from-proposal path.", "in": "query", "name": "rule_id", "required": false, "schema": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "description": "Deploy-from-draft (TIDY-14666 R7a): promote this EDITED draft rule (provenance='draft', caller-owned) instead of creating the original proposal. Additive — omitted keeps the create-from-proposal path.", "title": "Rule Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcceptResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Accept a suggestion — creates the rule, resolves everywhere", "tags": [ "defense", "defense" ], "x-mcp-skip": true } }, "/api/v1/defense/suggestions/{suggestion_id}/dismiss": { "post": { "operationId": "dismissDefenseSuggestion", "parameters": [ { "in": "path", "name": "suggestion_id", "required": true, "schema": { "format": "uuid", "title": "Suggestion Id", "type": "string" } }, { "in": "query", "name": "durable", "required": false, "schema": { "default": false, "title": "Durable", "type": "boolean" } }, { "in": "query", "name": "surface", "required": false, "schema": { "default": "analytics", "title": "Surface", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_service__routers__defense_suggestions__DismissResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Dismiss a suggestion (durable dismiss suppresses regeneration)", "tags": [ "defense", "defense" ], "x-mcp-skip": true } }, "/api/v1/delegation/audit": { "get": { "description": "The delegator audit view: \"what each delegatee did with my access\".\n\nScoped to ``principal = me`` (the caller as delegator). A tenant-wide audit\nis the admin audit surface, not this endpoint.", "operationId": "listDelegationAudit", "parameters": [ { "in": "query", "name": "principal", "required": false, "schema": { "default": "me", "pattern": "^me$", "title": "Principal", "type": "string" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "maximum": 200, "minimum": 1, "title": "Limit", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DelegationAuditResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Get Delegation Audit", "tags": [ "delegation", "delegation" ], "x-mcp-skip": true } }, "/api/v1/delegation/grants": { "get": { "description": "List the caller's grants. ``as=delegator`` shows grants the caller made;\n``as=delegatee`` shows grants made TO the caller; ``both`` (default) unions.", "operationId": "listDelegationGrants", "parameters": [ { "in": "query", "name": "as", "required": false, "schema": { "default": "both", "pattern": "^(delegator|delegatee|both)$", "title": "As", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GrantListResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "List Grants", "tags": [ "delegation", "delegation" ], "x-mcp-skip": true }, "post": { "description": "Create or upsert a delegation grant (idempotent on the unique key).\n\nCaller is the delegator by default. An admin holding ``manage_delegation``\nmay set ``delegator_account_id`` to act on behalf of a member.", "operationId": "createDelegationGrant", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateGrantRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GrantResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Create Grant", "tags": [ "delegation", "delegation" ], "x-mcp-skip": true } }, "/api/v1/delegation/grants/bulk": { "post": { "description": "Self-service bulk-create: grant several delegations in one call.\n\nThe delegator is ALWAYS the caller — there is no per-item delegator field,\nso this needs only normal member auth (unlike the admin\n``/admin/delegation/grants/bulk`` twin, which takes a per-item\n``delegator_account_id`` and requires ``manage_delegation``).\n\nReuses the SAME validation + write path as the single\n``POST /grants`` handler: ``upsert_grant`` (idempotent on the unique key —\na duplicate active grant is updated in place) plus the grant-created audit\nrow in the same transaction. Transactional PER ITEM so a bad row is\nreported in ``errors`` while the others succeed (never silently dropped).", "operationId": "bulkCreateSelfDelegationGrants", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SelfBulkGrantRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkGrantResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Bulk Create Self Grants", "tags": [ "delegation", "delegation" ], "x-mcp-skip": true } }, "/api/v1/delegation/grants/revoke-all": { "post": { "description": "Panic kill switch: revoke every active grant where the caller is the\ndelegator. Returns the number revoked.", "operationId": "revokeAllDelegationGrants", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevokeAllResponse" } } }, "description": "Successful Response" } }, "summary": "Revoke All Grants", "tags": [ "delegation", "delegation" ], "x-mcp-skip": true } }, "/api/v1/delegation/grants/{grant_id}": { "delete": { "description": "Revoke one grant. The delegator may revoke their own grants; an admin\nwith ``manage_delegation`` may revoke any grant in the tenant.", "operationId": "revokeDelegationGrant", "parameters": [ { "in": "path", "name": "grant_id", "required": true, "schema": { "format": "uuid", "title": "Grant Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_service__models__delegation__RevokeResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Revoke Grant", "tags": [ "delegation", "delegation" ], "x-mcp-skip": true } }, "/api/v1/deprecations": { "get": { "description": "Returns every deprecated endpoint with its sunset date, successor, and reason. Partners and agents use this to discover what's on the way out. See RFC 8594 and TIDY decision D26.", "operationId": "getApiDeprecations", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeprecationCatalog" } } }, "description": "Successful Response" } }, "summary": "Catalog of deprecated API endpoints", "tags": [ "meta", "meta" ] } }, "/api/v1/deprecations/_canary": { "get": { "description": "This endpoint exists only to prove the @deprecated decorator, headers middleware, discovery endpoint, and MCP resource are wired correctly end-to-end. It is not part of the product surface.", "operationId": "deprecationCanary", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeprecationCanaryResponse" } } }, "description": "Successful Response" } }, "summary": "Canary endpoint — deprecated on purpose for integration testing", "tags": [ "meta", "meta" ] } }, "/api/v1/desktop/version-policy": { "get": { "description": "Return the configured desktop version floor, decided against ``current``.\n\nUnauthenticated by design (works when auth is broken). With no ``current``\nthe raw policy (min/latest/message) is returned and both decision flags are\nFalse; with ``current`` supplied the backend does the semver compare and\nreturns the ``update_required`` / ``update_available`` decision.", "operationId": "getDesktopVersionPolicy", "parameters": [ { "description": "The desktop's running build version; when supplied the response carries the update_required / update_available decision for it.", "in": "query", "name": "current", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The desktop's running build version; when supplied the response carries the update_required / update_available decision for it.", "title": "Current" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DesktopVersionPolicy" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Get Desktop Version Policy", "tags": [ "desktop-version", "desktop-version" ], "x-mcp-skip": true, "x-mcp-skip-reason": "Unauthenticated desktop-host version gate, not an agent workflow." } }, "/api/v1/dev-signup": { "post": { "description": "Public pre-auth endpoint called by the developer-docs signup page. Creates an auth account via Supabase GoTrue admin API, provisions a sandbox tenant (env='sandbox'), seeds it with deterministic synthetic data, and returns a one-shot sandbox-scoped PAT that can be used against the API explorer. Rate-limited to 3 requests per IP per hour.", "operationId": "devSignup", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DevSignupRequest" } } }, "required": true }, "responses": { "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DevSignupResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Developer self-service sandbox onboarding", "tags": [ "dev-signup", "dev-signup" ] } }, "/api/v1/devices": { "get": { "description": "List the caller's devices (member-visible predicate).", "operationId": "listDevices", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeviceListResponse" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List Devices", "tags": [ "devices", "devices" ], "x-mcp-skip": true, "x-mcp-skip-reason": "Device + offload-consent management is a settings/desktop-host surface, not an agent workflow." } }, "/api/v1/devices/register": { "post": { "description": "Register a device (idempotent per device key) and mint a credential.", "operationId": "registerDevice", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeviceRegisterRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeviceRegisterResponse" } } }, "description": "Successful Response" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeviceErrorResponse" } } }, "description": "Malformed request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeviceErrorResponse" } } }, "description": "Credential/signature rejected" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeviceErrorResponse" } } }, "description": "Device key conflict" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Register Device", "tags": [ "devices", "devices" ], "x-mcp-skip": true, "x-mcp-skip-reason": "Device + offload-consent management is a settings/desktop-host surface, not an agent workflow." } }, "/api/v1/devices/token": { "post": { "description": "Exchange a device credential + PoP signature for a device access token.\n\nAuthenticated by the device credential and a signature over the device key\n— NOT by a user session. A credential replayed with a different key fails.", "operationId": "exchangeDeviceCredential", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeviceTokenRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeviceTokenResponse" } } }, "description": "Successful Response" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeviceErrorResponse" } } }, "description": "Malformed request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeviceErrorResponse" } } }, "description": "Credential/signature rejected" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Exchange Device Credential", "tags": [ "devices", "devices" ], "x-mcp-skip": true, "x-mcp-skip-reason": "Device + offload-consent management is a settings/desktop-host surface, not an agent workflow." } }, "/api/v1/devices/{device_id}/browser-egress": { "put": { "description": "Let the owner's browsing accounts use this computer's internet connection\n(TIDY-18934 F13; explicit, default OFF). Turning it off ends what it carries.", "operationId": "setDeviceBrowserEgress", "parameters": [ { "in": "path", "name": "device_id", "required": true, "schema": { "format": "uuid", "title": "Device Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeviceBrowserEgressRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeviceResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Set Device Browser Egress", "tags": [ "devices", "devices" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Device + offload-consent management is a settings/desktop-host surface, not an agent workflow." } }, "/api/v1/devices/{device_id}/consent": { "put": { "description": "Set per-device offload consent (explicit; default OFF).", "operationId": "setDeviceOffloadConsent", "parameters": [ { "in": "path", "name": "device_id", "required": true, "schema": { "format": "uuid", "title": "Device Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeviceOffloadConsentRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeviceResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Set Device Consent", "tags": [ "devices", "devices" ], "x-mcp-skip": true, "x-mcp-skip-reason": "Device + offload-consent management is a settings/desktop-host surface, not an agent workflow." } }, "/api/v1/devices/{device_id}/health": { "post": { "description": "Record a desktop's slow health beat against its own device row.\n\nThe receiving end of the S10.3 device-health heartbeat (TIDY-13274). The\ndesktop main process reports app version, offload serving state, and pending\nauto-update on a slow cadence, authenticated by the user session bearer and\nscoped to the caller's OWN device (tenant + account + device_id). It keeps\nlast_seen + serving state current even when the offload worker is withdrawn\non battery — the freshness the settings device list and Integration AC read.\n\n`device_id` is typed as UUID so a malformed path is a clean 422, never a 500.", "operationId": "reportDeviceHealth", "parameters": [ { "in": "path", "name": "device_id", "required": true, "schema": { "format": "uuid", "title": "Device Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeviceHealthReportRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeviceResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Report Device Health", "tags": [ "devices", "devices" ], "x-mcp-skip": true, "x-mcp-skip-reason": "Device + offload-consent management is a settings/desktop-host surface, not an agent workflow." } }, "/api/v1/devices/{device_id}/revoke": { "post": { "description": "Revoke a device; immediately invalidates its credential + access tokens.\n\n`device_id` is typed as UUID so a malformed path is a clean 422, never a\n500 from parsing it in the service (F9).", "operationId": "revokeDevice", "parameters": [ { "in": "path", "name": "device_id", "required": true, "schema": { "format": "uuid", "title": "Device Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeviceRevokeResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Revoke Device", "tags": [ "devices", "devices" ], "x-mcp-skip": true, "x-mcp-skip-reason": "Device + offload-consent management is a settings/desktop-host surface, not an agent workflow." } }, "/api/v1/drafts/organization/{draft_id}/resolve-conflict": { "post": { "description": "Approve a same-name pending organization and merge the draft into it.\n\nThe target must still be the exact conflict reported for this caller's\ndraft. Approval uses the canonical organization service; reference\nrepointing and the draft tombstone use the existing transactional merge\nengine. A changed conflict is refused instead of guessing.", "operationId": "resolveOrganizationDraftConflict", "parameters": [ { "description": "The organization draft to absorb", "in": "path", "name": "draft_id", "required": true, "schema": { "description": "The organization draft to absorb", "format": "uuid", "title": "Draft Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResolveOrganizationDraftConflictRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResolveOrganizationDraftConflictResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Resolve Organization Draft Conflict", "tags": [ "drafts", "drafts" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Human-confirmed resolution of a draft publish conflict." } }, "/api/v1/drafts/{primitive_kind}": { "post": { "description": "Create a draft row.\n\nIdempotent: re-calling with the same ``id`` returns ``inserted=false``.\nThe row is stamped ``draft_owner_id = current_user`` and is invisible\nto other users via RLS + sync rules.", "operationId": "createDraft", "parameters": [ { "description": "One of: task, note, event, project, contact, reminder, organization", "in": "path", "name": "primitive_kind", "required": true, "schema": { "description": "One of: task, note, event, project, contact, reminder, organization", "title": "Primitive Kind", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_service__routers__drafts__CreateDraftRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DraftLifecycleResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Create Draft", "tags": [ "drafts", "drafts" ] } }, "/api/v1/drafts/{primitive_kind}/{draft_id}": { "delete": { "description": "Discard a draft: hard ``DELETE`` of the row (D4 of TIDY-9334).\n\nReturns ``discarded=false`` if the row doesn't exist, was already\npublished (in which case the user should use the normal soft-delete\npath), belongs to a different user, or is in another scope.", "operationId": "discardDraft", "parameters": [ { "in": "path", "name": "primitive_kind", "required": true, "schema": { "title": "Primitive Kind", "type": "string" } }, { "description": "The draft row id to discard", "in": "path", "name": "draft_id", "required": true, "schema": { "description": "The draft row id to discard", "format": "uuid", "title": "Draft Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DraftLifecycleResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Discard Draft", "tags": [ "drafts", "drafts" ] } }, "/api/v1/drafts/{primitive_kind}/{draft_id}/publish": { "post": { "description": "Publish a draft: ``UPDATE SET draft_owner_id = NULL``.\n\nReturns ``published=false`` if the row doesn't exist, was already\npublished, belongs to a different user, or is in another scope. We\ndeliberately don't differentiate these cases in the response to avoid\nleaking existence information.\n\nA calendar-event draft goes through the conflict ward (TIDY-15855) —\npublishing is the moment it starts occupying the member's calendar — and\nanswers a refusal with a typed 409 carrying the conflict card.", "operationId": "publishDraft", "parameters": [ { "in": "path", "name": "primitive_kind", "required": true, "schema": { "title": "Primitive Kind", "type": "string" } }, { "description": "The draft row id to publish", "in": "path", "name": "draft_id", "required": true, "schema": { "description": "The draft row id to publish", "format": "uuid", "title": "Draft Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DraftLifecycleResponse" } } }, "description": "Successful Response" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DraftPublishConflictResponse" } } }, "description": "A published row already occupies the draft's unique key." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Publish Draft", "tags": [ "drafts", "drafts" ] } }, "/api/v1/drive/create": { "post": { "description": "Create a new Google Drive document or folder.\n\nSupports: document, spreadsheet, presentation, form, drawing, folder.\nUses the existing Google OAuth connection with drive scope.", "operationId": "createFile", "parameters": [ { "description": "OAuth connection ID (or the lent plugin id under a plugin grant)", "in": "query", "name": "connection_id", "required": true, "schema": { "description": "OAuth connection ID (or the lent plugin id under a plugin grant)", "title": "Connection Id", "type": "string" } }, { "in": "header", "name": "X-Tidy-Plugin-Grant", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tidy-Plugin-Grant" } }, { "in": "header", "name": "X-Tidy-Conversation-Id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tidy-Conversation-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DriveCreateRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DriveCreateResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Create a new Google Drive document or folder", "tags": [ "drive" ] } }, "/api/v1/drive/files": { "get": { "description": "List files and folders from the user's Google Drive.\n\nRequires an active Google OAuth connection with drive.readonly scope.\nPass folder_id to navigate into subfolders (default: root).", "operationId": "listFiles", "parameters": [ { "description": "OAuth connection ID (or the lent plugin id under a plugin grant)", "in": "query", "name": "connection_id", "required": true, "schema": { "description": "OAuth connection ID (or the lent plugin id under a plugin grant)", "title": "Connection Id", "type": "string" } }, { "description": "Drive folder ID to list", "in": "query", "name": "folder_id", "required": false, "schema": { "default": "root", "description": "Drive folder ID to list", "title": "Folder Id", "type": "string" } }, { "description": "Pagination token", "in": "query", "name": "page_token", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pagination token", "title": "Page Token" } }, { "description": "Results per page", "in": "query", "name": "page_size", "required": false, "schema": { "default": 50, "description": "Results per page", "maximum": 100, "minimum": 1, "title": "Page Size", "type": "integer" } }, { "in": "header", "name": "X-Tidy-Plugin-Grant", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tidy-Plugin-Grant" } }, { "in": "header", "name": "X-Tidy-Conversation-Id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tidy-Conversation-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DriveFilesResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List files and folders from Google Drive", "tags": [ "drive" ] } }, "/api/v1/drive/files/{file_id}": { "get": { "description": "Metadata always; text content for Docs, Sheets, Slides and ``text/*``\nfiles, truncated at 1 MB. Under a lend this needs ``drive.read``.", "operationId": "readFile", "parameters": [ { "in": "path", "name": "file_id", "required": true, "schema": { "title": "File Id", "type": "string" } }, { "description": "OAuth connection ID (or the lent plugin id under a plugin grant)", "in": "query", "name": "connection_id", "required": true, "schema": { "description": "OAuth connection ID (or the lent plugin id under a plugin grant)", "title": "Connection Id", "type": "string" } }, { "in": "header", "name": "X-Tidy-Plugin-Grant", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tidy-Plugin-Grant" } }, { "in": "header", "name": "X-Tidy-Conversation-Id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tidy-Conversation-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DriveFileReadResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Read a Google Drive file's metadata and text content", "tags": [ "drive" ], "x-local-capability": "cloud" } }, "/api/v1/drive/import": { "post": { "description": "Begin a Drive -> Tidy import.\n\nReturns 202 with `existing=false` for a brand-new import (note/file\nskeleton row created with import_status='extracting' once content\nlands), or 200 with `existing=true` when the (tenant, drive_file_id)\nhas already been imported and `replace=false`.\n\nPer TIDY-9139 R1 the orchestrator dispatches by Drive MIME type to\none of: doc-service /convert/{docx,xlsx,pptx} (Docs/Sheets/Slides +\ndirect OOXML uploads + CSV), Docling for PDFs, or file storage for\nimages / text. See drive_import_service for the full conversion\nmatrix.\n\nErrors:\n 400 unsupported MIME (RFC 9457 unsupported-mime)\n 401 Drive token bad / not authorized\n 404 Drive file not found\n 413 file/export exceeds size limits\n 422 limit_denied (RFC 9457 limit-denied)\n 502 Drive fetch failed\n 503 doc-service / Docling unreachable", "operationId": "importDriveFile", "parameters": [ { "in": "header", "name": "X-Request-Id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Request-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DriveImportRequest" } } }, "required": true }, "responses": { "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DriveImportResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Import a Google Drive file natively", "tags": [ "drive-import" ] } }, "/api/v1/drive/link": { "post": { "description": "Link (reference) a Google Drive file to Tidy's file system.\n\nCreates a files table row with storage_type='google_drive'.\nThe file is NOT copied -- it stays in Google Drive. Clicking the\nlinked file in Tidy opens the Google Drive web view URL.", "operationId": "linkFile", "parameters": [ { "description": "OAuth connection ID (or the lent plugin id under a plugin grant)", "in": "query", "name": "connection_id", "required": true, "schema": { "description": "OAuth connection ID (or the lent plugin id under a plugin grant)", "title": "Connection Id", "type": "string" } }, { "in": "header", "name": "X-Tidy-Plugin-Grant", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tidy-Plugin-Grant" } }, { "in": "header", "name": "X-Tidy-Conversation-Id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tidy-Conversation-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DriveLinkRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DriveLinkResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Link a Google Drive file to Tidy", "tags": [ "drive" ] } }, "/api/v1/drive/move": { "post": { "description": "Move one file between folders (``files.update`` with add/removeParents).\nThe file keeps its id and every link to it (TIDY-18241 / R22).", "operationId": "moveFile", "parameters": [ { "description": "OAuth connection ID (or the lent plugin id under a plugin grant)", "in": "query", "name": "connection_id", "required": true, "schema": { "description": "OAuth connection ID (or the lent plugin id under a plugin grant)", "title": "Connection Id", "type": "string" } }, { "in": "header", "name": "X-Tidy-Plugin-Grant", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tidy-Plugin-Grant" } }, { "in": "header", "name": "X-Tidy-Conversation-Id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tidy-Conversation-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DriveMoveRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DriveMoveResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Move a Google Drive file into another folder", "tags": [ "drive" ], "x-local-capability": "cloud" } }, "/api/v1/drive/save": { "post": { "description": "Save Tidy content into a NEW app-authored Google Doc (R7/D15).\n\nAlways creates a new Doc via Drive files.create and writes the note's\nmarkdown/plain text onto ONLY that new id — there is no parameter that\naccepts an existing Drive file id, so a user-owned Doc can never be\noverwritten (R8). The Tidy source is left unchanged.\n\nSuccessful saves count against a per-account daily quota (TIDY-17579,\ndefault 50/day, ``DRIVE_SAVE_DAILY_ACCOUNT_LIMIT``); over budget → 429\nproblem+json ``drive_save_budget_exceeded`` with ``retry_after_seconds``.\nFailed Google calls never consume budget.", "operationId": "saveToGoogleDoc", "parameters": [ { "in": "header", "name": "X-Tidy-Plugin-Grant", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tidy-Plugin-Grant" } }, { "in": "header", "name": "X-Tidy-Conversation-Id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tidy-Conversation-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DriveSaveRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DriveSaveResponse" } } }, "description": "Successful Response" }, "400": { "description": "Source has no content, or multiple connections need disambiguation" }, "404": { "description": "Connection, note, or file not found or not visible to the caller" }, "413": { "description": "Source content exceeds the save size limit" }, "415": { "description": "Source file is not a text document (v1 is text/markdown/html)" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Daily save quota exhausted for this account — problem+json `code: drive_save_budget_exceeded`, retryable, with `retry_after_seconds` pointing at the UTC-midnight reset (TIDY-17579). Failed saves never consume budget." }, "502": { "description": "Google Drive/Docs API failure (a partially-created Doc is deleted)" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "The quota reservation ledger could not be written — problem+json `code: drive_save_ledger_unavailable`. FAIL CLOSED: the save was NOT attempted; a retry may succeed (TIDY-17579)." } }, "security": [ { "HTTPBearer": [] } ], "summary": "Save a Tidy note or text file as a NEW Google Doc", "tags": [ "drive" ], "x-local-capability": "cloud" } }, "/api/v1/drive/search": { "get": { "description": "Search Google Drive files using native fullTextContains query.\n\nSearches file names and content. Results sorted by most recently modified.", "operationId": "searchFiles", "parameters": [ { "description": "OAuth connection ID (or the lent plugin id under a plugin grant)", "in": "query", "name": "connection_id", "required": true, "schema": { "description": "OAuth connection ID (or the lent plugin id under a plugin grant)", "title": "Connection Id", "type": "string" } }, { "description": "Search query", "in": "query", "name": "q", "required": true, "schema": { "description": "Search query", "minLength": 1, "title": "Q", "type": "string" } }, { "description": "Pagination token", "in": "query", "name": "page_token", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pagination token", "title": "Page Token" } }, { "description": "Results per page", "in": "query", "name": "page_size", "required": false, "schema": { "default": 50, "description": "Results per page", "maximum": 100, "minimum": 1, "title": "Page Size", "type": "integer" } }, { "in": "header", "name": "X-Tidy-Plugin-Grant", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tidy-Plugin-Grant" } }, { "in": "header", "name": "X-Tidy-Conversation-Id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tidy-Conversation-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DriveFilesResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Search Google Drive files", "tags": [ "drive" ] } }, "/api/v1/edge-inference/jobs": { "get": { "description": "Long-poll claim: returns ONE claimable job for this worker, atomically\nclaimed, or null when the wait lapses with nothing to serve.\n\nClaimable = the job is pending, unexpired, belongs to the worker's\nTENANT, and either targets the desktop rung with the function's min_tier\n<= the worker's tier, or targets client_local for the worker's own\naccount + surface.", "operationId": "poll_jobs_api_v1_edge_inference_jobs_get", "parameters": [ { "in": "query", "name": "worker_id", "required": true, "schema": { "title": "Worker Id", "type": "string" } }, { "in": "query", "name": "wait", "required": false, "schema": { "default": 30, "maximum": 60, "minimum": 0, "title": "Wait", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/EdgeJobPayload" }, { "type": "null" } ], "title": "Response Poll Jobs Api V1 Edge Inference Jobs Get" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Poll Jobs", "tags": [ "edge-inference", "edge-inference" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/edge-inference/jobs/{job_id}/result": { "post": { "description": "Result postback. Only the CLAIMING worker may post; an expired job\n409s (the ladder already descended — a late result is never served).", "operationId": "post_result_api_v1_edge_inference_jobs__job_id__result_post", "parameters": [ { "in": "path", "name": "job_id", "required": true, "schema": { "title": "Job Id", "type": "string" } }, { "in": "query", "name": "worker_id", "required": true, "schema": { "title": "Worker Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EdgeJobResultRequest" } } }, "required": true }, "responses": { "204": { "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Post Result", "tags": [ "edge-inference", "edge-inference" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/edge-inference/register": { "post": { "description": "Register (or refresh) an edge worker for this device.\n\nThe device must exist, belong to the caller, be unrevoked, and carry\n``offload_consent`` — the D6 authorization precondition.", "operationId": "register_worker_api_v1_edge_inference_register_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EdgeWorkerRegisterRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EdgeWorkerResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Register Worker", "tags": [ "edge-inference", "edge-inference" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/edge-inference/{worker_id}/heartbeat": { "post": { "operationId": "heartbeat_api_v1_edge_inference__worker_id__heartbeat_post", "parameters": [ { "in": "path", "name": "worker_id", "required": true, "schema": { "title": "Worker Id", "type": "string" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Heartbeat", "tags": [ "edge-inference", "edge-inference" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/email-corpus/snapshot/manifest": { "get": { "description": "Returns every cold email-corpus period manifest the caller owns — the index B4 diffs against its local cache to decide which periods to (re)download. Gated by the member-visible access predicate on the snapshot rows' scope columns plus an explicit account scope: a member only ever sees their own account's corpus.", "operationId": "listEmailCorpusSnapshotManifests", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CorpusSnapshotManifestList" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List the caller's cold email-corpus snapshot manifests", "tags": [ "email-corpus-snapshot" ], "x-mcp-skip": true, "x-mcp-skip-reason": "Local-first bulk-download transport for the cold email corpus (replaces PowerSync sync of cold email_content); a client sync mechanism, not an agent workflow." } }, "/api/v1/email-corpus/snapshot/{period_key}": { "get": { "description": "Streams the period's reassembled zstd-compressed artifact (the chunks concatenated in chunk_index order). Content-addressed: the response carries `ETag: \"<content_hash>\"`, and an `If-None-Match` that matches the current hash returns 304 Not Modified so an unchanged period is a cheap conditional GET. Range-resumable: `Accept-Ranges: bytes` is set and a `Range` request returns the correct 206 partial. Gated by the same member-visible predicate plus account scope — a caller can only fetch their own account's period.", "operationId": "downloadEmailCorpusSnapshotPeriod", "parameters": [ { "description": "Calendar period key, e.g. 2024-03", "in": "path", "name": "period_key", "required": true, "schema": { "description": "Calendar period key, e.g. 2024-03", "title": "Period Key", "type": "string" } }, { "in": "header", "name": "If-None-Match", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "If-None-Match" } }, { "in": "header", "name": "Range", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Range" } } ], "responses": { "200": { "content": { "application/zstd": {} }, "description": "Successful Response" }, "206": { "description": "Partial content (Range request)" }, "304": { "description": "Not Modified (If-None-Match matched content_hash)" }, "404": { "description": "No snapshot for this period in the caller's corpus" }, "416": { "description": "Requested Range Not Satisfiable" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Download a cold email-corpus period artifact (zstd blob)", "tags": [ "email-corpus-snapshot" ], "x-mcp-skip": true, "x-mcp-skip-reason": "Local-first bulk-download transport for the cold email corpus (replaces PowerSync sync of cold email_content); a client sync mechanism, not an agent workflow." } }, "/api/v1/email-images/proxy": { "get": { "description": "Fetch (or serve from cache) a sender's remote email image.", "operationId": "proxyEmailImage", "parameters": [ { "description": "Absolute https URL of the sender image to proxy.", "in": "query", "name": "src", "required": true, "schema": { "description": "Absolute https URL of the sender image to proxy.", "maxLength": 4096, "minLength": 1, "title": "Src", "type": "string" } }, { "in": "header", "name": "If-None-Match", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "If-None-Match" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_service__routers__email_image_proxy___BinaryStreamResponse" } }, "image/*": {} }, "description": "Proxied image bytes." }, "304": { "description": "Client's cached copy is current (If-None-Match)." }, "403": { "description": "URL failed SSRF validation." }, "413": { "description": "Image exceeds the size cap." }, "415": { "description": "Upstream content is not an image." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "502": { "description": "Upstream fetch failed." } }, "security": [ { "HTTPBearer": [] } ], "summary": "Proxy Email Image", "tags": [ "emails" ], "x-mcp-skip": true, "x-mcp-skip-reason": "Browser <img> transport for proxied sender images inside the email iframe; not an agent workflow." } }, "/api/v1/email/view/{doc_id}": { "get": { "description": "Retrieve parsed email content by trace_id, email_canonical.id, doc_id, or pipeline_runs.source_url. The last form supports legacy /email/view?source=<storage_uri> URLs emitted by pipeline admin views.", "operationId": "viewEmail", "parameters": [ { "in": "path", "name": "doc_id", "required": true, "schema": { "title": "Doc Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailViewResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get email content for viewing", "tags": [ "emails" ] } }, "/api/v1/emails": { "get": { "description": "List emails with pagination, folder filtering, search, label filtering, sorting, and date ranges.\n\n **Folder filtering:**\n - `inbox`: Non-archived, non-sent emails (default)\n - includes only screening-approved emails (or legacy emails with null screening_status)\n - `archive`: Archived emails\n - `sent`: Sent emails (is_sent = true)\n - `all`: All emails regardless of archive status\n\n **Search:** Searches subject and from_address fields using ILIKE.\n\n **Label filtering:** Filter by user labels using JSONB containment.\n Pass comma-separated labels to match emails having ALL specified labels.\n\n **Sorting:**\n - `sent_at_desc`: Newest first (default)\n - `sent_at_asc`: Oldest first\n - `from_address_asc`: Alphabetical by sender\n - `subject_asc`: Alphabetical by subject\n\n **Date filtering:**\n - `date_from`/`date_to`: Explicit date range (ISO 8601)\n - `date_range`: Preset (7days, 30days, 90days)\n\n **Depth filtering (TIDY-4773):**\n - `depth=header|body|processed|all`\n - Inbox includes header records for split pagination past the body window\n\n **Source filtering:**\n - `source`: Filter by email_source_config_id (UUID) to show emails from a specific email account\n\n **Split filtering (TIDY-4082):**\n - `split`: Filter by inbox split: important, feed, paper_trail, screening\n - important/feed/paper_trail filter by inbox_split column\n - screening returns emails with screening_status='pending'\n - `include_split_counts=true` on an inbox listing adds `split_counts`: each\n split's thread count under the same filters (TIDY-18527)\n\n **Calendar email filtering (KCC-3695):**\n - By default, calendar invite/response emails (with ICS attachments) are hidden\n - Use `include_calendar=true` to include them in results\n - Calendar emails have `archived_reason` set to 'calendar_invite' or 'calendar_response'\n\n Related: Email Interface Feature (KCC-3143), Split Inbox (KCC-3334), Calendar Filtering (KCC-3695)", "operationId": "listEmails", "parameters": [ { "description": "Items per page", "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "description": "Items per page", "maximum": 100, "minimum": 1, "title": "Limit", "type": "integer" } }, { "description": "Pagination offset", "in": "query", "name": "offset", "required": false, "schema": { "default": 0, "description": "Pagination offset", "minimum": 0, "title": "Offset", "type": "integer" } }, { "description": "Folder filter: inbox, archive, sent, or all", "in": "query", "name": "folder", "required": false, "schema": { "default": "inbox", "description": "Folder filter: inbox, archive, sent, or all", "title": "Folder", "type": "string" } }, { "description": "Split filter: important, feed, paper_trail, screening", "in": "query", "name": "split", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Split filter: important, feed, paper_trail, screening", "title": "Split" } }, { "description": "Search subject/from_address", "in": "query", "name": "search", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Search subject/from_address", "title": "Search" } }, { "description": "Comma-separated from constraints", "in": "query", "name": "from_filter", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Comma-separated from constraints", "title": "From Filter" } }, { "description": "Comma-separated to constraints", "in": "query", "name": "to_filter", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Comma-separated to constraints", "title": "To Filter" } }, { "description": "Comma-separated subject constraints", "in": "query", "name": "subject_filter", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Comma-separated subject constraints", "title": "Subject Filter" } }, { "description": "Comma-separated labels to filter", "in": "query", "name": "labels", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Comma-separated labels to filter", "title": "Labels" } }, { "description": "Comma-separated email_source_config_id (UUID) to filter by", "in": "query", "name": "source", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Comma-separated email_source_config_id (UUID) to filter by", "title": "Source" } }, { "description": "Filter by project_id (UUID)", "in": "query", "name": "project", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by project_id (UUID)", "title": "Project" } }, { "description": "Sort: sent_at_desc, sent_at_asc, from_address_asc, subject_asc", "in": "query", "name": "sort", "required": false, "schema": { "default": "sent_at_desc", "description": "Sort: sent_at_desc, sent_at_asc, from_address_asc, subject_asc", "title": "Sort", "type": "string" } }, { "description": "Filter sent_at >= date_from (ISO 8601)", "in": "query", "name": "date_from", "required": false, "schema": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "Filter sent_at >= date_from (ISO 8601)", "title": "Date From" } }, { "description": "Filter sent_at <= date_to (ISO 8601)", "in": "query", "name": "date_to", "required": false, "schema": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "Filter sent_at <= date_to (ISO 8601)", "title": "Date To" } }, { "description": "Preset: 7days, 30days, 90days", "in": "query", "name": "date_range", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Preset: 7days, 30days, 90days", "title": "Date Range" } }, { "description": "Depth filter: header, body, processed, or all", "in": "query", "name": "depth", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Depth filter: header, body, processed, or all", "title": "Depth" } }, { "description": "KCC-3695: Include calendar invite/response emails", "in": "query", "name": "include_calendar", "required": false, "schema": { "default": false, "description": "KCC-3695: Include calendar invite/response emails", "title": "Include Calendar", "type": "boolean" } }, { "description": "TIDY-8898: when true, ignore the folder filter and search the entire tenant corpus. Each result row carries tidy_folder + imap_folder so the UI can show which folder the hit lives in.", "in": "query", "name": "cross_folder_search", "required": false, "schema": { "default": false, "description": "TIDY-8898: when true, ignore the folder filter and search the entire tenant corpus. Each result row carries tidy_folder + imap_folder so the UI can show which folder the hit lives in.", "title": "Cross Folder Search", "type": "boolean" } }, { "description": "TIDY-12392: smart-filter `has:attachment`. When true, restrict to rows whose attachments jsonb array is non-empty. Forwarded so the historic/cross-folder lane honors the attachment filter the same way the local window does.", "in": "query", "name": "has_attachment", "required": false, "schema": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "TIDY-12392: smart-filter `has:attachment`. When true, restrict to rows whose attachments jsonb array is non-empty. Forwarded so the historic/cross-folder lane honors the attachment filter the same way the local window does.", "title": "Has Attachment" } }, { "description": "TIDY-10691: account id of the delegator whose inbox to view on behalf of. Email is outside the member-visible predicate, so the caller MUST hold an active inbox delegation grant from this account — otherwise this returns 403. Omit to view your own mailbox (unchanged behavior).", "in": "query", "name": "delegated_by", "required": false, "schema": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "description": "TIDY-10691: account id of the delegator whose inbox to view on behalf of. Email is outside the member-visible predicate, so the caller MUST hold an active inbox delegation grant from this account — otherwise this returns 403. Omit to view your own mailbox (unchanged behavior).", "title": "Delegated By" } }, { "description": "TIDY-18527: on folder=inbox, also return `split_counts` — the thread count of every inbox split (important, feed, paper_trail, screening) under the same filters, each equal to pagination.total for that split. Lets a caller reading one view of the inbox see the others.", "in": "query", "name": "include_split_counts", "required": false, "schema": { "default": false, "description": "TIDY-18527: on folder=inbox, also return `split_counts` — the thread count of every inbox split (important, feed, paper_trail, screening) under the same filters, each equal to pagination.total for that split. Lets a caller reading one view of the inbox see the others.", "title": "Include Split Counts", "type": "boolean" } }, { "in": "header", "name": "X-Trace-Id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailListResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List emails with search and filters", "tags": [ "emails" ] } }, "/api/v1/emails/actions/bulk": { "post": { "description": "Apply a mailbox action to a batch of email ids in one request.\n\nPer-id outcomes are reported in `results`; one bad id never fails the\nwhole request. Tenant isolation is enforced at the row level — ids that\ndo not belong to the caller's tenant return `success=false, error_code=not_found`\nand never expose data across tenants.", "operationId": "bulkEmailAction", "parameters": [ { "in": "header", "name": "X-Trace-Id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkEmailActionRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkEmailActionResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Bulk Email Action", "tags": [ "emails" ] } }, "/api/v1/emails/ai/grammar-check": { "post": { "description": "Check the provided text for grammar, spelling, and phrasing issues.\n Returns the corrected text and a list of individual corrections.\n\n Related: TIDY-4216 (AI Compose Tools)", "operationId": "grammarCheck", "parameters": [ { "in": "header", "name": "X-Trace-Id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GrammarCheckRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GrammarCheckResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Check grammar and spelling using AI", "tags": [ "emails" ] } }, "/api/v1/emails/ai/reformat": { "post": { "description": "Reformat the provided text for clarity without changing its meaning.", "operationId": "reformatText", "parameters": [ { "in": "header", "name": "X-Trace-Id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReformatTextRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReformatTextResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Reformat text using AI", "tags": [ "emails" ] } }, "/api/v1/emails/ai/summarize": { "post": { "description": "Summarize the provided text into a concise version.\n Used by the compose toolbar's AI summarize button.\n\n Related: TIDY-4203 (AI Summarize Button)", "operationId": "summarizeText", "parameters": [ { "in": "header", "name": "X-Trace-Id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SummarizeTextRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SummarizeTextResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Summarize text using AI", "tags": [ "emails" ] } }, "/api/v1/emails/attachment/download": { "get": { "description": "Generate a signed URL for downloading an email attachment from Supabase Storage.\n\n The signed URL expires after the specified duration (default 1 hour).\n Use this URL to download the attachment directly from storage.\n\n Related: Email Interface Feature (KCC-3143)", "operationId": "getAttachmentSignedUrl", "parameters": [ { "description": "Storage path from attachment metadata", "in": "query", "name": "storage_path", "required": true, "schema": { "description": "Storage path from attachment metadata", "title": "Storage Path", "type": "string" } }, { "in": "header", "name": "X-Trace-Id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttachmentSignedUrlResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get signed URL for attachment download", "tags": [ "emails" ] } }, "/api/v1/emails/bodies": { "post": { "description": "Returns ``id``, ``variant``, ``body_html_sanitized``, ``body_text``, and ``body_markdown`` for each id, in input order. One-off request variants return normalized ``variant`` values (``html`` or ``markdown``) so callers can render without persisting the canonical OPFS row. Markdown requests never return HTML; they use ``body_markdown`` then ``body_text``. Cross-tenant ids, non-existent ids, and soft-deleted rows are returned with null body fields — never 404 the whole batch.\n\nUsed by the OPFS body-store hydrator and one-off body-mode toggles.", "operationId": "postEmailBodies", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailBodiesRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailBodiesResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Fetch email bodies for a batch of email ids", "tags": [ "emails" ] } }, "/api/v1/emails/by-message-id/{message_id}": { "get": { "description": "Retrieve email content by its RFC 822 Message-ID header.\n\n This endpoint is used for deep-linking to emails from search results,\n particularly for historic emails that were indexed but not fully processed.\n\n The message_id is URL-encoded as it may contain special characters like\n angle brackets (< >) and @ symbols.\n\n Returns:\n - Basic email metadata (from email_canonical)\n - Processing status info (load_type, summary_type, triage_result)\n - Canonical body content if available\n - Attachments list\n\n If email is found but not fully processed (summary_type != 'llm'),\n the frontend should trigger pipeline resume via ingestion-service.\n\n Returns 404 if none of the caller's own email carries this Message-ID.\n\n Related: KCC-3435 (Email Historic Search), KCC-3451 (Auto-link generation)", "operationId": "getEmailByMessageId", "parameters": [ { "in": "path", "name": "message_id", "required": true, "schema": { "title": "Message Id", "type": "string" } }, { "in": "header", "name": "X-Trace-Id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Getemailbymessageid", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get email by RFC 822 Message-ID", "tags": [ "emails" ] } }, "/api/v1/emails/by-participant": { "get": { "description": "Get emails where any of the specified email addresses appear in the from,\n to, cc, bcc or delivered-to fields.\n\n `view=conversations` (default) returns one entry per conversation (grouped\n by thread_id) with the most recent email's info, newest conversations first.\n\n `view=messages` returns every individual message, newest first, one page at\n a time: pass the response's `next_cursor` back as `cursor` for the next\n (older) page; `has_more` is false on the page holding the oldest message.\n\n Related: KCC-3325 F3: Portal Views Navigation\n Related: KCC-3636 - Group by conversation, not individual emails\n Related: TIDY-19339 - Message-level history pages", "operationId": "getEmailsByParticipant", "parameters": [ { "description": "Comma-separated list of email addresses", "in": "query", "name": "emails", "required": true, "schema": { "description": "Comma-separated list of email addresses", "title": "Emails", "type": "string" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 20, "maximum": 100, "title": "Limit", "type": "integer" } }, { "description": "conversations: one entry per thread. messages: every message, paged by cursor.", "in": "query", "name": "view", "required": false, "schema": { "default": "conversations", "description": "conversations: one entry per thread. messages: every message, paged by cursor.", "enum": [ "conversations", "messages" ], "title": "View", "type": "string" } }, { "description": "view=messages only: the next_cursor of the previous page.", "in": "query", "name": "cursor", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "view=messages only: the next_cursor of the previous page.", "title": "Cursor" } }, { "in": "header", "name": "X-Trace-Id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Getemailsbyparticipant", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get emails by participant email addresses", "tags": [ "emails" ] } }, "/api/v1/emails/compose/contacts": { "get": { "description": "Search contacts for email recipient autocomplete.\n\n Searches by name and email address with per-word AND matching\n (so \"Emily Grant\" finds \"Emily Amendola Grant\"), ranked by trigram\n similarity. Returns up to 10 matching contacts.\n\n Related: KCC-3330, TIDY-4000", "operationId": "searchContactsForCompose", "parameters": [ { "description": "Search query", "in": "query", "name": "q", "required": true, "schema": { "description": "Search query", "maxLength": 100, "minLength": 1, "title": "Q", "type": "string" } }, { "description": "Max results", "in": "query", "name": "limit", "required": false, "schema": { "default": 10, "description": "Max results", "maximum": 20, "minimum": 1, "title": "Limit", "type": "integer" } }, { "in": "header", "name": "X-Trace-Id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactSuggestionsResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Search contacts for recipient autocomplete", "tags": [ "emails" ] } }, "/api/v1/emails/compose/recent-contacts": { "get": { "description": "Returns up to 8 recently contacted email addresses, ordered by\n frequency then recency. Used for the To field dropdown on focus.\n\n Related: TIDY-4000 (Recently contacted list)", "operationId": "getRecentContacts", "parameters": [ { "description": "Max results", "in": "query", "name": "limit", "required": false, "schema": { "default": 8, "description": "Max results", "maximum": 20, "minimum": 1, "title": "Limit", "type": "integer" } }, { "in": "header", "name": "X-Trace-Id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_service__routers__emails__compose_contacts__RecentContactsResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get recently contacted email addresses", "tags": [ "emails" ] } }, "/api/v1/emails/compose/send-as-addresses": { "get": { "description": "Aggregates primary and alias addresses from the caller's active provider connections (account-scoped). Pass delegated_by to include a delegator's addresses when an active read_write inbox grant exists.", "operationId": "listSendAsAddresses2", "parameters": [ { "description": "TIDY-10691: account id of a delegator to send AS. Requires an active read_write inbox grant from that account; otherwise their addresses are omitted (read-only delegation cannot send).", "in": "query", "name": "delegated_by", "required": false, "schema": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "description": "TIDY-10691: account id of a delegator to send AS. Requires an active read_write inbox grant from that account; otherwise their addresses are omitted (read-only delegation cannot send).", "title": "Delegated By" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/api_service__routers__emails__compose_send_as__SendAsAddress" }, "title": "Response Listsendasaddresses2", "type": "array" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List all send-as addresses", "tags": [ "emails" ] } }, "/api/v1/emails/compose/validate-recipients": { "post": { "description": "Expand group + org recipient chips to concrete primary emails and return the deduped counts + flags WITHOUT sending — the same expansion the send path runs, so the compose client can warn pre-send (TIDY-14747).", "operationId": "validateComposeRecipients", "parameters": [ { "in": "header", "name": "X-Trace-Id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidateRecipientsRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecipientValidationResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Preview send-time recipient expansion", "tags": [ "emails" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Compose-UI pre-send preview; the agentic send path validates inline." } }, "/api/v1/emails/count": { "get": { "description": "Returns the count of pipeline runs (source documents) for the authenticated user's tenant.", "operationId": "getEmailCount", "parameters": [ { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailCountResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get document count", "tags": [ "emails" ] } }, "/api/v1/emails/drafts": { "get": { "description": "Get all drafts for the current user, ordered by updated_at desc.", "operationId": "listDrafts", "parameters": [ { "description": "Max drafts to return", "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "description": "Max drafts to return", "maximum": 100, "minimum": 1, "title": "Limit", "type": "integer" } }, { "description": "Offset for pagination", "in": "query", "name": "offset", "required": false, "schema": { "default": 0, "description": "Offset for pagination", "minimum": 0, "title": "Offset", "type": "integer" } }, { "description": "Comma-separated status filter (e.g. 'draft' or 'sending,failed'). Default returns draft+failed+sending.", "in": "query", "name": "status", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Comma-separated status filter (e.g. 'draft' or 'sending,failed'). Default returns draft+failed+sending.", "title": "Status" } }, { "in": "header", "name": "X-Trace-Id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DraftListResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List all email drafts", "tags": [ "emails" ] }, "post": { "description": "Create a new email draft for composition.\n\n Supports:\n - New emails (compose_type: 'new')\n - Replies (compose_type: 'reply', 'reply_all')\n - Forwards (compose_type: 'forward')\n\n For replies/forwards, provide reply_to_email_id to link to the original email.\n\n Related: KCC-3330 (S1.1: Basic Email Compose)", "operationId": "createEmailDraft", "parameters": [ { "in": "header", "name": "X-Trace-Id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_service__routers__emails__compose_models__CreateDraftRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DraftResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Create a new email draft", "tags": [ "emails" ] } }, "/api/v1/emails/drafts/ai-metrics": { "get": { "description": "Send-without-edit rate and median normalized edit distance over AI-originated drafts that were sent (TIDY-13467 / S5). scope=account (default) reports the caller; scope=tenant aggregates the tenant.", "operationId": "getAiDraftEditMetrics", "parameters": [ { "in": "query", "name": "scope", "required": false, "schema": { "default": "account", "enum": [ "account", "tenant" ], "title": "Scope", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiDraftEditMetricsResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "AI draft edit-distance metrics", "tags": [ "emails" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Analytics/reporting readout for the settings UI, not an agent action." } }, "/api/v1/emails/drafts/{draft_id}": { "delete": { "description": "Delete a draft email.", "operationId": "deleteDraft", "parameters": [ { "in": "path", "name": "draft_id", "required": true, "schema": { "format": "uuid", "title": "Draft Id", "type": "string" } }, { "in": "header", "name": "X-Trace-Id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Delete a draft", "tags": [ "emails" ] }, "get": { "description": "Get a draft by ID.", "operationId": "getDraft", "parameters": [ { "in": "path", "name": "draft_id", "required": true, "schema": { "format": "uuid", "title": "Draft Id", "type": "string" } }, { "in": "header", "name": "X-Trace-Id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DraftResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get a specific draft", "tags": [ "emails" ] }, "put": { "description": "Update a draft with new content. Supports partial updates.\n\n This endpoint is designed for auto-save functionality -\n only provided fields are updated.\n\n Related: KCC-3330 (F1.7: Auto-save drafts every 10 seconds)", "operationId": "updateDraft", "parameters": [ { "in": "path", "name": "draft_id", "required": true, "schema": { "format": "uuid", "title": "Draft Id", "type": "string" } }, { "in": "header", "name": "X-Trace-Id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateDraftRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DraftResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Update a draft (auto-save)", "tags": [ "emails" ] } }, "/api/v1/emails/drafts/{draft_id}/attachments": { "get": { "description": "List attachments currently attached to an email draft.\n\n Returned in insertion order (the order they were uploaded).\n\n Related: TIDY-7366 (SDK-vs-spec contract drift reconciliation).", "operationId": "listDraftAttachments", "parameters": [ { "in": "path", "name": "draft_id", "required": true, "schema": { "format": "uuid", "title": "Draft Id", "type": "string" } }, { "in": "header", "name": "X-Trace-Id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DraftAttachmentListResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List attachments on a draft", "tags": [ "emails" ] }, "post": { "description": "Upload a file attachment to an email draft.\n\n Max file size: 10MB. Common document and image types supported.\n Attachments are stored in Supabase Storage and referenced in the draft.\n\n Related: KCC-3354 (S7.3: Compose Attachments)", "operationId": "uploadDraftAttachment", "parameters": [ { "in": "path", "name": "draft_id", "required": true, "schema": { "format": "uuid", "title": "Draft Id", "type": "string" } }, { "in": "header", "name": "X-Trace-Id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/Body_uploadDraftAttachment" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DraftAttachmentUploadResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Upload an attachment to a draft", "tags": [ "emails" ] } }, "/api/v1/emails/drafts/{draft_id}/attachments/from-object": { "post": { "description": "Server-side materializes the referenced email (.eml, original bytes) or event (.ics) and appends it as a draft attachment. The bytes never round-trip the browser. Oversize returns 413. An existing email attachment (`attachment` / `email_attachment`) or a My Files file (`file`) is attached by reference to its stored bytes — no copy is stored.", "operationId": "attachObjectToDraft", "parameters": [ { "in": "path", "name": "draft_id", "required": true, "schema": { "format": "uuid", "title": "Draft Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DraftAttachFromObjectRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DraftAttachmentUploadResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Attach a Tidy object (.eml/.ics, an email attachment or a file) to a draft", "tags": [ "emails" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Server-side object serialization + draft attach; agents use compose endpoints." } }, "/api/v1/emails/drafts/{draft_id}/attachments/{attachment_id}": { "delete": { "description": "Remove an attachment from an email draft.\n\n The file is deleted from storage and removed from the draft's attachments list.\n\n Related: KCC-3354 (S7.3: Compose Attachments)", "operationId": "removeDraftAttachment", "parameters": [ { "in": "path", "name": "draft_id", "required": true, "schema": { "format": "uuid", "title": "Draft Id", "type": "string" } }, { "in": "path", "name": "attachment_id", "required": true, "schema": { "title": "Attachment Id", "type": "string" } }, { "in": "header", "name": "X-Trace-Id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DraftAttachmentRemoveResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Remove an attachment from a draft", "tags": [ "emails" ] } }, "/api/v1/emails/drafts/{draft_id}/feedback": { "post": { "description": "Record user feedback on an AI-generated draft.\n Used to improve future generations.\n\n Acceptance Criteria:\n - F8.4: Feedback: 'Too formal', 'Too casual', 'Too long'\n\n Related: KCC-3349 (S6.1: Draft in My Tone)", "operationId": "recordFeedback", "parameters": [ { "in": "path", "name": "draft_id", "required": true, "schema": { "format": "uuid", "title": "Draft Id", "type": "string" } }, { "in": "header", "name": "X-Trace-Id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DraftFeedbackRequest" } } }, "required": true }, "responses": { "204": { "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Record feedback on AI draft", "tags": [ "emails" ] } }, "/api/v1/emails/drafts/{draft_id}/generate": { "post": { "description": "Generate an AI-powered email reply based on the original email context\n and user's writing style.\n\n For new emails, provide context_hint to guide generation.\n For replies, the original email is used for context.\n\n Acceptance Criteria:\n - F8.1: 'Draft in my tone' button generates reply based on context\n - F8.3: User can edit, accept, or regenerate draft\n\n Related: KCC-3349 (S6.1: Draft in My Tone)", "operationId": "generateDraft", "parameters": [ { "in": "path", "name": "draft_id", "required": true, "schema": { "format": "uuid", "title": "Draft Id", "type": "string" } }, { "in": "header", "name": "X-Trace-Id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerateDraftRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerateDraftResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Generate AI draft in user's tone", "tags": [ "emails" ] } }, "/api/v1/emails/drafts/{draft_id}/retry": { "post": { "description": "Retry sending a draft that previously failed via provider dispatch.", "operationId": "retrySend", "parameters": [ { "in": "path", "name": "draft_id", "required": true, "schema": { "format": "uuid", "title": "Draft Id", "type": "string" } }, { "in": "header", "name": "X-Trace-Id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendDraftResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Retry sending a failed email", "tags": [ "emails" ] } }, "/api/v1/emails/drafts/{draft_id}/schedule": { "delete": { "description": "Cancel a scheduled email send and return it to draft status.", "operationId": "cancelScheduledSend", "parameters": [ { "in": "path", "name": "draft_id", "required": true, "schema": { "format": "uuid", "title": "Draft Id", "type": "string" } }, { "in": "header", "name": "X-Trace-Id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UndoSendResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Cancel a scheduled send", "tags": [ "emails" ] }, "post": { "description": "Schedule a draft email to be sent at a future time.", "operationId": "scheduleSend", "parameters": [ { "in": "path", "name": "draft_id", "required": true, "schema": { "format": "uuid", "title": "Draft Id", "type": "string" } }, { "in": "header", "name": "X-Trace-Id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScheduleSendRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScheduleSendResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Schedule a draft to send later", "tags": [ "emails" ] } }, "/api/v1/emails/drafts/{draft_id}/send": { "post": { "description": "Send a draft email via the appropriate provider with undo grace period.", "operationId": "sendDraft", "parameters": [ { "in": "path", "name": "draft_id", "required": true, "schema": { "format": "uuid", "title": "Draft Id", "type": "string" } }, { "in": "header", "name": "X-Trace-Id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendDraftRequest", "default": { "suppress_signature": false, "wait_for_send": false } } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendDraftResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Send a draft email", "tags": [ "emails" ] } }, "/api/v1/emails/drafts/{draft_id}/status": { "get": { "description": "Lightweight status check for polling after send.", "operationId": "getDraftStatus", "parameters": [ { "in": "path", "name": "draft_id", "required": true, "schema": { "format": "uuid", "title": "Draft Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DraftStatusResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Check draft send status", "tags": [ "emails" ] } }, "/api/v1/emails/drafts/{draft_id}/undo": { "post": { "description": "Undo a recently sent email within the grace period.", "operationId": "undoSend", "parameters": [ { "in": "path", "name": "draft_id", "required": true, "schema": { "format": "uuid", "title": "Draft Id", "type": "string" } }, { "in": "header", "name": "X-Trace-Id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UndoSendResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Undo a recently sent email", "tags": [ "emails" ] } }, "/api/v1/emails/files/{attachment_id}/extractions": { "get": { "description": "Itemized extraction insight for one email attachment — the same contract\nthe defense replay renders, generalized to an attachment source. Gated on the\nowning email being the caller's (or delegated to them) and past the Important\nscreening gate; 404 otherwise.", "operationId": "getAttachmentExtractions", "parameters": [ { "in": "path", "name": "attachment_id", "required": true, "schema": { "format": "uuid", "title": "Attachment Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExtractionInsightsResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Extraction insight for an email attachment", "tags": [ "emails" ], "x-mcp-skip": true, "x-mcp-skip-reason": "Web insight panel; agents read extracted entities + canonical content via the pipeline/entity endpoints, not this aggregate view." } }, "/api/v1/emails/files/{file_id}": { "get": { "description": "Return processed attachment metadata by processed_attachments.id with tenant scoping. Used by the web file preview tab when the local-first cache misses.", "operationId": "getProcessedAttachment", "parameters": [ { "in": "path", "name": "file_id", "required": true, "schema": { "format": "uuid", "title": "File Id", "type": "string" } }, { "in": "header", "name": "X-Trace-Id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProcessedAttachmentResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get processed attachment metadata", "tags": [ "emails" ], "x-mcp-skip": true } }, "/api/v1/emails/focus-queue": { "get": { "description": "Return focus reply queue items with email metadata.", "operationId": "listFocusQueue", "parameters": [ { "in": "header", "name": "X-Trace-Id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FocusQueueResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List focus reply queue items", "tags": [ "emails" ] } }, "/api/v1/emails/focus-queue/add": { "post": { "description": "Add one or more emails to the focus reply queue.", "operationId": "addToFocusQueue", "parameters": [ { "in": "header", "name": "X-Trace-Id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddToFocusQueueRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddToFocusQueueResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Add emails to focus reply queue", "tags": [ "emails" ] } }, "/api/v1/emails/focus-queue/reorder": { "post": { "description": "Atomically reorder queue positions for the current account.", "operationId": "reorderFocusQueue", "parameters": [ { "in": "header", "name": "X-Trace-Id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReorderFocusQueueRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReorderFocusQueueResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Reorder focus reply queue", "tags": [ "emails" ] } }, "/api/v1/emails/focus-queue/{email_id}": { "delete": { "description": "Remove a single email from the focus reply queue.", "operationId": "removeFromFocusQueue", "parameters": [ { "description": "Typed ID with prefix 'E'", "in": "path", "name": "email_id", "required": true, "schema": { "description": "Typed ID with prefix 'E'", "title": "Email Id", "type": "string" } }, { "in": "header", "name": "X-Trace-Id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Remove an email from the focus reply queue", "tags": [ "emails" ] } }, "/api/v1/emails/folder-counts": { "get": { "description": "Get counts of emails in each folder (inbox, archive, all) and split categories.\n\n Returns counts for display in folder navigation/tabs and split tabs.\n Only counts non-deleted emails for the authenticated tenant.\n\n **Split counts (TIDY-4082 three-way splits):**\n - important: Action-required emails (VIP, direct personal)\n - feed: Newsletters, broadcasts, mailing lists\n - paper_trail: Receipts, confirmations, transactional\n - screening_count: Emails with screening_status='pending'\n\n Related: Email Interface Feature (KCC-3143), Split Inbox (TIDY-4082)", "operationId": "getFolderCounts", "parameters": [ { "in": "header", "name": "X-Trace-Id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FolderCountsResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get folder email counts", "tags": [ "emails" ] } }, "/api/v1/emails/folders": { "get": { "description": "Return the user's folder layout for left-nav rendering.\n\nResponse shape:\n {\n \"tidy_defaults\": [{key, label, count, icon}, ...],\n \"custom_folders\": [{provider_folder_path, ..., children: [...]}]\n }", "operationId": "listEmailFolders", "parameters": [ { "in": "query", "name": "email_source_id", "required": false, "schema": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Email Source Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Listemailfolders", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List Tidy default folders + nested provider custom folders", "tags": [ "emails" ] } }, "/api/v1/emails/folders/mapping": { "post": { "description": "Re-target a provider folder to a different Tidy bucket.\n\nValidates the new ``tidy_folder`` against the CHECK constraint\nvalues, updates the row, and forces ``email_canonical.tidy_folder``\nrecompute via the helper SQL function from migration 323.", "operationId": "updateFolderMapping", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FolderMappingUpdateRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FolderMappingResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Override the Tidy folder a provider folder maps to", "tags": [ "emails" ] } }, "/api/v1/emails/folders/refresh": { "post": { "description": "Re-run folder discovery for an existing source.\n\nAcquires a per-(tenant,source) advisory lock so two simultaneous\nrefresh requests do not race. New folders flow through\n``apply_default_folder_mappings()``; already-mapped paths are\nskipped via ``ON CONFLICT``.", "operationId": "refreshEmailFolders", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RefreshFoldersRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RefreshFoldersResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Re-discover provider folders and apply default mappings", "tags": [ "emails" ] } }, "/api/v1/emails/follow-ups": { "get": { "description": "Get list of emails that may need follow-up (sent emails without reply).\n\n Acceptance Criteria:\n - F8.5: Auto-draft follow-up if no reply in 3+ days\n - Notification for stale conversations needing follow-up\n\n Related: KCC-3351 (S6.3: Follow-up Reminders)", "operationId": "listFollowUps", "parameters": [ { "description": "Filter by status: pending, snoozed, all", "in": "query", "name": "status_filter", "required": false, "schema": { "default": "pending", "description": "Filter by status: pending, snoozed, all", "title": "Status Filter", "type": "string" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 20, "maximum": 100, "minimum": 1, "title": "Limit", "type": "integer" } }, { "in": "query", "name": "offset", "required": false, "schema": { "default": 0, "minimum": 0, "title": "Offset", "type": "integer" } }, { "in": "header", "name": "X-Trace-Id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FollowUpListResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List follow-up reminders", "tags": [ "emails" ] } }, "/api/v1/emails/follow-ups/scan": { "post": { "description": "Scan sent emails for conversations without replies.\n Creates follow-up reminders for emails older than threshold (default 3 days).\n\n Related: KCC-3351 (S6.3: Follow-up Reminders)", "operationId": "scanForFollowUps", "parameters": [ { "in": "header", "name": "X-Trace-Id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScanResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Scan for stale conversations", "tags": [ "emails" ] } }, "/api/v1/emails/follow-ups/{follow_up_id}/dismiss": { "post": { "description": "Dismiss a follow-up reminder (mark as not needed).\n\n Acceptance Criteria:\n - One-click send or dismiss follow-up\n\n Related: KCC-3351 (S6.3: Follow-up Reminders)", "operationId": "dismissFollowUp", "parameters": [ { "in": "path", "name": "follow_up_id", "required": true, "schema": { "format": "uuid", "title": "Follow Up Id", "type": "string" } }, { "in": "header", "name": "X-Trace-Id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Dismiss follow-up reminder", "tags": [ "emails" ] } }, "/api/v1/emails/follow-ups/{follow_up_id}/draft": { "post": { "description": "Generate an AI-powered follow-up email draft.\n\n Acceptance Criteria:\n - F8.5: Auto-draft follow-up if no reply in 3+ days\n\n Related: KCC-3351 (S6.3: Follow-up Reminders)", "operationId": "generateDraft2", "parameters": [ { "in": "path", "name": "follow_up_id", "required": true, "schema": { "format": "uuid", "title": "Follow Up Id", "type": "string" } }, { "in": "header", "name": "X-Trace-Id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FollowUpDraftResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Generate AI follow-up draft", "tags": [ "emails" ] } }, "/api/v1/emails/follow-ups/{follow_up_id}/snooze": { "post": { "description": "Snooze a follow-up reminder for later.\n\n Related: KCC-3351 (S6.3: Follow-up Reminders)", "operationId": "snoozeFollowUp", "parameters": [ { "in": "path", "name": "follow_up_id", "required": true, "schema": { "format": "uuid", "title": "Follow Up Id", "type": "string" } }, { "in": "header", "name": "X-Trace-Id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_service__routers__emails__ai_models__SnoozeRequest" } } }, "required": true }, "responses": { "204": { "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Snooze follow-up reminder", "tags": [ "emails" ] } }, "/api/v1/emails/groups": { "get": { "description": "Get recurring email participant groups.\n\nAnalyzes email threads to find groups of people that frequently appear together\nin conversations. Groups are sorted by recency and conversation count.\n\nThe algorithm:\n1. For each email, extract the participant set (from + to + cc)\n2. Group emails by their participant set hash\n3. Filter to groups with >= min_conversations emails\n4. Filter to groups with >= min_members participants (excluding self)\n5. Sort by last_email_at DESC, then conversation_count DESC", "operationId": "getEmailGroups", "parameters": [ { "in": "query", "name": "limit", "required": false, "schema": { "default": 20, "maximum": 100, "title": "Limit", "type": "integer" } }, { "description": "Minimum conversations to form a group", "in": "query", "name": "min_conversations", "required": false, "schema": { "default": 3, "description": "Minimum conversations to form a group", "title": "Min Conversations", "type": "integer" } }, { "description": "Minimum members in a group (excluding self)", "in": "query", "name": "min_members", "required": false, "schema": { "default": 2, "description": "Minimum members in a group (excluding self)", "title": "Min Members", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailGroupsResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Email Groups", "tags": [ "emails", "email-groups" ] } }, "/api/v1/emails/groups/{group_id}/conversations": { "get": { "description": "Get email conversations for a specific participant group.\n\nNote: This is a placeholder - actual implementation would need to\nreconstruct the participant set from group_id and query matching emails.", "operationId": "getGroupConversations", "parameters": [ { "in": "path", "name": "group_id", "required": true, "schema": { "title": "Group Id", "type": "string" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 20, "maximum": 100, "title": "Limit", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Getgroupconversations", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Group Conversations", "tags": [ "emails", "email-groups" ] } }, "/api/v1/emails/groups/{group_id}/name": { "patch": { "description": "Rename an email group with a custom name.\n\nPass custom_name as empty string or None to clear the custom name.", "operationId": "renameGroup", "parameters": [ { "in": "path", "name": "group_id", "required": true, "schema": { "title": "Group Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RenameGroupRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RenameGroupResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Rename Group", "tags": [ "emails", "email-groups" ] } }, "/api/v1/emails/imap-search": { "post": { "description": "Search the caller's own mailboxes on the mail server.\n\nThe mailbox's own transport decides the search: IMAP for an app password,\nthe Gmail API or Microsoft Graph for a Google or Microsoft mailbox\nconnected by sign-in alone. Without ``search_all_accounts`` only the\nmember's first-connected mailbox is searched.", "operationId": "searchEmailsImap", "parameters": [ { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImapSearchProxyRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImapSearchProxyResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Search historical emails directly on the mail server (IMAP, Gmail API or Microsoft Graph)", "tags": [ "emails" ], "x-mcp-skip": true, "x-mcp-skip-reason": "Assistant-internal mail-server search surface; exposed to users via the tidy_imap_search assistant tool, not a standalone MCP tool." } }, "/api/v1/emails/import": { "post": { "description": "Files a raw RFC 822 message in the caller's own mailbox through the email pipeline: threaded and extracted like arriving mail, dated by its own Date header, and never screened, notified or auto-answered as new mail. Deduplicated on Message-ID within the caller's mail: a message already there answers 200 with its existing id.", "operationId": "importEmail", "parameters": [ { "in": "header", "name": "X-Trace-Id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailImportRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailImportResponse" } } }, "description": "Already in the mailbox" }, "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailImportResponse" } } }, "description": "Successful Response" }, "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailImportResponse" } } }, "description": "Accepted, not filed yet" }, "413": { "description": "The message exceeds the email size limit" }, "422": { "description": "Not base64, unparseable, or missing a Message-ID" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Import one historical email into your mailbox", "tags": [ "emails" ], "x-local-capability": "cloud" } }, "/api/v1/emails/labels": { "get": { "description": "List all unique labels used across tenant's emails.\n\n Returns alphabetically sorted list of labels for autocomplete/suggestions.\n Only includes labels from non-deleted emails.\n\n Related: Email Interface Feature (KCC-3143), Phase 04-api-detail-actions", "operationId": "getAvailableLabels", "parameters": [ { "in": "header", "name": "X-Trace-Id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AvailableLabelsResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get available labels", "tags": [ "emails" ] } }, "/api/v1/emails/notes/{note_id}": { "delete": { "description": "Delete a private note by its ID.\n\n Only the note author can delete their own notes (enforced by RLS).\n Returns 204 No Content on success, 404 if note not found.\n\n Related: KCC-3245 (Unified Conversational Email Interface), KCC-3248", "operationId": "deleteNote", "parameters": [ { "in": "path", "name": "note_id", "required": true, "schema": { "format": "uuid", "title": "Note Id", "type": "string" } }, { "in": "header", "name": "X-Trace-Id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Delete a note", "tags": [ "emails" ] } }, "/api/v1/emails/quarantine": { "get": { "description": "List email_canonical rows held back by ingestion: provider-spam (S1) and malware-bearing (S2). Scoped to the caller's tenant + account. Oldest quarantines surface last (most recent first).", "operationId": "listQuarantinedEmails", "parameters": [ { "description": "Items per page", "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "description": "Items per page", "maximum": 100, "minimum": 1, "title": "Limit", "type": "integer" } }, { "description": "Pagination offset", "in": "query", "name": "offset", "required": false, "schema": { "default": 0, "description": "Pagination offset", "minimum": 0, "title": "Offset", "type": "integer" } }, { "in": "header", "name": "X-Trace-Id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuarantineListResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List quarantined emails", "tags": [ "emails" ] } }, "/api/v1/emails/reply-queue": { "get": { "description": "Returns emails where is_starred=true and is_archived=false, ordered by sent_at DESC. Related: TIDY-4099.", "operationId": "getReplyQueue", "parameters": [ { "in": "header", "name": "X-Trace-Id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReplyQueueResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get starred emails for Focus & Reply mode", "tags": [ "emails" ] } }, "/api/v1/emails/screening-audit": { "get": { "description": "Read-only tenant scan for the TIDY-17183 class of screening misses.", "operationId": "auditEmailScreening", "parameters": [ { "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "maximum": 200, "minimum": 1, "title": "Limit", "type": "integer" } }, { "in": "header", "name": "X-Trace-Id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailScreeningAuditResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List junk sender keys and orphaned screening holds for this tenant", "tags": [ "emails" ], "x-local-capability": "local" } }, "/api/v1/emails/send-as-addresses": { "get": { "description": "Return the caller's send-as addresses from active provider connections.\n\nTIDY-10691: account-scoped — only connections the caller owns (plus an\nauthorized delegator's, given an active read_write inbox grant) are\nreturned. Aliases from unrelated tenant members are never surfaced.", "operationId": "listSendAsAddresses", "parameters": [ { "description": "TIDY-10691: account id of a delegator to send AS. Requires an active read_write inbox grant from that account; otherwise their addresses are omitted.", "in": "query", "name": "delegated_by", "required": false, "schema": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "description": "TIDY-10691: account id of a delegator to send AS. Requires an active read_write inbox grant from that account; otherwise their addresses are omitted.", "title": "Delegated By" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/api_service__models__connection_policy__SendAsAddress" }, "title": "Response Listsendasaddresses", "type": "array" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List send-as addresses", "tags": [ "connection-policy", "connection-policy" ] } }, "/api/v1/emails/sources": { "get": { "description": "Get list of email sources (accounts) that have emails for this tenant.\n\n Returns email sources for filtering emails by source account.\n Only includes sources with status = 'active' or that have emails.\n\n Related: Email Interface Feature (KCC-3143), Phase 07-mobile-thread-view", "operationId": "getEmailSources", "parameters": [ { "in": "header", "name": "X-Trace-Id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailSourcesResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get available email sources", "tags": [ "emails" ] } }, "/api/v1/emails/splits": { "get": { "description": "List all custom email splits for the current user.\n\n Returns splits ordered by position, excluding hidden splits unless\n include_hidden query parameter is true.\n\n Related: KCC-3337 - Custom Splits", "operationId": "listSplits", "parameters": [ { "in": "query", "name": "include_hidden", "required": false, "schema": { "default": false, "title": "Include Hidden", "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomSplitListResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List custom email splits", "tags": [ "emails" ] }, "post": { "description": "Create a new custom email split.\n\n **Filter criteria (combine any):**\n - filter_senders: Email addresses to match\n - filter_domains: Domains to match (e.g., 'school.edu')\n - filter_keywords: Keywords in subject/body\n - filter_labels: Gmail/IMAP labels\n - filter_triage_labels: to_respond, fyi, low_priority\n - filter_has_attachments: true/false/null\n - filter_is_unread: true/false/null\n\n Related: KCC-3337 - Custom Splits", "operationId": "createSplit", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomSplitCreate" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomSplitResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Create a custom email split", "tags": [ "emails" ] } }, "/api/v1/emails/splits/reorder": { "post": { "description": "Reorder custom splits by providing an ordered list of split IDs.\n Position values will be assigned based on array order.\n\n Related: KCC-3337 - Custom Splits", "operationId": "reorderSplits", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomSplitReorderRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomSplitListResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Reorder custom splits", "tags": [ "emails" ] } }, "/api/v1/emails/splits/{split_id}": { "delete": { "description": "Delete a custom split.", "operationId": "deleteSplit", "parameters": [ { "in": "path", "name": "split_id", "required": true, "schema": { "format": "uuid", "title": "Split Id", "type": "string" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Delete a custom split", "tags": [ "emails" ] }, "get": { "description": "Get a custom split by ID.", "operationId": "getSplit", "parameters": [ { "in": "path", "name": "split_id", "required": true, "schema": { "format": "uuid", "title": "Split Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomSplitResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get custom split details", "tags": [ "emails" ] }, "put": { "description": "Update a custom split.", "operationId": "updateSplit", "parameters": [ { "in": "path", "name": "split_id", "required": true, "schema": { "format": "uuid", "title": "Split Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomSplitUpdate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomSplitResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Update a custom split", "tags": [ "emails" ] } }, "/api/v1/emails/thread/{thread_id}": { "get": { "description": "Retrieve all emails and notes belonging to a conversation thread.\n\n Returns a merged timeline of emails and user's private notes, sorted chronologically.\n Each item has a 'type' discriminator ('email' or 'note') for frontend rendering.\n\n Notes are filtered to the current user only (private annotations).\n Thread identification uses the computed thread_id field from email threading logic.\n\n Returns 404 if no emails exist for the given thread_id.\n\n Related: KCC-3245 (Unified Conversational Email Interface), KCC-3248", "operationId": "getThreadEmails", "parameters": [ { "in": "path", "name": "thread_id", "required": true, "schema": { "format": "uuid", "title": "Thread Id", "type": "string" } }, { "in": "header", "name": "X-Trace-Id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ThreadWithNotesResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get thread with emails and notes", "tags": [ "emails" ] } }, "/api/v1/emails/thread/{thread_id}/summary": { "get": { "description": "Get the conversation-level summary and badge counts for a thread.\n\n **Badges returned:**\n - Email count and participant count\n - Attachment count and has_attachments flag\n - Note count (user-created notes)\n - Task counts: total, completed, overdue\n - Unread email count\n\n Related: KCC-3336 - Conversation Summaries & Badges", "operationId": "getConversationSummary", "parameters": [ { "in": "path", "name": "thread_id", "required": true, "schema": { "format": "uuid", "title": "Thread Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationSummaryResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get conversation summary with badges", "tags": [ "emails" ] } }, "/api/v1/emails/threads/merge": { "post": { "description": "Merges multiple threads into the first thread_id (canonical). Related: TIDY-4097.", "operationId": "mergeThreads", "parameters": [ { "in": "header", "name": "X-Trace-Id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ThreadMergeRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ThreadMergeResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Merge email threads", "tags": [ "emails" ] } }, "/api/v1/emails/threads/{thread_id}/unfollow": { "delete": { "description": "Removes the unfollow marker from a thread. Related: TIDY-4098.", "operationId": "followThread", "parameters": [ { "in": "path", "name": "thread_id", "required": true, "schema": { "format": "uuid", "title": "Thread Id", "type": "string" } }, { "in": "header", "name": "X-Trace-Id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ThreadUnfollowResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Re-follow an email thread", "tags": [ "emails" ] }, "get": { "description": "Returns whether a thread is unfollowed. Related: TIDY-4098.", "operationId": "getUnfollowStatus", "parameters": [ { "in": "path", "name": "thread_id", "required": true, "schema": { "format": "uuid", "title": "Thread Id", "type": "string" } }, { "in": "header", "name": "X-Trace-Id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ThreadUnfollowStatusResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Check thread unfollow status", "tags": [ "emails" ] }, "post": { "description": "Marks a thread as unfollowed. New emails in this thread will be auto-archived. Related: TIDY-4098.", "operationId": "unfollowThread", "parameters": [ { "in": "path", "name": "thread_id", "required": true, "schema": { "format": "uuid", "title": "Thread Id", "type": "string" } }, { "in": "header", "name": "X-Trace-Id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ThreadUnfollowResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Unfollow an email thread", "tags": [ "emails" ] } }, "/api/v1/emails/threads/{thread_id}/unmerge": { "post": { "description": "Restores threads that were previously merged into this thread. Related: TIDY-4097.", "operationId": "unmergeThreads", "parameters": [ { "in": "path", "name": "thread_id", "required": true, "schema": { "format": "uuid", "title": "Thread Id", "type": "string" } }, { "in": "header", "name": "X-Trace-Id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ThreadUnmergeResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Unmerge threads from a canonical thread", "tags": [ "emails" ] } }, "/api/v1/emails/triage-drop": { "post": { "description": "Apply the per-target teach + message move, returning the undo snapshot.", "operationId": "triageSplitDrop", "parameters": [ { "in": "header", "name": "X-Trace-Id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TriageDropRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TriageDropResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Teach a sender's split rule and move the dropped message(s)", "tags": [ "emails" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/emails/triage-drop/undo": { "post": { "description": "Reverse the whole gesture: restore message placement AND the sender rule(s).", "operationId": "undoTriageSplitDrop", "parameters": [ { "in": "header", "name": "X-Trace-Id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TriageDropUndoRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TriageDropUndoResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Restore the exact pre-drop state of a triage-split drop", "tags": [ "emails" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/emails/writing-style": { "get": { "description": "Get the user's learned writing style profile.\n Returns defaults if no profile exists yet.\n\n Acceptance Criteria:\n - F8.2: AI learns from user's past sent emails\n\n Related: KCC-3349 (S6.1: Draft in My Tone)", "operationId": "getWritingStyle", "parameters": [ { "in": "header", "name": "X-Trace-Id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WritingStyleResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get user's writing style profile", "tags": [ "emails" ] } }, "/api/v1/emails/writing-style/extract": { "post": { "description": "Trigger writing style extraction from the user's 30 most recent sent emails.", "operationId": "triggerExtraction", "parameters": [ { "in": "header", "name": "X-Trace-Id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExtractResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Extract writing style from sent emails", "tags": [ "emails" ] } }, "/api/v1/emails/writing-style/profile": { "get": { "description": "Get the user's current writing style profile with all expanded fields.", "operationId": "getProfile", "parameters": [ { "in": "header", "name": "X-Trace-Id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProfileResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get current writing style profile", "tags": [ "emails" ] } }, "/api/v1/emails/{email_id}": { "get": { "description": "Get email body, attachments, and thread position. Accepts email_canonical.id, canonical_documents.id, or document_chunks.id (all resolved to email_canonical.id). Related: KCC-3143, KCC-3464", "operationId": "getEmailDetail", "parameters": [ { "description": "Typed ID with prefix 'E'", "in": "path", "name": "email_id", "required": true, "schema": { "description": "Typed ID with prefix 'E'", "title": "Email Id", "type": "string" } }, { "description": "TIDY-10691: account id of the delegator whose email detail to view on behalf of. Requires an active inbox delegation grant.", "in": "query", "name": "delegated_by", "required": false, "schema": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "description": "TIDY-10691: account id of the delegator whose email detail to view on behalf of. Requires an active inbox delegation grant.", "title": "Delegated By" } }, { "in": "header", "name": "X-Trace-Id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailDetailResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get full email detail with thread context", "tags": [ "emails" ] } }, "/api/v1/emails/{email_id}/accept-suggestion": { "post": { "description": "Copies suggested_subject to display_subject. Related: TIDY-4100.", "operationId": "acceptSuggestion", "parameters": [ { "description": "Typed ID with prefix 'E'", "in": "path", "name": "email_id", "required": true, "schema": { "description": "Typed ID with prefix 'E'", "title": "Email Id", "type": "string" } }, { "in": "header", "name": "X-Trace-Id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcceptSuggestionResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Accept AI subject suggestion", "tags": [ "emails" ] } }, "/api/v1/emails/{email_id}/archive": { "post": { "description": "Archive an email.", "operationId": "archiveEmail", "parameters": [ { "description": "Typed ID with prefix 'E'", "in": "path", "name": "email_id", "required": true, "schema": { "description": "Typed ID with prefix 'E'", "title": "Email Id", "type": "string" } }, { "in": "header", "name": "X-Trace-Id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailActionResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Archive Email", "tags": [ "emails" ] } }, "/api/v1/emails/{email_id}/associated-objects": { "get": { "description": "Returns real entities (events, tasks, contacts, reminders, notes, attachments, and reference extraction insights) linked to an email through the pipeline.", "operationId": "getAssociatedObjects", "parameters": [ { "description": "Typed ID with prefix 'E'", "in": "path", "name": "email_id", "required": true, "schema": { "description": "Typed ID with prefix 'E'", "title": "Email Id", "type": "string" } }, { "in": "header", "name": "X-Trace-Id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssociatedObjectsResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get associated objects for an email", "tags": [ "emails" ] } }, "/api/v1/emails/{email_id}/attachment/original": { "get": { "description": "Return an attachment directly from the stored raw MIME source for an email. Falls through to AttachmentBytesService (TIDY-6862) when raw MIME is not available (e.g., API-synced Gmail/Zoho/Microsoft emails).", "operationId": "getOriginalEmailAttachment", "parameters": [ { "description": "Typed ID with prefix 'E'", "in": "path", "name": "email_id", "required": true, "schema": { "description": "Typed ID with prefix 'E'", "title": "Email Id", "type": "string" } }, { "description": "Original attachment filename", "in": "query", "name": "filename", "required": true, "schema": { "description": "Original attachment filename", "minLength": 1, "title": "Filename", "type": "string" } }, { "in": "header", "name": "X-Trace-Id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Getoriginalemailattachment", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get original email attachment bytes", "tags": [ "emails" ] } }, "/api/v1/emails/{email_id}/attachments/{filename}/extracted-text": { "get": { "description": "Assistant attachment reader: returns the docling-extracted markdown text for one attachment, or a clear 'not processed yet' signal when the pipeline has not produced text. With queue_if_missing=true an unextracted attachment is dispatched for on-demand extraction and the response carries extraction_state + retry_after_seconds so the caller can poll for the result. TIDY-13457, TIDY-14782.", "operationId": "getEmailAttachmentText", "parameters": [ { "in": "path", "name": "filename", "required": true, "schema": { "title": "Filename", "type": "string" } }, { "description": "Typed ID with prefix 'E'", "in": "path", "name": "email_id", "required": true, "schema": { "description": "Typed ID with prefix 'E'", "title": "Email Id", "type": "string" } }, { "description": "When true and the attachment has no extracted text, queue an on-demand docling extraction (idempotent on double-submit) and report extraction_state='queued'/'processing'.", "in": "query", "name": "queue_if_missing", "required": false, "schema": { "default": false, "description": "When true and the attachment has no extracted text, queue an on-demand docling extraction (idempotent on double-submit) and report extraction_state='queued'/'processing'.", "title": "Queue If Missing", "type": "boolean" } }, { "in": "header", "name": "X-Trace-Id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailAttachmentTextResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Read the docling-extracted text of an email attachment", "tags": [ "emails" ], "x-mcp-skip": true, "x-mcp-skip-reason": "Assistant-internal email reader surface; exposed to users via the tidy_email_read / tidy_email_attachment_text assistant tools, not standalone MCP tools." } }, "/api/v1/emails/{email_id}/availability": { "get": { "description": "Check user's calendar availability for dates mentioned in email.\n\n Acceptance Criteria:\n - F7.3: Show user availability when date mentioned\n\n Related: KCC-3350 (S6.2: Calendar Integration)", "operationId": "checkAvailability", "parameters": [ { "description": "Typed ID with prefix 'E'", "in": "path", "name": "email_id", "required": true, "schema": { "description": "Typed ID with prefix 'E'", "title": "Email Id", "type": "string" } }, { "in": "header", "name": "X-Trace-Id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AvailabilityResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Check availability for detected dates", "tags": [ "emails" ] } }, "/api/v1/emails/{email_id}/block-sender": { "post": { "description": "Block a sender from the email detail context.", "operationId": "blockSenderFromEmail", "parameters": [ { "description": "Typed ID with prefix 'E'", "in": "path", "name": "email_id", "required": true, "schema": { "description": "Typed ID with prefix 'E'", "title": "Email Id", "type": "string" } }, { "in": "header", "name": "X-Trace-Id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BlockSenderRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BlockSenderResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Block Sender From Email", "tags": [ "emails" ] } }, "/api/v1/emails/{email_id}/cancel-expiry": { "post": { "description": "Cancels any pending email_expiry scheduled_events. Related: TIDY-4353.", "operationId": "cancelEmailExpiry", "parameters": [ { "description": "Typed ID with prefix 'E'", "in": "path", "name": "email_id", "required": true, "schema": { "description": "Typed ID with prefix 'E'", "title": "Email Id", "type": "string" } }, { "in": "header", "name": "X-Trace-Id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Cancelemailexpiry", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Cancel pending auto-expiry for an email", "tags": [ "emails" ] } }, "/api/v1/emails/{email_id}/create-event": { "post": { "description": "Create a calendar event based on detected dates and email context.\n\n Acceptance Criteria:\n - F7.2: One-click create calendar event from detected date\n\n Related: KCC-3350 (S6.2: Calendar Integration)", "operationId": "createEventFromEmail", "parameters": [ { "description": "Typed ID with prefix 'E'", "in": "path", "name": "email_id", "required": true, "schema": { "description": "Typed ID with prefix 'E'", "title": "Email Id", "type": "string" } }, { "in": "header", "name": "X-Trace-Id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateEventRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateEventResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Create calendar event from email", "tags": [ "emails" ] } }, "/api/v1/emails/{email_id}/create-note": { "post": { "description": "Create a note with quoted text provenance from an email body selection.\n\n The selected text is stored as immutable quoted content along with\n approximate character offsets, user-assigned tags, and optional user notes.\n The note is linked back to the source email for provenance tracking.\n\n Related: TIDY-4090 (Email-to-note text selection)", "operationId": "createExtractionNote", "parameters": [ { "description": "Typed ID with prefix 'E'", "in": "path", "name": "email_id", "required": true, "schema": { "description": "Typed ID with prefix 'E'", "title": "Email Id", "type": "string" } }, { "in": "header", "name": "X-Trace-Id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateExtractionNoteRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateExtractionNoteResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Create a note from selected email text", "tags": [ "emails" ] } }, "/api/v1/emails/{email_id}/credential/override": { "post": { "description": "Apply one credential override action to an email the caller owns.", "operationId": "credentialOverride", "parameters": [ { "description": "Typed ID with prefix 'E'", "in": "path", "name": "email_id", "required": true, "schema": { "description": "Typed ID with prefix 'E'", "title": "Email Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CredentialOverrideRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CredentialOverrideResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Correct the credential fast-lane treatment of an email", "tags": [ "emails" ], "x-mcp-skip": true } }, "/api/v1/emails/{email_id}/delete": { "post": { "description": "Soft-delete an email (deleted_at stamp; synced removal via PowerSync).\n\nIdempotent: deleting an already-deleted (or absent) email succeeds — the\ndesired end state holds either way, which keeps sync-batch retries safe.", "operationId": "deleteEmail", "parameters": [ { "description": "Typed ID with prefix 'E'", "in": "path", "name": "email_id", "required": true, "schema": { "description": "Typed ID with prefix 'E'", "title": "Email Id", "type": "string" } }, { "in": "header", "name": "X-Trace-Id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailActionResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Delete Email", "tags": [ "emails" ], "x-mcp-skip": true } }, "/api/v1/emails/{email_id}/detect-calendar": { "post": { "description": "Analyzes email content to detect:\n - Dates and times mentioned\n - Meeting links (Zoom, Meet, Teams, Webex)\n - Suggested event title\n\n Acceptance Criteria:\n - F7.1: Detect dates/times mentioned in email body\n - F7.4: Auto-detect meeting links\n\n Related: KCC-3350 (S6.2: Calendar Integration)", "operationId": "detectCalendarContent", "parameters": [ { "description": "Typed ID with prefix 'E'", "in": "path", "name": "email_id", "required": true, "schema": { "description": "Typed ID with prefix 'E'", "title": "Email Id", "type": "string" } }, { "in": "header", "name": "X-Trace-Id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CalendarDetectionResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Detect calendar content in email", "tags": [ "emails" ] } }, "/api/v1/emails/{email_id}/dismiss-suggestion": { "post": { "description": "Clears the suggested_subject. Related: TIDY-4100.", "operationId": "dismissSuggestion", "parameters": [ { "description": "Typed ID with prefix 'E'", "in": "path", "name": "email_id", "required": true, "schema": { "description": "Typed ID with prefix 'E'", "title": "Email Id", "type": "string" } }, { "in": "header", "name": "X-Trace-Id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_service__routers__emails__subject_suggestion__DismissSuggestionResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Dismiss AI subject suggestion", "tags": [ "emails" ] } }, "/api/v1/emails/{email_id}/display-subject": { "put": { "description": "Sets a custom display_subject on the email, preserving the original subject. Related: TIDY-4096.", "operationId": "updateDisplaySubject", "parameters": [ { "description": "Typed ID with prefix 'E'", "in": "path", "name": "email_id", "required": true, "schema": { "description": "Typed ID with prefix 'E'", "title": "Email Id", "type": "string" } }, { "in": "header", "name": "X-Trace-Id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DisplaySubjectRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DisplaySubjectResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Rename an email's display subject", "tags": [ "emails" ] } }, "/api/v1/emails/{email_id}/done": { "post": { "description": "Mark an email as done.", "operationId": "markAsDone", "parameters": [ { "description": "Typed ID with prefix 'E'", "in": "path", "name": "email_id", "required": true, "schema": { "description": "Typed ID with prefix 'E'", "title": "Email Id", "type": "string" } }, { "in": "header", "name": "X-Trace-Id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailActionResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Mark As Done", "tags": [ "emails" ] } }, "/api/v1/emails/{email_id}/feedback": { "post": { "description": "Submit feedback on an email's summary quality.\n\n **Feedback types:**\n - `thumbs_up` / `thumbs_down`: General quality indicator\n - `too_formal` / `too_casual`: Tone feedback\n - `too_long` / `too_short`: Length feedback\n - `inaccurate`: Summary doesn't match content\n - `helpful` / `unhelpful`: Usefulness feedback\n\n Feedback is used to improve summary quality over time.\n\n Related: KCC-3336 - Conversation Summaries & Badges", "operationId": "submitEmailSummaryFeedback", "parameters": [ { "description": "Typed ID with prefix 'E'", "in": "path", "name": "email_id", "required": true, "schema": { "description": "Typed ID with prefix 'E'", "title": "Email Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailFeedbackRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailFeedbackResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Submit email summary feedback", "tags": [ "emails" ] } }, "/api/v1/emails/{email_id}/fetch-body": { "post": { "description": "Fetch full email body from IMAP for a header-only email_canonical record.\n\nLooks up IMAP metadata (source, uid, folder), connects to IMAP,\nfetches RFC822, parses MIME, updates email_canonical with body fields\nand depth='body', then queues a HISTORIC_LIGHT pipeline message.\n\nThe path id is resolved by :data:`EmailIdPath`, which accepts the typed\n`E-<uuid>` id emitted by the LIST endpoint OR a bare `<uuid>` and yields\na bare canonical UUID before any DB query (malformed -> 422, never an\nuncaught asyncpg DataError -> 500). The dedup key therefore collapses\n`E-<uuid>` and `<uuid>` onto the same normalized id (TIDY-11855).\n\nReturns the parsed body immediately.", "operationId": "fetchBody", "parameters": [ { "description": "Typed ID with prefix 'E'", "in": "path", "name": "email_id", "required": true, "schema": { "description": "Typed ID with prefix 'E'", "title": "Email Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Fetchbody", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Fetch Body", "tags": [ "emails" ] } }, "/api/v1/emails/{email_id}/folder": { "post": { "description": "Move an email through ``EmailCanonicalWriter.apply_tidy_folder``.\n\nIdempotent: a no-op when the email already lives in the target\nfolder (writer's IS DISTINCT FROM guard returns 0).", "operationId": "moveEmailToFolder", "parameters": [ { "description": "Typed ID with prefix 'E'", "in": "path", "name": "email_id", "required": true, "schema": { "description": "Typed ID with prefix 'E'", "title": "Email Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MoveEmailFolderRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MoveEmailFolderResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Move an email to a different Tidy folder", "tags": [ "emails" ] } }, "/api/v1/emails/{email_id}/follow-up": { "delete": { "description": "Delete the email->contact follow-up link and reconcile the Follow Up\ngroup. 404 when no matching follow-up exists.", "operationId": "unflagEmailFollowUp", "parameters": [ { "in": "path", "name": "email_id", "required": true, "schema": { "format": "uuid", "title": "Email Id", "type": "string" } }, { "description": "Contact the follow-up was flagged against.", "in": "query", "name": "contact_id", "required": true, "schema": { "description": "Contact the follow-up was flagged against.", "format": "uuid", "title": "Contact Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FollowUpUnflagResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Resolve (unflag) an email follow-up", "tags": [ "emails", "emails" ] }, "post": { "description": "Flag an email for follow-up against a contact.\n\nWhen ``contact_id`` is omitted, the sender contact is resolved from the\nemail's from-address (404 if no approved contact matches, 409 with the\ncandidate list if ambiguous). Idempotent per (email, contact).", "operationId": "flagEmailFollowUp", "parameters": [ { "in": "path", "name": "email_id", "required": true, "schema": { "format": "uuid", "title": "Email Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FollowUpFlagRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FollowUpFlagResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Flag an email for follow-up", "tags": [ "emails", "emails" ] } }, "/api/v1/emails/{email_id}/forward": { "post": { "description": "Create a draft that forwards a specific email.\n\n The draft is pre-populated with:\n - Subject with \"Fwd:\" prefix\n - Forwarded message header and content\n - Optionally pre-set recipients if provided\n\n Related: KCC-3331 (F1.4: Forward email with optional cover message)", "operationId": "createForward", "parameters": [ { "description": "Typed ID with prefix 'E'", "in": "path", "name": "email_id", "required": true, "schema": { "description": "Typed ID with prefix 'E'", "title": "Email Id", "type": "string" } }, { "in": "header", "name": "X-Trace-Id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForwardRequest", "default": { "bcc_recipients": [], "body_html": "", "body_text": "", "cc_recipients": [], "include_original_attachments": false, "to_recipients": [] } } } } }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DraftResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Create a forward draft", "tags": [ "emails" ] } }, "/api/v1/emails/{email_id}/generate-draft": { "post": { "description": "Generate an AI-powered reply draft for the given email using the user's\n writing style profile and sent email examples. If a previous AI draft exists\n for this email, it is replaced.\n\n Related: TIDY-4357 (F3-S3: AI Draft Generation)", "operationId": "generateDraftForEmail", "parameters": [ { "description": "Typed ID with prefix 'E'", "in": "path", "name": "email_id", "required": true, "schema": { "description": "Typed ID with prefix 'E'", "title": "Email Id", "type": "string" } }, { "in": "header", "name": "X-Trace-Id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerateFocusDraftResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Generate or regenerate AI draft for an email", "tags": [ "emails" ] } }, "/api/v1/emails/{email_id}/labels": { "patch": { "description": "Add or remove labels from an email.", "operationId": "updateEmailLabels", "parameters": [ { "description": "Typed ID with prefix 'E'", "in": "path", "name": "email_id", "required": true, "schema": { "description": "Typed ID with prefix 'E'", "title": "Email Id", "type": "string" } }, { "in": "header", "name": "X-Trace-Id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LabelUpdateRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LabelUpdateResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Update Email Labels", "tags": [ "emails" ] } }, "/api/v1/emails/{email_id}/mark-not-spam": { "post": { "description": "Mark a spam/blocked email as not spam: revert classification and unblock sender.", "operationId": "markNotSpam", "parameters": [ { "description": "Typed ID with prefix 'E'", "in": "path", "name": "email_id", "required": true, "schema": { "description": "Typed ID with prefix 'E'", "title": "Email Id", "type": "string" } }, { "in": "header", "name": "X-Trace-Id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarkNotSpamResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Mark Not Spam", "tags": [ "emails" ] } }, "/api/v1/emails/{email_id}/mute": { "post": { "description": "Mute an email conversation.", "operationId": "muteEmail", "parameters": [ { "description": "Typed ID with prefix 'E'", "in": "path", "name": "email_id", "required": true, "schema": { "description": "Typed ID with prefix 'E'", "title": "Email Id", "type": "string" } }, { "in": "header", "name": "X-Trace-Id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailActionResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Mute Email", "tags": [ "emails" ] } }, "/api/v1/emails/{email_id}/mute-synthesis": { "get": { "description": "Deterministically propose sender + subject-template (+ discriminator token)\nconditions and embed a backtest of them so S4 can show impact + safety.", "operationId": "getMuteSynthesis", "parameters": [ { "description": "Typed ID with prefix 'E'", "in": "path", "name": "email_id", "required": true, "schema": { "description": "Typed ID with prefix 'E'", "title": "Email Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MuteSynthesisResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Propose the narrowest durable mute match for an email + backtest it", "tags": [ "emails" ], "x-mcp-skip": true } }, "/api/v1/emails/{email_id}/notes": { "get": { "description": "List private notes attached to a specific email message.\n\n Returns only notes authored by the current account (RLS enforcement).\n Returned in creation order (oldest first) so the UI can render them as\n a chronological thread.\n\n Returns 404 if the email is not found or belongs to a different tenant.\n\n Related: TIDY-7366 (SDK-vs-spec contract drift reconciliation).", "operationId": "listNotesForEmail", "parameters": [ { "description": "Typed ID with prefix 'E'", "in": "path", "name": "email_id", "required": true, "schema": { "description": "Typed ID with prefix 'E'", "title": "Email Id", "type": "string" } }, { "in": "header", "name": "X-Trace-Id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailNotesListResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List notes on an email", "tags": [ "emails" ] }, "post": { "description": "Create a private note attached to a specific email message.\n\n Notes are anchored to both the email (email_id) and its thread (thread_id).\n The thread_id is automatically derived from the email.\n Only the author can see their own notes (enforced by RLS).\n\n Returns 404 if the email is not found or belongs to a different tenant.\n\n Related: KCC-3245 (Unified Conversational Email Interface), KCC-3248", "operationId": "createNote", "parameters": [ { "description": "Typed ID with prefix 'E'", "in": "path", "name": "email_id", "required": true, "schema": { "description": "Typed ID with prefix 'E'", "title": "Email Id", "type": "string" } }, { "in": "header", "name": "X-Trace-Id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateNoteRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateNoteResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Create a note on an email", "tags": [ "emails" ] } }, "/api/v1/emails/{email_id}/overlays/{overlay_index}/approve": { "post": { "description": "Sets the overlay's approval_status to 'approved', confirming the AI extraction is correct. Related: TIDY-4089.", "operationId": "approveOverlay", "parameters": [ { "description": "Zero-based overlay index", "in": "path", "name": "overlay_index", "required": true, "schema": { "description": "Zero-based overlay index", "minimum": 0, "title": "Overlay Index", "type": "integer" } }, { "description": "Typed ID with prefix 'E'", "in": "path", "name": "email_id", "required": true, "schema": { "description": "Typed ID with prefix 'E'", "title": "Email Id", "type": "string" } }, { "in": "header", "name": "X-Trace-Id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Approveoverlay", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Approve an enrichment overlay", "tags": [ "emails" ] } }, "/api/v1/emails/{email_id}/overlays/{overlay_index}/dismiss": { "post": { "description": "Sets the overlay's approval_status to 'dismissed', indicating the user rejected the AI extraction. Related: TIDY-4089.", "operationId": "dismissOverlay", "parameters": [ { "description": "Zero-based overlay index", "in": "path", "name": "overlay_index", "required": true, "schema": { "description": "Zero-based overlay index", "minimum": 0, "title": "Overlay Index", "type": "integer" } }, { "description": "Typed ID with prefix 'E'", "in": "path", "name": "email_id", "required": true, "schema": { "description": "Typed ID with prefix 'E'", "title": "Email Id", "type": "string" } }, { "in": "header", "name": "X-Trace-Id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Dismissoverlay", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Dismiss an enrichment overlay", "tags": [ "emails" ] } }, "/api/v1/emails/{email_id}/proposed-items": { "get": { "description": "Returns pending-review entities (tasks, events, contacts, organizations) extracted from this email by the AI pipeline.", "operationId": "getProposedItems", "parameters": [ { "description": "Typed ID with prefix 'E'", "in": "path", "name": "email_id", "required": true, "schema": { "description": "Typed ID with prefix 'E'", "title": "Email Id", "type": "string" } }, { "in": "header", "name": "X-Trace-Id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProposedItemsResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get proposed items for an email", "tags": [ "emails" ] } }, "/api/v1/emails/{email_id}/proposed/event/{item_id}/apply-update": { "post": { "description": "Merges a pending extracted event into its close-match candidate and marks the pending event as resolved. Related: TIDY-3369.", "operationId": "applyProposedEventUpdate", "parameters": [ { "description": "Pending event ID", "in": "path", "name": "item_id", "required": true, "schema": { "description": "Pending event ID", "format": "uuid", "title": "Item Id", "type": "string" } }, { "description": "Typed ID with prefix 'E'", "in": "path", "name": "email_id", "required": true, "schema": { "description": "Typed ID with prefix 'E'", "title": "Email Id", "type": "string" } }, { "in": "header", "name": "X-Trace-Id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/ApplyEventUpdateRequest" }, { "type": "null" } ], "title": "Body" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplyEventUpdateResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Apply pending event updates to close-match event", "tags": [ "emails" ] } }, "/api/v1/emails/{email_id}/proposed/{entity_type}/{item_id}/approve": { "post": { "description": "Sets the item's approval_status to 'approved'. Related: TIDY-4367.", "operationId": "approveProposedItem", "parameters": [ { "description": "Entity type: task, event, contact, organization", "in": "path", "name": "entity_type", "required": true, "schema": { "description": "Entity type: task, event, contact, organization", "title": "Entity Type", "type": "string" } }, { "description": "Entity ID", "in": "path", "name": "item_id", "required": true, "schema": { "description": "Entity ID", "format": "uuid", "title": "Item Id", "type": "string" } }, { "description": "Typed ID with prefix 'E'", "in": "path", "name": "email_id", "required": true, "schema": { "description": "Typed ID with prefix 'E'", "title": "Email Id", "type": "string" } }, { "in": "header", "name": "X-Trace-Id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/ApproveProposedItemRequest" }, { "type": "null" } ], "title": "Payload" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Approveproposeditem", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Approve a proposed item", "tags": [ "emails" ] } }, "/api/v1/emails/{email_id}/proposed/{entity_type}/{item_id}/dismiss": { "post": { "description": "Sets the item's approval_status to 'rejected'. Related: TIDY-4367.", "operationId": "dismissProposedItem", "parameters": [ { "description": "Entity type: task, event, contact, organization", "in": "path", "name": "entity_type", "required": true, "schema": { "description": "Entity type: task, event, contact, organization", "title": "Entity Type", "type": "string" } }, { "description": "Entity ID", "in": "path", "name": "item_id", "required": true, "schema": { "description": "Entity ID", "format": "uuid", "title": "Item Id", "type": "string" } }, { "description": "Typed ID with prefix 'E'", "in": "path", "name": "email_id", "required": true, "schema": { "description": "Typed ID with prefix 'E'", "title": "Email Id", "type": "string" } }, { "in": "header", "name": "X-Trace-Id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/DismissProposedItemRequest" }, { "type": "null" } ], "title": "Payload" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Dismissproposeditem", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Dismiss a proposed item", "tags": [ "emails" ] } }, "/api/v1/emails/{email_id}/quarantine/delete": { "post": { "description": "Soft-deletes the email_canonical row (sets ``deleted_at``). Audit-logged via ``audit_log`` (operation='email.quarantine.delete'). Idempotent: a row already deleted returns ``changed=false``.", "operationId": "deleteQuarantinedEmail", "parameters": [ { "description": "Typed ID with prefix 'E'", "in": "path", "name": "email_id", "required": true, "schema": { "description": "Typed ID with prefix 'E'", "title": "Email Id", "type": "string" } }, { "in": "header", "name": "X-Trace-Id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailQuarantineActionResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Permanently delete a quarantined email", "tags": [ "emails" ] } }, "/api/v1/emails/{email_id}/quarantine/release": { "post": { "description": "Sets quarantine_status='released' so the row returns to the local inbox list query, and re-enqueues the email through the sync pipeline lane (quarantined emails never got triage/extraction; the orchestrator honors the released status and will not re-quarantine). Audit-logged via ``audit_log`` (operation='email.quarantine.release'). Idempotent: re-releasing an already-released row succeeds with ``changed=false`` and does not enqueue again.", "operationId": "releaseQuarantinedEmail", "parameters": [ { "description": "Typed ID with prefix 'E'", "in": "path", "name": "email_id", "required": true, "schema": { "description": "Typed ID with prefix 'E'", "title": "Email Id", "type": "string" } }, { "in": "header", "name": "X-Trace-Id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailQuarantineActionResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Release a quarantined email back to the inbox", "tags": [ "emails" ] } }, "/api/v1/emails/{email_id}/raw": { "get": { "description": "Streams the original RFC 5322 message as received (message/rfc822). Serves the byte-original from object storage; only pre-retention mail without stored raw bytes is reconstructed from canonical fields, with the filename marked '(reconstructed)'. Access is scoped to the calling member's mailbox.", "operationId": "downloadEmailRaw", "parameters": [ { "in": "path", "name": "email_id", "required": true, "schema": { "format": "uuid", "title": "Email Id", "type": "string" } } ], "responses": { "200": { "content": { "message/rfc822": {} }, "description": "Original .eml bytes" }, "404": { "description": "Email not found or not visible to the caller" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Download the original .eml for an email", "tags": [ "emails" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Binary .eml download; agents use email detail/reader endpoints." } }, "/api/v1/emails/{email_id}/read": { "post": { "description": "Mark an email as read.", "operationId": "markAsRead", "parameters": [ { "description": "Typed ID with prefix 'E'", "in": "path", "name": "email_id", "required": true, "schema": { "description": "Typed ID with prefix 'E'", "title": "Email Id", "type": "string" } }, { "in": "header", "name": "X-Trace-Id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailActionResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Mark As Read", "tags": [ "emails" ] } }, "/api/v1/emails/{email_id}/reader": { "get": { "description": "Assistant email reader: returns the email body as clean readable text (message_content -> body_markdown -> body_text -> html-to-text of body_html), never raw HTML, plus a compact attachment summary. Truncation is explicit. TIDY-13457.", "operationId": "getEmailReaderContent", "parameters": [ { "description": "Typed ID with prefix 'E'", "in": "path", "name": "email_id", "required": true, "schema": { "description": "Typed ID with prefix 'E'", "title": "Email Id", "type": "string" } }, { "in": "header", "name": "X-Trace-Id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailReaderContentResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Read an email as cleaned text with an attachment summary", "tags": [ "emails" ], "x-mcp-skip": true, "x-mcp-skip-reason": "Assistant-internal email reader surface; exposed to users via the tidy_email_read / tidy_email_attachment_text assistant tools, not standalone MCP tools." } }, "/api/v1/emails/{email_id}/reclassify": { "post": { "description": "Reclassify an email's triage category and optionally create a sender rule.", "operationId": "reclassifyEmail", "parameters": [ { "description": "Typed ID with prefix 'E'", "in": "path", "name": "email_id", "required": true, "schema": { "description": "Typed ID with prefix 'E'", "title": "Email Id", "type": "string" } }, { "in": "header", "name": "X-Trace-Id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReclassifyRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReclassifyResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Reclassify Email", "tags": [ "emails" ] } }, "/api/v1/emails/{email_id}/reference-extractions/{reference_id}": { "get": { "description": "Fetch full reference extraction payload for a single URL/document item.", "operationId": "getReferenceExtractionDetail", "parameters": [ { "in": "path", "name": "reference_id", "required": true, "schema": { "format": "uuid", "title": "Reference Id", "type": "string" } }, { "description": "Typed ID with prefix 'E'", "in": "path", "name": "email_id", "required": true, "schema": { "description": "Typed ID with prefix 'E'", "title": "Email Id", "type": "string" } }, { "in": "header", "name": "X-Trace-Id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReferenceExtractionDetailResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get full extracted URL/document detail for an email reference", "tags": [ "emails" ] } }, "/api/v1/emails/{email_id}/references/process": { "post": { "description": "Fetch and parse ONE reference (hyperlink or attachment) from an email and run it through the extraction pipeline. Results appear as pending-review items linked to this email. Returns 202 with a job id.", "operationId": "processEmailReference", "parameters": [ { "description": "Typed ID with prefix 'E'", "in": "path", "name": "email_id", "required": true, "schema": { "description": "Typed ID with prefix 'E'", "title": "Email Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProcessReferenceRequest" } } }, "required": true }, "responses": { "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProcessReferenceResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Process a link or attachment from an email", "tags": [ "emails" ], "x-mcp-skip": true, "x-mcp-skip-reason": "UI-triggered pipeline dispatch (right-click Process Link/Attachment). Not a data CRUD surface — results arrive local-first via linked references; agents extract from email bodies through the normal pipeline." } }, "/api/v1/emails/{email_id}/reharvest": { "post": { "description": "Re-queue one owner-scoped email through the real pipeline reprocess path.\n\n404 when the caller does not own the email. Idempotent on double-submit: an\nemail whose harvest is already pending is not re-queued — the existing job is\nreturned with ``queued=False``.", "operationId": "reharvestEmail", "parameters": [ { "description": "Typed ID with prefix 'E'", "in": "path", "name": "email_id", "required": true, "schema": { "description": "Typed ID with prefix 'E'", "title": "Email Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReharvestResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Force one email back through the extraction/harvest pipeline", "tags": [ "emails" ] } }, "/api/v1/emails/{email_id}/reply": { "post": { "description": "Create a draft that replies to a specific email.\n\n Modes:\n - reply: Reply to sender only\n - reply_all: Reply to sender and all recipients\n - reply_private: Reply to sender, but start a NEW thread (not in original thread)\n\n The draft is pre-populated with:\n - Recipients based on mode\n - Subject with \"Re:\" prefix\n - Quoted original content\n\n Related: KCC-3331 (F1.2, F1.3, F1.5)", "operationId": "createReply", "parameters": [ { "description": "Typed ID with prefix 'E'", "in": "path", "name": "email_id", "required": true, "schema": { "description": "Typed ID with prefix 'E'", "title": "Email Id", "type": "string" } }, { "in": "header", "name": "X-Trace-Id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReplyRequest", "default": { "body_html": "", "body_text": "", "mode": "reply" } } } } }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DraftResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Create a reply draft", "tags": [ "emails" ] } }, "/api/v1/emails/{email_id}/reply-context": { "get": { "description": "Fetch the context needed to compose a reply to an email, including\n quoted original body as HTML. Uses a raw-body-only fallback chain\n (body_html -> body_markdown -> body_text -> explicit placeholder)\n so the quoted content never uses cleaned display content.\n\n Optionally includes the full thread chain when include_thread=true.\n\n TIDY-4196: Fix reply not consistently including original email body.", "operationId": "getReplyContext", "parameters": [ { "description": "Typed ID with prefix 'E'", "in": "path", "name": "email_id", "required": true, "schema": { "description": "Typed ID with prefix 'E'", "title": "Email Id", "type": "string" } }, { "description": "Include full thread chain in quoted content", "in": "query", "name": "include_thread", "required": false, "schema": { "default": false, "description": "Include full thread chain in quoted content", "title": "Include Thread", "type": "boolean" } }, { "in": "header", "name": "X-Trace-Id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReplyContextResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get reply context with quoted content", "tags": [ "emails" ] } }, "/api/v1/emails/{email_id}/report-spam": { "post": { "description": "Report an email as spam: reclassify + block sender + delayed writeback + unsubscribe.", "operationId": "reportSpam", "parameters": [ { "description": "Typed ID with prefix 'E'", "in": "path", "name": "email_id", "required": true, "schema": { "description": "Typed ID with prefix 'E'", "title": "Email Id", "type": "string" } }, { "in": "header", "name": "X-Trace-Id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportSpamRequest", "default": { "attempt_unsubscribe": true, "block_sender": true } } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportSpamResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Report Spam", "tags": [ "emails" ] } }, "/api/v1/emails/{email_id}/screening-explain": { "get": { "description": "Read-only diagnosis for a just-approved sender missing from Important.", "operationId": "explainEmailScreening", "parameters": [ { "in": "path", "name": "email_id", "required": true, "schema": { "format": "uuid", "title": "Email Id", "type": "string" } }, { "in": "header", "name": "X-Trace-Id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailScreeningExplainResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Explain why an email is or isn't visible in inbox splits", "tags": [ "emails" ], "x-local-capability": "local" } }, "/api/v1/emails/{email_id}/sender/vip": { "post": { "description": "Promote (or demote) the email's sender as VIP.\n\nVIP = ``contacts.is_starred = TRUE``. The RPC handles the contact\nlookup (and minimal creation when promoting an unknown sender);\nthis endpoint adds the audit row + VIP cache rebuild.\n\nReturns 404 only when the email_id doesn't exist in this tenant.\nIdempotent: calling twice with the same ``is_vip`` value succeeds\nand returns the same contact_id without bumping ``updated_at`` a\nsecond time (RPC uses ``IS DISTINCT FROM`` guard).", "operationId": "setEmailSenderVip", "parameters": [ { "description": "Typed ID with prefix 'E'", "in": "path", "name": "email_id", "required": true, "schema": { "description": "Typed ID with prefix 'E'", "title": "Email Id", "type": "string" } }, { "in": "header", "name": "X-Trace-Id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SenderVipRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SenderVipResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Mark or unmark the email's sender as VIP", "tags": [ "emails", "Emails" ] } }, "/api/v1/emails/{email_id}/snooze": { "post": { "description": "Snooze an email until a specified time.", "operationId": "snoozeEmail", "parameters": [ { "description": "Typed ID with prefix 'E'", "in": "path", "name": "email_id", "required": true, "schema": { "description": "Typed ID with prefix 'E'", "title": "Email Id", "type": "string" } }, { "in": "header", "name": "X-Trace-Id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_service__models__email_requests__SnoozeRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SnoozeResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Snooze Email", "tags": [ "emails" ] } }, "/api/v1/emails/{email_id}/star": { "post": { "description": "Star an email. Also cancels any pending auto-expiry (TIDY-4353).", "operationId": "starEmail", "parameters": [ { "description": "Typed ID with prefix 'E'", "in": "path", "name": "email_id", "required": true, "schema": { "description": "Typed ID with prefix 'E'", "title": "Email Id", "type": "string" } }, { "in": "header", "name": "X-Trace-Id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailActionResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Star Email", "tags": [ "emails" ] } }, "/api/v1/emails/{email_id}/suggest-subject": { "post": { "description": "Generates a better subject line from email body using LLM. Related: TIDY-4100.", "operationId": "suggestSubject", "parameters": [ { "description": "Typed ID with prefix 'E'", "in": "path", "name": "email_id", "required": true, "schema": { "description": "Typed ID with prefix 'E'", "title": "Email Id", "type": "string" } }, { "in": "header", "name": "X-Trace-Id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuggestSubjectResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Generate AI subject suggestion", "tags": [ "emails" ] } }, "/api/v1/emails/{email_id}/teach-importance": { "post": { "description": "Synthesize a correction rule, flip the email now, emit + count the teach.", "operationId": "teachEmailImportance", "parameters": [ { "description": "Typed ID with prefix 'E'", "in": "path", "name": "email_id", "required": true, "schema": { "description": "Typed ID with prefix 'E'", "title": "Email Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TeachImportanceRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TeachImportanceResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Teach Tidy that an email is (or isn't) Important", "tags": [ "emails" ], "x-mcp-skip": true } }, "/api/v1/emails/{email_id}/teach-importance/undo": { "post": { "description": "Reverse the last teach: soft-delete its rule, restore any rules it removed,\nrevert the reclassify, and reopen a resolved suggestion.", "operationId": "undoTeachEmailImportance", "parameters": [ { "description": "Typed ID with prefix 'E'", "in": "path", "name": "email_id", "required": true, "schema": { "description": "Typed ID with prefix 'E'", "title": "Email Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TeachImportanceUndoResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Undo the most recent importance teach for an email", "tags": [ "emails" ], "x-mcp-skip": true } }, "/api/v1/emails/{email_id}/teach-mute": { "post": { "description": "Create the D4 mute rule, send the email to Done now, optionally retro-apply,\nresolve a matching open suggestion, and emit the replayable teach event.", "operationId": "teachEmailMute", "parameters": [ { "description": "Typed ID with prefix 'E'", "in": "path", "name": "email_id", "required": true, "schema": { "description": "Typed ID with prefix 'E'", "title": "Email Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TeachMuteRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TeachMuteResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Create a durable mute rule from confirmed conditions", "tags": [ "emails" ], "x-mcp-skip": true } }, "/api/v1/emails/{email_id}/teach-mute/undo": { "post": { "description": "Reverse the last mute: soft-delete the rule, restore the taught email's prior\nstate, un-archive retro'd emails (≤ cap), reopen a resolved suggestion.", "operationId": "undoTeachEmailMute", "parameters": [ { "description": "Typed ID with prefix 'E'", "in": "path", "name": "email_id", "required": true, "schema": { "description": "Typed ID with prefix 'E'", "title": "Email Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TeachMuteUndoResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Undo the most recent teach-mute for an email", "tags": [ "emails" ], "x-mcp-skip": true } }, "/api/v1/emails/{email_id}/unarchive": { "post": { "description": "Unarchive an email.", "operationId": "unarchiveEmail", "parameters": [ { "description": "Typed ID with prefix 'E'", "in": "path", "name": "email_id", "required": true, "schema": { "description": "Typed ID with prefix 'E'", "title": "Email Id", "type": "string" } }, { "in": "header", "name": "X-Trace-Id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailActionResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Unarchive Email", "tags": [ "emails" ] } }, "/api/v1/emails/{email_id}/unblock-sender": { "post": { "description": "Unblock a sender from the email detail context — the exact inverse of\nblockSenderFromEmail (TIDY-13253).\n\nBlock had no undo: approveSender only restored screening_status='pending'\nrows, so emails swept to 'blocked' by the block sweep stayed blocked. This\nreverses all three effects of the block in one transaction:\n1. sender_screening → 'approved' (same conflict key the block upserts on)\n2. the standing Gatekeeper disposition rule → route/approved, via the SAME\n write_disposition_rule writer the block uses (it flips the rule in place)\n3. email_canonical rows the block swept to 'blocked' for this sender →\n 'approved' AND re-enqueued for processing (TIDY-13694), using the block\n sweep's exact address/domain predicate so ONLY this sender's blocked rows\n are restored (rows blocked by other senders/rules are untouched). Blocked\n emails were turned away BEFORE the pipeline, so restoring the status alone\n leaves them permanently unharvested — each restored email that never\n completed a pipeline run is enqueued via the shared resume writer.", "operationId": "unblockSenderFromEmail", "parameters": [ { "description": "Typed ID with prefix 'E'", "in": "path", "name": "email_id", "required": true, "schema": { "description": "Typed ID with prefix 'E'", "title": "Email Id", "type": "string" } }, { "in": "header", "name": "X-Trace-Id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnblockSenderRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnblockSenderResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Unblock Sender From Email", "tags": [ "emails" ] } }, "/api/v1/emails/{email_id}/undo-spam": { "post": { "description": "Cancel a pending spam report within the undo window and revert local state.", "operationId": "undoSpam", "parameters": [ { "description": "Typed ID with prefix 'E'", "in": "path", "name": "email_id", "required": true, "schema": { "description": "Typed ID with prefix 'E'", "title": "Email Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UndoSpamResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Undo Spam", "tags": [ "emails" ] } }, "/api/v1/emails/{email_id}/undone": { "post": { "description": "Mark an email as not done.", "operationId": "markAsUndone", "parameters": [ { "description": "Typed ID with prefix 'E'", "in": "path", "name": "email_id", "required": true, "schema": { "description": "Typed ID with prefix 'E'", "title": "Email Id", "type": "string" } }, { "in": "header", "name": "X-Trace-Id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailActionResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Mark As Undone", "tags": [ "emails" ] } }, "/api/v1/emails/{email_id}/unmute": { "post": { "description": "Unmute an email conversation.", "operationId": "unmuteEmail", "parameters": [ { "description": "Typed ID with prefix 'E'", "in": "path", "name": "email_id", "required": true, "schema": { "description": "Typed ID with prefix 'E'", "title": "Email Id", "type": "string" } }, { "in": "header", "name": "X-Trace-Id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailActionResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Unmute Email", "tags": [ "emails" ] } }, "/api/v1/emails/{email_id}/unread": { "post": { "description": "Mark an email as unread.", "operationId": "markAsUnread", "parameters": [ { "description": "Typed ID with prefix 'E'", "in": "path", "name": "email_id", "required": true, "schema": { "description": "Typed ID with prefix 'E'", "title": "Email Id", "type": "string" } }, { "in": "header", "name": "X-Trace-Id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailActionResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Mark As Unread", "tags": [ "emails" ] } }, "/api/v1/emails/{email_id}/unsnooze": { "post": { "description": "Cancel snooze on an email.", "operationId": "unsnoozeEmail", "parameters": [ { "description": "Typed ID with prefix 'E'", "in": "path", "name": "email_id", "required": true, "schema": { "description": "Typed ID with prefix 'E'", "title": "Email Id", "type": "string" } }, { "in": "header", "name": "X-Trace-Id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailActionResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Unsnooze Email", "tags": [ "emails" ] } }, "/api/v1/emails/{email_id}/unstar": { "post": { "description": "Unstar an email.", "operationId": "unstarEmail", "parameters": [ { "description": "Typed ID with prefix 'E'", "in": "path", "name": "email_id", "required": true, "schema": { "description": "Typed ID with prefix 'E'", "title": "Email Id", "type": "string" } }, { "in": "header", "name": "X-Trace-Id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailActionResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Unstar Email", "tags": [ "emails" ] } }, "/api/v1/embeds/{embed_event_id}/expand": { "post": { "operationId": "trackEmbedExpand", "parameters": [ { "in": "path", "name": "embed_event_id", "required": true, "schema": { "title": "Embed Event Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmbedExpandRequest" } } }, "required": true }, "responses": { "204": { "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Track guest expansion of an embedded facet", "tags": [ "guest-audit" ], "x-mcp-skip": true } }, "/api/v1/employee-approvals/team": { "get": { "description": "The open approval requests on the calling employee's team.", "operationId": "listTeamApprovals", "parameters": [ { "in": "header", "name": "X-Tidy-Acting-Principal", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tidy-Acting-Principal" } }, { "in": "header", "name": "X-Internal-Service", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service" } }, { "in": "header", "name": "X-Internal-Service-Key", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service-Key" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TeamApprovalListResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List Team Approvals", "tags": [ "agents" ], "x-local-capability": "cloud" } }, "/api/v1/employee-approvals/team/{request_id}/resolve": { "post": { "description": "Answer one of your team's requests, once, as its team lead.", "operationId": "resolveTeamApproval", "parameters": [ { "description": "The request's id from the team list.", "in": "path", "name": "request_id", "required": true, "schema": { "description": "The request's id from the team list.", "title": "Request Id", "type": "string" } }, { "in": "header", "name": "X-Tidy-Acting-Principal", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tidy-Acting-Principal" } }, { "in": "header", "name": "X-Internal-Service", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service" } }, { "in": "header", "name": "X-Internal-Service-Key", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service-Key" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TeamApprovalResolveBody" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TeamApprovalResolveResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Resolve Team Approval", "tags": [ "agents" ], "x-local-capability": "cloud" } }, "/api/v1/employee-dm/inbox": { "get": { "description": "The calling employee's own unread colleague DMs and open mentions.\n\nReading never consumes: a DM stays until a wake hands it over or it is\nmarked read, a mention until it is answered or acked.", "operationId": "listEmployeeInbox", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmployeeInboxResponse" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List Inbox", "tags": [ "agents" ], "x-local-capability": "cloud" } }, "/api/v1/employee-dm/inbox/read": { "post": { "description": "Mark colleague DMs in the caller's own inbox read.", "operationId": "markEmployeeInboxRead", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmployeeInboxReadRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmployeeInboxReadResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Mark Inbox Read", "tags": [ "agents" ], "x-local-capability": "cloud" } }, "/api/v1/employee-dm/messages": { "post": { "description": "Message an employee — as a person asking it something, or an employee\nsteering a colleague about named work — and let the platform route it.", "operationId": "sendEmployeeDm", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmployeeDmRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmployeeDmResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Send Employee Dm", "tags": [ "agents" ], "x-local-capability": "cloud" } }, "/api/v1/employee-dm/team-conversations": { "get": { "description": "The conversations going for your own other instances, your manager, direct\nreports and peers — for a person, the employees they own — that the person you\nwork for may read. Metadata only; what was said stays behind the transcript's\nown read rules.", "operationId": "listTeamConversations", "parameters": [ { "description": "Only this employee's (name, slug, @handle or account id). It must be you, your manager, a direct report, a peer under your manager or one you own: anyone else is 403 `not_in_direct_line`.", "in": "query", "name": "employee", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Only this employee's (name, slug, @handle or account id). It must be you, your manager, a direct report, a peer under your manager or one you own: anyone else is 403 `not_in_direct_line`.", "title": "Employee" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "maximum": 50, "minimum": 1, "title": "Limit", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TeamConversationsResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List Team Conversations", "tags": [ "agents" ], "x-local-capability": "cloud" } }, "/api/v1/employee-dm/threads": { "get": { "description": "The employee↔employee threads on a profile, or the ones about an item.", "operationId": "listEmployeeDmThreads", "parameters": [ { "description": "Employee slug / handle / account id whose threads to list.", "in": "query", "name": "employee", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Employee slug / handle / account id whose threads to list.", "title": "Employee" } }, { "description": "Typed item id whose DM threads to list.", "in": "query", "name": "item_ref", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Typed item id whose DM threads to list.", "title": "Item Ref" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "maximum": 200, "minimum": 1, "title": "Limit", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmployeeDmThreadsResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List Threads", "tags": [ "agents" ], "x-local-capability": "cloud" } }, "/api/v1/employee-dm/work-graph": { "get": { "description": "Who is affected, from the work graph — never from session archaeology.", "operationId": "getEmployeeWorkGraph", "parameters": [ { "description": "Anchor task (`A-<uuid>`). Returns the items linked to it with their state, assignee and live conversation. Omit for the workspace's in-flight assigned work.", "in": "query", "name": "item_ref", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Anchor task (`A-<uuid>`). Returns the items linked to it with their state, assignee and live conversation. Omit for the workspace's in-flight assigned work.", "title": "Item Ref" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 25, "maximum": 100, "minimum": 1, "title": "Limit", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkGraphResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Work Graph", "tags": [ "agents" ], "x-local-capability": "cloud" } }, "/api/v1/employee-templates/from-employee": { "post": { "description": "Save a customized employee as a tenant-private template.\n\nConfiguration only — persona, skills, harness, providers. Memory,\nconversations and backlog stay with the person they belong to (D22).", "operationId": "saveEmployeeAsTemplate", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SaveAsTemplateRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SaveAsTemplateResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Save As Template", "tags": [ "employee-templates", "employee-templates" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/employee-templates/hire-funnel": { "get": { "description": "Where hiring from the bench stops — attempts, per-step reach, completion.", "operationId": "getEmployeeHireFunnel", "parameters": [ { "in": "query", "name": "days", "required": false, "schema": { "default": 30, "maximum": 365, "minimum": 1, "title": "Days", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FunnelSummaryResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Hire Funnel", "tags": [ "employee-templates", "employee-templates" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/employee-templates/hire-progress": { "post": { "description": "One step of one hire attempt reached — the stall detector's raw material.", "operationId": "recordEmployeeHireStep", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FunnelStepRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FunnelStepResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Record Hire Step", "tags": [ "employee-templates", "employee-templates" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/employee-templates/{template_id}/prefill": { "get": { "description": "Open a hire: the pre-filled journey plus the workspace's outstanding setup.", "operationId": "getEmployeeTemplatePrefill", "parameters": [ { "in": "path", "name": "template_id", "required": true, "schema": { "title": "Template Id", "type": "string" } }, { "description": "Judge the workshop requirements against this machine.", "in": "query", "name": "workshop_id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Judge the workshop requirements against this machine.", "title": "Workshop Id" } }, { "description": "Where this hire will run — a workshop machine, or Tidy compute.", "in": "query", "name": "execution_location", "required": false, "schema": { "default": "workshop", "description": "Where this hire will run — a workshop machine, or Tidy compute.", "pattern": "^(workshop|hosted)$", "title": "Execution Location", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HirePrefillResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Prefill", "tags": [ "employee-templates", "employee-templates" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/employee-templates/{template_id}/setup-check": { "get": { "description": "Re-check the checklist — after connecting a provider, before assigning.\n\n``ready`` is true only when NOTHING is outstanding, including requirements\nthat could not be judged: unresolved is not satisfied.", "operationId": "checkEmployeeTemplateSetup", "parameters": [ { "in": "path", "name": "template_id", "required": true, "schema": { "title": "Template Id", "type": "string" } }, { "in": "query", "name": "workshop_id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Workshop Id" } }, { "description": "Where this hire will run — a workshop machine, or Tidy compute.", "in": "query", "name": "execution_location", "required": false, "schema": { "default": "workshop", "description": "Where this hire will run — a workshop machine, or Tidy compute.", "pattern": "^(workshop|hosted)$", "title": "Execution Location", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetupCheckResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Check Setup", "tags": [ "employee-templates", "employee-templates" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/employee-templates/{template_id}/starter-content": { "post": { "description": "Plant the template's starter objectives and standing instructions.", "operationId": "plantEmployeeTemplateStarterContent", "parameters": [ { "in": "path", "name": "template_id", "required": true, "schema": { "title": "Template Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlantStarterRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlantStarterResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Plant Starter Content", "tags": [ "employee-templates", "employee-templates" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/employees/entitlement-state": { "get": { "description": "The banner's own source. PD4's promise is that a plan-paused employee\nSAYS so; the words come from here so the composer, the card and Android\ncannot each invent their own version of the upgrade path.", "operationId": "getEmployeeEntitlementState", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmployeeEntitlementStateResponse" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Whether this workspace's plan still includes employees", "tags": [ "agents", "Agents" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/entities": { "get": { "operationId": "listEntities", "parameters": [ { "in": "query", "name": "entity_type", "required": false, "schema": { "anyOf": [ { "maxLength": 120, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Entity Type" } }, { "in": "query", "name": "facet", "required": false, "schema": { "anyOf": [ { "maxLength": 120, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Facet" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "maximum": 200, "minimum": 1, "title": "Limit", "type": "integer" } }, { "in": "query", "name": "offset", "required": false, "schema": { "default": 0, "minimum": 0, "title": "Offset", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityListResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List generic entities", "tags": [ "entities", "entities" ], "x-mcp-skip": true, "x-mcp-skip-reason": "TIDY-8939 owns MCP tidy_create(kind='entity') tooling" }, "post": { "operationId": "createEntity", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityCreateRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Create a generic entity", "tags": [ "entities", "entities" ], "x-mcp-skip": true, "x-mcp-skip-reason": "TIDY-8939 owns MCP tidy_create(kind='entity') tooling" } }, "/api/v1/entities/{entity_id}": { "delete": { "operationId": "deleteEntity", "parameters": [ { "description": "Typed ID with prefix 'T'", "in": "path", "name": "entity_id", "required": true, "schema": { "description": "Typed ID with prefix 'T'", "title": "Entity Id", "type": "string" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Soft delete a generic entity", "tags": [ "entities", "entities" ], "x-mcp-skip": true, "x-mcp-skip-reason": "TIDY-8939 owns MCP tidy_create(kind='entity') tooling" }, "get": { "operationId": "getEntity", "parameters": [ { "description": "Typed ID with prefix 'T'", "in": "path", "name": "entity_id", "required": true, "schema": { "description": "Typed ID with prefix 'T'", "title": "Entity Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get a generic entity", "tags": [ "entities", "entities" ], "x-mcp-skip": true, "x-mcp-skip-reason": "TIDY-8939 owns MCP tidy_create(kind='entity') tooling" }, "patch": { "operationId": "patchEntity", "parameters": [ { "description": "Typed ID with prefix 'T'", "in": "path", "name": "entity_id", "required": true, "schema": { "description": "Typed ID with prefix 'T'", "title": "Entity Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityUpdateRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Update a generic entity", "tags": [ "entities", "entities" ], "x-mcp-skip": true, "x-mcp-skip-reason": "TIDY-8939 owns MCP tidy_create(kind='entity') tooling" } }, "/api/v1/entitlements": { "get": { "description": "Effective entitlements and inbox usage for the caller's tenant.", "operationId": "getMyEntitlements", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MyEntitlementsResponse" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get My Entitlements", "tags": [ "entitlements", "entitlements" ], "x-mcp-skip": true } }, "/api/v1/entity-match-suggestions": { "get": { "description": "List pending contact-to-project association suggestions for the authenticated user.", "operationId": "listSuggestions", "parameters": [ { "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "maximum": 200, "minimum": 1, "title": "Limit", "type": "integer" } }, { "in": "query", "name": "offset", "required": false, "schema": { "default": 0, "minimum": 0, "title": "Offset", "type": "integer" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityMatchSuggestionsResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List pending entity match suggestions", "tags": [ "entity-matching" ] } }, "/api/v1/entity-match-suggestions/{suggestion_id}/accept": { "post": { "description": "Accept a suggestion — creates a linked_references row linking email to project.", "operationId": "acceptSuggestion2", "parameters": [ { "in": "path", "name": "suggestion_id", "required": true, "schema": { "title": "Suggestion Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Acceptsuggestion2", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Accept a suggestion (link email to project)", "tags": [ "entity-matching" ] } }, "/api/v1/entity-match-suggestions/{suggestion_id}/dismiss": { "post": { "description": "Dismiss a suggestion without creating any link.", "operationId": "dismissSuggestion2", "parameters": [ { "in": "path", "name": "suggestion_id", "required": true, "schema": { "title": "Suggestion Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Dismisssuggestion2", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Dismiss a suggestion (no link created)", "tags": [ "entity-matching" ] } }, "/api/v1/errors": { "get": { "description": "Returns every ErrorCode Tidy can emit with its HTTP status, retry semantics, and canonical docs URL. Agents and SDK generators use this to build typed error classes.", "operationId": "getErrorCatalog", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorCatalog" } } }, "description": "Successful Response" } }, "summary": "Canonical catalog of Tidy error codes", "tags": [ "meta", "meta" ] } }, "/api/v1/escalations/funnel": { "get": { "description": "Sent -> seen -> acted per tier and channel, for the caller's tenant.", "operationId": "getEscalationFunnel", "parameters": [ { "in": "query", "name": "window_days", "required": false, "schema": { "default": 30, "maximum": 365, "minimum": 1, "title": "Window Days", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EscalationFunnelResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Escalation funnel and time-to-approval by channel", "tags": [ "escalations" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/escalations/{escalation_id}/resolve": { "get": { "description": "Resolve the opaque context id a notification carried.\n\nThe id in the link authorizes nothing. This handler is the authorization:\nthe row is read scoped to the CALLER's tenant, and a row belonging to\nsomeone else is reported as absent.", "operationId": "resolveEscalation", "parameters": [ { "in": "path", "name": "escalation_id", "required": true, "schema": { "title": "Escalation Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EscalationResolveResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Resolve an escalation deep link to its living context", "tags": [ "escalations" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/esp-connections": { "get": { "operationId": "listEspConnections", "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/EspConnectionResponse" }, "title": "Response Listespconnections", "type": "array" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List Connections", "tags": [ "esp-connections" ], "x-local-capability": "cloud", "x-mcp-skip": true }, "post": { "operationId": "createEspConnection", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EspConnectionCreate" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EspConnectionResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Create Connection", "tags": [ "esp-connections" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/esp-connections/{connection_id}": { "delete": { "operationId": "deleteEspConnection", "parameters": [ { "in": "path", "name": "connection_id", "required": true, "schema": { "title": "Connection Id", "type": "string" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Delete Connection", "tags": [ "esp-connections" ], "x-local-capability": "cloud", "x-mcp-skip": true }, "get": { "operationId": "getEspConnection", "parameters": [ { "in": "path", "name": "connection_id", "required": true, "schema": { "title": "Connection Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EspConnectionResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Connection", "tags": [ "esp-connections" ], "x-local-capability": "cloud", "x-mcp-skip": true }, "patch": { "operationId": "updateEspConnection", "parameters": [ { "in": "path", "name": "connection_id", "required": true, "schema": { "title": "Connection Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EspConnectionUpdate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EspConnectionResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Update Connection", "tags": [ "esp-connections" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/esp-connections/{connection_id}/verify": { "post": { "description": "Prove the stored credential against the provider (R24).\n\nnotification-service runs the adapter capability check (SES GetAccount +\nidentity listing), persists connected|broken, and returns quota + health.", "operationId": "verifyEspConnection", "parameters": [ { "in": "path", "name": "connection_id", "required": true, "schema": { "title": "Connection Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EspConnectionVerifyResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Verify Connection", "tags": [ "esp-connections" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/events/catalog": { "get": { "description": "Returns every event type Tidy emits with its version, description, and a schema_ref pointing into /api/v1/asyncapi.json. Subscribers use this to discover available event types before registering a webhook.", "operationId": "getEventCatalog", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventCatalog" } } }, "description": "Successful Response" } }, "summary": "Canonical catalog of Tidy event types", "tags": [ "meta", "meta", "events" ] } }, "/api/v1/events/stream": { "get": { "description": "Open an SSE stream of notification bump events scoped to the caller.\n\nTIDY-17775: Operators (typ=admin, no tenant) receive admin_notification\nevents only; user_notification events are tenant-scoped and never match.", "operationId": "eventsStream", "responses": { "200": { "content": { "text/event-stream": {} }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Live notification event stream (SSE)", "tags": [ "events", "events" ], "x-mcp-skip": true, "x-mcp-skip-reason": "Server-Sent Events push channel for the web notification bells; consumed by the browser event-stream client, not an agent tool." } }, "/api/v1/evidence/anchor-resolve": { "get": { "description": "R19: file_versions snapshot first (native-facet projects resolve here\nwith no git anywhere), then the provider adapter's blob read at `ref`.\nContent drift returns a then-vs-now offer. The API host never runs git.", "operationId": "resolveContentAnchor", "parameters": [ { "in": "query", "name": "path", "required": true, "schema": { "maxLength": 1024, "minLength": 1, "title": "Path", "type": "string" } }, { "in": "query", "name": "content_hash", "required": false, "schema": { "anyOf": [ { "maxLength": 128, "type": "string" }, { "type": "null" } ], "title": "Content Hash" } }, { "in": "query", "name": "repository", "required": false, "schema": { "anyOf": [ { "maxLength": 300, "type": "string" }, { "type": "null" } ], "title": "Repository" } }, { "in": "query", "name": "provider", "required": false, "schema": { "anyOf": [ { "maxLength": 40, "type": "string" }, { "type": "null" } ], "title": "Provider" } }, { "in": "query", "name": "ref", "required": false, "schema": { "anyOf": [ { "maxLength": 64, "type": "string" }, { "type": "null" } ], "title": "Ref" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnchorResolveResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Resolve a code anchor to file content (file_versions or provider blob)", "tags": [ "links" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/evidence/batch": { "post": { "description": "Batch upsert — the `tidy evidence ingest` transport. Duplicate harness\nevents collapse onto the natural keys; re-running is a no-op.", "operationId": "ingestEvidenceBatch", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EvidenceBatchIngest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EvidenceBatchResult" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Idempotently ingest a batch of evidence records", "tags": [ "links" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/evidence/commits": { "post": { "description": "201 on first ingest; 200 with the same id on a duplicate (natural key).", "operationId": "ingestEvidenceCommit", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommitIngest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EvidenceIngestResult" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Idempotently ingest one commit evidence record", "tags": [ "links" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/evidence/commits/{sha}/provenance": { "get": { "description": "Authored-ref links only (D8): a commit with no `commit_created` event\nreturns empty `links` — the honest \"unlinked\", never a heuristic guess.", "operationId": "getCommitProvenance", "parameters": [ { "in": "path", "name": "sha", "required": true, "schema": { "title": "Sha", "type": "string" } }, { "description": "Disambiguate multi-repo SHAs", "in": "query", "name": "repository", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Disambiguate multi-repo SHAs", "title": "Repository" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommitProvenanceResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Exact session/turn provenance for one commit SHA", "tags": [ "links" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/evidence/correlation-coverage": { "get": { "description": "The R17/R19 observability read for oversight — computed from recorded\nevidence only (authored-ref links + ledger edit operations).", "operationId": "getCorrelationCoverage", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CorrelationCoverageResponse" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Correlation coverage metrics (commits linked, anchors resolvable)", "tags": [ "links" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/evidence/for-target/{activity_id}": { "get": { "description": "Story → evidence traversal. The target activity is resolved through the\ncaller's member-visible predicate; evidence rows themselves are\ntenant-scoped operational data (no owner split — S16 design).", "operationId": "listEvidenceForTarget", "parameters": [ { "description": "Typed ID with prefix 'A'", "in": "path", "name": "activity_id", "required": true, "schema": { "description": "Typed ID with prefix 'A'", "title": "Activity Id", "type": "string" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 100, "maximum": 500, "minimum": 1, "title": "Limit", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EvidenceForTargetResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Evidence records linked to one work/requirement activity", "tags": [ "links" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/evidence/from-url": { "post": { "description": "Paste-to-attach transport (TIDY-15590): a GitHub commit / PR URL becomes\nthe matching evidence record, linked to the given targets. Same natural-key\nidempotency as the direct routes; 422 when the URL is not one Tidy records.", "operationId": "ingestEvidenceFromUrl", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SourceUrlIngest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EvidenceIngestResult" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Ingest a commit or pull request named by its web URL", "tags": [ "links" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/evidence/pull-requests": { "post": { "description": "Force-updated PRs mutate state/head_sha in place on the same row.", "operationId": "ingestEvidencePullRequest", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PullRequestIngest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EvidenceIngestResult" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Idempotently ingest one pull-request evidence record", "tags": [ "links" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/evidence/running-work": { "post": { "description": "TIDY-17350 (F10 / D13): the employee tells Tidy where the thing it is\nrunning can be LOOKED at, and what it saw when it last checked. The same\n(workshop, url) is the same object, so a later health report updates it in\nplace — which is how \"up\" becomes \"unreachable\" on the item without the\nowner losing the link or the link's history.", "operationId": "ingestEvidenceRunningWork", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunningWorkIngest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EvidenceIngestResult" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Register or refresh the live URL of work an employee is running", "tags": [ "links" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/evidence/sessions/{session_id}/commits": { "get": { "description": "The conversation view's commit list (R17's reverse direction). Tombstoned\nrewrites are included with their removal facts.", "operationId": "listSessionCommits", "parameters": [ { "in": "path", "name": "session_id", "required": true, "schema": { "format": "uuid", "title": "Session Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionCommitsResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Commits a conversation authored (turn-ordered, with file versions)", "tags": [ "links" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/evidence/validation-runs": { "post": { "description": "A rerun with the same run_identifier updates result/summary in place;\na different identifier creates a new row.", "operationId": "ingestEvidenceValidationRun", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationRunIngest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EvidenceIngestResult" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Idempotently ingest one validation-run evidence record", "tags": [ "links" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/evidence/{evidence_path_kind}/{evidence_id}": { "get": { "description": "Evidence → story traversal rides the `links` field. A deleted upstream\nrepository leaves the record intact — clients render the stored\nidentifiers with a dead source_url (R24 edge case).", "operationId": "getEvidenceRecord", "parameters": [ { "in": "path", "name": "evidence_path_kind", "required": true, "schema": { "enum": [ "commits", "pull-requests", "validation-runs", "running-work" ], "title": "Evidence Path Kind", "type": "string" } }, { "in": "path", "name": "evidence_id", "required": true, "schema": { "format": "uuid", "title": "Evidence Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EvidenceRecord" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "One evidence record by id (embed rendering)", "tags": [ "links" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/excalidraw/library": { "get": { "operationId": "getExcalidrawLibrary", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LibraryResponse" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get the current user's Excalidraw library", "tags": [ "excalidraw" ] }, "put": { "operationId": "saveExcalidrawLibrary", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SaveLibraryRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SaveLibraryResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Save the current user's Excalidraw library", "tags": [ "excalidraw" ] } }, "/api/v1/export": { "get": { "operationId": "listDataExportJobs", "parameters": [ { "in": "query", "name": "limit", "required": false, "schema": { "default": 20, "title": "Limit", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/DataExportJob" }, "title": "Response Listdataexportjobs", "type": "array" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "List Export Jobs", "tags": [ "export", "export" ] }, "post": { "description": "Queue a new export job and spawn the background worker.\n\nReturns 202 immediately. Poll GET /api/v1/export/{job_id} for status.", "operationId": "startDataExport", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExportCreateRequest" } } }, "required": true }, "responses": { "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExportCreateResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Start Export", "tags": [ "export", "export" ] } }, "/api/v1/export/docx": { "post": { "operationId": "exportDocx", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExportDocxRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/vnd.openxmlformats-officedocument.wordprocessingml.document": {} }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Export a Tidy note as a .docx file", "tags": [ "export-docs", "export-docs" ] } }, "/api/v1/export/facet-pdf": { "post": { "description": "Render a facet instance's host note as a report PDF (TIDY-14037 / S4).\n\nResolves the instance's host note under the caller's visibility, assembles\nthe report profile from the facet definition's ``rendering.report`` settings\n(cover, logo, brand color, section order) with the request cover as an\noverride, and streams the report PDF from doc-service.", "operationId": "exportFacetPdf", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExportFacetPdfRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/pdf": {} }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Export a templated facet instance as a report PDF", "tags": [ "export-docs", "export-docs" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Report export is an agent-facing facet ACTION (builtin:export_pdf / export_email via /facet-actions/invoke); MCP uses that, not this UI/workflow HTTP entry." } }, "/api/v1/export/images/resolve": { "get": { "operationId": "getExportImage", "parameters": [ { "in": "query", "name": "src", "required": true, "schema": { "maxLength": 4096, "minLength": 1, "title": "Src", "type": "string" } } ], "responses": { "200": { "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Export Image", "tags": [ "export-docs", "export-docs" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Image byte transport used by document export, not an agent workflow." } }, "/api/v1/export/pdf": { "post": { "operationId": "exportPdf", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExportPdfRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/pdf": {} }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Export a Tidy note as a PDF", "tags": [ "export-docs", "export-docs" ] } }, "/api/v1/export/pptx": { "post": { "description": "Flatten a deck to PowerPoint (S9 / TIDY-13673, D12).\n\nThe public contract is unchanged (`{noteId}`); this handler enriches the\ninternal doc-service call with the member render-session token, the deck\nhash, and the active design so rich embeds flatten to their rendered pixels\n(D6 — the render runs under the requesting member's own visibility).", "operationId": "exportPptx", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExportPptxRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/vnd.openxmlformats-officedocument.presentationml.presentation": {} }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Export a Tidy note as a .pptx presentation", "tags": [ "export-docs", "export-docs" ] } }, "/api/v1/export/xlsx": { "post": { "operationId": "exportXlsx", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExportXlsxRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": {} }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Export a Tidy spreadsheet note as .xlsx", "tags": [ "export-docs", "export-docs" ] } }, "/api/v1/export/{job_id}": { "get": { "operationId": "getDataExportStatus", "parameters": [ { "in": "path", "name": "job_id", "required": true, "schema": { "title": "Job Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataExportJob" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Get Export Status", "tags": [ "export", "export" ] } }, "/api/v1/extension/assistant/conversations": { "get": { "operationId": "listExtensionAssistantConversations", "parameters": [ { "in": "query", "name": "limit", "required": false, "schema": { "default": 30, "maximum": 100, "minimum": 1, "title": "Limit", "type": "integer" } }, { "in": "query", "name": "offset", "required": false, "schema": { "default": 0, "minimum": 0, "title": "Offset", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "title": "Response Listextensionassistantconversations" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List assistant conversations for the extension side panel", "tags": [ "extension" ] } }, "/api/v1/extension/assistant/conversations/{conversation_id}": { "get": { "operationId": "getExtensionAssistantConversation", "parameters": [ { "in": "path", "name": "conversation_id", "required": true, "schema": { "format": "uuid", "title": "Conversation Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "title": "Response Getextensionassistantconversation" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get one assistant conversation for the extension side panel", "tags": [ "extension" ] } }, "/api/v1/extension/assistant/message": { "post": { "operationId": "sendExtensionAssistantMessage", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExtensionAssistantMessageRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExtensionAssistantMessageResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Send a browser-extension contextual message to the assistant", "tags": [ "extension" ] } }, "/api/v1/extension/primitives-cache": { "get": { "description": "Return compact UUID-backed primitives for body links in clippings.", "operationId": "extensionListPrimitiveCache", "parameters": [ { "in": "query", "name": "q", "required": false, "schema": { "anyOf": [ { "maxLength": 120, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Q" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 700, "maximum": 1000, "minimum": 1, "title": "Limit", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExtensionPrimitiveCacheResponse" } } }, "description": "Successful Response" }, "401": { "description": "Missing or invalid browser session" }, "403": { "description": "Selected tenant not available to this account" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Return linkable primitives for extension rich-note typeahead", "tags": [ "extension" ] } }, "/api/v1/extension/suggest": { "post": { "description": "Return AI-ranked facet / tag / entity suggestions for ``body``.\n\nSingle round trip. Cached for 24h by sha256(tenant + url +\nmember + visible contact snapshot + first 1024 chars of plain_text). LLM call is tier `low` via\nEXTRACTOR_LLM_MODEL_LOW (gemini-2.5-flash-lite by default).", "operationId": "extensionSuggest", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuggestRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuggestResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "AI-ranked facet/tag/entity suggestions for a captured page", "tags": [ "extension" ] } }, "/api/v1/extension/web-clipping-screenshot": { "post": { "description": "Persist a clipping screenshot in tenant-scoped private storage.", "operationId": "extensionUploadWebClippingScreenshot", "parameters": [ { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/Body_extensionUploadWebClippingScreenshot" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebClippingScreenshotResponse" } } }, "description": "Successful Response" }, "400": { "description": "Invalid screenshot payload" }, "401": { "description": "Missing or invalid browser session" }, "403": { "description": "Selected tenant not available to this account" }, "413": { "description": "Screenshot too large" }, "415": { "description": "Unsupported screenshot content type" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Upload a browser-extension web clipping screenshot", "tags": [ "extension" ] } }, "/api/v1/extension/web-clipping-status": { "get": { "description": "Read saved-state for a URL using the selected browser-session tenant.", "operationId": "extensionGetWebClippingStatus", "parameters": [ { "in": "query", "name": "url", "required": true, "schema": { "maxLength": 2048, "minLength": 1, "title": "Url", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebClippingStatusResponse" } } }, "description": "Successful Response" }, "401": { "description": "Missing or invalid browser session" }, "403": { "description": "Selected tenant not available to this account" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Return whether the selected account has saved the current URL", "tags": [ "extension" ] } }, "/api/v1/extension/web-clippings": { "get": { "description": "Return gallery-ready web clippings scoped to the selected account.", "operationId": "extensionListWebClippings", "parameters": [ { "in": "query", "name": "limit", "required": false, "schema": { "default": 24, "maximum": 50, "minimum": 1, "title": "Limit", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebClippingGalleryResponse" } } }, "description": "Successful Response" }, "401": { "description": "Missing or invalid browser session" }, "403": { "description": "Selected tenant not available to this account" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Return recent web clipping visuals for the selected account", "tags": [ "extension" ] } }, "/api/v1/extension/web-clippings/{note_id}/ingest-content": { "post": { "description": "Fetch and clean article content for an already-saved clipping note.", "operationId": "extensionIngestWebClippingContent", "parameters": [ { "description": "Typed ID with prefix 'N'", "in": "path", "name": "note_id", "required": true, "schema": { "description": "Typed ID with prefix 'N'", "title": "Note Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/WebClippingIngestionRequest" }, { "type": "null" } ], "title": "Body" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebClippingIngestionResponse" } } }, "description": "Successful Response" }, "401": { "description": "Missing or invalid browser session" }, "403": { "description": "Selected tenant not available to this account" }, "404": { "description": "Web clipping note not found for selected account" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Start clean-content ingestion for a saved web clipping", "tags": [ "extension" ] } }, "/api/v1/extension/web-clippings/{note_id}/ingestion-status": { "get": { "description": "Read note-specific web clipping ingestion status.", "operationId": "extensionGetWebClippingIngestionStatus", "parameters": [ { "description": "Typed ID with prefix 'N'", "in": "path", "name": "note_id", "required": true, "schema": { "description": "Typed ID with prefix 'N'", "title": "Note Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebClippingIngestionResponse" } } }, "description": "Successful Response" }, "401": { "description": "Missing or invalid browser session" }, "403": { "description": "Selected tenant not available to this account" }, "404": { "description": "Web clipping note not found for selected account" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Return clean-content ingestion status for a saved web clipping", "tags": [ "extension" ] } }, "/api/v1/extractions/reject-memory": { "post": { "operationId": "recordExtractionRejectMemory", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RejectMemoryRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RejectMemoryResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Record an always-reject preference for an extracted entity", "tags": [ "extractions", "extractions" ], "x-mcp-skip": true, "x-mcp-skip-reason": "Approval-UI rejection-memory toggle." } }, "/api/v1/face-clusters": { "get": { "operationId": "listFaceClusters", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FaceClusterListResponse" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List Face Clusters", "tags": [ "face-clusters", "face-clusters" ], "x-mcp-skip": true, "x-mcp-skip-reason": "Batch facial-approvals UI surface; not an agent tool." } }, "/api/v1/face-clusters/{cluster_id}/dismiss": { "post": { "operationId": "dismissFaceCluster", "parameters": [ { "in": "path", "name": "cluster_id", "required": true, "schema": { "format": "uuid", "title": "Cluster Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_service__models__photo_faces__DismissResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Dismiss Face Cluster", "tags": [ "face-clusters", "face-clusters" ], "x-mcp-skip": true, "x-mcp-skip-reason": "Batch facial-approvals UI surface; not an agent tool." } }, "/api/v1/face-clusters/{cluster_id}/resolve": { "post": { "operationId": "resolveFaceCluster", "parameters": [ { "in": "path", "name": "cluster_id", "required": true, "schema": { "format": "uuid", "title": "Cluster Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResolveClusterRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResolveClusterResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Resolve Face Cluster", "tags": [ "face-clusters", "face-clusters" ], "x-mcp-skip": true, "x-mcp-skip-reason": "Batch facial-approvals UI surface; not an agent tool." } }, "/api/v1/faces/{face_id}/dismiss": { "post": { "operationId": "dismissFace", "parameters": [ { "in": "path", "name": "face_id", "required": true, "schema": { "format": "uuid", "title": "Face Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_service__models__photo_faces__DismissResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Dismiss Face", "tags": [ "photo-faces", "photo-faces" ], "x-mcp-skip": true, "x-mcp-skip-reason": "Face-recognition UI surface (overlays/markers/people rail); not an agent tool." } }, "/api/v1/faces/{face_id}/link": { "delete": { "operationId": "unlinkFace", "parameters": [ { "in": "path", "name": "face_id", "required": true, "schema": { "format": "uuid", "title": "Face Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FaceLinkResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Unlink Face", "tags": [ "photo-faces", "photo-faces" ], "x-mcp-skip": true, "x-mcp-skip-reason": "Face-recognition UI surface (overlays/markers/people rail); not an agent tool." }, "put": { "operationId": "linkFace", "parameters": [ { "in": "path", "name": "face_id", "required": true, "schema": { "format": "uuid", "title": "Face Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinkFaceRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FaceLinkResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Link Face", "tags": [ "photo-faces", "photo-faces" ], "x-mcp-skip": true, "x-mcp-skip-reason": "Face-recognition UI surface (overlays/markers/people rail); not an agent tool." } }, "/api/v1/faces/{face_id}/suggestions": { "get": { "operationId": "getFaceSuggestions", "parameters": [ { "in": "path", "name": "face_id", "required": true, "schema": { "format": "uuid", "title": "Face Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FaceSuggestionsResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Face Suggestions", "tags": [ "photo-faces", "photo-faces" ], "x-mcp-skip": true, "x-mcp-skip-reason": "Face-recognition UI surface (overlays/markers/people rail); not an agent tool." } }, "/api/v1/facet-actions/invoke": { "post": { "description": "Resolve params and dispatch a facet action (built-in or workflow).\n\nThin HTTP wrapper over the shared dispatch spine in\n``services.facet_action_dispatch`` (D4 — the Teleporter workflow-fire\nconsumer reuses the SAME spine; there is no second dispatcher).", "operationId": "invokeFacetAction", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvokeActionRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvokeActionResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Invoke Facet Action", "tags": [ "facet-actions", "facet-actions" ] } }, "/api/v1/facet-definitions": { "get": { "description": "Return the tenant's EFFECTIVE facet definitions (global ∪ tenant,\nfork-wins per slug — TIDY-14213), filtered and paginated server-side\n(TIDY-14582). The response stays a bare array; ``X-Total-Count`` always\ncarries the post-filter effective total so callers detect pagination\nwithout a shape change. Ordered by slug ASC (deterministic, unique\npost-resolution) so pages are stable and complete.\n\nTIDY-15680: every generated output type additionally carries the computed\n``generation_available`` / ``unavailable_reason`` / ``generation_enabled``.\nThey are computed server-side because only the server knows which model\nlanes this deployment can call and what the tenant admin has enabled.", "operationId": "listFacetDefinitions", "parameters": [ { "description": "Filter by primitive type", "in": "query", "name": "applies_to", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by primitive type", "title": "Applies To" } }, { "description": "Filter to the watch radial-ring subset. When true, returns only facets flagged for the Tidy Watch quick-capture ring (TIDY-13824).", "in": "query", "name": "watch_quick_capture", "required": false, "schema": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Filter to the watch radial-ring subset. When true, returns only facets flagged for the Tidy Watch quick-capture ring (TIDY-13824).", "title": "Watch Quick Capture" } }, { "description": "Facet class partition: system (built-in), user (user-created), utility (supporting facets kept out of primary navigation). Absent returns all classes.", "in": "query", "name": "class", "required": false, "schema": { "anyOf": [ { "enum": [ "system", "user", "utility" ], "type": "string" }, { "type": "null" } ], "description": "Facet class partition: system (built-in), user (user-created), utility (supporting facets kept out of primary navigation). Absent returns all classes.", "title": "Class" } }, { "description": "Filter by the declared storage primitive (e.g. records, activities, contacts, notes, calendar_events); `tasks` aliases to activities.", "in": "query", "name": "target_table", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by the declared storage primitive (e.g. records, activities, contacts, notes, calendar_events); `tasks` aliases to activities.", "title": "Target Table" } }, { "description": "Case-insensitive substring match on slug OR name.", "in": "query", "name": "q", "required": false, "schema": { "anyOf": [ { "minLength": 1, "type": "string" }, { "type": "null" } ], "description": "Case-insensitive substring match on slug OR name.", "title": "Q" } }, { "description": "Partition the generated output catalog (TIDY-15680). True returns only facets carrying a `generation` contract, false only the hand-filled ones. Absent returns both.", "in": "query", "name": "generated", "required": false, "schema": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Partition the generated output catalog (TIDY-15680). True returns only facets carrying a `generation` contract, false only the hand-filled ones. Absent returns both.", "title": "Generated" } }, { "description": "Page size. Absent returns the FULL effective list (no default cap — no silent truncation).", "in": "query", "name": "limit", "required": false, "schema": { "anyOf": [ { "maximum": 200, "minimum": 1, "type": "integer" }, { "type": "null" } ], "description": "Page size. Absent returns the FULL effective list (no default cap — no silent truncation).", "title": "Limit" } }, { "description": "Page start within the filtered effective list.", "in": "query", "name": "offset", "required": false, "schema": { "anyOf": [ { "minimum": 0, "type": "integer" }, { "type": "null" } ], "description": "Page start within the filtered effective list.", "title": "Offset" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "additionalProperties": true, "type": "object" }, "title": "Response Listfacetdefinitions", "type": "array" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List facet definitions for the authenticated tenant", "tags": [ "facet-definitions" ] }, "post": { "description": "Create or upsert a tenant-scoped facet definition.", "operationId": "createFacetDefinition", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Payload", "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Createfacetdefinition", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Create or upsert a facet definition", "tags": [ "facet-definitions" ] } }, "/api/v1/facet-definitions/generation-capabilities": { "get": { "description": "Read the authoring vocabulary off the renderer registry + lane config.\n\nLane availability is answered for THIS TENANT, not for the deployment\n(TIDY-15827). `video` is the case that forced it: no deployment model exists\nfor that lane anywhere in the fleet, so a tenant who has configured their own\n`video` key was still told \"not configured for this deployment\" — the author\ncould not declare a lane they were, in fact, paying for. The list endpoint\nalready resolved availability per tenant; this one did not, and the two\ndisagreeing about the same lane is the inconsistency.", "operationId": "getGenerationCapabilities", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerationCapabilitiesResponse" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "The modalities, tiers, model lanes and content producers an output type may declare", "tags": [ "facet-definitions" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/facet-definitions/openapi.json": { "get": { "description": "Render the tenant's resolved facet catalog as OpenAPI 3.1 (TIDY-14589).\n\nOne component schema per effective facet (tenant fork wins over the global\nsystem row) on EVERY primitive a facet can extend — records-backed facets\ndocument the generic records routes, lane-supported targets document the\ngeneric /api/v1/primitives lane, everything else is annotated\n``x-tidy-write-lane: none``. Each facet's target table is resolved through\nthe canonical inheritance walk — an unresolvable facet is annotated, never\nsilently dropped and never defaulted to ``notes`` (TIDY-10514). A facet\nwith an invalid/empty schema is annotated ``x-tidy-skipped`` rather than\nfailing the whole document.", "operationId": "getFacetCatalogOpenApi", "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Generated per-facet OpenAPI 3.1 catalog for the tenant", "tags": [ "facet-definitions" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/facet-definitions/{facet_id}": { "delete": { "description": "Delete a tenant-scoped facet definition when it is not system-managed.\n\nTIDY-14790 (R1 facet-delete edge case): a facet with attached automation\nrules cannot be deleted silently — the guard returns 409 naming every\naffected rule unless the caller explicitly passes ``retire_rules=true``.\nTIDY-14856: a facet installed by an applied workspace template 409s with\nthe source template unless ``template_confirmed=true`` — deleting one\ninstalled item NEVER cascades to the rest of the install.", "operationId": "deleteFacetDefinition", "parameters": [ { "in": "path", "name": "facet_id", "required": true, "schema": { "title": "Facet Id", "type": "string" } }, { "description": "TIDY-14790 (R1): required true when automation rules are attached — retires them (status -> paused, paused_reason='facet deleted') alongside the facet. Without it the delete 409s with the affected rule list (that list IS the UI confirmation payload).", "in": "query", "name": "retire_rules", "required": false, "schema": { "default": false, "description": "TIDY-14790 (R1): required true when automation rules are attached — retires them (status -> paused, paused_reason='facet deleted') alongside the facet. Without it the delete 409s with the affected rule list (that list IS the UI confirmation payload).", "title": "Retire Rules", "type": "boolean" } }, { "description": "TIDY-14856: required true when the facet came from an applied workspace template — without it the delete 409s with an advisory naming the source template (deleting removes ONLY this item; the rest of the install is untouched).", "in": "query", "name": "template_confirmed", "required": false, "schema": { "default": false, "description": "TIDY-14856: required true when the facet came from an applied workspace template — without it the delete 409s with an advisory naming the source template (deleting removes ONLY this item; the rest of the install is untouched).", "title": "Template Confirmed", "type": "boolean" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Delete a facet definition", "tags": [ "facet-definitions" ] }, "get": { "description": "Return one tenant-scoped facet definition with its full detail.", "operationId": "getFacetDefinition", "parameters": [ { "in": "path", "name": "facet_id", "required": true, "schema": { "title": "Facet Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Getfacetdefinition", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get a single facet definition by id", "tags": [ "facet-definitions" ] }, "patch": { "description": "Partially update a facet definition by id.\n\nCopy-on-write (TIDY-14970): when the id addresses a GLOBAL system facet,\nthe patch creates or updates the tenant's fork for that slug instead of\ntouching the shared row — the response is the FORK row, whose ``id``\ndiffers from the path id. Fork-wins-by-slug (TIDY-14213) makes the edit\neffective as soon as the client's registry refreshes from sync.", "operationId": "patchFacetDefinition", "parameters": [ { "in": "path", "name": "facet_id", "required": true, "schema": { "title": "Facet Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Payload", "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Patchfacetdefinition", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Partially update a facet definition", "tags": [ "facet-definitions" ] }, "put": { "description": "Upsert a facet definition by id.\n\nCopy-on-write (TIDY-14970): when the id addresses a GLOBAL system facet,\nthe write creates or updates the tenant's fork for that slug instead of\ntouching the shared row — the response is the FORK row, whose ``id``\ndiffers from the path id. Fork-wins-by-slug (TIDY-14213) makes the edit\neffective as soon as the client's registry refreshes from sync.", "operationId": "putFacetDefinition", "parameters": [ { "in": "path", "name": "facet_id", "required": true, "schema": { "title": "Facet Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Payload", "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Putfacetdefinition", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Update or upsert a facet definition", "tags": [ "facet-definitions" ] } }, "/api/v1/facet-definitions/{facet_id}/template-source": { "get": { "description": "TIDY-14856: preflight for delete UX. The web app deletes facets via the\nlocal-first write path (no API call), so it asks here first whether the\nfacet belongs to an applied template install — to say so in the confirm\ndialog. Returns nulls when the facet is not template-installed.", "operationId": "getFacetTemplateSource", "parameters": [ { "in": "path", "name": "facet_id", "required": true, "schema": { "title": "Facet Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Getfacettemplatesource", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Advisory: the workspace template this facet came from, if any", "tags": [ "facet-definitions" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/facet-options/{source}": { "get": { "operationId": "resolveFacetOptions", "parameters": [ { "in": "path", "name": "source", "required": true, "schema": { "title": "Source", "type": "string" } }, { "description": "Form facet context; unsaved dependency values are supplied as depends_on[key].", "in": "query", "name": "facet", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Form facet context; unsaved dependency values are supplied as depends_on[key].", "title": "Facet" } }, { "description": "Optional form record context. No primitive is fetched: caller-supplied dependencies describe the current form.", "in": "query", "name": "record_id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional form record context. No primitive is fetched: caller-supplied dependencies describe the current form.", "title": "Record Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FacetOptionsResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Facet Options", "x-local-capability": "cloud" } }, "/api/v1/facets/extract": { "post": { "operationId": "extractFacetFields", "parameters": [ { "in": "header", "name": "x-internal-service", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service" } }, { "in": "header", "name": "x-internal-service-key", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service-Key" } }, { "in": "header", "name": "x-tenant-id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tenant-Id" } }, { "in": "header", "name": "x-account-id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Account-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FacetExtractionRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FacetExtractionResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Extract facet fields from text using AI", "tags": [ "facet-extraction" ] } }, "/api/v1/facets/{facet_id}/automations": { "get": { "operationId": "listFacetAutomationRules", "parameters": [ { "in": "path", "name": "facet_id", "required": true, "schema": { "title": "Facet Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/AutomationRuleResponse" }, "title": "Response Listfacetautomationrules", "type": "array" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Rules attached to a facet (facet must be member-visible)", "tags": [ "automations", "automations" ], "x-local-capability": "local", "x-mcp-skip": true, "x-mcp-skip-reason": "UI-shaped read; the automation_* MCP tools cover the rule/run surface." } }, "/api/v1/family-members": { "get": { "operationId": "listManagedFamilyMembers", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_service__models__family_members__FamilyMembersListResponse" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List Family Members", "tags": [ "family-members" ] }, "post": { "operationId": "createManagedFamilyMember", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_service__models__family_members__FamilyMemberCreate" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_service__models__family_members__FamilyMemberResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Create Family Member", "tags": [ "family-members" ] } }, "/api/v1/family-members/{member_id}": { "delete": { "operationId": "deleteManagedFamilyMember", "parameters": [ { "in": "path", "name": "member_id", "required": true, "schema": { "format": "uuid", "title": "Member Id", "type": "string" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Delete Family Member", "tags": [ "family-members" ] }, "patch": { "operationId": "updateManagedFamilyMember", "parameters": [ { "in": "path", "name": "member_id", "required": true, "schema": { "format": "uuid", "title": "Member Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FamilyMemberPatch" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_service__models__family_members__FamilyMemberResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Update Family Member", "tags": [ "family-members" ] } }, "/api/v1/feed": { "get": { "description": "Get the unified feed for the authenticated user.\n\n The feed combines news, events, tasks, and reminders into a single\n chronological view optimized for mobile display. Cards are sorted\n by a composite score based on priority, time-sensitivity, and recency.\n\n Query Parameters:\n cardTypes: Filter by card types (comma-separated: news,event,task,reminder,alert,weather,travel,conflict,recipe)\n category: Filter by category (e.g., 'school', 'activity')\n includeArchived: Include archived cards (default: false)\n limit: Max cards to return (1-500, default: 200)\n cursor: Pagination cursor from previous response\n\n Response:\n {\n \"cards\": [\n {\n \"id\": \"event_a1b2c3d4-...\",\n \"cardType\": \"event\",\n \"sourceId\": \"a1b2c3d4-...\",\n \"title\": \"School Picture Day\",\n \"subtitle\": \"Lincoln Elementary\",\n \"body\": \"Remember to bring your order form...\",\n \"icon\": \"event\",\n \"accentColor\": \"#10B981\",\n \"badge\": \"Tomorrow\",\n \"timestamp\": \"2025-12-28T09:00:00Z\",\n \"displayDate\": \"Tomorrow\",\n \"isTimeSensitive\": false,\n \"priority\": \"high\",\n \"confidence\": 0.95,\n \"category\": \"school\",\n \"isArchived\": false,\n \"isRead\": false,\n \"shareText\": \"School Picture Day on Dec 28\",\n \"deepLink\": \"tidy://V-550e8400-e29b-41d4-a716-446655440000\"\n }\n ],\n \"nextCursor\": \"50\",\n \"hasMore\": true,\n \"totalCount\": 125\n }\n\n Error Responses:\n - 401 Unauthorized: Missing or invalid JWT token\n - 404 Not Found: No tenant associated with account\n - 500 Internal Server Error: Database operation failed\n\n Related: Android App v1", "operationId": "getFeed", "parameters": [ { "description": "Comma-separated card types: news,event,task,reminder", "in": "query", "name": "cardTypes", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Comma-separated card types: news,event,task,reminder", "title": "Cardtypes" } }, { "description": "Filter by primary category", "in": "query", "name": "category", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by primary category", "title": "Category" } }, { "description": "Comma-separated tags to filter by (OR logic: matches if any tag present)", "in": "query", "name": "tags", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Comma-separated tags to filter by (OR logic: matches if any tag present)", "title": "Tags" } }, { "description": "Include archived cards", "in": "query", "name": "includeArchived", "required": false, "schema": { "default": false, "description": "Include archived cards", "title": "Includearchived", "type": "boolean" } }, { "description": "Filter by date (YYYY-MM-DD format). Shows items for that specific day.", "in": "query", "name": "date", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by date (YYYY-MM-DD format). Shows items for that specific day.", "title": "Date" } }, { "description": "Max cards to return", "in": "query", "name": "limit", "required": false, "schema": { "default": 200, "description": "Max cards to return", "maximum": 500, "minimum": 1, "title": "Limit", "type": "integer" } }, { "description": "Pagination cursor", "in": "query", "name": "cursor", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pagination cursor", "title": "Cursor" } }, { "description": "Force refresh: fetch fresh weather data and generate recipe cards", "in": "query", "name": "refresh", "required": false, "schema": { "default": false, "description": "Force refresh: fetch fresh weather data and generate recipe cards", "title": "Refresh", "type": "boolean" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeedResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get paginated feed", "tags": [ "feed" ] } }, "/api/v1/feed/archive": { "post": { "description": "Archive a feed card to hide it from the user's feed.\n\n Archived cards can be restored using the DELETE endpoint.\n Archive status is per-user, not per-tenant.\n\n Request:\n {\n \"cardType\": \"news\",\n \"sourceId\": \"a1b2c3d4-...\"\n }\n\n Response:\n {\n \"success\": true,\n \"cardType\": \"news\",\n \"sourceId\": \"a1b2c3d4-...\",\n \"archived\": true,\n \"archivedAt\": \"2025-12-27T14:30:00Z\"\n }\n\n Error Responses:\n - 400 Bad Request: Invalid card type or source ID\n - 401 Unauthorized: Missing or invalid JWT token\n - 404 Not Found: No tenant associated with account\n - 500 Internal Server Error: Database operation failed\n\n Related: Android App v1", "operationId": "archiveCard", "parameters": [ { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeedArchiveRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeedArchiveResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Archive a feed card", "tags": [ "feed" ] } }, "/api/v1/feed/archive/{card_type}/{source_id}": { "delete": { "description": "Unarchive a feed card to restore it to the user's feed.\n\n Path Parameters:\n cardType: Type of card (news|event|task|reminder)\n sourceId: UUID of the source entity\n\n Response:\n {\n \"success\": true,\n \"cardType\": \"news\",\n \"sourceId\": \"a1b2c3d4-...\",\n \"archived\": false,\n \"archivedAt\": null\n }\n\n Note: Returns success even if the card was not archived.\n\n Error Responses:\n - 400 Bad Request: Invalid card type\n - 401 Unauthorized: Missing or invalid JWT token\n - 404 Not Found: No tenant associated with account\n - 500 Internal Server Error: Database operation failed\n\n Related: Android App v1", "operationId": "unarchiveCard", "parameters": [ { "in": "path", "name": "card_type", "required": true, "schema": { "title": "Card Type", "type": "string" } }, { "in": "path", "name": "source_id", "required": true, "schema": { "title": "Source Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeedArchiveResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Unarchive a feed card", "tags": [ "feed" ] } }, "/api/v1/feed/cards": { "post": { "description": "Creates a new user-initiated feed card (Ask, Note, or Journal).\n The card is persisted to the database immediately and processing begins asynchronously.\n\n - **Ask**: Routes to assistant v2 for AI response\n - **Note**: Routes to pipeline for entity extraction\n - **Journal**: Returns stub response (future coaching agent)", "operationId": "createCard", "parameters": [ { "in": "header", "name": "authorization", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Authorization" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCardRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCardResponse" } } }, "description": "Successful Response" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_service__routers__cards__ErrorResponse" } } }, "description": "Invalid request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_service__routers__cards__ErrorResponse" } } }, "description": "Unauthorized" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Create a new feed card", "tags": [ "cards" ] } }, "/api/v1/feed/cards/pending-synthesis": { "get": { "description": "Returns note and journal cards that have unsynthesized user sections.\n Used by overnight batch processing to find cards that need synthesis.\n\n A card is pending synthesis if:\n - It's a note or journal card\n - It has at least one user/text section where synthesized_at IS NULL\n\n Related: 001-card-ux-rem-sleep, Phase 12 (Batch Processing)", "operationId": "getPendingSynthesisCards", "parameters": [ { "in": "query", "name": "limit", "required": false, "schema": { "default": 100, "title": "Limit", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PendingSynthesisResponse" } } }, "description": "Successful Response" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_service__routers__cards__ErrorResponse" } } }, "description": "Unauthorized" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get cards pending synthesis (T076)", "tags": [ "cards" ] } }, "/api/v1/feed/cards/{card_id}": { "get": { "description": "Retrieves a card with its complete conversation history (all sections).\n Used for viewing full multi-turn conversations.", "operationId": "getCard", "parameters": [ { "in": "path", "name": "card_id", "required": true, "schema": { "title": "Card Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Getcard", "type": "object" } } }, "description": "Successful Response" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_service__routers__cards__ErrorResponse" } } }, "description": "Card not found" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get a single card with all sections", "tags": [ "cards" ] } }, "/api/v1/feed/cards/{card_id}/reply": { "post": { "description": "Appends a reply to an existing card's conversation.\n\n - **Ask**: Sends follow-up to assistant v2 with existing conversation_id\n - **Note**: Appends content to sections (no pipeline re-processing)\n - **Journal**: Appends content (stub response until coaching agent)\n\n The card's sections array is extended with the new message and any AI response.", "operationId": "replyToCard", "parameters": [ { "in": "path", "name": "card_id", "required": true, "schema": { "title": "Card Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReplyCardRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReplyCardResponse" } } }, "description": "Successful Response" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_service__routers__cards__ErrorResponse" } } }, "description": "Invalid request" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_service__routers__cards__ErrorResponse" } } }, "description": "Card not found" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Reply to an existing card", "tags": [ "cards" ] } }, "/api/v1/feed/cards/{card_id}/sections": { "patch": { "description": "Updates the text content of user-created sections in a card.\n Only user/text sections can be modified - AI sections are read-only.\n\n After modification, synthesized_at is cleared on modified sections,\n queuing them for re-processing on next synthesis.\n\n Related: 001-card-ux-rem-sleep, User Story 5 (Edit Mode)", "operationId": "updateSections", "parameters": [ { "in": "path", "name": "card_id", "required": true, "schema": { "title": "Card Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSectionsRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSectionsResponse" } } }, "description": "Successful Response" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_service__routers__cards__ErrorResponse" } } }, "description": "Invalid request (e.g., trying to edit AI section)" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_service__routers__cards__ErrorResponse" } } }, "description": "Card not found" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Update card sections (T046)", "tags": [ "cards" ] } }, "/api/v1/feed/cards/{card_id}/synthesize": { "post": { "description": "Triggers AI synthesis on a note card's user sections.\n\n Synthesis extracts entities (events, tasks, contacts, etc.) from user-created\n sections and creates AI sections with extracted information.\n\n Only note cards can be synthesized. AI sections are never re-synthesized.\n\n Related: 001-card-ux-rem-sleep, User Story 6 (Note Synthesis)", "operationId": "synthesizeCard", "parameters": [ { "in": "path", "name": "card_id", "required": true, "schema": { "title": "Card Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SynthesizeCardResponse" } } }, "description": "Successful Response" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_service__routers__cards__ErrorResponse" } } }, "description": "Invalid card type (not note)" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_service__routers__cards__ErrorResponse" } } }, "description": "Card not found" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Synthesize card content (T053)", "tags": [ "cards" ] } }, "/api/v1/feed/cards/{card_type}/{source_id}": { "delete": { "description": "Permanently delete a feed card (logical delete - sets status to 'deleted').\n\n Cards are not physically removed from the database but marked as deleted.\n This allows for potential recovery and maintains referential integrity.\n\n Path Parameters:\n cardType: Type of card (news|event|task|reminder|note|ask|journal)\n sourceId: UUID of the source entity\n\n Response:\n {\n \"success\": true,\n \"cardType\": \"note\",\n \"sourceId\": \"a1b2c3d4-...\",\n \"archived\": true,\n \"archivedAt\": \"2025-12-27T14:30:00Z\"\n }\n\n Error Responses:\n - 400 Bad Request: Invalid card type\n - 401 Unauthorized: Missing or invalid JWT token\n - 404 Not Found: No tenant associated with account or card not found\n - 500 Internal Server Error: Database operation failed\n\n Related: 018-unified-card-architecture, Archive section UX", "operationId": "deleteCard", "parameters": [ { "in": "path", "name": "card_type", "required": true, "schema": { "title": "Card Type", "type": "string" } }, { "in": "path", "name": "source_id", "required": true, "schema": { "title": "Source Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeedArchiveResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Delete a feed card", "tags": [ "feed" ] } }, "/api/v1/feed/check-duplicate": { "post": { "description": "Check if content has already been shared/created based on SHA-256 hash.\n\n Use this endpoint before creating a note to detect duplicates and\n offer the user options (append to existing, create new anyway).\n\n Request:\n {\n \"content_hash\": \"a1b2c3d4e5f6...\" (64-char hex SHA-256)\n }\n\n Response:\n {\n \"is_duplicate\": true,\n \"existing_card_id\": \"550e8400-e29b-41d4-a716-446655440000\",\n \"existing_card_title\": \"Pick up soccer uniform...\"\n }\n\n Related: Mobile Feed UX Refactor (017-feed-ux-refactor)", "operationId": "checkDuplicate", "parameters": [ { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckDuplicateRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_service__models__feed_cards__CheckDuplicateResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Check for duplicate content", "tags": [ "feed" ] } }, "/api/v1/feed/notes": { "post": { "deprecated": true, "description": "This endpoint has been deprecated. Use POST /feed/cards with cardType='note' instead.", "operationId": "createNoteDeprecated", "responses": { "410": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Createnotedeprecated", "type": "object" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "[DEPRECATED] Create a note card", "tags": [ "feed" ] } }, "/api/v1/feedback": { "post": { "description": "Emit the appropriate event. The n8n integration consumes it as a\nregistered subscription, preserving the historical behavior of the\ndirect FEEDBACK_WEBHOOK_URL path at the Tidy boundary.", "operationId": "submitFeedback", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeedbackSubmitRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeedbackSubmitResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Submit Feedback", "tags": [ "feedback", "feedback" ] } }, "/api/v1/files": { "get": { "description": "Return files visible to the authenticated user (owned or shared).\n\nOBO delegation (TIDY-16796): when `X-Principal-Id` is present and the caller\nholds an active `files` grant (read or read_write), returns the principal's\nfiles instead. Falls back to the caller's own files when no grant exists.", "operationId": "listFiles2", "parameters": [ { "description": "Filter by folder path", "in": "query", "name": "folder_path", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by folder path", "title": "Folder Path" } }, { "description": "Filter by project UUID", "in": "query", "name": "project_id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by project UUID", "title": "Project Id" } }, { "description": "Filter by MIME type prefix", "in": "query", "name": "mime_type", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by MIME type prefix", "title": "Mime Type" } }, { "description": "Max results", "in": "query", "name": "limit", "required": false, "schema": { "default": 100, "description": "Max results", "maximum": 500, "minimum": 1, "title": "Limit", "type": "integer" } }, { "description": "Pagination offset", "in": "query", "name": "offset", "required": false, "schema": { "default": 0, "description": "Pagination offset", "minimum": 0, "title": "Offset", "type": "integer" } }, { "in": "header", "name": "X-Principal-Id", "required": false, "schema": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "X-Principal-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileListResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List files for the current tenant", "tags": [ "files" ] } }, "/api/v1/files/banners": { "post": { "description": "Upload a banner/icon into \"My Files > Page Backgrounds\" (TIDY-10501 F6 S2).\n\nReuses ``file_service.upload_file`` with ``folder_path='/Page Backgrounds'``\nand ``trigger_pipeline=False`` (banners are images, not pipeline documents).\nWhen ``note_id`` is provided, aligns the new asset's ``files.visibility`` to\nthe owning note's visibility (Plan-D3) so the asset is visible to exactly\nthe members who can see the note. The returned ``storage_ref`` is what the\ncaller sets as ``notes.banner_url`` (F4's column).", "operationId": "uploadBanner", "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/Body_uploadBanner" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Upload a page banner/icon asset into the Page Backgrounds folder", "tags": [ "files" ], "x-mcp-skip": true } }, "/api/v1/files/from-attachment": { "post": { "description": "Copy an email attachment's bytes into a first-class ``files`` row the\ncaller owns, kept after the attachment cache window closes (no re-processing:\nthe email's extraction stands). Idempotent on the provenance key, so a repeat\nPOST returns the first copy. 404 when the source email is not the caller's\n(or delegated to them); the content endpoint's typed errors when the bytes\ncannot be fetched (401 provider reauth, 404, 413, 502).", "operationId": "createFileFromAttachment", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateFileFromAttachmentRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Save an email attachment into Files", "tags": [ "files" ], "x-mcp-skip": true, "x-mcp-skip-reason": "User Save to Tidy / drag of an email attachment into Files (web UI, Android); not an agent tool." } }, "/api/v1/files/from-object": { "post": { "description": "Serialize the referenced object server-side (email → ``.eml`` original\nbytes, event → ``.ics``) and store it as a first-class ``files`` row in\n``folder_path``. The bytes never round-trip the browser. 404 when the object\nis not visible to the caller; 413 when the serialized object is too large.", "operationId": "createFileFromObject", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateFileFromObjectRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Materialize a Tidy object (.eml/.ics) into a Files row", "tags": [ "files" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "User drag of an email/event into a Files folder (web UI); not an agent tool." } }, "/api/v1/files/upload": { "post": { "description": "Upload a file to tenant storage.\n\nStores the binary in Supabase Storage and creates a metadata row.\nReturns 413 if the upload would exceed the tenant's storage quota.\nA malformed ``client_analysis`` envelope is a 422 (``invalid_client_analysis``).\nWith ``client_upload_id`` the upload is idempotent (see the field docs);\nlegacy no-ID uploads are unchanged (R9/D8).\n\nOBO delegation (TIDY-16796): when `X-Principal-Id` is present and the caller\nholds an active `files: read_write` grant, the uploaded file is owned by the\nprincipal. Returns 403 when the grant is read-only or missing.", "operationId": "upload", "parameters": [ { "in": "header", "name": "X-Principal-Id", "required": false, "schema": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "X-Principal-Id" } } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/Body_upload" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileResponse" } } }, "description": "Successful Response", "headers": { "X-Tidy-Op-Outcome": { "description": "With client_upload_id only. replayed: that id had already landed this file; nothing was stored again", "schema": { "enum": [ "applied", "replayed" ], "type": "string" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Upload a file", "tags": [ "files" ] } }, "/api/v1/files/upload-receipt": { "get": { "description": "The status read for an upload whose answer was lost.\n\nThe file and its receipt commit in ONE transaction, so a 404\n``upload_not_found`` means nothing landed under that id yet and the same\nupload with the same id stores it once. Read from the caller's own receipts\nonly — another member's upload ids are not found. 410\n``client_upload_id_gone``: it landed, but you can no longer see the file.", "operationId": "getFileUploadReceipt", "parameters": [ { "description": "The client_upload_id you uploaded with.", "in": "query", "name": "client_upload_id", "required": true, "schema": { "description": "The client_upload_id you uploaded with.", "maxLength": 200, "minLength": 1, "title": "Client Upload Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "The file a keyed upload of yours landed, if it did (TIDY-18493)", "tags": [ "files" ], "x-local-capability": "cloud" } }, "/api/v1/files/upload-tickets": { "post": { "operationId": "createFileUploadTicket", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileUploadTicketCreate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileUploadTicketResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get a one-time address to upload a file you have on disk, by its size and SHA-256", "tags": [ "files" ], "x-local-capability": "cloud" } }, "/api/v1/files/upload-tickets/{ticket_id}/content": { "put": { "operationId": "uploadFileTicketContent", "parameters": [ { "in": "path", "name": "ticket_id", "required": true, "schema": { "format": "uuid", "title": "Ticket Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileUploadTicketResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Send a ticketed file's bytes, once, with its upload token", "tags": [ "files" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "The agent's shell sends the file here; through a tool call its bytes would pass through the model." } }, "/api/v1/files/{file_id}": { "delete": { "description": "Delete file from storage and metadata from DB.\n\nOnly the file owner can delete. A storage-layer refusal fails LOUD as\n502 with the metadata row left intact (TIDY-17529: never orphan the\nblob by deleting its only handle), so the delete can be retried.", "operationId": "deleteFile", "parameters": [ { "description": "Typed ID with prefix 'F'", "in": "path", "name": "file_id", "required": true, "schema": { "description": "Typed ID with prefix 'F'", "title": "File Id", "type": "string" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Delete a file", "tags": [ "files" ] }, "get": { "description": "Get metadata for a single file (must be owned by user or shared).\n\nOBO delegation (TIDY-16796): when `X-Principal-Id` is present and the caller\nholds an active `files` grant (read or read_write), may access the principal's\nfile. Falls back to the caller's own visibility when no grant exists.", "operationId": "getFile", "parameters": [ { "description": "Typed ID with prefix 'F'", "in": "path", "name": "file_id", "required": true, "schema": { "description": "Typed ID with prefix 'F'", "title": "File Id", "type": "string" } }, { "in": "header", "name": "X-Principal-Id", "required": false, "schema": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "X-Principal-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get file metadata", "tags": [ "files" ] }, "patch": { "description": "Update file metadata (name, folder_path, project_id, visibility, tags).\n\nOnly the file owner can update. ``tags`` is trigger-maintained via the\nassignment writer (TIDY-15281), so it is applied separately from the\nmetadata UPDATE; omitting it leaves existing tags untouched.", "operationId": "updateFile", "parameters": [ { "description": "Typed ID with prefix 'F'", "in": "path", "name": "file_id", "required": true, "schema": { "description": "Typed ID with prefix 'F'", "title": "File Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileUpdateRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Update file metadata", "tags": [ "files" ] } }, "/api/v1/files/{file_id}/actions": { "post": { "description": "Durable create: request row + outbox command commit in ONE transaction.\n\nAn exact retry (same client_request_id + same semantic tuple) returns the\nexisting row with ``created=false``; changed device timezone/locale on a\nretry still replays (effective values were persisted at first create).", "operationId": "createFileActionRequest", "parameters": [ { "description": "Typed ID with prefix 'F'", "in": "path", "name": "file_id", "required": true, "schema": { "description": "Typed ID with prefix 'F'", "title": "File Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileActionRequestCreate" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileActionRequestResponse" } } }, "description": "Successful Response" }, "404": { "description": "File not found or not visible to the caller" }, "409": { "description": "client_request_id semantic conflict, or an active successor exists" }, "422": { "description": "Blank/over-limit instruction or invalid supersession target" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Create a durable idempotent file action request", "tags": [ "files" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Client upload companion surface (scan-and-instruct); agents act on files via assistant tools, not this durable request queue." } }, "/api/v1/files/{file_id}/actions/{request_id}": { "get": { "description": "Caller-owned read; re-runs current source-file visibility (R10/D6).", "operationId": "getFileActionRequest", "parameters": [ { "in": "path", "name": "request_id", "required": true, "schema": { "title": "Request Id", "type": "string" } }, { "description": "Typed ID with prefix 'F'", "in": "path", "name": "file_id", "required": true, "schema": { "description": "Typed ID with prefix 'F'", "title": "File Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileActionRequestResponse" } } }, "description": "Successful Response" }, "404": { "description": "Not found, not the caller's request, or file access revoked" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Read a file action request's durable status", "tags": [ "files" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Client status surface; steady-state reads are local-first via the synced file_action_requests table." } }, "/api/v1/files/{file_id}/actions/{request_id}/retry": { "post": { "description": "Re-dispatch: status→pending, attempt+1, outbox command re-published in\nthe same transaction. Old results are never re-planned — a correction goes\nthrough supersession instead.", "operationId": "retryFileActionRequest", "parameters": [ { "in": "path", "name": "request_id", "required": true, "schema": { "title": "Request Id", "type": "string" } }, { "description": "Typed ID with prefix 'F'", "in": "path", "name": "file_id", "required": true, "schema": { "description": "Typed ID with prefix 'F'", "title": "File Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileActionRequestResponse" } } }, "description": "Successful Response" }, "404": { "description": "Not found, not the caller's request, or file access revoked" }, "409": { "description": "Not in a retryable status, or an active successor exists" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Retry a failed/needs_input file action request", "tags": [ "files" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Client retry surface (Story 06 UI)." } }, "/api/v1/files/{file_id}/content": { "get": { "description": "Raw text read for the agent file review-and-fix loop (TIDY-13373).\n\nServes the stored bytes of text documents (text/*, JSON) UTF-8 decoded,\nwrapped in JSON so raw HTML is never inline-renderable from this origin.\nVisibility is the canonical member-visible predicate — the same gate the\ninteractive file viewer's raw render path runs under. Binary files stay\non /download.", "operationId": "getFileContent", "parameters": [ { "description": "Typed ID with prefix 'F'", "in": "path", "name": "file_id", "required": true, "schema": { "description": "Typed ID with prefix 'F'", "title": "File Id", "type": "string" } }, { "in": "header", "name": "X-Principal-Id", "required": false, "schema": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "X-Principal-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileContentResponse" } } }, "description": "Successful Response" }, "404": { "description": "File not found or not visible to the caller" }, "413": { "description": "File exceeds the 5242880 byte text-read limit" }, "415": { "description": "File is not a text document" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Read the raw text content of a file", "tags": [ "files" ] }, "put": { "description": "In-place content replace for text documents (TIDY-13373).\n\nThe file keeps its id, storage_ref, and MIME type, so wiki links and deep\nlinks keep resolving to the corrected document. Owner-only (404 for a\nmember-visible file owned by someone else, matching the metadata PATCH\nshape) — to preserve the original, upload a new file instead.", "operationId": "updateFileContent", "parameters": [ { "description": "Typed ID with prefix 'F'", "in": "path", "name": "file_id", "required": true, "schema": { "description": "Typed ID with prefix 'F'", "title": "File Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileContentUpdateRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileResponse" } } }, "description": "Successful Response" }, "404": { "description": "File not found, not visible, or not owned by the caller" }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuotaErrorDetail" } } }, "description": "Content exceeds the size limit or the tenant storage quota" }, "415": { "description": "File is not a text document" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Replace the text content of an owned file", "tags": [ "files" ] } }, "/api/v1/files/{file_id}/download": { "get": { "description": "Generate a presigned download URL (valid for 1 hour).", "operationId": "downloadFile", "parameters": [ { "description": "Typed ID with prefix 'F'", "in": "path", "name": "file_id", "required": true, "schema": { "description": "Typed ID with prefix 'F'", "title": "File Id", "type": "string" } }, { "in": "header", "name": "X-Principal-Id", "required": false, "schema": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "X-Principal-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DownloadUrlResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get presigned download URL", "tags": [ "files" ] } }, "/api/v1/files/{file_id}/extracted-text": { "get": { "description": "Assistant file reader: returns the docling-extracted markdown for a processed file (PDF, DOCX, etc.), or a clear 'not processed yet' signal. With queue_if_missing=true an unextracted file is dispatched for on-demand extraction and the response carries extraction_state + retry_after_seconds so the caller can poll for the result. TIDY-14968. mode=deep returns (or dispatches) the raster+VLM page variant for PDFs (TIDY-17553) — processor=deep_vision, pages_used, daily page-unit budgets; 415 non-PDF, 429 over budget/concurrent.", "operationId": "getFileExtractedText", "parameters": [ { "description": "Typed ID with prefix 'F'", "in": "path", "name": "file_id", "required": true, "schema": { "description": "Typed ID with prefix 'F'", "title": "File Id", "type": "string" } }, { "description": "When true and no extracted text exists yet, dispatch the docling extraction pipeline for this file on demand.", "in": "query", "name": "queue_if_missing", "required": false, "schema": { "default": false, "description": "When true and no extracted text exists yet, dispatch the docling extraction pipeline for this file on demand.", "title": "Queue If Missing", "type": "boolean" } }, { "description": "\"standard\" (default) returns the Docling consolidated markdown; 'deep' returns (or dispatches) the raster+VLM page variant (TIDY-17553), PDF-only, subject to daily page-unit budgets.", "in": "query", "name": "mode", "required": false, "schema": { "default": "standard", "description": "\"standard\" (default) returns the Docling consolidated markdown; 'deep' returns (or dispatches) the raster+VLM page variant (TIDY-17553), PDF-only, subject to daily page-unit budgets.", "pattern": "^(standard|deep)$", "title": "Mode", "type": "string" } }, { "description": "Deep extract only: 1-based page selection like '1-3,7'. Default first 8 pages, hard cap 20. Invalid values are a 400.", "in": "query", "name": "pages", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Deep extract only: 1-based page selection like '1-3,7'. Default first 8 pages, hard cap 20. Invalid values are a 400.", "title": "Pages" } }, { "in": "header", "name": "X-Principal-Id", "required": false, "schema": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "X-Principal-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileExtractedTextResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Read the docling-extracted text of an uploaded file", "tags": [ "files" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Assistant-internal file reader surface; exposed to users via the tidy_file_extracted_text assistant tool, not a standalone MCP tool." } }, "/api/v1/files/{file_id}/extractions": { "get": { "description": "Itemized extraction insight for an uploaded file — the same contract the\ndefense replay renders, generalized to a file source. 404 when the file is\nnot visible to the caller.", "operationId": "getFileExtractions", "parameters": [ { "description": "Typed ID with prefix 'F'", "in": "path", "name": "file_id", "required": true, "schema": { "description": "Typed ID with prefix 'F'", "title": "File Id", "type": "string" } }, { "in": "header", "name": "X-Principal-Id", "required": false, "schema": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "X-Principal-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExtractionInsightsResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Extraction insight (documents, contacts, events, memories) for a file", "tags": [ "files" ], "x-mcp-skip": true, "x-mcp-skip-reason": "Web insight panel; agents read extracted entities + canonical content via the pipeline/entity endpoints, not this aggregate view." } }, "/api/v1/files/{file_id}/html-preview": { "get": { "description": "Sanitize-on-read for native HTML file viewing (TIDY-11982).\n\nMirrors the email pipeline: server-side nh3 with the document profile\n(``<style>`` blocks + inline ``style=`` preserved; every script vector\nstripped). Returned as JSON so the raw markup is never inline-renderable\nfrom this origin. Visibility is gated by the canonical member-visible\npredicate inside ``file_service.get_file``.", "operationId": "getFileHtmlPreview", "parameters": [ { "description": "Typed ID with prefix 'F'", "in": "path", "name": "file_id", "required": true, "schema": { "description": "Typed ID with prefix 'F'", "title": "File Id", "type": "string" } }, { "in": "header", "name": "X-Principal-Id", "required": false, "schema": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "X-Principal-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HtmlPreviewResponse" } } }, "description": "Successful Response" }, "404": { "description": "File not found or not visible to the caller" }, "413": { "description": "File exceeds the 5 MB HTML preview limit" }, "415": { "description": "File is not text/html" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Sanitized HTML preview of a text/html file", "tags": [ "files" ], "x-mcp-skip": true } }, "/api/v1/files/{file_id}/pull-latest": { "post": { "description": "Append the provider's HEAD content as a new version.\n\nA provider refusal — the file deleted upstream, the connection revoked —\nis surfaced VERBATIM with no version appended. There is deliberately no\ncached-copy fallback here.", "operationId": "pullFileLatest", "parameters": [ { "description": "Typed ID with prefix 'F'", "in": "path", "name": "file_id", "required": true, "schema": { "description": "Typed ID with prefix 'F'", "title": "File Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PullLatestResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Pull the repository's current version of a linked deliverable", "tags": [ "deliverables" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/files/{file_id}/reprocess": { "post": { "description": "Re-run text extraction + LLM processing for a file the caller can see.\n\n404 when the file is not visible to the caller. Idempotent on double-submit:\na still-processing run for this file is reused rather than re-dispatched.", "operationId": "reprocessFile", "parameters": [ { "description": "Typed ID with prefix 'F'", "in": "path", "name": "file_id", "required": true, "schema": { "description": "Typed ID with prefix 'F'", "title": "File Id", "type": "string" } } ], "responses": { "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReprocessFileResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Re-run the ingestion pipeline for an uploaded file", "tags": [ "files" ], "x-mcp-skip": true, "x-mcp-skip-reason": "UI-triggered pipeline dispatch (re-process a file). Extracted content arrives via the normal pipeline and is read locally, not from this route." } }, "/api/v1/files/{file_id}/versions": { "get": { "description": "Newest first. Each entry deep-links to its commit on the provider.", "operationId": "listFileVersions", "parameters": [ { "description": "Typed ID with prefix 'F'", "in": "path", "name": "file_id", "required": true, "schema": { "description": "Typed ID with prefix 'F'", "title": "File Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileVersionListResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List a file's version history", "tags": [ "deliverables" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/files/{file_id}/versions/{version}/scm-reference": { "post": { "description": "Mint the version's stored-file reference and link it to the project.\n\nIdempotent: linking the same version twice returns the same reference and\nadds no second link. A version Tidy never published to the repository has no\nprovider identity and is refused with the reason (409) — the panel hides the\naction for exactly that case.", "operationId": "createFileVersionScmReference", "parameters": [ { "in": "path", "name": "version", "required": true, "schema": { "title": "Version", "type": "integer" } }, { "description": "Typed ID with prefix 'F'", "in": "path", "name": "file_id", "required": true, "schema": { "description": "Typed ID with prefix 'F'", "title": "File Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileVersionScmReferenceResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Link one version of a file to its project as a reference", "tags": [ "deliverables" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/follow-ups/actions": { "post": { "description": "Record one correction, idempotently, with its durable evidence.", "operationId": "recordFollowUpAction", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FollowUpActionRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FollowUpActionResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Post Follow Up Action", "tags": [ "follow-ups", "follow-ups" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/follow-ups/actions/{action_id}/reversal": { "post": { "description": "Undo a correction — unmute, un-dismiss, un-snooze.\n\nIdempotent: reversing an already-reversed correction returns the same row\nwithout a second evidence event and without re-ranking the card.", "operationId": "reverseFollowUpAction", "parameters": [ { "in": "path", "name": "action_id", "required": true, "schema": { "format": "uuid", "title": "Action Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FollowUpActionResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Post Follow Up Action Reversal", "tags": [ "follow-ups", "follow-ups" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/follow-ups/candidates": { "get": { "operationId": "listFollowUpCandidates", "parameters": [ { "description": "Restrict the gate to one communication surface.", "in": "query", "name": "channel", "required": false, "schema": { "default": "all", "description": "Restrict the gate to one communication surface.", "pattern": "^(all|email|chat)$", "title": "Channel", "type": "string" } }, { "description": "Also return every refused message with the rule that refused it.", "in": "query", "name": "include_excluded", "required": false, "schema": { "default": false, "description": "Also return every refused message with the rule that refused it.", "title": "Include Excluded", "type": "boolean" } }, { "description": "How far back a follow-up obligation stays live.", "in": "query", "name": "recency_window_hours", "required": false, "schema": { "default": 336, "description": "How far back a follow-up obligation stays live.", "maximum": 2160, "minimum": 1, "title": "Recency Window Hours", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FollowUpCandidatesResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List Follow Up Candidates", "tags": [ "follow-ups" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/follow-ups/promotion/evaluate": { "post": { "description": "Measure the window and report the decision. Persists nothing.", "operationId": "evaluateFollowUpPromotion", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EvaluationWindow" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EvaluationResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Post Evaluate", "tags": [ "follow-ups", "follow-ups" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/follow-ups/promotion/verdicts": { "get": { "operationId": "listFollowUpPromotionVerdicts", "parameters": [ { "in": "query", "name": "limit", "required": false, "schema": { "default": 20, "maximum": 100, "minimum": 1, "title": "Limit", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/VerdictResponse" }, "title": "Response Listfollowuppromotionverdicts", "type": "array" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Verdicts", "tags": [ "follow-ups", "follow-ups" ], "x-local-capability": "cloud", "x-mcp-skip": true }, "post": { "description": "Measure the window and persist the verdict immutably.\n\nA failing measurement is persisted too, unsigned — a `hold` is a real result\nand the review wants the record of it. Only a passing one is signed, and\nonly a signed one can broaden the rollout.", "operationId": "createFollowUpPromotionVerdict", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EvaluationWindow" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EvaluationResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Post Verdict", "tags": [ "follow-ups", "follow-ups" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/follow-ups/promotion/verdicts/{verdict_id}": { "get": { "operationId": "getFollowUpPromotionVerdict", "parameters": [ { "in": "path", "name": "verdict_id", "required": true, "schema": { "format": "uuid", "title": "Verdict Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerdictResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Verdict", "tags": [ "follow-ups", "follow-ups" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/follow-ups/recommendations": { "get": { "description": "At most three grounded follow-ups for the calling member, right now.\n\nEmail only. A Matrix candidate's body is end-to-end encrypted and the server\ncannot read it, so chat recommendations require the caller to submit the\ndecrypted event (`MatrixMessageSubmission`) — a GET has nowhere to put it.", "operationId": "listFollowUpRecommendations", "parameters": [ { "description": "How many gate survivors to classify. Each one costs a model call.", "in": "query", "name": "max_candidates", "required": false, "schema": { "default": 10, "description": "How many gate survivors to classify. Each one costs a model call.", "maximum": 30, "minimum": 1, "title": "Max Candidates", "type": "integer" } }, { "description": "How far back a follow-up obligation stays live.", "in": "query", "name": "recency_window_hours", "required": false, "schema": { "default": 336, "description": "How far back a follow-up obligation stays live.", "maximum": 2160, "minimum": 1, "title": "Recency Window Hours", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FollowUpRecommendationsResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List Follow Up Recommendations", "tags": [ "follow-ups" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/follow-ups/rollout/allowlist": { "post": { "description": "Add a member to the dogfood cohort. Their consent still decides.", "operationId": "addFollowUpDogfoodAllowlistEntry", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AllowlistEntryRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemberGateStatusResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Post Allowlist Entry", "tags": [ "follow-ups", "follow-ups" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/follow-ups/rollout/allowlist/{account_id}": { "delete": { "operationId": "removeFollowUpDogfoodAllowlistEntry", "parameters": [ { "in": "path", "name": "account_id", "required": true, "schema": { "format": "uuid", "title": "Account Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemberGateStatusResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Delete Allowlist Entry", "tags": [ "follow-ups", "follow-ups" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/follow-ups/rollout/config": { "get": { "operationId": "getFollowUpRolloutConfig", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RolloutConfigResponse" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Rollout Config", "tags": [ "follow-ups", "follow-ups" ], "x-local-capability": "cloud", "x-mcp-skip": true }, "put": { "description": "Append a new active config version (CAS on ``expected_version``).", "operationId": "activateFollowUpRolloutConfig", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RolloutConfigUpdate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RolloutConfigResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Put Rollout Config", "tags": [ "follow-ups", "follow-ups" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/follow-ups/rollout/config/rollback": { "post": { "description": "Restore a previous version by appending a new one (never a resurrection).\n\nWith nothing to restore the gate closes to ``disabled`` — the deterministic\nsafe end state while an incident is reviewed.", "operationId": "rollbackFollowUpRolloutConfig", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RolloutRollbackRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RolloutConfigResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Post Rollout Rollback", "tags": [ "follow-ups", "follow-ups" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/follow-ups/rollout/me": { "get": { "operationId": "getOwnFollowUpGateStatus", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemberGateStatusResponse" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Own Gate Status", "tags": [ "follow-ups", "follow-ups" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/follow-ups/rollout/me/consent": { "delete": { "description": "Withdraw consent — existing rows stop rendering, none are deleted.", "operationId": "revokeOwnFollowUpConsent", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemberGateStatusResponse" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Delete Own Consent", "tags": [ "follow-ups", "follow-ups" ], "x-local-capability": "cloud", "x-mcp-skip": true }, "post": { "operationId": "grantOwnFollowUpConsent", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemberGateStatusResponse" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Post Own Consent", "tags": [ "follow-ups", "follow-ups" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/forms": { "get": { "operationId": "listForms", "parameters": [ { "description": "Filter by facet slug", "in": "query", "name": "facet_slug", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by facet slug", "title": "Facet Slug" } }, { "description": "Filter by page type", "in": "query", "name": "page_type", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by page type", "title": "Page Type" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FormList" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "List forms", "tags": [ "forms" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Form DESIGN surface (TIDY-16218 / D1): authored in the unified builder by a person; agents operate on records, not on their layout." }, "post": { "operationId": "createForm", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FormCreateRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FormDetail" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Create a form, scaffolded from the facet schema by page type", "tags": [ "forms" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Form DESIGN surface (TIDY-16218 / D1): authored in the unified builder by a person; agents operate on records, not on their layout." } }, "/api/v1/forms/compile": { "post": { "operationId": "compileFormBundle", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompileFormBundleRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompileFormBundleResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Compile a publication config into a self-contained public form bundle", "tags": [ "forms" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "CRM publish-flow surface (D18): the runtime epic calls this from its publication pipeline; agents reach it via tidy_api_request." } }, "/api/v1/forms/public-host": { "get": { "operationId": "getPublicFormHost", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicFormHostResponse" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Public Form Host", "tags": [ "forms" ], "x-local-capability": "cloud", "x-mcp-skip": true }, "put": { "description": "Write the tenant's public-form settings.\n\n``public_form_host`` is always written (blank clears it). The unsubscribe\ndesignation is written only when the key is PRESENT in the request, so a\ncaller that knows nothing about it — every pre-TIDY-16835 client — cannot\nsilently clear a tenant's unsubscribe form by saving a host.", "operationId": "putPublicFormHost", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicFormHostBody" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicFormHostResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Put Public Form Host", "tags": [ "forms" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/forms/publications": { "get": { "operationId": "listFormPublications", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FormPublicationList" } } }, "description": "Successful Response" } }, "summary": "List the tenant's form publications", "tags": [ "forms" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "CRM publish-flow management surface (D13); agents reach it via tidy_api_request." }, "post": { "operationId": "publishForm", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublishFormRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublishFormResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Publish a form: compile once, persist the snapshot, mint the public token", "tags": [ "forms" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "CRM publish-flow management surface (D13); agents reach it via tidy_api_request." } }, "/api/v1/forms/publications/{publication_id}": { "get": { "operationId": "getFormPublication", "parameters": [ { "in": "path", "name": "publication_id", "required": true, "schema": { "title": "Publication Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FormPublicationDetail" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "One publication: config, counters, daily stats", "tags": [ "forms" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "CRM publish-flow management surface (D13); agents reach it via tidy_api_request." }, "patch": { "operationId": "updateFormPublication", "parameters": [ { "in": "path", "name": "publication_id", "required": true, "schema": { "title": "Publication Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdatePublicationRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FormPublicationDetail" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Tune a publication's protections / redirect / thanks message", "tags": [ "forms" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "CRM publish-flow management surface (D13); agents reach it via tidy_api_request." } }, "/api/v1/forms/publications/{publication_id}/revoke": { "post": { "operationId": "revokeFormPublication", "parameters": [ { "in": "path", "name": "publication_id", "required": true, "schema": { "title": "Publication Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevokePublicationResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Revoke a publication — the public URL and its assets 404 immediately", "tags": [ "forms" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "CRM publish-flow management surface (D13); agents reach it via tidy_api_request." } }, "/api/v1/forms/publications/{publication_id}/rotate": { "post": { "operationId": "rotateFormPublicationToken", "parameters": [ { "in": "path", "name": "publication_id", "required": true, "schema": { "title": "Publication Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RotateTokenResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Rotate the publish token — the old URL 404s, the new one serves", "tags": [ "forms" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "CRM publish-flow management surface (D13); agents reach it via tidy_api_request." } }, "/api/v1/forms/publications/{publication_id}/row-links": { "post": { "description": "Idempotent: the first call mints, every later call returns the SAME link,\nso the same person's URL is stable across sends (AC1).", "operationId": "mintFormPublicationRowLink", "parameters": [ { "in": "path", "name": "publication_id", "required": true, "schema": { "title": "Publication Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MintRowLinkRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RowLinkResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Mint (or return) this row's per-row link for a publication", "tags": [ "forms" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "CRM publish-flow management surface (D13); agents reach it via tidy_api_request." } }, "/api/v1/forms/{form_id}": { "delete": { "description": "Soft-delete a form.\n\nTIDY-18070: what the delete does to a surface that showed this form is\npart of the response, never a side effect. A copy hands its bindings back\nto the document it was copied from (the built-in it overrode, the form it\nduplicated, or the legacy page it imported) and `rebound` says which\nsurfaces moved where; an original that a surface still shows is refused\nwith 409 `form_bound` until the member picks something else for it.", "operationId": "deleteForm", "parameters": [ { "in": "path", "name": "form_id", "required": true, "schema": { "format": "uuid", "title": "Form Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FormDeleteResponse" } } }, "description": "Successful Response" }, "409": { "description": "The form is bound to a surface and has no source to hand it to (`form_bound`); reassign those surfaces first." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Soft-delete a form; its surface bindings return to the source it was copied from", "tags": [ "forms" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Form DESIGN surface (TIDY-16218 / D1): authored in the unified builder by a person; agents operate on records, not on their layout." }, "get": { "operationId": "getForm", "parameters": [ { "in": "path", "name": "form_id", "required": true, "schema": { "format": "uuid", "title": "Form Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FormDetail" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Get one form with its document", "tags": [ "forms" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Form DESIGN surface (TIDY-16218 / D1): authored in the unified builder by a person; agents operate on records, not on their layout." }, "patch": { "description": "Patch a form, forking a system-global one to the tenant first.\n\nTIDY-16419: the system row is shared by every tenant and writable by none,\nso a save aimed at it copies it into the caller's tenant\n(`overrides_form_id` = the system id) and applies the patch there. The\nreturned `id` is the fork's — callers must follow it rather than assume the\nid they sent.", "operationId": "updateForm", "parameters": [ { "in": "path", "name": "form_id", "required": true, "schema": { "format": "uuid", "title": "Form Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FormUpdateRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FormDetail" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Update a form; a doc change mints a version. A system form forks first", "tags": [ "forms" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Form DESIGN surface (TIDY-16218 / D1): authored in the unified builder by a person; agents operate on records, not on their layout." } }, "/api/v1/forms/{form_id}/fork": { "post": { "operationId": "forkForm", "parameters": [ { "in": "path", "name": "form_id", "required": true, "schema": { "format": "uuid", "title": "Form Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FormForkRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FormDetail" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Fork a form into an editable private copy", "tags": [ "forms" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Form DESIGN surface (TIDY-16218 / D1): authored in the unified builder by a person; agents operate on records, not on their layout." } }, "/api/v1/forms/{form_id}/publish": { "delete": { "operationId": "unpublishFirstClassForm", "parameters": [ { "in": "path", "name": "form_id", "required": true, "schema": { "format": "uuid", "title": "Form Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FormOfflineResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Take a first-class form offline", "tags": [ "forms" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Form DESIGN surface (TIDY-16218 / D1): authored in the unified builder by a person; agents operate on records, not on their layout." }, "post": { "operationId": "publishFirstClassForm", "parameters": [ { "in": "path", "name": "form_id", "required": true, "schema": { "format": "uuid", "title": "Form Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FormPublishRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FormPublishResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Publish a first-class form with a scoped anonymous grant", "tags": [ "forms" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Form DESIGN surface (TIDY-16218 / D1): authored in the unified builder by a person; agents operate on records, not on their layout." } }, "/api/v1/fts": { "get": { "description": "Searches notes, news updates, contacts, activities (tasks), calendar events, projects, organizations, and emails in parallel. Every query is scoped to the caller's tenant. Returns results merged and sorted by relevance rank.", "operationId": "fullTextSearch", "parameters": [ { "description": "Search query. Minimum 2 characters.", "in": "query", "name": "q", "required": false, "schema": { "default": "", "description": "Search query. Minimum 2 characters.", "title": "Q", "type": "string" } }, { "description": "Max total results (1-50).", "in": "query", "name": "limit", "required": false, "schema": { "default": 10, "description": "Max total results (1-50).", "maximum": 50, "minimum": 1, "title": "Limit", "type": "integer" } }, { "description": "Include archived activities in results (badged via `archived`). Default search excludes them; direct by-id reads always work.", "in": "query", "name": "include_archived", "required": false, "schema": { "default": false, "description": "Include archived activities in results (badged via `archived`). Default search excludes them; direct by-id reads always work.", "title": "Include Archived", "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FtsResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Cross-table full-text search", "tags": [ "search", "search" ] } }, "/api/v1/generation-artifacts/{file_id}/playback": { "post": { "description": "Count a play-start or a play-through of a generated video or audio file.\n\nR15 asks for playback COMPLETION RATE, which no server-side signal can\nsupply — only the element that played the bytes knows it reached the end.\nA file that is not a generated artifact answers ``recorded: false`` rather\nthan erroring: this rides on the shared media surface, so being handed an\nordinary attachment is expected traffic, not a fault.", "operationId": "recordGenerationPlayback", "parameters": [ { "description": "Typed ID with prefix 'F'", "in": "path", "name": "file_id", "required": true, "schema": { "description": "Typed ID with prefix 'F'", "title": "File Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerationPlaybackRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerationPlaybackResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Report playback of a generated media artifact", "tags": [ "generation" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/generation-jobs": { "get": { "operationId": "listGenerationJobs", "parameters": [ { "description": "Only jobs from this bundle", "in": "query", "name": "bundle_id", "required": false, "schema": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "description": "Only jobs from this bundle", "title": "Bundle Id" } }, { "description": "Filter by job status", "in": "query", "name": "status", "required": false, "schema": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "description": "Filter by job status", "title": "Status" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "maximum": 200, "minimum": 1, "title": "Limit", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerationJobListResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List the caller's generation jobs", "tags": [ "generation" ], "x-local-capability": "cloud", "x-mcp-skip": true }, "post": { "description": "Queue a generation whose one source is the prompt.\n\nThe job carries the `bundle_id` of the bundle made to hold the prompt; that\nbundle is never the caller's active tray. Refusals are the bundle route's\nnamed errors, and a refused prompt leaves no bundle behind.", "operationId": "generateFromPrompt", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PromptGenerateRequest" } } }, "required": true }, "responses": { "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerationJobResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Generate an output from a prompt", "tags": [ "generation" ], "x-local-capability": "cloud" } }, "/api/v1/generation-jobs/{job_id}": { "get": { "operationId": "getGenerationJob", "parameters": [ { "description": "Generation job id", "in": "path", "name": "job_id", "required": true, "schema": { "description": "Generation job id", "format": "uuid", "title": "Job Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerationJobResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Read one generation job", "tags": [ "generation" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/generation-jobs/{job_id}/build-log": { "get": { "description": "What the T3 producer did, attempt by attempt (R21).\n\nR21 requires the user can expand this while the run is going and after it\nends: it is how \"the code failed\", \"it timed out\", \"it tried to reach the\nnetwork\" and \"it is still running\" stay four different answers instead of\none spinner.\n\nOwner-private, and gated on the JOB rather than on the log: the owner read\nbelow is the authorization, so a build log for a job the caller does not own\nis indistinguishable from a job that does not exist. The rows themselves are\nservice-side (no PowerSync bucket, no client role) precisely because they\ncarry raw sandbox output.", "operationId": "getGenerationJobBuildLog", "parameters": [ { "description": "Generation job id", "in": "path", "name": "job_id", "required": true, "schema": { "description": "Generation job id", "format": "uuid", "title": "Job Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerationBuildLogResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "The build log of a generation that wrote and ran code", "tags": [ "generation" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/generation-jobs/{job_id}/cancel": { "post": { "description": "Ask the job to stop, and return immediately.\n\n202 always, including for a job that already finished — the client may not\nhave seen completion yet, so a late cancel is a no-op rather than an error.\nA queued job stops here; a running one stops at its next stage boundary,\nwith nothing half-written left behind (D17).", "operationId": "cancelGenerationJob", "parameters": [ { "description": "Generation job id", "in": "path", "name": "job_id", "required": true, "schema": { "description": "Generation job id", "format": "uuid", "title": "Job Id", "type": "string" } } ], "responses": { "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerationJobResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Cancel a running generation", "tags": [ "generation" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/generation-jobs/{job_id}/respond": { "post": { "description": "Approve or adjust what a paused job asked for, and resume it.\n\n202 with a re-queued job. Every refusal is named: a job that is not waiting\n(409), one cancelled while it waited (409), and one whose approval window\nclosed (409, and the job is FAILED here rather than run against columns the\nuser never approved — a table nobody agreed to is worse than no table).", "operationId": "respondToGenerationJob", "parameters": [ { "description": "Generation job id", "in": "path", "name": "job_id", "required": true, "schema": { "description": "Generation job id", "format": "uuid", "title": "Job Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerationInputResponse" } } }, "required": true }, "responses": { "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerationJobResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Answer what a paused generation is waiting for", "tags": [ "generation" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/generation-jobs/{job_id}/spend": { "get": { "description": "Estimate versus actual for one generation, from the cost ledger.\n\nOwner-private like every other generation read: another member's job is\nindistinguishable from one that does not exist.", "operationId": "getGenerationJobSpend", "parameters": [ { "description": "Generation job id", "in": "path", "name": "job_id", "required": true, "schema": { "description": "Generation job id", "format": "uuid", "title": "Job Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerationSpendResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "What this generation was quoted and what it actually cost", "tags": [ "generation" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/generation/quota": { "get": { "operationId": "getGenerationQuota", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerationQuotaResponse" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Generation Quota", "tags": [ "generation" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Tenant settings surface (S4 credentials page); not an agent tool." }, "put": { "description": "Owner/tenant-admin sets the workspace and per-member caps.\n\nOnly the fields present in the request are written, so setting a member cap\nnever disturbs the workspace one. `hard_stop` defaults to the tenant's\ncurrent policy when omitted.", "operationId": "updateGenerationQuota", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerationQuotaRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerationQuotaResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Update Generation Quota", "tags": [ "generation" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Tenant settings surface (S4 credentials page); not an agent tool." } }, "/api/v1/google/drive/notifications": { "post": { "operationId": "receiveDriveNotification", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DriveNotificationReceipt" } } }, "description": "Successful Response" } }, "summary": "Google Drive's push notification for a picked spreadsheet (header-only, empty body)", "tags": [ "plugins" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "The public door Google's Drive push channels post to; never called on a member's behalf." } }, "/api/v1/growth/newsletter/rollup": { "get": { "description": "Cadence adherence, per-issue engagement, and the CMO's quality notes.\n\n``missed_weeks`` is the flag that matters: a week inside the window with no\nshipped issue. It is computed from the ISSUE's own week (the slug), not the\nsend timestamp, so a Tuesday send still covers Monday's week.", "operationId": "getNewsletterRollup", "parameters": [ { "description": "ISO weeks to look back.", "in": "query", "name": "weeks", "required": false, "schema": { "default": 8, "description": "ISO weeks to look back.", "maximum": 52, "minimum": 1, "title": "Weeks", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewsletterRollupResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Newsletter Rollup", "tags": [ "growth" ], "x-local-capability": "cloud" } }, "/api/v1/harnesses/{runtime}/credential-methods": { "get": { "operationId": "getHarnessCredentialMethods", "parameters": [ { "in": "path", "name": "runtime", "required": true, "schema": { "title": "Runtime", "type": "string" } }, { "in": "query", "name": "employee_account_id", "required": false, "schema": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Employee Account Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HarnessCredentialMethods" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Harness Credential Methods", "tags": [ "agents" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Credential custody is a first-party settings/runtime surface; secrets are never assistant-callable." } }, "/api/v1/health": { "get": { "description": "Health check endpoint for service monitoring.\n\n Returns service health status and database connectivity.\n Always returns 200 OK if service is running (even if database unreachable).\n\n Use Cases:\n - Docker Compose healthcheck: Verify service container running\n - Load balancer health check: Remove unhealthy instances from pool\n - Monitoring systems: Track uptime and availability\n\n NOT a Kubernetes probe. Kubernetes uses /livez (liveness) and /readyz\n (readiness + startup), which signal in the status code — TIDY-17694.\n\n Response Statuses:\n - status=\"ok\": Service healthy, database connected\n - status=\"degraded\": Service running but database unreachable (partial outage)\n\n Always returns HTTP 200 OK (service alive).\n For strict readiness checks, consider status=\"degraded\" as not ready.", "operationId": "healthCheck", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthResponse" } } }, "description": "Successful Response" } }, "summary": "Health check endpoint", "tags": [ "health" ] } }, "/api/v1/health/model-components": { "get": { "description": "Report the per-machine loadable inference components and their resource\n profiles: WhisperX + Pyannote (GPU, hosted by the whisperx service) and the\n CPU-only audio-fingerprint extractor (this service).\n\n The fingerprint probe imports the `audio_fingerprint` PyO3 wheel and reads its\n live ALGO_VERSION — `audio_fingerprint.loaded=false` means the wheel is\n missing/broken in this image (a build problem), surfaced as status=degraded.", "operationId": "modelComponentsHealth", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Modelcomponentshealth", "type": "object" } } }, "description": "Successful Response" } }, "summary": "Per-machine loadable model components (CA2 D8/D36)", "tags": [ "health" ] } }, "/api/v1/health/replication-slots": { "get": { "description": "Report every PostgreSQL logical replication slot and its WAL lag.\n\n Returns a list of slots with fields:\n - slot_name, plugin, active, active_pid\n - confirmed_flush_lsn, restart_lsn\n - lag_bytes: WAL bytes behind `pg_current_wal_lsn()`\n - lag_human: pg_size_pretty-formatted string\n - wal_status: 'reserved' | 'extended' | 'unreserved' | 'lost'\n - unhealthy: true when lag_bytes > 500 MB OR wal_status IN ('extended','lost')\n\n Top-level status:\n - 'ok' — all slots healthy\n - 'degraded' — at least one slot crossed the alert threshold\n - 'error' — query failed\n\n Typical misbehavior patterns this surfaces:\n - Orphaned CDC consumers (e.g. Logflare cainophile adaptor crash-loop)\n - A stopped service leaving a persistent slot behind\n - A slow consumer falling behind writes\n\n Consumed by Prometheus via /metrics scrape and by Grafana alert\n `PGReplicationSlotLag`.", "operationId": "replicationSlotHealth", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Replicationslothealth", "type": "object" } } }, "description": "Successful Response" } }, "summary": "PostgreSQL replication slot lag (TIDY-6793)", "tags": [ "health" ] } }, "/api/v1/health/vip-cache": { "get": { "description": "Health check for signal-extractor VIP cache status.\n\n Returns cache statistics for all active tenants including:\n - contacts_loaded: Number of contacts in cache\n - projects_loaded: Number of projects in cache\n - organizations_loaded: Number of organizations in cache\n - last_rebuild: When the cache was last rebuilt\n\n This endpoint is useful for verifying the cache is populated after\n service startup or CRUD operations.", "operationId": "vipCacheHealth", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Vipcachehealth", "type": "object" } } }, "description": "Successful Response" } }, "summary": "VIP cache health check (KCC-3436)", "tags": [ "health" ] } }, "/api/v1/health/vip-cache/rebuild/{tenant_id}": { "post": { "description": "Manually trigger VIP cache rebuild for a specific tenant.\n\n Use this when:\n - Cache is empty and needs immediate population\n - Cache is stale and needs refresh\n - Debugging cache issues", "operationId": "rebuildTenantVipCache", "parameters": [ { "in": "path", "name": "tenant_id", "required": true, "schema": { "title": "Tenant Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Rebuildtenantvipcache", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Rebuild VIP cache for a tenant (KCC-3436)", "tags": [ "health" ] } }, "/api/v1/health/vip-cache/warmup": { "post": { "description": "Manually trigger VIP cache warmup for all active tenants.\n\n This is the same operation that runs during service startup.\n Use this to repopulate all caches without restarting the service.", "operationId": "warmupVipCaches", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Warmupvipcaches", "type": "object" } } }, "description": "Successful Response" } }, "summary": "Warm up VIP cache for all tenants (KCC-3436)", "tags": [ "health" ] } }, "/api/v1/huddles/{huddle_id}/advanced-audio/session": { "post": { "operationId": "createHuddleAdvancedAudioSession", "parameters": [ { "in": "path", "name": "huddle_id", "required": true, "schema": { "format": "uuid", "title": "Huddle Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdvancedAudioSessionRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdvancedAudioSessionResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Mint a short-lived advanced noise suppression credential", "tags": [ "huddles" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/huddles/{huddle_id}/advanced-audio/session/renew": { "post": { "operationId": "renewHuddleAdvancedAudioSession", "parameters": [ { "in": "path", "name": "huddle_id", "required": true, "schema": { "format": "uuid", "title": "Huddle Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdvancedAudioSessionRenewRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdvancedAudioSessionResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Rotate an advanced noise suppression credential before it expires", "tags": [ "huddles" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/identity/resolve": { "post": { "description": "Resolve a value to its identity record.\n\nPriority order: bare/typed UUID → date → short ID → project shortcode →\nexact project name. Case-insensitive code/name matches are member-visible.\nFailure returns 422 with structured ``reason`` and ``hint``; ambiguity\nincludes visible ``candidates`` (at most 20) and ``has_more``. A cut-short\ntyped ID resolves only to the one visible item it starts (TIDY-19705). No\nfuzzy matching or implicit default project.\n\nTIDY-19687: an employee that may read its owner's project resolves that\nproject's shortcode or name too, through the same delegation the project's\nown detail read applies — the two forms of one reference cannot disagree.", "operationId": "resolveIdentity", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResolveRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResolveResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Resolve any identifier form to typed UUID + display info", "tags": [ "identity" ] } }, "/api/v1/identity/resolve-name": { "post": { "description": "Resolve a bare name to the recency-best page, disclosing alternatives.\n\nAmbiguity is never an error: multiple matches → 200 with ``ambiguous: true``\nand a populated ``alternatives`` list. Zero matches → 200 with\n``resolved: null`` (the caller decides whether to create, R13). Candidates\nare gated by the member-visible predicate, so another member's private page\nnever appears.", "operationId": "resolveIdentityByName", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResolveNameRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResolveNameResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Resolve a bare page name to the best-match page + alternatives", "tags": [ "identity" ] } }, "/api/v1/images/generate": { "post": { "description": "Generate an icon/banner from the page's content, store it (F6), record\nusage (R20), and enforce the per-user monthly quota (R22/D6).", "operationId": "generateImage", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerateImageRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerateImageResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Generate an AI image and store it in My Files", "tags": [ "images" ], "x-mcp-skip": true } }, "/api/v1/images/quota": { "get": { "description": "Return the caller's image-gen usage vs cap this month (R21/R22). Reads\nthe same source as the pre-check (Plan-D1). Admin → unlimited.", "operationId": "getImageQuota", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImageQuotaResponse" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Per-user image-generation quota status", "tags": [ "images" ], "x-mcp-skip": true } }, "/api/v1/import/evernote": { "post": { "operationId": "importEvernote", "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/Body_importEvernote" } } }, "required": true }, "responses": { "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportCreateResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Import Evernote", "tags": [ "import", "import" ] } }, "/api/v1/import/ics": { "post": { "operationId": "importIcs", "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/Body_importIcs" } } }, "required": true }, "responses": { "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportCreateResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Import Ics", "tags": [ "import", "import" ] } }, "/api/v1/import/mbox": { "post": { "operationId": "importMbox", "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/Body_importMbox" } } }, "required": true }, "responses": { "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportCreateResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Import Mbox", "tags": [ "import", "import" ] } }, "/api/v1/import/notion": { "post": { "operationId": "importNotion", "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/Body_importNotion" } } }, "required": true }, "responses": { "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportCreateResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Import Notion", "tags": [ "import", "import" ] } }, "/api/v1/import/vcf": { "post": { "operationId": "importVcf", "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/Body_importVcf" } } }, "required": true }, "responses": { "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportCreateResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Import Vcf", "tags": [ "import", "import" ] } }, "/api/v1/import/{job_id}": { "get": { "operationId": "getDataImportJob", "parameters": [ { "in": "path", "name": "job_id", "required": true, "schema": { "title": "Job Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataImportJob" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Get Import Status", "tags": [ "import", "import" ] } }, "/api/v1/import/{job_id}/cancel": { "post": { "operationId": "cancelImport", "parameters": [ { "in": "path", "name": "job_id", "required": true, "schema": { "title": "Job Id", "type": "string" } } ], "responses": { "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportCreateResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Cancel Import", "tags": [ "import", "import" ] } }, "/api/v1/import/{job_id}/confirm": { "post": { "operationId": "confirmImport", "parameters": [ { "in": "path", "name": "job_id", "required": true, "schema": { "title": "Job Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportConfirmRequest" } } }, "required": true }, "responses": { "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportCreateResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Confirm Import", "tags": [ "import", "import" ] } }, "/api/v1/inbox/labels": { "get": { "description": "List all inbox labels for the current tenant with email counts.", "operationId": "listLabels", "parameters": [ { "description": "Include inactive labels", "in": "query", "name": "include_inactive", "required": false, "schema": { "default": false, "description": "Include inactive labels", "title": "Include Inactive", "type": "boolean" } }, { "description": "Filter by type: system, user, extracted", "in": "query", "name": "label_type", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by type: system, user, extracted", "title": "Label Type" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LabelListResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List inbox labels", "tags": [ "inbox-labels", "Inbox Labels" ] }, "post": { "description": "Create a new custom inbox label.", "operationId": "createLabel", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LabelCreate" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LabelResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Create label", "tags": [ "inbox-labels", "Inbox Labels" ] } }, "/api/v1/inbox/labels/colors": { "get": { "description": "Return the curated color palette for label selection.", "operationId": "getColorPalette", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ColorPaletteResponse" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get color palette", "tags": [ "inbox-labels", "Inbox Labels" ] } }, "/api/v1/inbox/labels/{label_id}": { "delete": { "description": "Delete a custom inbox label. System labels cannot be deleted.", "operationId": "deleteLabel", "parameters": [ { "in": "path", "name": "label_id", "required": true, "schema": { "format": "uuid", "title": "Label Id", "type": "string" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Delete label", "tags": [ "inbox-labels", "Inbox Labels" ] }, "get": { "description": "Get details for a specific inbox label.", "operationId": "getLabel", "parameters": [ { "in": "path", "name": "label_id", "required": true, "schema": { "format": "uuid", "title": "Label Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LabelResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get label details", "tags": [ "inbox-labels", "Inbox Labels" ] }, "patch": { "description": "Update an inbox label's settings.", "operationId": "updateLabel", "parameters": [ { "in": "path", "name": "label_id", "required": true, "schema": { "format": "uuid", "title": "Label Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LabelUpdate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LabelResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Update label", "tags": [ "inbox-labels", "Inbox Labels" ] } }, "/api/v1/insights/seed": { "post": { "description": "Seed/merge a user-authored belief into the SINGLE living Insights facet.\n\nTIDY-12175 / S3 — the local-first seed CREATE for a ``note_kind='insight'``\nrow cannot go through the public ``NoteCreate`` API (insight rows are\nserver-side-only, owned by ``InsightFacetWriter`` per the repository-pattern\nrule). The sync-batch routes a user-seeded insight CREATE here instead.\n\nThis is a SUBSTRATE write authored by the human principal (the user typing\ntheir own belief), so the owner is the principal (``account_id``) and the\nwrite goes through ``InsightFacetWriter.upsert_living_facet`` — never\nhand-set owner_id, never an agent owner. The belief is merged into the one\nliving facet (append-or-create): the Dreamer (S2) reads it back as the belief\nlayer on its next run. Private by default (the user can promote later).", "operationId": "seedInsightFacet", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InsightSeedRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InsightSeedResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Seed Insight Facet", "tags": [ "insights", "insights" ], "x-mcp-skip": true } }, "/api/v1/insights/{facet_id}/demote": { "post": { "description": "Demote a single Insight Facet's visibility (global -> shared/private).\n\nOwner-only (403 ``not_facet_owner`` otherwise, unless tenant owner). The\nwrite routes through ``InsightFacetWriter`` and is audit-logged.", "operationId": "demoteInsightFacet", "parameters": [ { "description": "Insight Facet (note) id to demote", "in": "path", "name": "facet_id", "required": true, "schema": { "description": "Insight Facet (note) id to demote", "title": "Facet Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FacetDemoteRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FacetVisibilityResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Demote Insight Facet", "tags": [ "insights", "insights" ] } }, "/api/v1/insights/{facet_id}/promote": { "post": { "description": "Promote a single Insight Facet's visibility (private -> shared/global).\n\nEnforces owner-only + derivation-source floor (D11) + target-entity floor\nBEFORE the write; rejects with 403 + a machine error code on each. The write\nroutes through ``InsightFacetWriter`` and is audit-logged.", "operationId": "promoteInsightFacet", "parameters": [ { "description": "Insight Facet (note) id to promote", "in": "path", "name": "facet_id", "required": true, "schema": { "description": "Insight Facet (note) id to promote", "title": "Facet Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FacetPromoteRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FacetVisibilityResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Promote Insight Facet", "tags": [ "insights", "insights" ] } }, "/api/v1/integrations/github": { "delete": { "description": "Soft-delete one of the tenant's connections.\n\nThis removes TIDY's side only. The App installation still exists on GitHub\nuntil the user removes it there — we deliberately do not call GitHub's\ndelete-installation endpoint, because doing so would silently revoke an\nintegration the user may also be using outside Tidy.\n\n``plugin_id`` names the account (TIDY-19699). It may be omitted only when\nthe workspace has one: disconnecting \"GitHub\" while several accounts are\nconnected would have to guess which, so it is refused instead.", "operationId": "deleteGitHubConnection", "parameters": [ { "in": "query", "name": "plugin_id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Plugin Id" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Disconnect GitHub", "tags": [ "integrations" ], "x-local-capability": "cloud", "x-mcp-skip": true }, "get": { "description": "Report the connection as it really is.\n\nNever infers \"connected\" from a row existing — `status` and\n`last_verified_at` come from what GitHub last told us.", "operationId": "getGitHubConnection", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GitHubConnectionResponse" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Read the tenant's GitHub App connection state", "tags": [ "integrations" ], "x-local-capability": "cloud" } }, "/api/v1/integrations/github/agent-token": { "post": { "description": "Mint a token that reaches ONE repository — the VE git credential path.\n\nTIDY-17032. The credential helper on the VE learns which repository git is\ntalking to from the credential protocol (`useHttpPath=true` makes git send\nthe path) and names it here. The token GitHub returns is scoped to it, so a\nVE pushing to one repository never holds a credential for the rest of the\ninstallation for the hour that token lives.\n\nRepository context is REQUIRED, and that is the security property rather\nthan an input-validation detail: if a missing `repository` fell back to an\ninstallation-wide mint, every helper bug, every un-upgraded install and\nevery caller that simply omitted the field would silently widen the token\nback to the whole tenant — and would do so invisibly, because the wide\ntoken works. So a context-free request is refused, loudly, here.", "operationId": "mintGitHubAgentToken", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GitHubAgentTokenRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GitHubInstallationTokenResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Mint a GitHub token bounded to one repository, for a VE's git operations", "tags": [ "integrations" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/integrations/github/install-outcome": { "get": { "description": "Tell a silent failure from a slow one (TIDY-19102).\n\nOn 2026-09-20 a connect started on dev1 completed GitHub's install UI and\nlanded on the production apex — a marketing page that answers HTTP 200. The\nmember saw a normal page; Tidy never heard; the installation existed on\nGitHub with no row here. Nothing in the product said anything was wrong.\n\nThe state Tidy minted is the evidence. The callback consumes it, so a state\nthat is still live after the member has come back means the ceremony did\nnot return to THIS environment — which is the App's registered callback\nlist, and not something the server can fix by pinning `redirect_uri` harder\n(it already does). So the answer carries this environment's exact callback\nURL, and the surface can name what has to be added rather than showing a\nconnection that silently is not one.\n\nRead-only and single-use-preserving: the state is PEEKED, never popped, so\nasking cannot break a flow that is genuinely still in flight. Scoped to the\nmember who started it — a state minted by someone else, or for another\ntenant, reads as settled rather than confirming that it exists.", "operationId": "getGitHubInstallOutcome", "parameters": [ { "in": "query", "name": "state", "required": true, "schema": { "maxLength": 256, "minLength": 16, "title": "State", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GitHubInstallOutcomeResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Did the install ceremony this state started reach Tidy?", "tags": [ "integrations" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/integrations/github/install-url": { "post": { "description": "Mint one-shot state and hand back GitHub's install URL.\n\nState carries the tenant/account so the callback — which arrives WITHOUT a\nTidy session cookie (it is a top-level redirect from github.com) — can\nattribute the installation. Same mechanism the Google/Microsoft flows use.", "operationId": "createGitHubInstallUrl", "parameters": [ { "in": "query", "name": "return_to", "required": false, "schema": { "default": "/automations/plugins?connect=github", "title": "Return To", "type": "string" } }, { "in": "query", "name": "install", "required": false, "schema": { "default": false, "title": "Install", "type": "boolean" } }, { "in": "query", "name": "desktop", "required": false, "schema": { "default": false, "title": "Desktop", "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GitHubInstallUrlResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Begin connecting GitHub — returns the install URL", "tags": [ "integrations" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/integrations/github/pending-installations": { "get": { "description": "Render the choice (TIDY-18055). Reads without consuming the token.", "operationId": "getGitHubPendingInstallations", "parameters": [ { "in": "query", "name": "choice", "required": true, "schema": { "title": "Choice", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GitHubPendingInstallationsResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "The installations a connect left for the person to choose from", "tags": [ "integrations" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/integrations/github/repositories": { "get": { "description": "Read every usable account's repositories live, and say where it may create.\n\nDeliberately uncached and deliberately paginated to exhaustion. A picker\nthat hides a repository the user just granted is indistinguishable, to\nthem, from Tidy having lost their grant.\n\nTIDY-19699 — one list across every connected account the caller may use.\nAn account the gate refuses, or GitHub fails for, is reported on its\n``accounts`` entry rather than silently left out; only when no account can\nbe read does the request fail, with that account's own refusal.", "operationId": "listGitHubRepositories", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GitHubRepositoryListResponse" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List the repositories this tenant's GitHub installation can reach", "tags": [ "integrations" ], "x-local-capability": "cloud", "x-mcp-skip": true }, "post": { "description": "The new-user path: one button, a usable repository at the end of it.\n\nThe permission is re-checked against a FRESH mint inside the service call,\nnot against whatever the picker read a minute ago — an org that turned off\napp repository creation in between must refuse here, in its own words.", "operationId": "createGitHubRepository", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GitHubCreateRepositoryRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GitHubRepository" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Create a repository through the tenant's GitHub App installation", "tags": [ "integrations" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/integrations/github/repositories/{owner}/{repo}/branches": { "get": { "description": "Live branch list for the binding picker.", "operationId": "listGitHubBranches", "parameters": [ { "in": "path", "name": "owner", "required": true, "schema": { "title": "Owner", "type": "string" } }, { "in": "path", "name": "repo", "required": true, "schema": { "title": "Repo", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GitHubBranchListResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List a repository's branches", "tags": [ "integrations" ], "x-local-capability": "cloud", "x-mcp-skip": true }, "post": { "description": "Create the branch the picker offered, on GitHub, before anything clones.\n\nCreating it remotely rather than on the host is what makes the picker's\n\"create branch\" honest for a repository the VE has not cloned yet: the\nbranch exists the moment the user chooses it, and the clone/worktree jobs\nthat follow simply check it out.", "operationId": "createGitHubBranch", "parameters": [ { "in": "path", "name": "owner", "required": true, "schema": { "title": "Owner", "type": "string" } }, { "in": "path", "name": "repo", "required": true, "schema": { "title": "Repo", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GitHubCreateBranchRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GitHubBranch" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Create a branch from an existing ref", "tags": [ "integrations" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/integrations/github/select-installation": { "post": { "description": "The choosing half of the connect flow (TIDY-18055).\n\nThe candidate list was built from the person's OWN token at callback time,\nso a selection outside it is a forged request, not a typo. The choice token\nis consumed here — one selection per authorization — and only by the\nprincipal it was stashed for: the Redis key carries tenant + member (review\nF7), so another member's POST consumes nothing.", "operationId": "selectGitHubInstallation", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GitHubSelectInstallationRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GitHubConnectionResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Bind one of the pending installations to this workspace", "tags": [ "integrations" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/integrations/github/token": { "post": { "description": "Mint an installation access token for one of the tenant's connections.\n\nThe UNBOUNDED mint: the token reaches every repository the installation\nselected. It is what `gh` needs — a `gh pr list` or `gh api` names no\nrepository the way a git remote does, so there is no path to bound from.\nGit's own operations use ``/agent-token`` below, which is bounded to the one\nrepository git named.\n\nTIDY-19699 — WHICH installation: the one owning ``body.repository`` when\nthe caller names it (the gh wrapper does, from ``-R``/``GH_REPO``/the\nclone's origin), otherwise the caller's only account. With several and no\nrepository the gate refuses by name rather than picking one; a body-less\nrequest from an older connector keeps working wherever it is unambiguous.\n\nNothing is cached and nothing is stored: the token lives ~1h, and a helper\nthat re-mints is strictly safer than a file on the host holding a credential\nwith a shelf life nobody is watching.\n\nA revoked or missing connection fails LOUD (409/404) rather than returning\nan empty token — a credential-less \"success\" surfaces as an unexplained\n`git push` 403 on the user's machine three steps later.", "operationId": "mintGitHubInstallationToken", "requestBody": { "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/GitHubInstallationTokenRequest" }, { "type": "null" } ], "title": "Body" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GitHubInstallationTokenResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Mint a short-lived GitHub token for this caller's git operations", "tags": [ "integrations" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/integrations/github/verify": { "post": { "description": "Probe GitHub and persist what it says — for one account, or every one.\n\nWith webhooks off for v1 we never receive ``installation.deleted``, so an\nuninstall is invisible until something asks. This is that ask — and it\nrecords `error`/`revoked` rather than leaving a stale `active` behind.\n\n``plugin_id`` re-checks that account; omitted, every connected account is\nre-checked (TIDY-19699), each against its own connector's sign-in.", "operationId": "verifyGitHubConnection", "parameters": [ { "in": "query", "name": "plugin_id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Plugin Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GitHubConnectionResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Re-check the connection against GitHub", "tags": [ "integrations" ], "x-local-capability": "cloud" } }, "/api/v1/integrations/gitlab": { "delete": { "description": "Tidy-side disconnect of one account: vault entries die, the row soft-deletes.", "operationId": "deleteGitLabConnection", "parameters": [ { "in": "query", "name": "connection_id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Connection Id" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Disconnect GitLab (vault secrets removed)", "tags": [ "integrations" ], "x-local-capability": "cloud", "x-mcp-skip": true }, "get": { "description": "Report every connection as it really is.\n\nNever infers \"connected\" from a row existing — `status` and\n`last_verified_at` come from what the instance last told us.", "operationId": "getGitLabConnection", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GitLabConnectionResponse" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Read the tenant's GitLab connection state", "tags": [ "integrations" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/integrations/gitlab/agent-token": { "post": { "description": "The VE git credential path (the GitLab sibling of GitHub's /agent-token).\n\nRepository context is REQUIRED — a missing bound silently widening back to\nthe tenant's whole grant would be invisible, because the wide credential\nworks. Consent is checked BEFORE any tenant state is read, in the same\norder as GitHub's mint, so a declined employee cannot probe for a\nconnection at all.", "operationId": "mintGitLabAgentToken", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GitLabAgentTokenRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GitLabAgentTokenResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Mint a per-op git credential bounded to one project, for a VE's git operations", "tags": [ "integrations" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/integrations/gitlab/start": { "post": { "description": "Record the pending binding and hand back the instance's authorize URL.\n\nThe base URL is normalized and persisted NOW so the callback — which is\nunauthenticated except for the state — can derive every URL from the same\norigin the user saw when they started.", "operationId": "startGitLabConnect", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GitLabStartRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GitLabStartResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Begin the OAuth connect flow against an instance", "tags": [ "integrations" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/integrations/gitlab/token": { "post": { "description": "The Advanced lane: verify a pasted token LIVE before trusting it.\n\nA token that fails `/user` still lands as `error` with the instance's own\nverdict recorded — a row that renders connected but has never worked is\nexactly the TIDY-16297 failure this route exists to prevent.", "operationId": "submitGitLabProjectToken", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GitLabTokenRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GitLabTokenResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Connect by pasting a project/group access token (Advanced)", "tags": [ "integrations" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/integrations/gitlab/verify": { "post": { "operationId": "verifyGitLabConnection", "parameters": [ { "in": "query", "name": "connection_id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Connection Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GitLabVerifyResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Re-probe the instance and record the honest outcome", "tags": [ "integrations" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/integrations/gitlab/webhook-secret": { "post": { "description": "Generate, vault, and return the secret the user pastes into GitLab.\n\nThe old secret dies with this call: the receiver verifies against the\nvault, so an instance still holding the previous value fails verification\nuntil its webhook form is updated — rotation is honest about that.", "operationId": "rotateGitLabWebhookSecret", "parameters": [ { "in": "query", "name": "connection_id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Connection Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GitLabWebhookSecretResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Rotate the per-connection webhook secret (shown once)", "tags": [ "integrations" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/integrations/trmnl/complete-install": { "post": { "description": "Consent-Allow: exchange the TRMNL code and create the link + default instance.\n\nOrder matters: state is consumed and the code exchanged BEFORE any row is\nwritten, so an exchange failure (502) leaves zero rows.", "operationId": "trmnlCompleteInstall", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompleteInstallRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompleteInstallResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Trmnl Complete Install", "tags": [ "integrations-trmnl", "integrations-trmnl" ], "x-mcp-skip": true } }, "/api/v1/integrations/trmnl/install": { "get": { "description": "Browser landing from TRMNL's Install button.\n\nPacks the single-use ``code`` + callback into a short-lived state token and\nbounces to the web consent route. NO token exchange here — the exchange\nhappens on Allow, so a canceled consent leaves nothing behind.", "operationId": "trmnlInstallRedirect", "parameters": [ { "in": "query", "name": "code", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Code" } }, { "in": "query", "name": "installation_callback_url", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Installation Callback Url" } } ], "responses": { "302": { "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Trmnl Install", "tags": [ "integrations-trmnl", "integrations-trmnl" ], "x-mcp-skip": true } }, "/api/v1/integrations/trmnl/instances": { "get": { "description": "Management-page read: instance + link summary keyed by TRMNL uuid.", "operationId": "trmnlGetInstance", "parameters": [ { "in": "query", "name": "uuid", "required": true, "schema": { "title": "Uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InstanceSummary" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Trmnl Get Instance", "tags": [ "integrations-trmnl", "integrations-trmnl" ], "x-mcp-skip": true } }, "/api/v1/integrations/trmnl/instances/{instance_id}": { "patch": { "description": "Update an instance's screen_type/config. Rejects an ungranted screen (422).", "operationId": "trmnlPatchInstance", "parameters": [ { "in": "path", "name": "instance_id", "required": true, "schema": { "title": "Instance Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatchInstanceRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InstanceSummary" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Trmnl Patch Instance", "tags": [ "integrations-trmnl", "integrations-trmnl" ], "x-mcp-skip": true } }, "/api/v1/integrations/trmnl/links": { "get": { "description": "List the caller's live links (with instances) in the active tenant (R12).", "operationId": "trmnlListLinks", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListLinksResponse" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Trmnl List Links", "tags": [ "integrations-trmnl", "integrations-trmnl" ], "x-mcp-skip": true } }, "/api/v1/integrations/trmnl/links/{link_id}": { "delete": { "description": "Revoke a link from Tidy settings: subsequent TRMNL bearer calls get 401 (R12).", "operationId": "trmnlRevokeLink", "parameters": [ { "in": "path", "name": "link_id", "required": true, "schema": { "title": "Link Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevokeLinkResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Trmnl Revoke Link", "tags": [ "integrations-trmnl", "integrations-trmnl" ], "x-mcp-skip": true } }, "/api/v1/integrations/trmnl/markup": { "post": { "description": "TRMNL device poll (D5, reads only): serve the four markup variants.\n\nAuthenticated by the TRMNL-issued Bearer token (hash lookup, NOT Tidy auth).\nA poll never triggers computation — it projects already-computed content. The\nonly writes are ``last_served_at`` and a one-time auto-create for a new uuid.", "operationId": "trmnlMarkup", "parameters": [ { "in": "header", "name": "Authorization", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Authorization" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarkupResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Trmnl Markup", "tags": [ "integrations-trmnl", "integrations-trmnl" ], "x-mcp-skip": true } }, "/api/v1/integrations/trmnl/webhooks/install-success": { "post": { "description": "TRMNL confirms an install: persist the user object and key the instance.", "operationId": "trmnlInstallSuccessWebhook", "parameters": [ { "in": "header", "name": "Authorization", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Authorization" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InstallSuccessRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookOkResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Trmnl Install Success", "tags": [ "integrations-trmnl", "integrations-trmnl" ], "x-mcp-skip": true } }, "/api/v1/integrations/trmnl/webhooks/uninstall": { "post": { "description": "TRMNL uninstall: soft-delete the instance; revoke the link if it was the last.", "operationId": "trmnlUninstallWebhook", "parameters": [ { "in": "header", "name": "Authorization", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Authorization" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_service__routers__trmnl__UninstallRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookOkResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Trmnl Uninstall", "tags": [ "integrations-trmnl", "integrations-trmnl" ], "x-mcp-skip": true } }, "/api/v1/integrations/{connection_id}/header-backfill-continue": { "post": { "description": "Owner-only retry; shares the worker lock, preserves completed folders/cursors.", "operationId": "continueHeaderBackfill", "parameters": [ { "in": "path", "name": "connection_id", "required": true, "schema": { "format": "uuid", "title": "Connection Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContinueHeaderBackfillResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Continue loading unfinished email history", "tags": [ "integrations", "integrations" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/integrations/{connection_id}/header-backfill-status": { "get": { "description": "Return per-folder header-backfill progress for one email\nintegration. 404 when the connection doesn't exist OR belongs to\nanother tenant — tenant scoping is enforced inside the SELECT.", "operationId": "getHeaderBackfillStatus", "parameters": [ { "description": "plugin_mail_state.id", "in": "path", "name": "connection_id", "required": true, "schema": { "description": "plugin_mail_state.id", "title": "Connection Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HeaderBackfillStatusResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Per-folder header-backfill progress for one email connection", "tags": [ "integrations", "integrations" ] } }, "/api/v1/internal/agent-runtime-artifacts/api-contract": { "get": { "description": "Release-time proof of what THIS API serves, read before a connector release\nis promoted to it (TIDY-19569). The served OpenAPI is session-gated at the\nedge, so the publisher's own key reads this instead. The caller's nonce is\nechoed so a cached or replayed answer cannot stand in for a live one; an API\nthat predates this route answers 405, which a promotion must treat as refusal.\nRead-only: no row, no value, no agent data.", "operationId": "getAgentRuntimeApiContract", "parameters": [ { "in": "query", "name": "nonce", "required": true, "schema": { "pattern": "^[A-Za-z0-9_-]{16,128}$", "title": "Nonce", "type": "string" } }, { "in": "header", "name": "x-internal-service", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service" } }, { "in": "header", "name": "x-internal-service-key", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service-Key" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentRuntimeApiContractResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Get Agent Runtime Api Contract", "tags": [ "agent-runtime" ], "x-mcp-skip": true } }, "/api/v1/internal/agent-runtime-artifacts/assemble-candidate": { "post": { "description": "Reassemble ordered staging parts into the immutable candidate object.\n\nParts that were PUT one at a time (because a proxy refused the whole body)\nare concatenated in the given order and written through the ordinary\ncandidate ``put``, so canonical-path, create-only, digest and scope\ninvariants all still run in exactly one place. A size or digest mismatch\nfails before any candidate row is written. On success the parts are removed\nso staging cannot accumulate; on failure they are left for a retried\nassemble or the existing retention prune (which drops a candidate namespace\nonce it predates the retained window) — never the row-less reconcile sweep,\nwhich correctly refuses to touch a path that has a row.", "operationId": "assembleAgentRuntimeCandidate", "parameters": [ { "in": "header", "name": "x-internal-service", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service" } }, { "in": "header", "name": "x-internal-service-key", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service-Key" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssembleCandidateRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ArtifactResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Assemble Agent Runtime Candidate", "tags": [ "agent-runtime" ], "x-mcp-skip": true } }, "/api/v1/internal/agent-runtime-artifacts/candidate-grants": { "post": { "operationId": "createAgentRuntimeCandidateGrant", "parameters": [ { "in": "header", "name": "x-internal-service", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service" } }, { "in": "header", "name": "x-internal-service-key", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service-Key" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CandidateGrantRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CandidateGrantResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Create Candidate Grant", "tags": [ "agent-runtime" ], "x-mcp-skip": true } }, "/api/v1/internal/agent-runtime-artifacts/promotions": { "post": { "operationId": "promoteAgentRuntimeArtifact", "parameters": [ { "in": "header", "name": "x-internal-service", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service" } }, { "in": "header", "name": "x-internal-service-key", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service-Key" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PromotionRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActivationResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Promote Agent Runtime Artifact", "tags": [ "agent-runtime" ], "x-mcp-skip": true } }, "/api/v1/internal/agent-runtime-artifacts/prune": { "post": { "description": "Drop superseded releases and their candidate namespaces, rows and objects\ntogether. The plan is always computed here — a caller names versions, never\npaths — so the refusals cannot be talked past by a stale client-side plan.", "operationId": "pruneAgentRuntimeReleases", "parameters": [ { "in": "header", "name": "x-internal-service", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service" } }, { "in": "header", "name": "x-internal-service-key", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service-Key" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PruneRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PruneResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Prune Agent Runtime Releases", "tags": [ "agent-runtime" ], "x-mcp-skip": true } }, "/api/v1/internal/agent-runtime-artifacts/reconcile": { "post": { "description": "Reclaim objects that have no `agent_runtime_artifacts` row — the residue the\nrow-driven prune cannot see. Path-driven, but never touching a path that has a\nrow, and the diff is always recomputed here from a live listing.", "operationId": "reconcileAgentRuntimeObjects", "parameters": [ { "in": "header", "name": "x-internal-service", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service" } }, { "in": "header", "name": "x-internal-service-key", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service-Key" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReconcileRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReconcileResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Reconcile Agent Runtime Objects", "tags": [ "agent-runtime" ], "x-mcp-skip": true } }, "/api/v1/internal/agent-runtime-artifacts/{path}": { "put": { "operationId": "putAgentRuntimeArtifact", "parameters": [ { "in": "path", "name": "path", "required": true, "schema": { "title": "Path", "type": "string" } }, { "in": "header", "name": "x-artifact-size", "required": true, "schema": { "minimum": 0, "title": "X-Artifact-Size", "type": "integer" } }, { "in": "header", "name": "x-artifact-sha256", "required": true, "schema": { "pattern": "^[0-9a-f]{64}$", "title": "X-Artifact-Sha256", "type": "string" } }, { "in": "header", "name": "x-internal-service", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service" } }, { "in": "header", "name": "x-internal-service-key", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service-Key" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ArtifactResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Put Agent Runtime Artifact", "tags": [ "agent-runtime" ], "x-mcp-skip": true } }, "/api/v1/internal/agents/approval-grants": { "post": { "description": "TIDY-16675 — assistant-service's /resolve mints the LIVE-path grant here.\n\nDelegates to the same ``record_grant`` the connector's endpoint uses, so\nstanding-allowed, membership binding, degrade refusals, idempotency and the\naudit trail have exactly one owner. A duplicate ``request_id`` (the resume\npath already minted this ask) answers with the existing grant.", "operationId": "internalRecordAgentApprovalGrant", "parameters": [ { "in": "header", "name": "X-Internal-Service-Key", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service-Key" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalRecordGrantRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalGrant" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Mint a live-path approval grant on behalf of the authenticated resolver", "tags": [ "agents", "internal" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Virtual-employee authorization surface for the settings UI and the local connector — never an assistant-callable tool." } }, "/api/v1/internal/audit/record": { "post": { "operationId": "internalRecordAuditEntry", "parameters": [ { "in": "header", "name": "X-Internal-Service-Key", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service-Key" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuditRecordRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuditRecordResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Record Audit Entry", "tags": [ "internal-audit", "internal-audit" ] } }, "/api/v1/internal/browser-relay/clients/attach": { "post": { "operationId": "attachBrowserRelayClient", "parameters": [ { "in": "header", "name": "X-Internal-Service-Key", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service-Key" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrowserRelayAttachRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrowserRelayAuthorityResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Attach Client", "tags": [ "browser-relay" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Browser control transport and configured actions; harness tools are a separate contract." } }, "/api/v1/internal/browser-relay/clients/file-transfer": { "post": { "operationId": "authorizeBrowserFileTransfer", "parameters": [ { "in": "header", "name": "X-Internal-Service-Key", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service-Key" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrowserFileTransferRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrowserRelayAuthorityResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Authorize Transfer", "tags": [ "browser-controller" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Browser control transport and configured actions; harness tools are a separate contract." } }, "/api/v1/internal/browser-relay/clients/mode": { "post": { "operationId": "requestBrowserRelayMode", "parameters": [ { "in": "header", "name": "X-Internal-Service-Key", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service-Key" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrowserRelayModeRequest" } } }, "required": true }, "responses": { "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrowserRelayModeResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Request Mode", "tags": [ "browser-relay" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Browser control transport and configured actions; harness tools are a separate contract." } }, "/api/v1/internal/browser-relay/clients/pause": { "post": { "operationId": "pauseBrowserRelayClient", "parameters": [ { "in": "header", "name": "X-Internal-Service-Key", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service-Key" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrowserRelayPauseRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrowserSessionResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Pause Client", "tags": [ "browser-relay" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Browser control transport and configured actions; harness tools are a separate contract." } }, "/api/v1/internal/browser-relay/clients/refresh": { "post": { "operationId": "refreshBrowserRelayClient", "parameters": [ { "in": "header", "name": "X-Internal-Service-Key", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service-Key" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrowserRelayRefreshRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrowserRelayAuthorityResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Refresh Client", "tags": [ "browser-relay" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Browser control transport and configured actions; harness tools are a separate contract." } }, "/api/v1/internal/browser-relay/controllers/attach": { "post": { "operationId": "attachBrowserRelayController", "parameters": [ { "in": "header", "name": "X-Internal-Service-Key", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service-Key" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrowserRelayControllerAttachRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrowserRelayControllerResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Attach Controller", "tags": [ "browser-relay" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Browser control transport and configured actions; harness tools are a separate contract." } }, "/api/v1/internal/browser-relay/egress/devices/attach": { "post": { "operationId": "attachBrowserEgressDevice", "parameters": [ { "in": "header", "name": "X-Internal-Service-Key", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service-Key" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrowserEgressDeviceAttachRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrowserEgressDeviceLinkResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Attach Egress Device", "tags": [ "browser-relay" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Browser control transport and configured actions; harness tools are a separate contract." } }, "/api/v1/internal/browser-relay/egress/devices/check": { "post": { "operationId": "checkBrowserEgressDevice", "parameters": [ { "in": "header", "name": "X-Internal-Service-Key", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service-Key" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrowserEgressDeviceCheckRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrowserEgressDeviceLinkResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Check Egress Device", "tags": [ "browser-relay" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Browser control transport and configured actions; harness tools are a separate contract." } }, "/api/v1/internal/browser-relay/egress/sessions/attach": { "post": { "operationId": "attachBrowserEgressSession", "parameters": [ { "in": "header", "name": "X-Internal-Service-Key", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service-Key" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrowserEgressSessionAttachRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrowserEgressSessionBinding-Output" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Attach Egress Session", "tags": [ "browser-relay" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Browser control transport and configured actions; harness tools are a separate contract." } }, "/api/v1/internal/browser-relay/egress/sessions/check": { "post": { "operationId": "checkBrowserEgressSession", "parameters": [ { "in": "header", "name": "X-Internal-Service-Key", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service-Key" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrowserEgressSessionCheckRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrowserEgressSessionBinding-Output" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Check Egress Session", "tags": [ "browser-relay" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Browser control transport and configured actions; harness tools are a separate contract." } }, "/api/v1/internal/calendar/shield-decline": { "post": { "description": "Decline the invite via the shared invite-response path (never deletes it).", "operationId": "internalCalendarShieldDecline", "parameters": [ { "in": "header", "name": "X-Internal-Service-Key", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service-Key" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShieldDeclineRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShieldDeclineResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Auto-decline a calendar invite for a Shield Generator rule", "tags": [ "internal", "internal" ] } }, "/api/v1/internal/campaigns/render-recipient": { "post": { "description": "Render the campaign template for ONE snapshotted recipient row.", "operationId": "render_recipient_api_v1_internal_campaigns_render_recipient_post", "parameters": [ { "in": "header", "name": "X-Internal-Service", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service" } }, { "in": "header", "name": "X-Internal-Service-Key", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service-Key" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RenderRecipientRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Render Recipient Api V1 Internal Campaigns Render Recipient Post", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Render Recipient", "tags": [ "internal-campaigns", "internal-campaigns" ] } }, "/api/v1/internal/channel-ingress/deliver-pending": { "post": { "operationId": "internalChannelIngressDeliverPending", "parameters": [ { "in": "header", "name": "X-Internal-Service-Key", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service-Key" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChannelHandoffRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChannelHandoffResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Deliver everything that arrived while a workshop employee was offline", "tags": [ "channel-ingress", "internal" ], "x-mcp-skip": true } }, "/api/v1/internal/channel-ingress/dispatch": { "post": { "operationId": "internalChannelIngressDispatch", "parameters": [ { "in": "header", "name": "X-Internal-Service-Key", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service-Key" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChannelIngressRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChannelIngressResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Route one inbound channel message to its configured employee", "tags": [ "channel-ingress", "internal" ], "x-mcp-skip": true } }, "/api/v1/internal/channel-ingress/reply": { "post": { "description": "Atomic and lossless-by-omission: a lost race claims nothing and says so.\n\nThe tenant is resolved from the conversation rather than trusted from the\ncaller: the conversation id IS the correlation key, and letting a service\nname its own tenant here would make the claim cross-tenant addressable.", "operationId": "internalChannelIngressReply", "parameters": [ { "in": "header", "name": "X-Internal-Service-Key", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service-Key" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChannelReplyRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChannelReplyResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Claim an open ingress item with an employee's reply", "tags": [ "channel-ingress", "internal" ], "x-mcp-skip": true } }, "/api/v1/internal/crm/outbound-trigger": { "post": { "description": "Evaluate one sent email's To/Cc recipients and record CRM proposals.", "operationId": "outbound_trigger_api_v1_internal_crm_outbound_trigger_post", "parameters": [ { "in": "header", "name": "X-Internal-Service", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service" } }, { "in": "header", "name": "X-Internal-Service-Key", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service-Key" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OutboundTriggerRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Outbound Trigger Api V1 Internal Crm Outbound Trigger Post", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Outbound Trigger", "tags": [ "internal-crm", "internal-crm" ] } }, "/api/v1/internal/devices/heartbeat": { "post": { "description": "Re-assert worker liveness and throttled-refresh last_seen (AC-7).\n\n``valid=false`` signals the gateway to drop the worker socket: the device or\nits credential was revoked/expired since connect (AC-1).", "operationId": "internalDeviceHeartbeat", "parameters": [ { "in": "header", "name": "X-Internal-Service", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service" } }, { "in": "header", "name": "X-Internal-Service-Key", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service-Key" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeviceHeartbeatRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeviceHeartbeatResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Heartbeat", "tags": [ "internal-devices", "internal-devices" ] } }, "/api/v1/internal/devices/verify-access-token": { "post": { "description": "Resolve a device access token to a live identity for the gateway.\n\nReturns ``valid=false`` (never raises) for an unknown/expired/revoked token\nso the gateway gets a typed, branch-free answer. A valid response carries\n``offload_consent`` so the gateway can refuse a consent-OFF worker.", "operationId": "internalVerifyDeviceAccessToken", "parameters": [ { "in": "header", "name": "X-Internal-Service", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service" } }, { "in": "header", "name": "X-Internal-Service-Key", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service-Key" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeviceVerifyRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeviceVerifyResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Verify Access Token", "tags": [ "internal-devices", "internal-devices" ] } }, "/api/v1/internal/drawings/{note_id}/regenerate-preview": { "post": { "description": "Change-driven trigger: read the committed scene, render → sanitise → upload.\n\nIdempotent: regenerating from the same persisted scene yields the same\nSVG. The trigger fires per ``drawing_version`` bump; re-firing for the\nsame version is harmless (overwrites the same bytes).", "operationId": "internalRegenerateDrawingPreview", "parameters": [ { "in": "path", "name": "note_id", "required": true, "schema": { "format": "uuid", "title": "Note Id", "type": "string" } }, { "in": "header", "name": "X-Internal-Service-Key", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service-Key" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegeneratePreviewRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegeneratePreviewResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Regenerate a drawing's preview SVG from the authoritative scene", "tags": [ "notes" ] } }, "/api/v1/internal/email-bodies:read": { "post": { "operationId": "internalEmailBodiesRead", "parameters": [ { "in": "header", "name": "X-Internal-Service-Key", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service-Key" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalEmailBodiesRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalEmailBodiesResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Decrypt email_canonical bodies for a cross-service caller", "tags": [ "internal", "internal" ], "x-mcp-skip": true } }, "/api/v1/internal/entitlements/{tenant_id}": { "get": { "description": "Effective entitlements for any tenant (service-to-service callers).", "operationId": "getInternalEntitlements", "parameters": [ { "in": "path", "name": "tenant_id", "required": true, "schema": { "format": "uuid", "title": "Tenant Id", "type": "string" } }, { "in": "header", "name": "X-Internal-Service-Key", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service-Key" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntitlementsResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Get Internal Entitlements", "tags": [ "entitlements", "entitlements" ], "x-mcp-skip": true } }, "/api/v1/internal/entity-match-trigger": { "post": { "description": "Internal endpoint called by pipeline services when a new email arrives.\nChecks contacts against project-linked contacts and creates suggestions.", "operationId": "triggerEntityMatching", "parameters": [ { "in": "header", "name": "x-internal-service", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service" } }, { "in": "header", "name": "x-internal-service-key", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service-Key" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityMatchTriggerRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Triggerentitymatching", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Trigger entity matching for a new email (internal)", "tags": [ "entity-matching" ] } }, "/api/v1/internal/escalations/receipt": { "post": { "description": "Land a delivery receipt on the escalation that sent the message.", "operationId": "recordEscalationReceipt", "parameters": [ { "in": "header", "name": "X-Internal-Service-Key", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service-Key" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EscalationReceiptRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EscalationReceiptResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Correlate an SMS delivery receipt to its escalation", "tags": [ "internal" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/internal/feature-switches/{key}": { "get": { "operationId": "internalEvaluateFeatureSwitch", "parameters": [ { "in": "path", "name": "key", "required": true, "schema": { "title": "Key", "type": "string" } }, { "in": "query", "name": "tenant_id", "required": true, "schema": { "format": "uuid", "title": "Tenant Id", "type": "string" } }, { "in": "header", "name": "X-Internal-Service-Key", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service-Key" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeatureSwitchEvaluation" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Evaluate one feature switch for a tenant through THE seam", "tags": [ "internal", "internal" ], "x-mcp-skip": true } }, "/api/v1/internal/gdpr/pseudonymize-audit": { "post": { "operationId": "internalPseudonymizeAuditActor", "parameters": [ { "in": "header", "name": "X-Internal-Service-Key", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service-Key" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PseudonymizeRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PseudonymizeResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Pseudonymize Audit", "tags": [ "internal-gdpr", "internal-gdpr" ] } }, "/api/v1/internal/hosted-employees/harness-credentials/materialize": { "post": { "description": "assistant-service's equivalent of the connector's materialize call.\n\nThe KEY RING lives here, in api-service, and it stays here: handing\nassistant-service the decryption keys so it could read `ve_credentials`\ndirectly would put every tenant's vault behind a service whose job is to\nrun turns. So the hosted factory asks for exactly one conversation's\ncredentials, by internal service identity, and gets back the same\n`{env_key, value}` shape the connector gets — with the model selection\nalongside, because a key without the lane it pays for is half an answer.", "operationId": "materializeHostedEmployeeCredentials", "parameters": [ { "in": "header", "name": "X-Internal-Service", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service" } }, { "in": "header", "name": "X-Internal-Service-Key", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service-Key" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HostedCredentialRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HostedCredentialResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Materialize a hosted employee's model key for one conversation", "tags": [ "agents", "Agents" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/internal/hosted-employees/tidy-inference-models": { "get": { "description": "TIDY-19215 — the lane list a tidy_inference selection is validated against.\n\nA `tidy/*` model is never host capability: the connector writes and\nauthenticates the lane per turn, so no host catalogue lists it. The\nauthority at turn start is therefore the SAME one the selection write\nasserted against (`assert_published_lane_models`): the delivered key's own\nallowlist, read here so assistant-service never holds the lane key or a\ncopy of the list. A failed read is a named 503 — the caller refuses the\nturn rather than treating \"could not check\" as \"checked\".", "operationId": "listInternalTidyInferenceModels", "parameters": [ { "in": "header", "name": "X-Internal-Service", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service" } }, { "in": "header", "name": "X-Internal-Service-Key", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service-Key" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TidyInferenceLaneModelsResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "The published Tidy inference lanes, for turn-start model validation", "tags": [ "agents", "Agents" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/internal/livekit/webhook": { "post": { "operationId": "receiveLivekitWebhook", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LiveKitWebhookAck" } } }, "description": "Successful Response" } }, "summary": "LiveKit server webhook (track_published → per-track egress)", "tags": [ "internal" ], "x-mcp-skip": true, "x-mcp-skip-reason": "Server-to-server webhook from the LiveKit media server, authenticated by LiveKit's signed-JWT scheme; not an agent workflow." } }, "/api/v1/internal/matrix/assistant-redact": { "post": { "description": "TIDY-19500 F0: the hosted mouth's discard of its own placeholder.\n\n@tidy's own redactions stay on the sync loop's client; a hosted employee's\nplaceholder is the employee's event, which only the employee can redact.", "operationId": "postMatrixAssistantRedactInternal", "parameters": [ { "in": "header", "name": "X-Internal-Service", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service" } }, { "in": "header", "name": "X-Internal-Service-Key", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service-Key" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssistantRedactRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssistantRedactResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Redact a Tidy-compute employee's own event (internal/service only)", "tags": [ "matrix" ], "x-mcp-skip": true } }, "/api/v1/internal/matrix/assistant-send": { "post": { "operationId": "postMatrixAssistantSendInternal", "parameters": [ { "in": "header", "name": "X-Internal-Service", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service" } }, { "in": "header", "name": "X-Internal-Service-Key", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service-Key" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssistantSendRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssistantSendResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Send a room event as the tenant's assistant identity (internal/service only)", "tags": [ "matrix" ], "x-mcp-skip": true } }, "/api/v1/internal/matrix/assistant-thread": { "post": { "description": "TIDY-19370: where the built-in assistant's scheduled runs and wakes happen.\n\nThe assistant principal has no home room; its work for a member runs in\na new session of that member's @tidy chat, with the member's access.", "operationId": "postMatrixAssistantThreadInternal", "parameters": [ { "in": "header", "name": "X-Internal-Service", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service" } }, { "in": "header", "name": "X-Internal-Service-Key", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service-Key" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssistantThreadRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssistantThreadResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Open a session in a member's chat with the Tidy Assistant for its own work (internal/service only)", "tags": [ "matrix" ], "x-mcp-skip": true } }, "/api/v1/internal/matrix/hosted-thread": { "post": { "description": "TIDY-19500 F0: where a hosted scheduled job's runs happen.\n\nConverges the employee's presence (registered identity, home room) — which\nis how an employee created before F0 gets one the first time it works — and\nopens the job's thread in its home room, as a box opens its anchor thread.", "operationId": "postMatrixHostedThreadInternal", "parameters": [ { "in": "header", "name": "X-Internal-Service", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service" } }, { "in": "header", "name": "X-Internal-Service-Key", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service-Key" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HostedThreadRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HostedThreadResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Open a home-room thread for a Tidy-compute employee's work (internal/service only)", "tags": [ "matrix" ], "x-mcp-skip": true } }, "/api/v1/internal/matrix/key-escrow/{account_id}": { "get": { "operationId": "getMatrixKeyEscrowInternal", "parameters": [ { "in": "path", "name": "account_id", "required": true, "schema": { "title": "Account Id", "type": "string" } }, { "in": "header", "name": "X-Internal-Service", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service" } }, { "in": "header", "name": "X-Internal-Service-Key", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service-Key" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KeyEscrowMaterialResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Fetch a member's escrowed recovery key (internal/service only)", "tags": [ "matrix" ], "x-mcp-skip": true } }, "/api/v1/internal/matrix/room-keys/{account_id}": { "get": { "description": "Recover one room's megolm session keys from a member's key backup.\n\nThreat T8: re-checks ``assistant_chat_decrypt_enabled`` for the target\ntenant on EVERY call (never cached). The recovery key + member Matrix token\nstay inside api-service; only the backups-scoped private key + encrypted\nsession blobs leave. Audited as ``actor_type=service``.", "operationId": "getMatrixRoomKeysInternal", "parameters": [ { "in": "path", "name": "account_id", "required": true, "schema": { "title": "Account Id", "type": "string" } }, { "in": "query", "name": "room_id", "required": true, "schema": { "title": "Room Id", "type": "string" } }, { "in": "header", "name": "X-Internal-Service", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service" } }, { "in": "header", "name": "X-Internal-Service-Key", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service-Key" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoomKeysResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Recover a room's backed-up megolm keys for the assistant (internal)", "tags": [ "matrix" ], "x-mcp-skip": true } }, "/api/v1/internal/mcp-servers/active": { "get": { "operationId": "listActiveMcpServersInternal", "parameters": [ { "in": "query", "name": "tenant_id", "required": true, "schema": { "title": "Tenant Id", "type": "string" } }, { "in": "query", "name": "principal_id", "required": true, "schema": { "title": "Principal Id", "type": "string" } }, { "in": "query", "name": "ai_employee_id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Ai Employee Id" } }, { "in": "query", "name": "agent_member_id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Agent Member Id" } }, { "in": "header", "name": "X-Internal-Service", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service" } }, { "in": "header", "name": "X-Internal-Service-Key", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service-Key" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpRuntimeActiveResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Resolve an AI employee's active MCP servers + auth (internal)", "tags": [ "automations" ], "x-mcp-skip": true } }, "/api/v1/internal/memory/settle": { "post": { "description": "Trigger Memory Service settling check.\n\nWithout page_id: scans all notes for the tenant that have settled.\nWith page_id + force=true: immediately processes the specified page.", "operationId": "triggerSettlingCheck", "parameters": [ { "description": "Force-process a specific page", "in": "query", "name": "page_id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Force-process a specific page", "title": "Page Id" } }, { "description": "Bypass settling timer", "in": "query", "name": "force", "required": false, "schema": { "default": false, "description": "Bypass settling timer", "title": "Force", "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Triggersettlingcheck", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Trigger Settling Check", "tags": [ "memory" ] } }, "/api/v1/internal/notes": { "post": { "description": "Internal endpoint for service-to-service note creation (MRS, notification-service).\n\n Requires X-Internal-Service and X-Internal-Service-Key headers\n plus X-Tenant-ID header.\n No JWT authentication required - for trusted internal services only.\n\n Related: MRS SMS note generation", "operationId": "createNoteInternal", "parameters": [ { "in": "header", "name": "X-Account-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Account-Id" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } }, { "in": "header", "name": "X-Internal-Service", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service" } }, { "in": "header", "name": "X-Internal-Service-Key", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service-Key" } }, { "in": "header", "name": "X-Tenant-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tenant-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NoteCreate" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NoteResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Create note (internal service-to-service)", "tags": [ "notes", "Internal" ] } }, "/api/v1/internal/ooo/maybe-reply": { "post": { "description": "Evaluate OOO + send an auto-reply if applicable.\n\nAlways returns 200 with the outcome on the body — the orchestrator\ntreats every reason except an exception as a normal result.", "operationId": "internalOooMaybeReply", "parameters": [ { "in": "header", "name": "X-Internal-Service-Key", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service-Key" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OooTriggerRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OooTriggerResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Trigger OOO auto-reply evaluation for one inbound email", "tags": [ "internal", "internal" ] } }, "/api/v1/internal/podcast-corpus/contract": { "get": { "description": "Producer preflight: lets the pipeline detect a schema-version drift\nBEFORE burning GPU runs into 422 deliveries (2026-06-10 v1/v2 incident).", "operationId": "getPodcastCorpusContract", "parameters": [ { "in": "header", "name": "X-Internal-Service", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service" } }, { "in": "header", "name": "X-Internal-Service-Key", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service-Key" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CorpusContractResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Accepted podcast corpus record schema version (producer preflight)", "tags": [ "internal" ], "x-mcp-skip": true, "x-mcp-skip-reason": "Internal producer-preflight endpoint for the external podcast pipeline's writeback contract check; not an agent workflow." } }, "/api/v1/internal/podcast-corpus/ingest": { "post": { "operationId": "ingestPodcastCorpusRecord", "parameters": [ { "in": "header", "name": "X-Internal-Service", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service" } }, { "in": "header", "name": "X-Internal-Service-Key", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service-Key" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CorpusIngestRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CorpusIngestResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Ingest a podcast corpus record (writeback/seed)", "tags": [ "internal" ], "x-mcp-skip": true, "x-mcp-skip-reason": "Internal service-to-service writeback receiver for the external podcast pipeline; not an agent workflow." } }, "/api/v1/internal/podcast-corpus/priority-failure": { "post": { "description": "Mark the ledger item(s) for ``request_ref`` failed with the error payload.\n\nUnknown request_ref → 404 (a real not-found; the pipeline's 422-is-a-bug rule\napplies only to a malformed payload, which Pydantic rejects as 422 here).", "operationId": "recordPodcastPriorityFailure", "parameters": [ { "in": "header", "name": "X-Internal-Service", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service" } }, { "in": "header", "name": "X-Internal-Service-Key", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service-Key" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PriorityFailureRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PriorityFailureResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Record a priority transcription failure pushed by the pipeline", "tags": [ "internal" ], "x-mcp-skip": true, "x-mcp-skip-reason": "Internal service-to-service failure receiver for the external podcast pipeline's priority lane; not an agent workflow." } }, "/api/v1/internal/projection-routing/cutover": { "post": { "operationId": "internalProjectionRoutingCutover", "parameters": [ { "in": "header", "name": "X-Internal-Service", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service" } }, { "in": "header", "name": "X-Internal-Service-Key", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service-Key" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoutingChangeRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoutingStateResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Cutover", "tags": [ "internal-projection-routing" ], "x-mcp-skip": true } }, "/api/v1/internal/projection-routing/evaluate": { "post": { "operationId": "internalProjectionRoutingEvaluate", "parameters": [ { "in": "header", "name": "X-Internal-Service", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service" } }, { "in": "header", "name": "X-Internal-Service-Key", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service-Key" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EvaluateRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EvaluationResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Evaluate", "tags": [ "internal-projection-routing" ], "x-mcp-skip": true } }, "/api/v1/internal/projection-routing/rollback": { "post": { "operationId": "internalProjectionRoutingRollback", "parameters": [ { "in": "header", "name": "X-Internal-Service", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service" } }, { "in": "header", "name": "X-Internal-Service-Key", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service-Key" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoutingChangeRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoutingStateResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Rollback", "tags": [ "internal-projection-routing" ], "x-mcp-skip": true } }, "/api/v1/internal/projection-routing/verdict": { "post": { "operationId": "internalProjectionRoutingVerdict", "parameters": [ { "in": "header", "name": "X-Internal-Service", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service" } }, { "in": "header", "name": "X-Internal-Service-Key", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service-Key" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerdictRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerdictResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Record Verdict", "tags": [ "internal-projection-routing" ], "x-mcp-skip": true } }, "/api/v1/internal/projection-routing/{family}": { "get": { "operationId": "internalProjectionRoutingGet", "parameters": [ { "in": "path", "name": "family", "required": true, "schema": { "title": "Family", "type": "string" } }, { "in": "header", "name": "X-Internal-Service", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service" } }, { "in": "header", "name": "X-Internal-Service-Key", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service-Key" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoutingStateResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Get Routing", "tags": [ "internal-projection-routing" ], "x-mcp-skip": true } }, "/api/v1/internal/projection-routing/{family}/retirement": { "get": { "operationId": "internalProjectionRoutingRetirement", "parameters": [ { "in": "path", "name": "family", "required": true, "schema": { "title": "Family", "type": "string" } }, { "in": "header", "name": "X-Internal-Service", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service" } }, { "in": "header", "name": "X-Internal-Service-Key", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service-Key" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetirementResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Retirement", "tags": [ "internal-projection-routing" ], "x-mcp-skip": true } }, "/api/v1/internal/projection-shadow-metrics/run": { "post": { "operationId": "internalProjectionShadowMetricsRun", "parameters": [ { "in": "header", "name": "X-Internal-Service", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service" } }, { "in": "header", "name": "X-Internal-Service-Key", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service-Key" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShadowMetricsRunRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShadowMetricsRunResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Run Projection Shadow Metrics", "tags": [ "internal-projection-shadow" ], "x-mcp-skip": true } }, "/api/v1/internal/scheduled-job-fire/notify": { "post": { "operationId": "internalNotifyScheduledJobFire", "parameters": [ { "in": "header", "name": "X-Internal-Service-Key", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service-Key" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScheduledFireNotifyRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionAttentionNotifyResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Notify a job's owner of a terminal failed fire through the existing agent engine", "tags": [ "internal", "internal" ], "x-mcp-skip": true } }, "/api/v1/internal/session-attention/notify": { "post": { "operationId": "internalNotifySessionAttention", "parameters": [ { "in": "header", "name": "X-Internal-Service-Key", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service-Key" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionAttentionNotifyRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionAttentionNotifyResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Emit one conversation-attention notification through the central engine", "tags": [ "internal", "internal" ], "x-mcp-skip": true } }, "/api/v1/internal/session-attention/withdraw": { "post": { "operationId": "internalWithdrawSessionAttention", "parameters": [ { "in": "header", "name": "X-Internal-Service-Key", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service-Key" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionAttentionWithdrawRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionAttentionWithdrawResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Take back a conversation's attention cards once it no longer waits (TIDY-20023)", "tags": [ "internal", "internal" ], "x-mcp-skip": true } }, "/api/v1/internal/sign-request": { "post": { "description": "Internal endpoint for sandbox workflows to sign requests with a Custom API plugin whose scheme is hmac or aws_sigv4. Authenticated by the sandbox run JWT (ES256 delegated token). Never exposes the plugin's secret to the guest — signing happens host-side.", "operationId": "sign_request_endpoint_api_v1_internal_sign_request_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignRequestBody" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignRequestResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Sign an outgoing HTTP request with a Custom API plugin", "tags": [ "internal", "internal" ] } }, "/api/v1/internal/ve-approvals/park-alert": { "post": { "operationId": "internalNotifyVeApprovalPark", "parameters": [ { "in": "header", "name": "X-Internal-Service-Key", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service-Key" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VeApprovalParkAlertRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VeApprovalParkAlertResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Notify the owner of one parked approval (and record it in the home room)", "tags": [ "internal", "internal" ], "x-mcp-skip": true } }, "/api/v1/internal/ve-approvals/relay-control": { "post": { "operationId": "internalRelayVeApprovalControl", "parameters": [ { "in": "header", "name": "X-Internal-Service-Key", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service-Key" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VeApprovalRelayControlRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VeApprovalRelayControlResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Post a share holder's approval answer into the employee's home room", "tags": [ "internal", "internal" ], "x-mcp-skip": true } }, "/api/v1/internal/ve-heartbeat/status": { "post": { "description": "TIDY-16409 (A5): the ONE writer of the two autonomy statuses.\n\nThe transition rides ``AgentProvisioningService`` rather than an UPDATE\nhere, so the lifecycle guards that already exist (a terminated VE cannot be\nchanged; only liveness-recoverable states return to ``active``) hold for\nthe heartbeat exactly as they do for a human clicking Suspend.", "operationId": "internalSetVeAutonomyStatus", "parameters": [ { "in": "header", "name": "X-Internal-Service-Key", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service-Key" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VeAutonomyStatusRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VeAutonomyStatusResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Move a VE between active / degraded / needs_reauth", "tags": [ "internal", "internal" ], "x-mcp-skip": true } }, "/api/v1/internal/ve-heartbeat/stuck-work-wake": { "post": { "operationId": "internalMintVeStuckWorkWake", "parameters": [ { "in": "header", "name": "X-Internal-Service-Key", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service-Key" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VeStuckWorkWakeRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VeHeartbeatWakeResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Wake a manager employee for its team's stuck work", "tags": [ "internal", "internal" ], "x-mcp-skip": true } }, "/api/v1/internal/ve-heartbeat/wake": { "post": { "operationId": "internalMintVeHeartbeatWake", "parameters": [ { "in": "header", "name": "X-Internal-Service-Key", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service-Key" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VeHeartbeatWakeRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VeHeartbeatWakeResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Post one wake message into a stalled VE's conversation", "tags": [ "internal", "internal" ], "x-mcp-skip": true } }, "/api/v1/internal/ve-meeting-wake/mint": { "post": { "operationId": "internalMintVeMeetingWake", "parameters": [ { "in": "header", "name": "X-Internal-Service-Key", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service-Key" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VeMeetingWakeRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VeMeetingWakeResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Post one meeting wake into the event's channel", "tags": [ "internal", "internal" ], "x-mcp-skip": true } }, "/api/v1/internal/ve-prompts/{prompt_id}/steer": { "post": { "operationId": "internalDeliverVePromptSteer", "parameters": [ { "in": "path", "name": "prompt_id", "required": true, "schema": { "title": "Prompt Id", "type": "string" } }, { "in": "header", "name": "X-Internal-Service-Key", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service-Key" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VePromptSteerRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VePromptSteerResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Deliver a decided question's or approval's steer into its conversation", "tags": [ "internal", "internal" ], "x-mcp-skip": true } }, "/api/v1/internal/ve-reflection/wake": { "post": { "operationId": "internalMintVeReflectionWake", "parameters": [ { "in": "header", "name": "X-Internal-Service-Key", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service-Key" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VeReflectionWakeRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VeReflectionWakeResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Post one reflection wake into a VE's conversation and latch the conversation", "tags": [ "internal", "internal" ], "x-mcp-skip": true } }, "/api/v1/invitations/{code}": { "get": { "description": "Public view of a workspace invitation for its landing page: workspace, inviter, role, masked address and whether it can still be accepted. No auth: the invitee has no account yet.", "operationId": "previewInvitation", "parameters": [ { "description": "7-character invitation code", "in": "path", "name": "code", "required": true, "schema": { "description": "7-character invitation code", "title": "Code", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvitationPreviewResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Preview a tenant invitation", "tags": [ "invitations", "Invitations" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/invitations/{code}/accept": { "post": { "description": "Accept a tenant invitation using the invitation code. Authenticated user joins the tenant.", "operationId": "acceptInvitation2", "parameters": [ { "description": "7-character invitation code", "in": "path", "name": "code", "required": true, "schema": { "description": "7-character invitation code", "title": "Code", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvitationAcceptResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Accept a tenant invitation", "tags": [ "invitations", "Invitations" ] } }, "/api/v1/invite-codes": { "get": { "description": "List current user's invite codes with referral summary.", "operationId": "listInviteCodes", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Listinvitecodes", "type": "object" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List Invite Codes", "tags": [ "growth" ] } }, "/api/v1/invite-codes/eligibility": { "get": { "description": "Per-user invite-generation gate + allowance in one authoritative read.\n\nCombines the TIDY-12620 generation gate (admin master switch + subscription\nsub-gate) with the TIDY-12621 per-user allowance so the UI can render the\ngenerate button, the at-cap state, and the self-generation banner from a\nsingle call. ``enablement_key`` is the master switch's ``updated_at`` — the\nbanner keys its per-user dismissal on it, so an admin disable→re-enable\ncycle re-shows the banner once to users who never acknowledged the new\nenablement. Fails closed via the gate service (unknown switch → OFF).", "operationId": "getInviteGenerationEligibility", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InviteGenerationEligibilityResponse" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Invite Generation Eligibility", "tags": [ "growth" ], "x-mcp-skip": true, "x-mcp-skip-reason": "UI gate-state read that drives the Invites page button + banner; not an agent action." } }, "/api/v1/invite-codes/generate": { "post": { "description": "Self-generate one invite code, enforcing eligibility + allowance.\n\nServer-authoritative (fail closed): the caller must be eligible per the\nTIDY-12620 generation gate (admin master switch ON + subscription sub-gate)\nAND have remaining allowance (R10). Over-limit or ineligible → 403 — never\nUI-only. The code is a first-class invite (status 'available'), redeemable\nthrough the same provision path as founder codes (TIDY-12617).", "operationId": "generateInviteCode", "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerateInviteCodeResponse" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Generate Invite Code", "tags": [ "growth" ], "x-mcp-skip": true, "x-mcp-skip-reason": "Growth action; an agent should not mint invite codes on a user's behalf." } }, "/api/v1/invite-codes/{code_id}/send": { "post": { "description": "Mark an invite code as sent to a recipient.", "operationId": "sendInvite", "parameters": [ { "in": "path", "name": "code_id", "required": true, "schema": { "title": "Code Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendInviteRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Sendinvite", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Send Invite", "tags": [ "growth" ] } }, "/api/v1/invites": { "get": { "description": "List the caller's calendar invites awaiting response.\n\nReturns events where:\n- the caller is the recipient (owns the event) and can see it\n- ics_method = 'REQUEST' (incoming invite)\n- our_partstat = 'NEEDS-ACTION' (not yet responded), unless include_responded=true\n- the event has not ended, when upcoming_only=true", "operationId": "listPendingInvites", "parameters": [ { "description": "Include invites we've already responded to", "in": "query", "name": "include_responded", "required": false, "schema": { "default": false, "description": "Include invites we've already responded to", "title": "Include Responded", "type": "boolean" } }, { "description": "Only invites whose event has not ended yet", "in": "query", "name": "upcoming_only", "required": false, "schema": { "default": false, "description": "Only invites whose event has not ended yet", "title": "Upcoming Only", "type": "boolean" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 100, "maximum": 1000, "minimum": 1, "title": "Limit", "type": "integer" } }, { "in": "query", "name": "offset", "required": false, "schema": { "default": 0, "minimum": 0, "title": "Offset", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InviteListResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List pending calendar invites", "tags": [ "Calendar Invites", "Calendar Invites" ] } }, "/api/v1/invites/availability-preview": { "get": { "description": "The busy-blocks-only week the member is about to publish (TIDY-16595).\n\nSame computation seam the COUNTER email builder uses, under the caller's own\nmember-visible predicate — so the preview is the artifact, not a client-side\nguess at it. Blocks only: no titles, locations or attendees exist on this\npayload to leak.", "operationId": "previewProposalAvailability", "parameters": [ { "description": "Any instant inside the week to preview. The window is the Monday-to-Monday week containing it, in the member's timezone.", "in": "query", "name": "week_of", "required": true, "schema": { "description": "Any instant inside the week to preview. The window is the Monday-to-Monday week containing it, in the member's timezone.", "format": "date-time", "title": "Week Of", "type": "string" } }, { "description": "Typed ID with prefix 'V' (or bare UUID during deprecation)", "in": "query", "name": "exclude_event_id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Typed ID with prefix 'V' (or bare UUID during deprecation)", "title": "Exclude Event Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AvailabilityPreviewResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Preview the availability snippet an outbound proposal would carry", "tags": [ "Calendar Invites", "Calendar Invites" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/invites/send-capability": { "get": { "description": "Report whether the tenant's invite-send source can physically send.", "operationId": "getInviteSendCapability", "parameters": [ { "description": "Email source to check. Omitted checks the tenant's default send source — the same one sendInvites would pick.", "in": "query", "name": "email_source_id", "required": false, "schema": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "description": "Email source to check. Omitted checks the tenant's default send source — the same one sendInvites would pick.", "title": "Email Source Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InviteSendCapabilityResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Whether this tenant can actually send ICS invites", "tags": [ "Calendar Invites", "Calendar Invites" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/invites/{event_id}": { "get": { "description": "Get one of the caller's calendar invites; another member's is a 404.", "operationId": "getInvite", "parameters": [ { "description": "Typed ID with prefix 'V'", "in": "path", "name": "event_id", "required": true, "schema": { "description": "Typed ID with prefix 'V'", "title": "Event Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PendingInvite" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get invite details", "tags": [ "Calendar Invites", "Calendar Invites" ] } }, "/api/v1/invites/{event_id}/accept-proposal": { "post": { "description": "Accept a time proposal (COUNTER) and update the event.\n\nThis updates the event to the proposed time and sends a new REQUEST\nto all attendees with the updated time.\n\n**Use case**: Someone proposed a different time, and you want to accept it.", "operationId": "acceptTimeProposal", "parameters": [ { "description": "Typed ID with prefix 'V'", "in": "path", "name": "event_id", "required": true, "schema": { "description": "Typed ID with prefix 'V'", "title": "Event Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcceptProposalResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Accept a time proposal", "tags": [ "Calendar Invites", "Calendar Invites" ] } }, "/api/v1/invites/{event_id}/counter": { "post": { "description": "Propose a different time for a calendar invite (METHOD=COUNTER).\n\nThis sends a COUNTER proposal to the organizer requesting a different time.\nThe organizer can accept (update the event) or decline (DECLINECOUNTER).\n\n**Use case**: You received an invite but the time doesn't work for you.\n\nThe local event is never moved — a COUNTER asks the organizer, it does not\nreschedule anything on our side.\n\nWith `include_availability` the outbound email carries a busy-blocks-only\nsnippet of the member's week (TIDY-16595). If that cannot be computed the\nrequest fails and NO email is sent, rather than quietly sending one without\nthe section the member asked for. Omitted, the field follows the member's\nstored preference (TIDY-16596) — \"where enabled\" without every caller\nhaving to re-read it.", "operationId": "proposeNewTime", "parameters": [ { "description": "Typed ID with prefix 'V'", "in": "path", "name": "event_id", "required": true, "schema": { "description": "Typed ID with prefix 'V'", "title": "Event Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CounterProposalRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CounterProposalResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Propose a different time", "tags": [ "Calendar Invites", "Calendar Invites" ] } }, "/api/v1/invites/{event_id}/decline-proposal": { "post": { "description": "Decline a time proposal (COUNTER) and keep the original time.\n\nThis sends a DECLINECOUNTER to the proposer, keeping the event unchanged.\n\n**Use case**: Someone proposed a different time, but you can't accommodate it.", "operationId": "declineTimeProposal", "parameters": [ { "description": "Typed ID with prefix 'V'", "in": "path", "name": "event_id", "required": true, "schema": { "description": "Typed ID with prefix 'V'", "title": "Event Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeclineProposalRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeclineProposalResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Decline a time proposal", "tags": [ "Calendar Invites", "Calendar Invites" ] } }, "/api/v1/invites/{event_id}/respond": { "post": { "description": "Respond to a calendar invite (accept, decline, maybe).\n\nThe response is evaluated by the conflict ward before it applies\n(TIDY-15403). When the slot is clear, one transaction records our_partstat\non the invite response, the event's status, and the attendee partstat the\nStatus Matrix renders. When it collides, nothing is applied and a 409\ncarries the conflict card.\n\nThis will:\n1. Record our_partstat in the invite_responses table\n2. Set the event status (approved for accept, cancelled for decline)\n3. Optionally send an ICS REPLY email to the organizer\n\n**Actions:**\n- `accept` → PARTSTAT=ACCEPTED, event_status=approved\n- `decline` → PARTSTAT=DECLINED, event_status=cancelled\n- `maybe` / `tentative` → PARTSTAT=TENTATIVE, event_status=approved", "operationId": "respondToInvite", "parameters": [ { "description": "Typed ID with prefix 'V'", "in": "path", "name": "event_id", "required": true, "schema": { "description": "Typed ID with prefix 'V'", "title": "Event Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InviteResponseRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InviteResponseResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Respond to calendar invite", "tags": [ "Calendar Invites", "Calendar Invites" ] } }, "/api/v1/items/{item_id}/session-links": { "get": { "description": "The full supersession chain for one item, oldest first.\n\n``own`` carries the calling VE's active link when the caller is an agent\nmember with one (its resume anchor). An item with no links returns an\nempty chain — never an error.", "operationId": "getItemSessionLinks", "parameters": [ { "in": "path", "name": "item_id", "required": true, "schema": { "title": "Item Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Getitemsessionlinks", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "The VE conversation episodes that worked an item (trace-back chain)", "tags": [ "agents" ], "x-local-capability": "cloud" } }, "/api/v1/journal/operational-notices/{notice_id}/dismiss": { "post": { "description": "Dismiss one of the caller's own notices and clear its bell entry.", "operationId": "dismissJournalOperationalNotice", "parameters": [ { "in": "path", "name": "notice_id", "required": true, "schema": { "format": "uuid", "title": "Notice Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperationalNoticeDismissResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Dismiss a Journal operational notice", "tags": [ "journal", "journal" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/journals": { "get": { "description": "List journals with optional date range and type filter.\n\nOBO-aware (TIDY-11595): with an active ``notes`` read grant the list runs\nunder the principal named in ``X-Tidy-On-Behalf-Of``; otherwise it falls back\nto the caller's own visibility (no widening, no leak).", "operationId": "listJournals", "parameters": [ { "description": "Start date (inclusive)", "in": "query", "name": "from", "required": false, "schema": { "anyOf": [ { "format": "date", "type": "string" }, { "type": "null" } ], "description": "Start date (inclusive)", "title": "From" } }, { "description": "End date (inclusive)", "in": "query", "name": "to", "required": false, "schema": { "anyOf": [ { "format": "date", "type": "string" }, { "type": "null" } ], "description": "End date (inclusive)", "title": "To" } }, { "description": "daily|weekly|monthly", "in": "query", "name": "type", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "daily|weekly|monthly", "title": "Type" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JournalListResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List journals", "tags": [ "journals", "journals" ] }, "post": { "description": "Create a journal entry (used by tracker materialization).", "operationId": "createJournal", "parameters": [ { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JournalCreateRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JournalResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Create journal", "tags": [ "journals", "journals" ] } }, "/api/v1/journals/by-id/{journal_id}": { "get": { "description": "Get a single journal by its ID.\n\nOBO-aware (TIDY-11595): when an active ``notes`` read grant covers the\nprincipal named in ``X-Tidy-On-Behalf-Of``, the member-visible predicate runs\nunder that principal so a delegated agent can open the journal a comment\nrefers to. Without a grant it falls back to the caller's own visibility (404\non a principal's private journal — no widening, no leak).", "operationId": "getJournalById", "parameters": [ { "description": "Typed ID with prefix 'J'", "in": "path", "name": "journal_id", "required": true, "schema": { "description": "Typed ID with prefix 'J'", "title": "Journal Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JournalResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get journal by ID", "tags": [ "journals", "journals" ] } }, "/api/v1/journals/template-section": { "post": { "description": "Write one section into the template a member's journals start from.\n\nThe member is the caller, or for a virtual employee the person it works\nfor, whose approval of the exact change is asked on a card first (409\n``owner_approval_required``; the same call after they approve writes it).\nThe result is always the member's own private template, bound as their\ntemplate for that cadence.", "operationId": "setJournalTemplateSection", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JournalTemplateSectionRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JournalTemplateSectionResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Add or replace a section of a member's journal template", "tags": [ "journals" ], "x-local-capability": "cloud" } }, "/api/v1/journals/template-widgets": { "get": { "description": "The built-ins' state, derived from the bound template.\n\nThe read is self-healing: it re-projects the preference columns, so a widget\ndeleted directly in the template editor is reflected in every consumer of\nthose columns the next time settings is opened.", "operationId": "getJournalTemplateWidgets", "parameters": [ { "in": "query", "name": "journal_type", "required": false, "schema": { "default": "daily", "title": "Journal Type", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JournalTemplateWidgetsResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Journal Template Widgets", "tags": [ "journals" ], "x-local-capability": "cloud", "x-mcp-skip": true }, "post": { "description": "Place or remove one built-in widget in the bound journal template.", "operationId": "setJournalTemplateWidget", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JournalTemplateWidgetUpdate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JournalTemplateWidgetsResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Set Journal Template Widget", "tags": [ "journals" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/journals/{journal_id}": { "patch": { "description": "Partial update of a journal entry (used by PowerSync sync for facet properties).", "operationId": "updateJournal", "parameters": [ { "description": "Typed ID with prefix 'J'", "in": "path", "name": "journal_id", "required": true, "schema": { "description": "Typed ID with prefix 'J'", "title": "Journal Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JournalUpdateRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JournalResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Update journal (partial update)", "tags": [ "journals", "journals" ] }, "put": { "description": "Full update of a journal entry (used by PowerSync sync).", "operationId": "updateJournalPut", "parameters": [ { "description": "Typed ID with prefix 'J'", "in": "path", "name": "journal_id", "required": true, "schema": { "description": "Typed ID with prefix 'J'", "title": "Journal Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JournalUpdateRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JournalResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Update journal (full update)", "tags": [ "journals", "journals" ] } }, "/api/v1/journals/{journal_id}/append-markdown": { "post": { "description": "Append once through the collab-owned transactional merge lane.\n\nDelegation-aware (TIDY-19325): a journal the caller cannot see is written\nas the owner whose ``notes`` read_write grant covers it, while the version\nrow still names the caller. The same token that read the journal under a\ngrant used to 404 here. A read-only grant is a 403 naming the grant; no\ngrant is a 404, as before.", "operationId": "appendMarkdownToJournal", "parameters": [ { "description": "Typed ID with prefix 'J'", "in": "path", "name": "journal_id", "required": true, "schema": { "description": "Typed ID with prefix 'J'", "title": "Journal Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } }, { "in": "header", "name": "X-Tidy-Acting-Principal", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tidy-Acting-Principal" } }, { "in": "header", "name": "X-Internal-Service", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service" } }, { "in": "header", "name": "X-Internal-Service-Key", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service-Key" } }, { "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "maxLength": 128, "title": "Idempotency-Key" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JournalAppendMarkdownRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JournalResponse" } } }, "description": "Successful Response", "headers": { "X-Tidy-Op-Id": { "schema": { "type": "string" } }, "X-Tidy-Op-Outcome": { "description": "replayed: this Idempotency-Key had already landed; nothing was written again", "schema": { "enum": [ "applied", "replayed" ], "type": "string" } } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentConflictResponse" } } }, "description": "collab_liveness_unprovable (retry the same key) or idempotency_key_reused", "headers": { "Retry-After": { "schema": { "type": "integer" } }, "X-Tidy-Op-Id": { "schema": { "type": "string" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Append markdown to journal body (Yjs-aware, TIDY-9874)", "tags": [ "journals", "journals" ] } }, "/api/v1/journals/{journal_id}/append-markdown/status": { "get": { "description": "The status read for an append whose answer was lost.\n\n``applied`` names the version it made; ``not_applied`` means nothing under\nthat key has landed, and sending the same append with the same key writes\nit once. Anyone who can read the journal may ask — the receipt, like the\nkey, belongs to the document.", "operationId": "getJournalAppendMarkdownStatus", "parameters": [ { "description": "Typed ID with prefix 'J'", "in": "path", "name": "journal_id", "required": true, "schema": { "description": "Typed ID with prefix 'J'", "title": "Journal Id", "type": "string" } }, { "description": "The Idempotency-Key the write was sent with.", "in": "query", "name": "operation_key", "required": true, "schema": { "description": "The Idempotency-Key the write was sent with.", "maxLength": 128, "minLength": 1, "title": "Operation Key", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentOperationStatus" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Did a keyed markdown append land in this journal? (TIDY-18493)", "tags": [ "journals", "journals" ], "x-local-capability": "cloud" } }, "/api/v1/journals/{journal_id}/embed-block": { "post": { "description": "Insert an embeddedBlock referencing a primitive row into a journal body.\n\nYjs-aware incremental write (pycrdt) — the journal is never rebuilt from\nplain text. The embed is captured by the whole-doc linked_references\nre-sync (TIDY-9849), so a backlink row is created for the embedded row.", "operationId": "embedBlockInJournal", "parameters": [ { "description": "Typed ID with prefix 'J'", "in": "path", "name": "journal_id", "required": true, "schema": { "description": "Typed ID with prefix 'J'", "title": "Journal Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JournalEmbedBlockRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JournalResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Embed a primitive row as an embeddedBlock in a journal (Yjs-aware, TIDY-12983)", "tags": [ "journals", "journals" ], "x-mcp-skip": true, "x-mcp-skip-reason": "TIDY-12983 assistant-service registry owns the agent tool" } }, "/api/v1/journals/{journal_id}/wiki-links/sync": { "post": { "description": "DELETE-then-INSERT replaces all `linked_references` rows sourced from\n wiki-link sync (link_source IN 'wiki_link_sync', 'content_embed') for\n the given journal day, with the provided set. Rows authored by other\n sources (llm_extracted, pipeline_auto, etc.) are preserved.\n\n Called by the Yjs wiki-link sync path on the client after journal-page\n edits (TIDY-13515). `source_note_id` stays NULL — the FK points at\n `notes`, and the journal is identified by source_container_id.", "operationId": "syncJournalWikiLinks", "parameters": [ { "description": "Journal UUID", "in": "path", "name": "journal_id", "required": true, "schema": { "description": "Journal UUID", "title": "Journal Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WikiLinkSyncRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WikiLinkSyncResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Atomically replace wiki-link rows for a journal", "tags": [ "links" ], "x-mcp-skip": true } }, "/api/v1/journals/{target_date}": { "get": { "description": "Get journal for date, auto-creating if needed.\n\nOBO-aware (TIDY-11595): a non-delegated call get-or-creates under the caller\n(unchanged). A DELEGATED call (active ``notes`` read grant for the principal\nnamed in ``X-Tidy-On-Behalf-Of``) does a read-only fetch under the principal\nand 404s when the journal does not exist — a read grant must NOT auto-create\na journal under the principal. Without a covering grant it falls back to the\ncaller's own visibility (no widening, no leak).", "operationId": "getJournal", "parameters": [ { "in": "path", "name": "target_date", "required": true, "schema": { "format": "date", "title": "Target Date", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JournalResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get or create journal for date", "tags": [ "journals", "journals" ] } }, "/api/v1/knowledge-packs/tools": { "get": { "description": "Active packs as tool schemas derived from their declared contracts.", "operationId": "listKnowledgePackTools", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PackToolsResponse" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List Pack Tools", "tags": [ "knowledge-packs", "knowledge-packs" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/knowledge-packs/{slug}/invoke": { "post": { "description": "Invoke the current active version under the caller's own principal.", "operationId": "invokeKnowledgePack", "parameters": [ { "in": "path", "name": "slug", "required": true, "schema": { "title": "Slug", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PackInvokeRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PackInvokeResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Invoke Pack As Agent", "tags": [ "knowledge-packs", "knowledge-packs" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/links": { "get": { "description": "Returns all links connected to a specific primitive (both directions).\n\n Query Parameters:\n - primitive_type: Type of the primitive (event, contact, task, note, news_update)\n - primitive_id: ID of the primitive (UUID)\n - link_type: Optional filter by relationship type\n - target_type: Optional filter by target primitive type\n - limit: Max results (1-100), default: 20\n - cursor: Pagination cursor\n\n Returns paginated list of links.", "operationId": "getLinks", "parameters": [ { "description": "Type of the primitive", "in": "query", "name": "primitive_type", "required": true, "schema": { "description": "Type of the primitive", "title": "Primitive Type", "type": "string" } }, { "description": "Typed primitive ID (e.g. 'C-<uuid>') or bare UUID during the typed-id deprecation window", "in": "query", "name": "primitive_id", "required": true, "schema": { "description": "Typed primitive ID (e.g. 'C-<uuid>') or bare UUID during the typed-id deprecation window", "title": "Primitive Id", "type": "string" } }, { "description": "Filter by link type", "in": "query", "name": "link_type", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by link type", "title": "Link Type" } }, { "description": "Filter by target type", "in": "query", "name": "target_type", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by target type", "title": "Target Type" } }, { "description": "Max results", "in": "query", "name": "limit", "required": false, "schema": { "default": 20, "description": "Max results", "maximum": 100, "minimum": 1, "title": "Limit", "type": "integer" } }, { "description": "Pagination cursor", "in": "query", "name": "cursor", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pagination cursor", "title": "Cursor" } }, { "description": "Include links whose related side is an archived activity (badged)", "in": "query", "name": "include_archived", "required": false, "schema": { "default": false, "description": "Include links whose related side is an archived activity (badged)", "title": "Include Archived", "type": "boolean" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinkListResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "The linked-reference read FAILED — problem+json with `code: links_unavailable` (retryable). Distinct from a 200 carrying an empty list, which means the primitive genuinely has no links. Before TIDY-16299 a failed read answered 200 + [] and the two were indistinguishable." } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get links for a primitive", "tags": [ "links" ] }, "post": { "description": "Create a link between two primitives.\n\n The link is created as 'user_created' with confidence 1.0.\n\n Request body:\n - source_type: Type of source primitive\n - source_id: ID of source primitive\n - target_type: Type of target primitive\n - target_id: ID of target primitive\n - link_type: Relationship type\n - metadata: Optional additional context\n\n Returns 201 Created with the created link.\n Returns 409 Conflict if link already exists (returns existing link).", "operationId": "createLink", "parameters": [ { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinkCreate" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinkResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "The linked-reference write FAILED — problem+json with `code: link_write_failed` (retryable; the writes are idempotent, so a retry cannot double-apply). Nothing was changed. Distinct from the 404 on DELETE, which means no such link existed: before TIDY-16299 a refused delete returned that same 404." } }, "security": [ { "HTTPBearer": [] } ], "summary": "Create a new link", "tags": [ "links" ] } }, "/api/v1/links/approval/batch": { "post": { "description": "Batch reject linked_references rows (link rows ONLY).\n\nAny non-rejected, non-superseded link is rejectable (D13 — retained as\nnegative knowledge; drops from sync + summaries automatically). Ids\noutside the tenant, outside the caller's member-visible scope, or already\nrejected/superseded are skipped and reported in `skipped`.", "operationId": "linksApprovalBatch", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinksApprovalBatchRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinksApprovalBatchResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Links Approval Batch", "tags": [ "links", "links" ], "x-mcp-skip": true } }, "/api/v1/links/counts": { "get": { "description": "Returns count of related primitives by type.\n\n Query Parameters:\n - primitive_type: Type of the primitive\n - primitive_id: ID of the primitive (UUID)\n\n Returns counts for each primitive type.", "operationId": "getLinkCounts", "parameters": [ { "description": "Type of the primitive", "in": "query", "name": "primitive_type", "required": true, "schema": { "description": "Type of the primitive", "title": "Primitive Type", "type": "string" } }, { "description": "Typed primitive ID (e.g. 'C-<uuid>') or bare UUID during the typed-id deprecation window", "in": "query", "name": "primitive_id", "required": true, "schema": { "description": "Typed primitive ID (e.g. 'C-<uuid>') or bare UUID during the typed-id deprecation window", "title": "Primitive Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinkCountsResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "The linked-reference read FAILED — problem+json with `code: links_unavailable` (retryable). Distinct from a 200 carrying an empty list, which means the primitive genuinely has no links. Before TIDY-16299 a failed read answered 200 + [] and the two were indistinguishable." } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get link counts for a primitive", "tags": [ "links" ] } }, "/api/v1/links/full": { "get": { "description": "Returns all linked_references rows for a given primitive (direction out,\n in, or both), cursor-paginated. Used when the 200-entry cap on the\n `linked_refs_summary` jsonb column is insufficient (heavily-referenced\n contacts, popular projects, common tags).\n\n Query Parameters:\n - primitive_type: Type of the primitive (note, email, contact, event,\n calendar_event, activity, task, project, notebook, organization, file).\n 'journal' and 'tag_definition' are rejected (not link participants).\n - primitive_id: UUID of the primitive.\n - direction: 'out', 'in', or 'both'. Default 'both'.\n - link_type: Optional filter by relationship type.\n - limit: 1..500, default 50.\n - cursor: Opaque token from a previous response's next_cursor.\n\n Response:\n - links: Page of linked_references rows (LinkFullItem).\n - next_cursor: Opaque cursor for the next page, or null when no more.\n - total: Total matching rows ignoring the cursor predicate (for UI\n \"X of Y\" display).\n\n Ordering: updated_at DESC, id DESC. Cursor-based pagination (not offset)\n is stable under concurrent writes.", "operationId": "getLinksFull", "parameters": [ { "description": "Type of the primitive", "in": "query", "name": "primitive_type", "required": true, "schema": { "description": "Type of the primitive", "title": "Primitive Type", "type": "string" } }, { "description": "Typed primitive ID (e.g. 'C-<uuid>') or bare UUID during the typed-id deprecation window", "in": "query", "name": "primitive_id", "required": true, "schema": { "description": "Typed primitive ID (e.g. 'C-<uuid>') or bare UUID during the typed-id deprecation window", "title": "Primitive Id", "type": "string" } }, { "description": "Direction filter", "in": "query", "name": "direction", "required": false, "schema": { "default": "both", "description": "Direction filter", "enum": [ "out", "in", "both" ], "title": "Direction", "type": "string" } }, { "description": "Filter by link type", "in": "query", "name": "link_type", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by link type", "title": "Link Type" } }, { "description": "Max results per page", "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "description": "Max results per page", "maximum": 500, "minimum": 1, "title": "Limit", "type": "integer" } }, { "description": "Opaque pagination cursor", "in": "query", "name": "cursor", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Opaque pagination cursor", "title": "Cursor" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinksFullResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Paginated full link list for a primitive", "tags": [ "links" ] } }, "/api/v1/links/{link_id}": { "delete": { "description": "Remove a link between primitives.\n\n Returns 204 No Content on success.\n Returns 404 Not Found if link does not exist or does not belong to tenant.\n\n Traceability pairs (TIDY-14984): both directions live on ONE stored row,\n so deleting it removes the pair.", "operationId": "deleteLink", "parameters": [ { "in": "path", "name": "link_id", "required": true, "schema": { "title": "Link Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "The linked-reference write FAILED — problem+json with `code: link_write_failed` (retryable; the writes are idempotent, so a retry cannot double-apply). Nothing was changed. Distinct from the 404 on DELETE, which means no such link existed: before TIDY-16299 a refused delete returned that same 404." } }, "security": [ { "HTTPBearer": [] } ], "summary": "Delete a link", "tags": [ "links" ] } }, "/api/v1/lint/orphaned-facets": { "get": { "description": "List the caller's orphaned insight facets, grouped by target entity.\n\nEach card carries the target's last-known display name (snapshot or\nprivileged read), facet count, a short preview, and best-effort\n'demoted by [name]' attribution.", "operationId": "listOrphanedFacets", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrphanedFacetListResponse" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List Orphaned Facets", "tags": [ "lint", "lint" ], "x-mcp-skip": true } }, "/api/v1/lint/orphaned-facets/resolve": { "post": { "description": "Resolve one orphan group with ``promote_to_own`` or ``discard``.\n\nOwner-scoped: the WHERE clauses in the resolver target only the caller's own\nfacets, so a member can never resolve another member's orphan (RLS-equivalent\nisolation in SQL).", "operationId": "resolveOrphanedFacet", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResolveOrphanRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResolveOrphanResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Resolve Orphaned Facet", "tags": [ "lint", "lint" ], "x-mcp-skip": true } }, "/api/v1/lint/orphaned-facets/resolve-all": { "post": { "description": "Bulk-resolve every pending orphan for the caller with one chosen action.", "operationId": "resolveAllOrphanedFacets", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResolveAllRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResolveAllResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Resolve All Orphaned Facets", "tags": [ "lint", "lint" ], "x-mcp-skip": true } }, "/api/v1/location/geocode": { "post": { "description": "Forward-geocodes a free-text address via the Google Geocoding API, cached per tenant on the normalized address and bounded by the same daily budget as /location/resolve. An address the provider cannot place returns 404 — never a silent (0, 0). TIDY-17056 (S4 / R13): the one door behind the `location` facet field's Locate button and the scan → location extraction bridge.", "operationId": "geocodeAddress", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeocodeRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeocodeResponse" } } }, "description": "Successful Response" }, "404": { "description": "The provider has no result for this address" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Daily address-lookup limit exceeded" }, "503": { "description": "Geocoding provider unavailable or unconfigured" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Resolve a street address to map coordinates", "tags": [ "location" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "UI-support geocoder for the location facet field widget, sibling to /location/static-map. It is a metered third-party proxy with no Tidy primitive behind it, not an assistant capability." } }, "/api/v1/location/resolve": { "post": { "description": "Resolves latitude/longitude to a human-readable place name.\n Uses Google Places API with caching and ORS fallback.\n\n TIDY-3875: Google Places API integration", "operationId": "resolveLocation", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LocationResolveRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LocationResolveResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "description": "Rate limit exceeded" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Resolve GPS coordinates to place name", "tags": [ "location" ] } }, "/api/v1/location/reverse-geocode": { "post": { "description": "Converts latitude/longitude coordinates to a human-readable address\n using OpenRouteService. Returns POI name (business name) if available,\n otherwise returns street address.\n\n Related: 001-card-ux-rem-sleep, FR-003", "operationId": "reverseGeocode", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReverseGeocodeRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReverseGeocodeResponse" } } }, "description": "Successful Response" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_service__routers__cards__ErrorResponse" } } }, "description": "Invalid coordinates" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_service__routers__cards__ErrorResponse" } } }, "description": "Geocoding service unavailable" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Reverse geocode coordinates to address", "tags": [ "cards" ] } }, "/api/v1/location/static-map": { "get": { "description": "Return a PNG static map image centered on the given coordinates with a single red pin marker. Proxied from Google Static Maps and cached on disk by sha256 of the canonical render parameters. TIDY-10998 (F1 S2 of TIDY-10992).", "operationId": "getStaticMap", "parameters": [ { "description": "Latitude coordinate (-90 to 90)", "in": "query", "name": "lat", "required": true, "schema": { "description": "Latitude coordinate (-90 to 90)", "title": "Lat", "type": "number" } }, { "description": "Longitude coordinate (-180 to 180)", "in": "query", "name": "lng", "required": true, "schema": { "description": "Longitude coordinate (-180 to 180)", "title": "Lng", "type": "number" } }, { "description": "Map zoom level (10-18)", "in": "query", "name": "zoom", "required": false, "schema": { "default": 15, "description": "Map zoom level (10-18)", "title": "Zoom", "type": "integer" } }, { "description": "Image size 'WxH' in pixels (max 640x320)", "in": "query", "name": "size", "required": false, "schema": { "default": "300x160", "description": "Image size 'WxH' in pixels (max 640x320)", "title": "Size", "type": "string" } }, { "description": "Image scale factor (1 or 2)", "in": "query", "name": "scale", "required": false, "schema": { "default": 2, "description": "Image scale factor (1 or 2)", "title": "Scale", "type": "integer" } } ], "responses": { "200": { "content": { "image/png": {} }, "description": "PNG static map image" }, "422": { "description": "Invalid coordinates, zoom, scale, or size" }, "429": { "description": "Daily static-map quota exceeded" }, "502": { "description": "Upstream Google Static Maps error" }, "503": { "description": "Google Static Maps API key not configured" }, "504": { "description": "Upstream Google Static Maps timeout" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Static map PNG proxy (Google Static Maps)", "tags": [ "location" ], "x-mcp-skip": true, "x-mcp-skip-reason": "Internal image proxy consumed by the LocationFacet UI; binary PNG response, not a useful MCP tool surface." } }, "/api/v1/matrix/channel-templates": { "get": { "operationId": "listMatrixChannelTemplates", "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/TemplateResponse" }, "title": "Response Listmatrixchanneltemplates", "type": "array" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List Templates", "x-mcp-skip": true }, "post": { "operationId": "createMatrixChannelTemplate", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Create Template", "x-mcp-skip": true } }, "/api/v1/matrix/channel-templates/{template_id}": { "delete": { "operationId": "deleteMatrixChannelTemplate", "parameters": [ { "in": "path", "name": "template_id", "required": true, "schema": { "format": "uuid", "title": "Template Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_service__routers__matrix_message_management__OkResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Delete Template", "x-mcp-skip": true }, "get": { "operationId": "getMatrixChannelTemplate", "parameters": [ { "in": "path", "name": "template_id", "required": true, "schema": { "format": "uuid", "title": "Template Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Template", "x-mcp-skip": true }, "patch": { "operationId": "updateMatrixChannelTemplate", "parameters": [ { "in": "path", "name": "template_id", "required": true, "schema": { "format": "uuid", "title": "Template Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplatePatchRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Update Template", "x-mcp-skip": true } }, "/api/v1/matrix/channel-templates/{template_id}/instantiate": { "post": { "operationId": "instantiateMatrixChannelTemplate", "parameters": [ { "in": "path", "name": "template_id", "required": true, "schema": { "format": "uuid", "title": "Template Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InstantiateTemplateRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_service__routers__matrix_message_management__OkResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Instantiate Template", "x-mcp-skip": true } }, "/api/v1/matrix/create-room": { "post": { "description": "Create a Matrix room using the caller's Matrix credentials.", "operationId": "createRoom", "parameters": [ { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateRoomRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoomResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Create a Matrix room, optionally mapped to a project", "tags": [ "matrix" ] } }, "/api/v1/matrix/custom-emoji": { "get": { "operationId": "listMatrixCustomEmoji", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomEmojiListResponse" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List Custom Emoji", "x-mcp-skip": true } }, "/api/v1/matrix/directory": { "get": { "operationId": "browseChannelDirectory", "parameters": [ { "in": "query", "name": "search", "required": false, "schema": { "default": "", "maxLength": 120, "title": "Search", "type": "string" } }, { "in": "query", "name": "sort", "required": false, "schema": { "default": "activity", "enum": [ "members", "activity", "name" ], "title": "Sort", "type": "string" } }, { "in": "query", "name": "visibility", "required": false, "schema": { "default": "public_in_workspace,restricted", "maxLength": 120, "title": "Visibility", "type": "string" } }, { "in": "query", "name": "include_archived", "required": false, "schema": { "default": false, "title": "Include Archived", "type": "boolean" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "maximum": 100, "minimum": 1, "title": "Limit", "type": "integer" } }, { "in": "query", "name": "offset", "required": false, "schema": { "default": 0, "minimum": 0, "title": "Offset", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DirectoryListResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Browse channels in this workspace", "tags": [ "matrix" ] } }, "/api/v1/matrix/dm": { "post": { "description": "Create a 1:1 or group DM room, deduplicating against existing DMs.", "operationId": "createDm", "parameters": [ { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_service__routers__matrix_dm__CreateDmRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_service__routers__matrix_dm__CreateDmResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Create or reuse a direct-message room with the given participants", "tags": [ "matrix" ] } }, "/api/v1/matrix/huddles/ring": { "post": { "operationId": "createHuddleRing", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateRingRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateRingResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Create Ring", "tags": [ "matrix" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/matrix/huddles/ring-preferences": { "get": { "operationId": "getHuddleRingPreferences", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RingPreferencesResponse" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Ring Preferences", "tags": [ "matrix" ], "x-local-capability": "cloud", "x-mcp-skip": true }, "put": { "operationId": "updateHuddleRingPreferences", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RingPreferencesUpdate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RingPreferencesResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Update Ring Preferences", "tags": [ "matrix" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/matrix/huddles/ring/active": { "get": { "operationId": "listHuddleRings", "parameters": [ { "in": "query", "name": "active_only", "required": false, "schema": { "default": false, "title": "Active Only", "type": "boolean" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cursor" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 20, "maximum": 20, "minimum": 1, "title": "Limit", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RingListResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List Rings", "tags": [ "matrix" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/matrix/huddles/ring/{ring_id}": { "delete": { "operationId": "deleteHuddleRing", "parameters": [ { "in": "path", "name": "ring_id", "required": true, "schema": { "format": "uuid", "title": "Ring Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RingStateResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Delete Ring", "tags": [ "matrix" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/matrix/huddles/ring/{ring_id}/answer": { "post": { "operationId": "answerHuddleRing", "parameters": [ { "in": "path", "name": "ring_id", "required": true, "schema": { "format": "uuid", "title": "Ring Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RingTokenRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnswerResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Answer Ring", "tags": [ "matrix" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/matrix/huddles/ring/{ring_id}/decline": { "post": { "operationId": "declineHuddleRing", "parameters": [ { "in": "path", "name": "ring_id", "required": true, "schema": { "format": "uuid", "title": "Ring Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RingTokenRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeclineResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Decline Ring", "tags": [ "matrix" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/matrix/huddles/ring/{ring_id}/end": { "post": { "operationId": "endHuddleRing", "parameters": [ { "in": "path", "name": "ring_id", "required": true, "schema": { "format": "uuid", "title": "Ring Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RingStateResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "End Ring", "tags": [ "matrix" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/matrix/huddles/{huddle_id}": { "delete": { "description": "Delete a huddle's transcript/notes with FULL propagation (TIDY-11953 /\nS9, R13): storage objects, ``audio_refs``, the AI-notes row, and (via the\n``purge_huddle_artifacts`` seam S11 extends) index entries — then the\nhuddle row soft-deletes. An active legal hold blocks absolutely (409).\nTidy-side copies only; Google-side Meet/Drive artifacts belong to the\ncustomer's Workspace and are never touched.", "operationId": "deleteMatrixHuddle", "parameters": [ { "in": "path", "name": "huddle_id", "required": true, "schema": { "format": "uuid", "title": "Huddle Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HuddleResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Delete Huddle", "tags": [ "matrix" ], "x-mcp-skip": true }, "patch": { "description": "Rename a huddle, or hand its name back to derivation (TIDY-15371 / R12).\n\nA member's title is durable by construction: setting it claims the override\nin the same statement, and every later notes event checks that flag first.\nClearing the override is the deliberate inverse — it re-derives immediately\nfrom the latest notes rather than leaving the member's old name sitting\nunder a ``derived`` provenance until some future notes event that, for a\nfinished huddle, may never come.", "operationId": "updateMatrixHuddleTitle", "parameters": [ { "in": "path", "name": "huddle_id", "required": true, "schema": { "format": "uuid", "title": "Huddle Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateHuddleTitleRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HuddleResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Update Huddle Title", "tags": [ "matrix" ], "x-local-capability": "outbox", "x-mcp-skip": true } }, "/api/v1/matrix/huddles/{huddle_id}/composite": { "post": { "description": "Store the dogfood composite contact sheet for an ENDED huddle\n(TIDY-15371, evaluation path — OFF by default).\n\nThree refusals, all of them louder than a silent accept: the tenant has not\nenabled the evaluation (403), the huddle's capture consent is not\naffirmative (the composite is made of people's faces), or the image is over\nthe 500 KB bar the experiment is being judged against. It never touches the\nper-track captures — this artifact is alongside them, never instead.", "operationId": "recordMatrixHuddleComposite", "parameters": [ { "in": "path", "name": "huddle_id", "required": true, "schema": { "format": "uuid", "title": "Huddle Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HuddleCompositeRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HuddleCompositeResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Record Huddle Composite", "tags": [ "matrix" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/matrix/huddles/{huddle_id}/end": { "post": { "operationId": "endMatrixHuddle", "parameters": [ { "in": "path", "name": "huddle_id", "required": true, "schema": { "format": "uuid", "title": "Huddle Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HuddleResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "End Huddle", "tags": [ "matrix" ], "x-mcp-skip": true } }, "/api/v1/matrix/huddles/{huddle_id}/events": { "post": { "operationId": "createMatrixHuddleEvent", "parameters": [ { "in": "path", "name": "huddle_id", "required": true, "schema": { "format": "uuid", "title": "Huddle Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HuddleEventRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HuddleEventResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Create Huddle Event", "tags": [ "matrix" ], "x-mcp-skip": true } }, "/api/v1/matrix/huddles/{huddle_id}/join": { "post": { "operationId": "joinMatrixHuddle", "parameters": [ { "in": "path", "name": "huddle_id", "required": true, "schema": { "format": "uuid", "title": "Huddle Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JoinHuddleRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HuddleResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Join Huddle", "tags": [ "matrix" ], "x-mcp-skip": true } }, "/api/v1/matrix/huddles/{huddle_id}/leave": { "post": { "operationId": "leaveMatrixHuddle", "parameters": [ { "in": "path", "name": "huddle_id", "required": true, "schema": { "format": "uuid", "title": "Huddle Id", "type": "string" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Leave Huddle", "tags": [ "matrix" ], "x-mcp-skip": true } }, "/api/v1/matrix/huddles/{huddle_id}/notes": { "get": { "description": "AI notes for an ended huddle (R8). 404 until notes are generated.", "operationId": "getMatrixHuddleNotes", "parameters": [ { "in": "path", "name": "huddle_id", "required": true, "schema": { "format": "uuid", "title": "Huddle Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HuddleNotesResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Huddle Notes", "tags": [ "matrix" ], "x-mcp-skip": true } }, "/api/v1/matrix/huddles/{huddle_id}/notes/regenerate": { "post": { "description": "Explicit notes regeneration from the current transcript (PD5).\n\nAllowed from ``complete`` or ``failed: notes_generation_error`` only.\nReplaces the content on the SAME note id (edit, don't orphan) and\nre-emits ``huddle.notes_ready``. No automatic re-runs exist anywhere.", "operationId": "regenerateMatrixHuddleNotes", "parameters": [ { "in": "path", "name": "huddle_id", "required": true, "schema": { "format": "uuid", "title": "Huddle Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HuddleNotesResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Regenerate Huddle Notes", "tags": [ "matrix" ], "x-mcp-skip": true } }, "/api/v1/matrix/huddles/{huddle_id}/opt-out": { "post": { "description": "Participant opt-out (TIDY-11953 / S9, R11/D11): blocks capture for the\nENTIRE huddle — no track-exclusion half-measures. Stops any running\ncapture, destroys every partial Tidy-side artifact, and stamps\n``skipped: consent_blocked``. NEVER ends or degrades the live call.", "operationId": "optOutMatrixHuddleCapture", "parameters": [ { "in": "path", "name": "huddle_id", "required": true, "schema": { "format": "uuid", "title": "Huddle Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HuddleResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Opt Out Huddle Capture", "tags": [ "matrix" ], "x-mcp-skip": true } }, "/api/v1/matrix/huddles/{huddle_id}/participant": { "patch": { "operationId": "updateMatrixHuddleParticipant", "parameters": [ { "in": "path", "name": "huddle_id", "required": true, "schema": { "format": "uuid", "title": "Huddle Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateHuddleParticipantRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HuddleParticipantUpdateResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Update Huddle Participant", "tags": [ "matrix" ], "x-mcp-skip": true } }, "/api/v1/matrix/huddles/{huddle_id}/sfu-token": { "get": { "operationId": "getMatrixHuddleSfuToken", "parameters": [ { "in": "path", "name": "huddle_id", "required": true, "schema": { "format": "uuid", "title": "Huddle Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HuddleSfuTokenResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Huddle Sfu Token", "tags": [ "matrix" ], "x-mcp-skip": true } }, "/api/v1/matrix/huddles/{huddle_id}/transcript": { "get": { "description": "Speaker-labeled diarized transcript for an ended huddle (R7).\n404 until the result consumer has persisted the artifact.", "operationId": "getMatrixHuddleTranscript", "parameters": [ { "in": "path", "name": "huddle_id", "required": true, "schema": { "format": "uuid", "title": "Huddle Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HuddleTranscriptResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Huddle Transcript", "tags": [ "matrix" ], "x-mcp-skip": true } }, "/api/v1/matrix/huddles/{huddle_id}/transcript/speakers": { "post": { "description": "One-click speaker correction (D7): re-point a transcript speaker label\nat a member OR a contact. Idempotent — re-asserting the same assignment\nreturns ``changed=false``.", "operationId": "assignMatrixHuddleSpeaker", "parameters": [ { "in": "path", "name": "huddle_id", "required": true, "schema": { "format": "uuid", "title": "Huddle Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssignHuddleSpeakerRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssignHuddleSpeakerResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Assign Huddle Speaker", "tags": [ "matrix" ], "x-mcp-skip": true } }, "/api/v1/matrix/huddles/{huddle_id}/transcription/retry": { "post": { "description": "Explicit retry of a stalled huddle transcription (TIDY-11950 / S6, R10).\n\nFrom ``failed``: resets ``failed → pending`` (clearing the reason) and\nqueues a fresh one-shot run. Does NOT re-emit ``huddle.ended`` — that would\ndouble-count metering consumers (S12).\n\nFrom ``pending`` past ``STRANDED_PENDING_GRACE`` (TIDY-16007): re-queues the\nrun WITHOUT a status write, because the huddle is already pending. This\nsecond case is not a convenience. ``pending`` is the state the END seam\nstamps, and it is left ONLY by a change-driven ``huddle.ended`` delivery —\nthere is no clock sweep and no redrive, so a delivery that never arrives\nparks the huddle there permanently. Six huddles sat exactly like that for 62\ndays, and this endpoint answered every one of them with 409 not_retryable:\nthe one recovery action in the system refused the one state that actually\ngets stuck. Executor entry is idempotent on ``status == 'pending'``, so a\nredrive that races a live dispatch is a no-op rather than a double-run,\nwhich is what makes admitting this state safe.\n\nFrom ``transcribing`` past ``STRANDED_TRANSCRIBING_GRACE`` (TIDY-16573):\nresets ``transcribing → pending`` and queues a fresh run. Same argument one\nstate later — ``transcribing`` is left ONLY by a pushed pipeline result, so\na remote job that dies without pushing parks the huddle there permanently,\nand this endpoint refused that state too. Three dev1 huddles were sitting\nexactly there. The stale-item reaper will eventually fail such a huddle on\nits own; this is the operator's immediate path, and it re-drives the run\nrather than merely terminating it.", "operationId": "retryMatrixHuddleTranscription", "parameters": [ { "in": "path", "name": "huddle_id", "required": true, "schema": { "format": "uuid", "title": "Huddle Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HuddleResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Retry Huddle Transcription", "tags": [ "matrix" ], "x-mcp-skip": true } }, "/api/v1/matrix/key-escrow": { "get": { "operationId": "getMatrixKeyEscrow", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KeyEscrowMaterialResponse" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Fetch the caller's escrowed Matrix recovery key (self)", "tags": [ "matrix", "matrix" ], "x-mcp-skip": true }, "put": { "operationId": "putMatrixKeyEscrow", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KeyEscrowStashRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KeyEscrowStatusResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Record backup metadata for the caller's escrowed Matrix recovery key (self)", "tags": [ "matrix", "matrix" ], "x-mcp-skip": true } }, "/api/v1/matrix/key-escrow/bootstrap": { "post": { "description": "The first device on an account creates its recovery here (TIDY-19733).\n\nWeb and Android call this when GET returns 404, and again when a restore\nleaves the backup off: an existing recovery is returned (healing a server\nbackup the key no longer opens), an absent one is minted once under the\nescrow lock. Whichever client asks first, every device restores the same\nrecovery.", "operationId": "bootstrapMatrixKeyEscrow", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KeyEscrowBootstrapResponse" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get or create the caller's one Matrix recovery (self)", "tags": [ "matrix", "matrix" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/matrix/pins": { "get": { "operationId": "listMatrixWorkspacePins", "parameters": [ { "in": "query", "name": "q", "required": false, "schema": { "anyOf": [ { "maxLength": 200, "type": "string" }, { "type": "null" } ], "title": "Q" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/PinResponse" }, "title": "Response Listmatrixworkspacepins", "type": "array" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List Workspace Pins", "x-mcp-skip": true } }, "/api/v1/matrix/polls/{poll_id}": { "get": { "operationId": "getMatrixPoll", "parameters": [ { "in": "path", "name": "poll_id", "required": true, "schema": { "format": "uuid", "title": "Poll Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PollResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Poll", "tags": [ "matrix" ], "x-mcp-skip": true } }, "/api/v1/matrix/polls/{poll_id}/close": { "post": { "operationId": "closeMatrixPoll", "parameters": [ { "in": "path", "name": "poll_id", "required": true, "schema": { "format": "uuid", "title": "Poll Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PollResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Close Poll", "tags": [ "matrix" ], "x-mcp-skip": true } }, "/api/v1/matrix/polls/{poll_id}/votes": { "post": { "operationId": "voteMatrixPoll", "parameters": [ { "in": "path", "name": "poll_id", "required": true, "schema": { "format": "uuid", "title": "Poll Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PollVoteRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PollResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Vote Poll", "tags": [ "matrix" ], "x-mcp-skip": true } }, "/api/v1/matrix/polls/{poll_id}/votes/{option_idx}": { "delete": { "operationId": "retractMatrixPollVote", "parameters": [ { "in": "path", "name": "poll_id", "required": true, "schema": { "format": "uuid", "title": "Poll Id", "type": "string" } }, { "in": "path", "name": "option_idx", "required": true, "schema": { "title": "Option Idx", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PollResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Retract Vote", "tags": [ "matrix" ], "x-mcp-skip": true } }, "/api/v1/matrix/preferences/recent-emoji": { "get": { "operationId": "listRecentMatrixEmoji", "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/RecentEmojiResponse" }, "title": "Response Listrecentmatrixemoji", "type": "array" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Recent Emoji", "x-mcp-skip": true }, "post": { "operationId": "pushRecentMatrixEmoji", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecentEmojiRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecentEmojiResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Push Recent Emoji", "x-mcp-skip": true } }, "/api/v1/matrix/provision-user": { "post": { "description": "Register a Matrix identity for the given user_id within tenant_id.\n\nAuthorization: caller must be provisioning themselves (account_id matches\nbody.user_id AND tenant_id matches) OR be an Owner/admin of the target tenant.", "operationId": "provisionUser", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProvisionUserRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProvisionUserResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Provision a Matrix user for a tenant member", "tags": [ "matrix" ] } }, "/api/v1/matrix/room-key-requests": { "post": { "operationId": "requestMatrixRoomKey", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoomKeyRequestBody" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoomKeyRequestResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Ask the assistant to resend a room key this device missed (self)", "tags": [ "matrix", "matrix" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/matrix/rooms": { "get": { "description": "List all Matrix rooms for the current tenant with project mappings.", "operationId": "listRooms", "parameters": [ { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/RoomResponse" }, "title": "Response Listrooms", "type": "array" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List Matrix rooms for the current tenant", "tags": [ "matrix" ] } }, "/api/v1/matrix/rooms/{dest_room_id}/forward": { "post": { "operationId": "forwardMatrixMessage", "parameters": [ { "in": "path", "name": "dest_room_id", "required": true, "schema": { "title": "Dest Room Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForwardMessageRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForwardMessageResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Forward Message", "x-mcp-skip": true } }, "/api/v1/matrix/rooms/{room_id}": { "patch": { "operationId": "patchChannel", "parameters": [ { "in": "path", "name": "room_id", "required": true, "schema": { "title": "Room Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChannelPatchRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_service__routers__channels__OkResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Update channel metadata (name, topic, description, visibility, archived)", "tags": [ "matrix" ] } }, "/api/v1/matrix/rooms/{room_id}/bookmarks": { "get": { "operationId": "listChannelBookmarks", "parameters": [ { "in": "path", "name": "room_id", "required": true, "schema": { "title": "Room Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/BookmarkResponse" }, "title": "Response Listchannelbookmarks", "type": "array" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List channel bookmarks", "tags": [ "matrix" ] }, "post": { "operationId": "createChannelBookmark", "parameters": [ { "in": "path", "name": "room_id", "required": true, "schema": { "title": "Room Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookmarkCreateRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookmarkResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Create a channel bookmark", "tags": [ "matrix" ] } }, "/api/v1/matrix/rooms/{room_id}/bookmarks/{bookmark_id}": { "delete": { "operationId": "deleteChannelBookmark", "parameters": [ { "in": "path", "name": "room_id", "required": true, "schema": { "title": "Room Id", "type": "string" } }, { "in": "path", "name": "bookmark_id", "required": true, "schema": { "title": "Bookmark Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_service__routers__channels__OkResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Delete a channel bookmark", "tags": [ "matrix" ] }, "patch": { "operationId": "updateChannelBookmark", "parameters": [ { "in": "path", "name": "room_id", "required": true, "schema": { "title": "Room Id", "type": "string" } }, { "in": "path", "name": "bookmark_id", "required": true, "schema": { "title": "Bookmark Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookmarkPatchRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookmarkResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Update a channel bookmark", "tags": [ "matrix" ] } }, "/api/v1/matrix/rooms/{room_id}/canvas": { "post": { "operationId": "ensureChannelCanvas", "parameters": [ { "in": "path", "name": "room_id", "required": true, "schema": { "title": "Room Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChannelCanvasResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Ensure and open the canonical Canvas note for a channel", "tags": [ "matrix" ], "x-mcp-skip": true, "x-mcp-skip-reason": "Browser workspace tab bootstrap; MCP opens notes directly." } }, "/api/v1/matrix/rooms/{room_id}/files": { "post": { "description": "Upload a file and stamp its room membership on the canonical file row.", "operationId": "attachChannelFile", "parameters": [ { "in": "path", "name": "room_id", "required": true, "schema": { "title": "Room Id", "type": "string" } } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/Body_attachChannelFile" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Attach a file to a channel", "tags": [ "matrix" ] } }, "/api/v1/matrix/rooms/{room_id}/files/{file_id}": { "delete": { "operationId": "detachChannelFile", "parameters": [ { "in": "path", "name": "room_id", "required": true, "schema": { "title": "Room Id", "type": "string" } }, { "in": "path", "name": "file_id", "required": true, "schema": { "title": "File Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_service__routers__channels__OkResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Detach a file from a channel", "tags": [ "matrix" ] } }, "/api/v1/matrix/rooms/{room_id}/huddles/active": { "get": { "operationId": "getActiveMatrixHuddle", "parameters": [ { "in": "path", "name": "room_id", "required": true, "schema": { "title": "Room Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HuddleResponse" }, { "type": "null" } ], "title": "Response Getactivematrixhuddle" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Active Huddle", "tags": [ "matrix" ], "x-mcp-skip": true } }, "/api/v1/matrix/rooms/{room_id}/huddles/start": { "post": { "operationId": "startMatrixHuddle", "parameters": [ { "in": "path", "name": "room_id", "required": true, "schema": { "title": "Room Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/StartHuddleRequest" }, { "type": "null" } ], "title": "Body" } } } }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HuddleResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Start Huddle", "tags": [ "matrix" ], "x-mcp-skip": true } }, "/api/v1/matrix/rooms/{room_id}/invite": { "post": { "operationId": "inviteChannelMember", "parameters": [ { "in": "path", "name": "room_id", "required": true, "schema": { "title": "Room Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InviteMemberRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_service__routers__channels__OkResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Invite a tenant member to a channel", "tags": [ "matrix" ] } }, "/api/v1/matrix/rooms/{room_id}/invite-external": { "post": { "operationId": "inviteExternalGuest", "parameters": [ { "in": "path", "name": "room_id", "required": true, "schema": { "title": "Room Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InviteExternalRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InviteExternalResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Invite an external email address as a guest scoped to this room", "tags": [ "guests" ] } }, "/api/v1/matrix/rooms/{room_id}/join": { "post": { "description": "Caller joins a public_in_workspace channel directly.\n\nPrivate / restricted channels must go through invite (S1) or join-request\n(S6) — this endpoint returns 403 for them.", "operationId": "joinChannel", "parameters": [ { "in": "path", "name": "room_id", "required": true, "schema": { "title": "Room Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_service__routers__channels__OkResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Self-join a public_in_workspace channel", "tags": [ "matrix" ] } }, "/api/v1/matrix/rooms/{room_id}/join-requests": { "get": { "operationId": "listChannelJoinRequests", "parameters": [ { "in": "path", "name": "room_id", "required": true, "schema": { "title": "Room Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/JoinRequestResponse" }, "title": "Response Listchanneljoinrequests", "type": "array" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List pending + recent join requests (moderator only)", "tags": [ "matrix" ] }, "post": { "operationId": "createChannelJoinRequest", "parameters": [ { "in": "path", "name": "room_id", "required": true, "schema": { "title": "Room Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JoinRequestCreateRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JoinRequestResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Request to join a restricted channel", "tags": [ "matrix" ] } }, "/api/v1/matrix/rooms/{room_id}/join-requests/{request_id}": { "delete": { "operationId": "cancelChannelJoinRequest", "parameters": [ { "in": "path", "name": "room_id", "required": true, "schema": { "title": "Room Id", "type": "string" } }, { "in": "path", "name": "request_id", "required": true, "schema": { "title": "Request Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_service__routers__channels__OkResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Cancel own pending join request", "tags": [ "matrix" ] } }, "/api/v1/matrix/rooms/{room_id}/join-requests/{request_id}/decision": { "post": { "operationId": "decideChannelJoinRequest", "parameters": [ { "in": "path", "name": "room_id", "required": true, "schema": { "title": "Room Id", "type": "string" } }, { "in": "path", "name": "request_id", "required": true, "schema": { "title": "Request Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JoinRequestDecisionRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_service__routers__channels__OkResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Approve or deny a pending join request (moderator only)", "tags": [ "matrix" ] } }, "/api/v1/matrix/rooms/{room_id}/leave": { "post": { "operationId": "leaveChannel", "parameters": [ { "in": "path", "name": "room_id", "required": true, "schema": { "title": "Room Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_service__routers__channels__OkResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Leave a channel (cannot leave the tenant seed/general room)", "tags": [ "matrix" ] } }, "/api/v1/matrix/rooms/{room_id}/members": { "get": { "operationId": "listMatrixRoomMembersForMentions", "parameters": [ { "in": "path", "name": "room_id", "required": true, "schema": { "title": "Room Id", "type": "string" } }, { "in": "query", "name": "query", "required": false, "schema": { "default": "", "maxLength": 80, "title": "Query", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MatrixRoomMembersResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List Matrix mention candidates for the current tenant room", "tags": [ "matrix" ] } }, "/api/v1/matrix/rooms/{room_id}/members/{target_account_id}": { "delete": { "operationId": "kickChannelMember", "parameters": [ { "in": "path", "name": "room_id", "required": true, "schema": { "title": "Room Id", "type": "string" } }, { "in": "path", "name": "target_account_id", "required": true, "schema": { "title": "Target Account Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChannelMemberRemovedResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Remove a member from a channel (requires moderator PL)", "tags": [ "matrix" ] } }, "/api/v1/matrix/rooms/{room_id}/messages": { "get": { "description": "Return recent text messages for a tenant-scoped Matrix room.\n\nThe caller authenticates to Tidy with the browser session. api-service\nobtains the caller's Matrix credentials internally and does not expose the\nMatrix access token to extension code.", "operationId": "listMatrixRoomMessages", "parameters": [ { "in": "path", "name": "room_id", "required": true, "schema": { "title": "Room Id", "type": "string" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 40, "title": "Limit", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MatrixRoomMessagesResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List recent Matrix room messages for the current tenant member", "tags": [ "matrix" ] } }, "/api/v1/matrix/rooms/{room_id}/messages/{event_id}": { "delete": { "operationId": "deleteMatrixRoomMessage", "parameters": [ { "in": "path", "name": "room_id", "required": true, "schema": { "title": "Room Id", "type": "string" } }, { "in": "path", "name": "event_id", "required": true, "schema": { "title": "Event Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteMessageRequest", "default": {} } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteMessageResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Delete a Matrix message via m.room.redaction", "tags": [ "matrix" ], "x-mcp-skip": true } }, "/api/v1/matrix/rooms/{room_id}/messages/{event_id}/edit": { "post": { "operationId": "editMatrixRoomMessage", "parameters": [ { "in": "path", "name": "room_id", "required": true, "schema": { "title": "Room Id", "type": "string" } }, { "in": "path", "name": "event_id", "required": true, "schema": { "title": "Event Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EditMessageRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EditMessageResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Edit a previously sent Matrix message via m.replace", "tags": [ "matrix" ], "x-mcp-skip": true } }, "/api/v1/matrix/rooms/{room_id}/messages/{event_id}/reply": { "post": { "operationId": "replyToMatrixRoomMessage", "parameters": [ { "in": "path", "name": "room_id", "required": true, "schema": { "title": "Room Id", "type": "string" } }, { "in": "path", "name": "event_id", "required": true, "schema": { "title": "Event Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReplyMatrixRoomMessageRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MatrixRoomMessageResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Reply to a Matrix room message in the main timeline", "tags": [ "matrix" ] } }, "/api/v1/matrix/rooms/{room_id}/pins": { "get": { "operationId": "listMatrixRoomPins", "parameters": [ { "in": "path", "name": "room_id", "required": true, "schema": { "title": "Room Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/PinResponse" }, "title": "Response Listmatrixroompins", "type": "array" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List Room Pins", "x-mcp-skip": true }, "patch": { "operationId": "reorderMatrixRoomPins", "parameters": [ { "in": "path", "name": "room_id", "required": true, "schema": { "title": "Room Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReorderPinsRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_service__routers__matrix_message_management__OkResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Reorder Room Pins", "x-mcp-skip": true }, "post": { "operationId": "pinMatrixRoomMessage", "parameters": [ { "in": "path", "name": "room_id", "required": true, "schema": { "title": "Room Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PinRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PinResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Pin Message", "x-mcp-skip": true } }, "/api/v1/matrix/rooms/{room_id}/pins/{event_id}": { "delete": { "operationId": "unpinMatrixRoomMessage", "parameters": [ { "in": "path", "name": "room_id", "required": true, "schema": { "title": "Room Id", "type": "string" } }, { "in": "path", "name": "event_id", "required": true, "schema": { "title": "Event Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_service__routers__matrix_message_management__OkResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Unpin Message", "x-mcp-skip": true } }, "/api/v1/matrix/rooms/{room_id}/polls": { "post": { "operationId": "createMatrixPoll", "parameters": [ { "in": "path", "name": "room_id", "required": true, "schema": { "title": "Room Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePollRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PollResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Create Poll", "tags": [ "matrix" ], "x-mcp-skip": true } }, "/api/v1/matrix/rooms/{room_id}/reactions/{event_id}/reactors": { "get": { "operationId": "listMatrixMessageReactors", "parameters": [ { "in": "path", "name": "room_id", "required": true, "schema": { "title": "Room Id", "type": "string" } }, { "in": "path", "name": "event_id", "required": true, "schema": { "title": "Event Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": { "items": { "type": "string" }, "type": "array" }, "title": "Response Listmatrixmessagereactors", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List Reactors", "x-mcp-skip": true } }, "/api/v1/matrix/rooms/{room_id}/send-message": { "post": { "operationId": "sendMatrixRoomMessage", "parameters": [ { "in": "path", "name": "room_id", "required": true, "schema": { "title": "Room Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendMatrixRoomMessageRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendMatrixRoomMessageResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Send a Matrix room message as the current tenant member", "tags": [ "matrix" ] } }, "/api/v1/matrix/rooms/{room_id}/share": { "delete": { "operationId": "leaveSharedMatrixRoom", "parameters": [ { "in": "path", "name": "room_id", "required": true, "schema": { "title": "Room Id", "type": "string" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Leave a federated shared channel", "tags": [ "matrix-federation" ] }, "post": { "operationId": "shareMatrixRoom", "parameters": [ { "in": "path", "name": "room_id", "required": true, "schema": { "title": "Room Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShareChannelRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShareChannelResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Share a Matrix room with a peer workspace via federation", "tags": [ "matrix-federation" ] } }, "/api/v1/matrix/rooms/{room_id}/tabs": { "get": { "operationId": "listRoomTabs", "parameters": [ { "in": "path", "name": "room_id", "required": true, "schema": { "title": "Room Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/TabResponse" }, "title": "Response Listroomtabs", "type": "array" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List Room Tabs", "x-mcp-skip": true }, "patch": { "operationId": "reorderRoomTabs", "parameters": [ { "in": "path", "name": "room_id", "required": true, "schema": { "title": "Room Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReorderTabsRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TabOkResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Reorder Room Tabs", "x-mcp-skip": true }, "post": { "operationId": "createRoomTab", "parameters": [ { "in": "path", "name": "room_id", "required": true, "schema": { "title": "Room Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTabRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TabResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Create Room Tab", "x-mcp-skip": true } }, "/api/v1/matrix/rooms/{room_id}/tabs/{tab_id}": { "delete": { "operationId": "deleteRoomTab", "parameters": [ { "in": "path", "name": "room_id", "required": true, "schema": { "title": "Room Id", "type": "string" } }, { "in": "path", "name": "tab_id", "required": true, "schema": { "title": "Tab Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TabOkResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Delete Room Tab", "x-mcp-skip": true }, "patch": { "operationId": "renameRoomTab", "parameters": [ { "in": "path", "name": "room_id", "required": true, "schema": { "title": "Room Id", "type": "string" } }, { "in": "path", "name": "tab_id", "required": true, "schema": { "title": "Tab Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RenameTabRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TabResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Rename Room Tab", "x-mcp-skip": true } }, "/api/v1/matrix/rooms/{room_id}/threads/{root_event_id}/read": { "put": { "description": "Thread read-receipt projection write (TIDY-15464): member-authorized,\nroot-scoped, idempotent per operation_id, monotonic by homeserver event\norder. Never touches room-level unread markers.", "operationId": "markMatrixThreadRead", "parameters": [ { "in": "path", "name": "room_id", "required": true, "schema": { "title": "Room Id", "type": "string" } }, { "in": "path", "name": "root_event_id", "required": true, "schema": { "title": "Root Event Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ThreadReadRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ThreadReadResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Mark Thread Read", "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/matrix/rooms/{room_id}/unread": { "delete": { "operationId": "clearMatrixRoomUnread", "parameters": [ { "in": "path", "name": "room_id", "required": true, "schema": { "title": "Room Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_service__routers__matrix_message_management__OkResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Clear Room Unread", "x-mcp-skip": true }, "post": { "operationId": "markMatrixRoomUnread", "parameters": [ { "in": "path", "name": "room_id", "required": true, "schema": { "title": "Room Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarkUnreadRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_service__routers__matrix_message_management__OkResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Mark Room Unread", "x-mcp-skip": true } }, "/api/v1/matrix/saved": { "post": { "operationId": "saveMatrixMessage", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SaveMessageRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SavedMessageResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Save Message", "x-mcp-skip": true } }, "/api/v1/matrix/saved/{saved_id}": { "delete": { "operationId": "unsaveMatrixMessage", "parameters": [ { "in": "path", "name": "saved_id", "required": true, "schema": { "format": "uuid", "title": "Saved Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_service__routers__matrix_message_management__OkResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Unsave Message", "x-mcp-skip": true }, "patch": { "operationId": "updateSavedMatrixMessageNote", "parameters": [ { "in": "path", "name": "saved_id", "required": true, "schema": { "format": "uuid", "title": "Saved Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSavedRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_service__routers__matrix_message_management__OkResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Update Saved Note", "x-mcp-skip": true } }, "/api/v1/matrix/scheduled": { "get": { "operationId": "listScheduledMatrixMessages", "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/ScheduledMessageResponse" }, "title": "Response Listscheduledmatrixmessages", "type": "array" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List Scheduled Messages", "x-mcp-skip": true }, "post": { "operationId": "scheduleMatrixMessage", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScheduledMessageRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScheduledMessageResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Schedule Message", "x-mcp-skip": true } }, "/api/v1/matrix/scheduled/{scheduled_id}": { "delete": { "operationId": "cancelScheduledMatrixMessage", "parameters": [ { "in": "path", "name": "scheduled_id", "required": true, "schema": { "format": "uuid", "title": "Scheduled Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_service__routers__matrix_message_management__OkResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Cancel Scheduled Message", "x-mcp-skip": true }, "patch": { "operationId": "updateScheduledMatrixMessage", "parameters": [ { "in": "path", "name": "scheduled_id", "required": true, "schema": { "format": "uuid", "title": "Scheduled Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateScheduledMessageRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScheduledMessageResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Update Scheduled Message", "x-mcp-skip": true } }, "/api/v1/matrix/threads/follow": { "post": { "operationId": "followMatrixThread", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SaveMessageRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_service__routers__matrix_message_management__OkResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Follow Thread", "x-mcp-skip": true } }, "/api/v1/matrix/threads/follow/{follow_id}": { "delete": { "operationId": "unfollowMatrixThread", "parameters": [ { "in": "path", "name": "follow_id", "required": true, "schema": { "format": "uuid", "title": "Follow Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_service__routers__matrix_message_management__OkResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Unfollow Thread", "x-mcp-skip": true } }, "/api/v1/matrix/threads/follows": { "get": { "operationId": "listFollowedMatrixThreads", "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/SavedMessageResponse" }, "title": "Response Listfollowedmatrixthreads", "type": "array" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List Thread Follows", "x-mcp-skip": true } }, "/api/v1/matrix/token": { "get": { "description": "Return Matrix credentials for the authenticated user.\n\nIf the user is not yet provisioned, auto-provisions them first.", "operationId": "getMatrixToken", "parameters": [ { "in": "header", "name": "X-Tidy-Matrix-Device-Id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tidy-Matrix-Device-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MatrixTokenResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Exchange Supabase JWT for Matrix credentials", "tags": [ "matrix" ] } }, "/api/v1/matrix/workspace-members": { "get": { "description": "Return tenant members for the picker, with optional search filter.", "operationId": "listDmWorkspaceMembers", "parameters": [ { "in": "query", "name": "q", "required": false, "schema": { "default": "", "maxLength": 80, "title": "Q", "type": "string" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 30, "maximum": 50, "minimum": 1, "title": "Limit", "type": "integer" } }, { "in": "query", "name": "include_bots", "required": false, "schema": { "default": true, "title": "Include Bots", "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceMembersResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List workspace members for the DM contact picker", "tags": [ "matrix" ] } }, "/api/v1/me/agent-runs": { "get": { "operationId": "listMyAgentRuns", "parameters": [ { "in": "query", "name": "agent_name", "required": false, "schema": { "anyOf": [ { "maxLength": 64, "type": "string" }, { "type": "null" } ], "title": "Agent Name" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 20, "maximum": 100, "minimum": 1, "title": "Limit", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentRunListResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List my recent background-agent runs", "tags": [ "agents", "agents" ], "x-mcp-skip": true, "x-mcp-skip-reason": "Per-user agent run history for the browser settings UI." } }, "/api/v1/me/agents/dreamer/pause": { "post": { "operationId": "pauseMyDreamer", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DreamerPauseRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DreamerPauseResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Pause (or unpause) my Dreamer", "tags": [ "agents", "agents" ], "x-mcp-skip": true, "x-mcp-skip-reason": "User/admin settings toggle for the browser UI." } }, "/api/v1/me/agents/dreamer/state": { "get": { "operationId": "getMyDreamerState", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DreamerStateResponse" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get my Dreamer pause state and recent-run summary", "tags": [ "agents", "agents" ], "x-mcp-skip": true, "x-mcp-skip-reason": "User/admin settings toggle for the browser UI." } }, "/api/v1/me/extraction-defaults": { "get": { "operationId": "getMyExtractionDefaults", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExtractionDefaultsResponse" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get my default extraction destinations", "tags": [ "extractions", "extractions" ], "x-mcp-skip": true, "x-mcp-skip-reason": "User/admin settings for the browser approval UI." }, "put": { "operationId": "putMyExtractionDefaults", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExtractionDefaultsBody" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExtractionDefaultsResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Set my default extraction destinations", "tags": [ "extractions", "extractions" ], "x-mcp-skip": true, "x-mcp-skip-reason": "User/admin settings for the browser approval UI." } }, "/api/v1/me/insights": { "get": { "description": "Return the caller's self peer card — their own ``account``-target insights.\n\nTIDY-11517 (S8): the principal IS the target. The overlay is RLS-filtered to\nthe caller's own (private) account-target facets. This feeds the editable\n\"About you\" section in Settings → Profile (the section also reads local-first\nvia PowerSync; this route is the REST/MCP-readable surface + mobile ad-hoc).", "operationId": "getSelfInsightOverlay", "parameters": [ { "in": "query", "name": "limit", "required": false, "schema": { "default": 40, "maximum": 40, "minimum": 1, "title": "Limit", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InsightOverlayResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Self Insight Overlay", "tags": [ "insights", "insights" ], "x-mcp-skip": true } }, "/api/v1/me/podcast-data-export": { "post": { "description": "Self-service GDPR export of the caller's tenant-scoped podcast data +\nreferenced corpus context (D71). Blocked if the caller has no membership\n(data already deleted).", "operationId": "exportMyPodcastData", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExportResult" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Export My Podcast Data", "tags": [ "podcast", "podcast" ] } }, "/api/v1/me/tenant-memberships": { "get": { "description": "Returns the caller's tenant memberships ordered `is_primary DESC, last_active_at DESC NULLS LAST`. Replaces the PostgREST `person_account_memberships` read that `hooks.server.ts` ran on every request to resolve the active tenant (TIDY-12311). Authenticated by the Tidy ES256 bearer; the caller is resolved from the token `sub` — this endpoint never accepts a client-supplied account id. It does NOT resolve or gate on a single active tenant (no 402/404 for tenant state), so the hot path can pick its own preferred tenant from the full list.", "operationId": "getMyTenantMemberships", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantMembershipsResponse" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List the caller's tenant memberships", "tags": [ "accounts-me" ], "x-mcp-skip": true } }, "/api/v1/meetings/{meeting_id}": { "get": { "description": "The meeting's transcript + speaker map for the detail/rename surface\n(S5). Owner-only (D7) — 404 when not the caller's meeting.", "operationId": "getMeetingUpload", "parameters": [ { "in": "path", "name": "meeting_id", "required": true, "schema": { "title": "Meeting Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MeetingDetailResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Meeting", "tags": [ "meetings" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Owner-private meeting detail read for the web transcript/rename surface; the synced row is read local-first." } }, "/api/v1/meetings/{meeting_id}/speakers": { "patch": { "description": "Rename / assign a meeting's speakers (S5 — D9/D10). Re-attributes the\ntranscript, re-renders the summary note from the persisted structure (NO\nLLM call), and re-owns the affected extracted tasks — one transaction.\nOwner-only (D7).", "operationId": "renameMeetingSpeakers", "parameters": [ { "in": "path", "name": "meeting_id", "required": true, "schema": { "title": "Meeting Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RenameSpeakersRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RenameSpeakersResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Rename Speakers", "tags": [ "meetings" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Web speaker-rename affordance on the meeting transcript surface; not an agent tool." } }, "/api/v1/memory/corrections": { "post": { "description": "Retire the named memory row and emit the negative reinforcement signal.\n\nIdempotent: correcting an already-corrected row returns 200 with ``action``\nreflecting the row's current state and produces no duplicate signal or\naudit row. Rows outside the caller's member-visible predicate are 404;\nepisodic rows require an acting agent (403); unknown kinds are 422.", "operationId": "correctMemory", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemoryCorrectionRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemoryCorrectionResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Correct (retire) a wrong memory", "tags": [ "memory" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Reached by agents through the assistant correction tool tidy_memory_correct (TIDY-14271), which wraps this endpoint; not a standalone MCP tool surface." } }, "/api/v1/memory/remember": { "post": { "description": "Write the fact to the principal's substrate and (if actionable) a reminder.\n\nThe substrate fact is owned by the resolved single principal; the recall\nself-card leg surfaces it on every later turn. Rows are never argued with —\na later contradiction is handled by the correction lane (TIDY-14270).", "operationId": "rememberFact", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemoryRememberRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemoryRememberResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Remember a user-stated fact (substrate + primitive)", "tags": [ "memory" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Reached by agents through the assistant tidy_remember tool (TIDY-14298), which wraps this endpoint; not a standalone MCP tool surface." } }, "/api/v1/memory/search": { "post": { "description": "Run a pull-mode recall for the caller and return labelled memory hits.", "operationId": "searchMemory", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemorySearchRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemorySearchResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Pull-mode memory search under the single principal", "tags": [ "memory" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Reached by agents through the assistant tidy_memory_search tool (TIDY-14298), which wraps this endpoint; not a standalone MCP tool surface." } }, "/api/v1/model-pricing": { "get": { "description": "List all model pricing for UI components. No admin auth needed.", "operationId": "listModelPricingPublic", "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/ModelPricingRow" }, "title": "Response Listmodelpricingpublic", "type": "array" } } }, "description": "Successful Response" } }, "summary": "List model pricing (public read)", "tags": [ "admin-pricing" ] } }, "/api/v1/native-email/rollout/policy": { "get": { "operationId": "getNativeEmailRolloutPolicy", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RolloutPolicyResponse" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Policy", "tags": [ "native-email" ], "x-local-capability": "cloud", "x-mcp-skip": true }, "put": { "operationId": "activateNativeEmailRolloutPolicy", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RolloutPolicyRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RolloutPolicyResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Put Policy", "tags": [ "native-email" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/native-email/rollout/verdicts": { "post": { "operationId": "recordNativeEmailDogfoodVerdict", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DogfoodVerdictRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DogfoodVerdictResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Post Verdict", "tags": [ "native-email" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/news-updates": { "get": { "description": "List news updates with filtering, pagination, and sorting.\n\n**Authentication**: Requires valid JWT token.\n**Authorization**: Returns only updates for user's tenant(s).\n\n**Query Parameters**:\n- `limit`: Number of results (1-100, default 50)\n- `offset`: Pagination offset (default 0)\n- `category`: Filter by category (arts, sports, academic, etc.)\n- `read_status`: Filter by read status (all, read, unread)\n- `start_date`: Filter published_at >= start_date (ISO 8601)\n- `end_date`: Filter published_at <= end_date (ISO 8601)\n- `search`: Full-text search query\n- `sort`: Sort order (published_at_desc, published_at_asc, importance_desc)\n\n**Response (200 OK)**:\n```json\n{\n \"updates\": [{...}, {...}],\n \"pagination\": {\n \"total\": 127,\n \"limit\": 50,\n \"offset\": 0,\n \"has_more\": true\n }\n}\n```", "operationId": "listNewsUpdates", "parameters": [ { "description": "Number of results (max 100)", "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "description": "Number of results (max 100)", "maximum": 100, "minimum": 1, "title": "Limit", "type": "integer" } }, { "description": "Pagination offset", "in": "query", "name": "offset", "required": false, "schema": { "default": 0, "description": "Pagination offset", "minimum": 0, "title": "Offset", "type": "integer" } }, { "description": "Filter by category", "in": "query", "name": "category", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by category", "title": "Category" } }, { "description": "Filter: all, read, unread", "in": "query", "name": "read_status", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter: all, read, unread", "title": "Read Status" } }, { "description": "Filter: 7days, 30days, 90days, all", "in": "query", "name": "date_range", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter: 7days, 30days, 90days, all", "title": "Date Range" } }, { "description": "Filter published_at >= start_date", "in": "query", "name": "start_date", "required": false, "schema": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "Filter published_at >= start_date", "title": "Start Date" } }, { "description": "Filter published_at <= end_date", "in": "query", "name": "end_date", "required": false, "schema": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "Filter published_at <= end_date", "title": "End Date" } }, { "description": "Full-text search query", "in": "query", "name": "search", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Full-text search query", "title": "Search" } }, { "description": "Sort order", "in": "query", "name": "sort", "required": false, "schema": { "default": "published_at_desc", "description": "Sort order", "title": "Sort", "type": "string" } }, { "in": "header", "name": "X-Trace-Id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewsUpdatesListResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List News Updates", "tags": [ "news-updates" ] } }, "/api/v1/news-updates/categories": { "get": { "description": "Get distinct categories from news updates for this tenant.\n\nReturns categories that actually have news updates, grouped by type.\nUsed by frontend to populate category filter dropdowns dynamically.\n\n**Response (200 OK)**:\n```json\n{\n \"categories\": [\n {\"value\": \"school\", \"label\": \"School\", \"count\": 15, \"group\": \"valuable\"},\n {\"value\": \"sports\", \"label\": \"Sports\", \"count\": 8, \"group\": \"valuable\"},\n ...\n ]\n}\n```", "operationId": "getNewsCategories", "parameters": [ { "in": "header", "name": "X-Trace-Id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Getnewscategories", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get News Categories", "tags": [ "news-updates" ] } }, "/api/v1/news-updates/ingest": { "post": { "description": "Batch ingest news updates (LLM extractor → API).\n\n**Authentication**: Requires valid JWT token.\n**Authorization**: User must belong to a tenant.\n**Rate Limit**: 20 requests/minute per tenant.\n\n**Request Body**:\n```json\n{\n \"updates\": [\n {\n \"title\": \"School Play Auditions\",\n \"content\": \"Auditions next week...\",\n \"source_type\": \"email\",\n \"category\": \"arts\",\n ...\n }\n ]\n}\n```\n\n**Response (201 Created)**:\n```json\n{\n \"status\": \"success\",\n \"message\": \"3 news updates ingested successfully\",\n \"created_ids\": [\"uuid1\", \"uuid2\", \"uuid3\"],\n \"tenant_id\": \"tenant-uuid-here\"\n}\n```\n\n**Error Responses**:\n- 400: Invalid request body (validation errors)\n- 401: Unauthorized (missing/invalid JWT)\n- 500: Internal server error", "operationId": "ingestNewsUpdates", "parameters": [ { "in": "header", "name": "X-Trace-Id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IngestRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IngestResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Ingest News Updates", "tags": [ "news-updates" ] } }, "/api/v1/news-updates/preferences": { "get": { "description": "Get user notification preferences.\n\nReturns defaults if preferences not set.\n\n**Authentication**: Requires valid JWT token.\n\n**Response (200 OK)**:\n```json\n{\n \"enabled_channels\": [\"in_app\", \"email\"],\n \"update_frequency\": \"daily\",\n \"summary_frequency\": \"weekly\",\n \"quiet_hours_start\": \"22:00:00\",\n \"quiet_hours_end\": \"07:00:00\",\n \"excluded_categories\": []\n}\n```", "operationId": "getNewsUpdatePreferences", "parameters": [ { "in": "header", "name": "X-Trace-Id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserNotificationPreferencesResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get User Preferences", "tags": [ "news-updates" ] }, "put": { "description": "Update user notification preferences.\n\n**Authentication**: Requires valid JWT token.\n\n**Request Body**:\n```json\n{\n \"enabled_channels\": [\"in_app\", \"email\", \"sms\"],\n \"update_frequency\": \"daily\",\n \"summary_frequency\": \"weekly\",\n \"quiet_hours_start\": \"22:00:00\",\n \"quiet_hours_end\": \"07:00:00\",\n \"excluded_categories\": [\"sports\"]\n}\n```\n\n**Response (200 OK)**: UserNotificationPreferencesResponse object\n**Error Responses**:\n- 400: Invalid field values\n- 401: Unauthorized\n- 500: Internal server error", "operationId": "updateUserPreferences", "parameters": [ { "in": "header", "name": "X-Trace-Id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserNotificationPreferencesUpdate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserNotificationPreferencesResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Update User Preferences", "tags": [ "news-updates" ] } }, "/api/v1/news-updates/summaries": { "get": { "description": "List news summaries (daily, weekly, monthly).\n\n**Authentication**: Requires valid JWT token.\n**Authorization**: Returns only summaries for user's tenant(s).\n\n**Response (200 OK)**:\n```json\n{\n \"summaries\": [{...}, {...}],\n \"pagination\": {\n \"total\": 12,\n \"limit\": 10,\n \"offset\": 0,\n \"has_more\": true\n }\n}\n```", "operationId": "listNewsSummaries", "parameters": [ { "description": "Filter: daily, weekly, monthly, custom", "in": "query", "name": "summary_type", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter: daily, weekly, monthly, custom", "title": "Summary Type" } }, { "description": "Filter period_start >= start_date", "in": "query", "name": "start_date", "required": false, "schema": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "Filter period_start >= start_date", "title": "Start Date" } }, { "description": "Filter period_end <= end_date", "in": "query", "name": "end_date", "required": false, "schema": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "Filter period_end <= end_date", "title": "End Date" } }, { "description": "Number of results (max 50)", "in": "query", "name": "limit", "required": false, "schema": { "default": 10, "description": "Number of results (max 50)", "maximum": 50, "minimum": 1, "title": "Limit", "type": "integer" } }, { "description": "Pagination offset", "in": "query", "name": "offset", "required": false, "schema": { "default": 0, "description": "Pagination offset", "minimum": 0, "title": "Offset", "type": "integer" } }, { "in": "header", "name": "X-Trace-Id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewsSummariesListResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List News Summaries", "tags": [ "news-updates" ] } }, "/api/v1/news-updates/summaries/{summary_id}": { "get": { "description": "Get a single news summary by ID.\n\n**Authentication**: Requires valid JWT token.\n**Authorization**: Returns summary only if user has access.\n\n**Response (200 OK)**: NewsSummaryResponse object\n**Error Responses**:\n- 401: Unauthorized\n- 404: Summary not found\n- 500: Internal server error", "operationId": "getNewsSummary", "parameters": [ { "in": "path", "name": "summary_id", "required": true, "schema": { "format": "uuid", "title": "Summary Id", "type": "string" } }, { "in": "header", "name": "X-Trace-Id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewsSummaryResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get News Summary", "tags": [ "news-updates" ] }, "put": { "description": "Update a news summary read-state for the current account.\n\n Actions:\n - mark_read: appends account_id to read_by array (idempotent).\n - mark_unread: removes account_id from read_by array (idempotent).\n\n Related: TIDY-7366 (SDK-vs-spec contract drift reconciliation).", "operationId": "updateNewsSummary", "parameters": [ { "in": "path", "name": "summary_id", "required": true, "schema": { "format": "uuid", "title": "Summary Id", "type": "string" } }, { "in": "header", "name": "X-Trace-Id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewsSummaryUpdate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewsSummaryUpdateResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Update news summary read-state", "tags": [ "news-updates" ] } }, "/api/v1/news-updates/{update_id}": { "delete": { "description": "Soft delete news update (Owners only).\n\n**Authentication**: Requires valid JWT token.\n**Authorization**: User must be Owner of the tenant.\n\n**Response (200 OK)**:\n```json\n{\n \"status\": \"success\",\n \"message\": \"Update deleted successfully\",\n \"update_id\": \"uuid-here\"\n}\n```\n\n**Error Responses**:\n- 401: Unauthorized\n- 403: Forbidden (not Owner)\n- 404: Update not found\n- 500: Internal server error", "operationId": "deleteNewsUpdate", "parameters": [ { "in": "path", "name": "update_id", "required": true, "schema": { "format": "uuid", "title": "Update Id", "type": "string" } }, { "in": "header", "name": "X-Trace-Id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Deletenewsupdate", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Delete News Update", "tags": [ "news-updates" ] }, "get": { "description": "Get a single news update by ID.\n\n**Authentication**: Requires valid JWT token.\n**Authorization**: Returns update only if user has access (tenant member).\n\n**Response (200 OK)**: NewsUpdateResponse object\n**Error Responses**:\n- 401: Unauthorized\n- 404: Update not found or access denied\n- 500: Internal server error", "operationId": "getNewsUpdate", "parameters": [ { "in": "path", "name": "update_id", "required": true, "schema": { "format": "uuid", "title": "Update Id", "type": "string" } }, { "in": "header", "name": "X-Trace-Id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewsUpdateResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get News Update", "tags": [ "news-updates" ] }, "put": { "description": "Update news update (mark read/unread, dismiss/undismiss).\n\n**Authentication**: Requires valid JWT token.\n**Authorization**: User must have access to the update.\n\n**Request Body**:\n```json\n{\n \"action\": \"mark_read\" // or \"mark_unread\", \"dismiss\", \"undismiss\"\n}\n```\n\n**Response (200 OK)**:\n```json\n{\n \"status\": \"success\",\n \"message\": \"Update marked as read\",\n \"update_id\": \"uuid-here\",\n \"is_read\": true,\n \"is_dismissed\": false\n}\n```\n\n**Error Responses**:\n- 400: Invalid action\n- 401: Unauthorized\n- 404: Update not found\n- 500: Internal server error", "operationId": "updateNewsUpdate", "parameters": [ { "in": "path", "name": "update_id", "required": true, "schema": { "format": "uuid", "title": "Update Id", "type": "string" } }, { "in": "header", "name": "X-Trace-Id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewsUpdateUpdate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Updatenewsupdate", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Update News Update", "tags": [ "news-updates" ] } }, "/api/v1/notebooks": { "get": { "description": "List notebooks accessible to the current user (own + global + shared).", "operationId": "listNotebooks", "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/NotebookResponse" }, "title": "Response Listnotebooks", "type": "array" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List Notebooks", "tags": [ "notebooks" ] }, "post": { "description": "Create a new notebook.", "operationId": "createNotebook", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotebookCreate" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotebookResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Create Notebook", "tags": [ "notebooks" ] } }, "/api/v1/notebooks/{notebook_id}": { "delete": { "description": "Soft delete a notebook. Notes are moved to user's default notebook.", "operationId": "deleteNotebook", "parameters": [ { "description": "Typed ID with prefix 'B'", "in": "path", "name": "notebook_id", "required": true, "schema": { "description": "Typed ID with prefix 'B'", "title": "Notebook Id", "type": "string" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Delete Notebook", "tags": [ "notebooks" ] }, "get": { "description": "Get a single notebook by ID.", "operationId": "getNotebook", "parameters": [ { "description": "Typed ID with prefix 'B'", "in": "path", "name": "notebook_id", "required": true, "schema": { "description": "Typed ID with prefix 'B'", "title": "Notebook Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotebookResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Notebook", "tags": [ "notebooks" ] }, "patch": { "description": "Update notebook name, icon, color, sort_order, or promote to global.", "operationId": "updateNotebook", "parameters": [ { "description": "Typed ID with prefix 'B'", "in": "path", "name": "notebook_id", "required": true, "schema": { "description": "Typed ID with prefix 'B'", "title": "Notebook Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotebookUpdate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotebookResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Update Notebook", "tags": [ "notebooks" ] } }, "/api/v1/notebooks/{notebook_id}/members": { "get": { "description": "Get notebook owner + shared members.", "operationId": "listNotebookMembers", "parameters": [ { "description": "Typed ID with prefix 'B'", "in": "path", "name": "notebook_id", "required": true, "schema": { "description": "Typed ID with prefix 'B'", "title": "Notebook Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/NotebookMemberResponse" }, "title": "Response Listnotebookmembers", "type": "array" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List notebook members", "tags": [ "notebooks" ] }, "post": { "description": "Add a member to a notebook. Only notebook owner can add members.", "operationId": "addNotebookMember", "parameters": [ { "description": "Typed ID with prefix 'B'", "in": "path", "name": "notebook_id", "required": true, "schema": { "description": "Typed ID with prefix 'B'", "title": "Notebook Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotebookMemberCreate" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotebookMemberResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Add member to notebook", "tags": [ "notebooks" ] } }, "/api/v1/notebooks/{notebook_id}/members/{user_id}": { "delete": { "description": "Remove a member from a notebook. Only notebook owner can remove members.", "operationId": "removeNotebookMember", "parameters": [ { "in": "path", "name": "user_id", "required": true, "schema": { "title": "User Id", "type": "string" } }, { "description": "Typed ID with prefix 'B'", "in": "path", "name": "notebook_id", "required": true, "schema": { "description": "Typed ID with prefix 'B'", "title": "Notebook Id", "type": "string" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Remove member from notebook", "tags": [ "notebooks" ] } }, "/api/v1/notes": { "get": { "description": "List all notes for authenticated user's tenant with optional filtering.\n\n Query Parameters:\n note_type: Filter by type (gate_code|wifi|carpool|medical|emergency|reference|policy|contact_info|procedure)\n is_sensitive: Filter by sensitivity flag (true|false)\n location: Filter by location (partial match)\n search: Full-text search across title and body text\n email_id: Filter by email anchor (UUID)\n contact_id: Filter by contact anchor (UUID)\n event_id: Filter by event anchor (UUID)\n project_id: Filter to the notes in a project (UUID; notes.project_id)\n feed_target_date: Filter by feed date (YYYY-MM-DD)\n source: Filter by source (user|system|sms_agent)\n limit: Max results (1-1000), default: 100\n offset: Pagination offset, default: 0\n\n Returns:\n {\n \"notes\": [...],\n \"count\": 15\n }\n\n Multi-Tenant Isolation: Only returns notes for user's tenant.\n\n Related: Notes Feature, KCC-3305 (Unified Notes)", "operationId": "listNotes", "parameters": [ { "in": "query", "name": "note_type", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Note Type" } }, { "in": "query", "name": "is_sensitive", "required": false, "schema": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is Sensitive" } }, { "in": "query", "name": "location", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Location" } }, { "in": "query", "name": "search", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Search" } }, { "in": "query", "name": "email_id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Email Id" } }, { "in": "query", "name": "contact_id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Contact Id" } }, { "in": "query", "name": "event_id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Event Id" } }, { "in": "query", "name": "project_id", "required": false, "schema": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Project Id" } }, { "in": "query", "name": "feed_target_date", "required": false, "schema": { "anyOf": [ { "format": "date", "type": "string" }, { "type": "null" } ], "title": "Feed Target Date" } }, { "in": "query", "name": "source", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Source" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 100, "maximum": 1000, "minimum": 1, "title": "Limit", "type": "integer" } }, { "in": "query", "name": "offset", "required": false, "schema": { "default": 0, "minimum": 0, "title": "Offset", "type": "integer" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Listnotes", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List notes with filtering", "tags": [ "notes", "Notes" ] }, "post": { "description": "Create a new reference note.\n\n Request:\n {\n \"title\": \"School Gate Code\",\n \"content\": \"Gate code: 1234#\",\n \"note_type\": \"gate_code\",\n \"location\": \"Lincoln Elementary\",\n \"is_sensitive\": true\n }\n\n Response (201 Created):\n {\n \"id\": \"a1b2c3d4-...\",\n \"tenant_id\": \"tenant-uuid\",\n \"title\": \"School Gate Code\",\n \"content\": \"Gate code: 1234#\",\n \"note_type\": \"gate_code\",\n \"location\": \"Lincoln Elementary\",\n \"is_sensitive\": true,\n ...\n }\n\n Error Responses:\n - 400 Bad Request: Invalid note data\n - 401 Unauthorized: Missing or invalid JWT token\n - 403 Forbidden: PAT/service-account caller lacks `notes:write` scope\n - 404 Not Found: No tenant associated with account\n - 500 Internal Server Error: Database operation failed\n\n Related: Notes Feature", "operationId": "createNote2", "parameters": [ { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } }, { "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "maxLength": 128, "title": "Idempotency-Key" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NoteCreate" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NoteResponse" } } }, "description": "Successful Response", "headers": { "X-Tidy-Op-Id": { "schema": { "type": "string" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Create new note", "tags": [ "notes" ] } }, "/api/v1/notes/autocomplete": { "get": { "description": "Search contacts, notes, events, tasks for wiki link autocomplete.", "operationId": "autocomplete", "parameters": [ { "description": "Search term", "in": "query", "name": "q", "required": true, "schema": { "description": "Search term", "maxLength": 200, "minLength": 1, "title": "Q", "type": "string" } }, { "description": "Max results", "in": "query", "name": "limit", "required": false, "schema": { "default": 10, "description": "Max results", "maximum": 50, "minimum": 1, "title": "Limit", "type": "integer" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Autocomplete", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Wiki link autocomplete search (TIDY-3968)", "tags": [ "notes" ] } }, "/api/v1/notes/by-import-hash": { "get": { "description": "Narrow lookup used before DOCX/PPTX/XLSX import so the UI can prompt the user instead of silently creating a duplicate note. Returns `{exists: false}` when no note the caller can read has the given hash.", "operationId": "getNoteByImportHash", "parameters": [ { "description": "Hex-encoded file hash (SHA-256 in current clients).", "in": "query", "name": "hash", "required": true, "schema": { "description": "Hex-encoded file hash (SHA-256 in current clients).", "maxLength": 128, "minLength": 32, "title": "Hash", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NoteByImportHashResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Look up an existing note by its import_file_hash", "tags": [ "notes" ] } }, "/api/v1/notes/by-slug/{slug}": { "get": { "description": "Resolve a note by its slug (e.g. 2026-02-21 for journal pages).", "operationId": "getBySlug", "parameters": [ { "in": "path", "name": "slug", "required": true, "schema": { "title": "Slug", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NoteResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get note by slug (TIDY-4151)", "tags": [ "notes" ] } }, "/api/v1/notes/ensure-tag-page": { "post": { "description": "Idempotent tenant-scoped upsert for tag-backed standalone note pages.", "operationId": "ensureTagPage", "parameters": [ { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } }, { "in": "header", "name": "X-Internal-Service", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service" } }, { "in": "header", "name": "X-Internal-Service-Key", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service-Key" } }, { "in": "header", "name": "X-Tenant-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tenant-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnsureTagPageRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnsureTagPageResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Ensure a standalone note page exists for a tag", "tags": [ "notes", "Internal" ] } }, "/api/v1/notes/import/jobs": { "post": { "operationId": "createImportJob", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportJobCreateRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportJobCreateResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Create a new import job", "tags": [ "notes", "Note Import Jobs" ] } }, "/api/v1/notes/import/jobs/active": { "get": { "operationId": "getActiveImportJob", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportJobResponse" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get the active import job for the tenant", "tags": [ "notes", "Note Import Jobs" ] } }, "/api/v1/notes/import/jobs/{job_id}": { "delete": { "operationId": "cancelImportJob", "parameters": [ { "in": "path", "name": "job_id", "required": true, "schema": { "format": "uuid", "title": "Job Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportJobTransitionResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Cancel an import job", "tags": [ "notes", "Note Import Jobs" ] }, "get": { "operationId": "getImportJob", "parameters": [ { "in": "path", "name": "job_id", "required": true, "schema": { "format": "uuid", "title": "Job Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportJobResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get the current state of an import job", "tags": [ "notes", "Note Import Jobs" ] } }, "/api/v1/notes/import/jobs/{job_id}/review": { "post": { "operationId": "submitImportReview", "parameters": [ { "in": "path", "name": "job_id", "required": true, "schema": { "format": "uuid", "title": "Job Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportJobReviewRequest" } } }, "required": true }, "responses": { "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportJobTransitionResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Submit facet selections and start execution", "tags": [ "notes", "Note Import Jobs" ] } }, "/api/v1/notes/import/jobs/{job_id}/upload-complete": { "post": { "operationId": "markUploadComplete", "parameters": [ { "in": "path", "name": "job_id", "required": true, "schema": { "format": "uuid", "title": "Job Id", "type": "string" } } ], "responses": { "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportJobTransitionResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Mark upload complete and start analysis", "tags": [ "notes", "Note Import Jobs" ] } }, "/api/v1/notes/import/jobs/{job_id}/upload/abort": { "post": { "operationId": "abortImportUpload", "parameters": [ { "in": "path", "name": "job_id", "required": true, "schema": { "format": "uuid", "title": "Job Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportUploadAbortRequest" } } }, "required": true }, "responses": { "204": { "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Abort an in-progress multipart upload of the import archive", "tags": [ "notes", "Note Import Jobs" ], "x-mcp-skip": true, "x-mcp-skip-reason": "browser upload plumbing" } }, "/api/v1/notes/import/jobs/{job_id}/upload/complete": { "post": { "operationId": "completeImportUpload", "parameters": [ { "in": "path", "name": "job_id", "required": true, "schema": { "format": "uuid", "title": "Job Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportUploadCompleteRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportUploadCompleteResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Finalise the multipart upload of the import archive", "tags": [ "notes", "Note Import Jobs" ], "x-mcp-skip": true, "x-mcp-skip-reason": "browser upload plumbing" } }, "/api/v1/notes/import/jobs/{job_id}/upload/initiate": { "post": { "operationId": "initiateImportUpload", "parameters": [ { "in": "path", "name": "job_id", "required": true, "schema": { "format": "uuid", "title": "Job Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportUploadInitiateResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Begin an S3 multipart upload for the import archive", "tags": [ "notes", "Note Import Jobs" ], "x-mcp-skip": true, "x-mcp-skip-reason": "browser upload plumbing" } }, "/api/v1/notes/import/quota": { "get": { "operationId": "getImportQuota", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportQuotaResponse" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get import storage quota", "tags": [ "notes", "Note Import Jobs" ] } }, "/api/v1/notes/inbox": { "get": { "description": "List notes with pending or processed inbox_status for the tenant.", "operationId": "listInboxItems", "parameters": [ { "description": "Filter by inbox_status (pending, processed). Default: all non-null.", "in": "query", "name": "inbox_status", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by inbox_status (pending, processed). Default: all non-null.", "title": "Inbox Status" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "maximum": 500, "minimum": 1, "title": "Limit", "type": "integer" } }, { "in": "query", "name": "offset", "required": false, "schema": { "default": 0, "minimum": 0, "title": "Offset", "type": "integer" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Listinboxitems", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List inbox items", "tags": [ "note-inbox" ] } }, "/api/v1/notes/inbox/process/{note_id}": { "post": { "description": "Fetches note content, extracts URLs, generates title suggestion, suggests facets, and produces a summary. Does not auto-apply changes.", "operationId": "processInboxItem", "parameters": [ { "in": "path", "name": "note_id", "required": true, "schema": { "title": "Note Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InboxProcessResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "AI-process an inbox item", "tags": [ "note-inbox" ] } }, "/api/v1/notes/journal/{target_date}": { "get": { "description": "Legacy endpoint — redirects to /api/v1/journals/{date}.", "operationId": "getJournalRedirect", "parameters": [ { "in": "path", "name": "target_date", "required": true, "schema": { "format": "date", "title": "Target Date", "type": "string" } } ], "responses": { "308": { "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Redirect to /journals/{date} (TIDY-5657)", "tags": [ "notes" ] } }, "/api/v1/notes/merge": { "post": { "description": "Merge source notes into a target note.", "operationId": "mergeNotes", "parameters": [ { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MergeNotesRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MergeNotesResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Merge notes into target", "tags": [ "notes" ] } }, "/api/v1/notes/pages": { "get": { "description": "List all pages (journals + standalone) for the page navigator.", "operationId": "listPagesEndpoint", "parameters": [ { "description": "journal_page|standalone_page|drawing|all", "in": "query", "name": "type", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "journal_page|standalone_page|drawing|all", "title": "Type" } }, { "description": "Search pages by title", "in": "query", "name": "search", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Search pages by title", "title": "Search" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PagesListResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List journals and pages", "tags": [ "notes" ] }, "post": { "description": "Create a page (or materialize an existing phantom for standalone notes).", "operationId": "createPage", "parameters": [ { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageCreateRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NoteResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Create page", "tags": [ "notes" ] } }, "/api/v1/notes/phantom": { "post": { "description": "Create a wiki-link stub page (regular page with no content).\n\nThe phantom concept has been eliminated (TIDY-6078). This endpoint\nnow creates a regular empty page for backward compatibility.", "operationId": "createPhantom", "parameters": [ { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PhantomCreateRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NoteResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Create wiki-link stub page (backward compat)", "tags": [ "notes" ] } }, "/api/v1/notes/yjs-bulk": { "get": { "operationId": "yjsBulk", "parameters": [ { "description": "ISO 8601 timestamp — only return items updated after this time", "in": "query", "name": "since", "required": false, "schema": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "ISO 8601 timestamp — only return items updated after this time", "title": "Since" } }, { "description": "Room kind: note, drawing-note, contact, event, org, project, activity", "in": "query", "name": "kind", "required": false, "schema": { "default": "note", "description": "Room kind: note, drawing-note, contact, event, org, project, activity", "title": "Kind", "type": "string" } }, { "description": "TIDY-9671: when set, filter the stream to a single row by id. Used by the eager single-note pull path when the local ydoc_state_local cache misses but the primitive row exists. When set, the `since` parameter is ignored.", "in": "query", "name": "note_id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "TIDY-9671: when set, filter the stream to a single row by id. Used by the eager single-note pull path when the local ydoc_state_local cache misses but the primitive row exists. When set, the `since` parameter is ignored.", "title": "Note Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Yjsbulk", "type": "object" } }, "application/octet-stream": {} }, "description": "Successful Response" }, "204": { "description": "No items match" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Bulk download Y.doc binaries", "tags": [ "notes" ] } }, "/api/v1/notes/yjs-bulk-upload/apply": { "post": { "operationId": "applyYjsUpdates", "parameters": [ { "description": "Room kind: note, task, contact, event, org", "in": "query", "name": "kind", "required": false, "schema": { "default": "note", "description": "Room kind: note, task, contact, event, org", "title": "Kind", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_service__routers__notes__yjs_bulk_upload__ApplyRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplyResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Apply Y.doc CRDT updates to server state", "tags": [ "notes" ] } }, "/api/v1/notes/yjs-bulk-upload/compare": { "post": { "operationId": "compareStateVectors", "parameters": [ { "description": "Room kind: note, task, contact, event, org", "in": "query", "name": "kind", "required": false, "schema": { "default": "note", "description": "Room kind: note, task, contact, event, org", "title": "Kind", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompareRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompareResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Compare client state vectors against server", "tags": [ "notes" ] } }, "/api/v1/notes/{note_id}": { "delete": { "description": "Soft delete note (sets deleted_at timestamp).\n\n Note is not permanently removed from database.\n Preserved for audit trail.\n\n Returns 204 No Content on success.\n\n Error Responses:\n - 401 Unauthorized: Missing or invalid JWT token\n - 404 Not Found: Note does not exist or does not belong to user's tenant\n - 500 Internal Server Error: Database operation failed\n\n Related: Notes Feature", "operationId": "deleteNote2", "parameters": [ { "description": "Typed ID with prefix 'N'", "in": "path", "name": "note_id", "required": true, "schema": { "description": "Typed ID with prefix 'N'", "title": "Note Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Delete note", "tags": [ "notes" ] }, "get": { "description": "Retrieve details for a specific note.\n\n Response:\n {\n \"id\": \"a1b2c3d4-...\",\n \"tenant_id\": \"tenant-uuid\",\n \"title\": \"School Gate Code\",\n \"content\": \"Gate code: 1234#\",\n \"note_type\": \"gate_code\",\n ...\n }\n\n Error Responses:\n - 401 Unauthorized: Missing or invalid JWT token\n - 404 Not Found: Note does not exist or does not belong to user's tenant\n - 500 Internal Server Error: Database operation failed\n\n Related: Notes Feature", "operationId": "getNote", "parameters": [ { "description": "Typed ID with prefix 'N'", "in": "path", "name": "note_id", "required": true, "schema": { "description": "Typed ID with prefix 'N'", "title": "Note Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NoteResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get note details", "tags": [ "notes" ] }, "patch": { "description": "Update note fields using PATCH (partial update).\n\n Request (all fields optional):\n {\n \"is_sensitive\": true\n }\n\n Only provided fields are updated.\n\n Error Responses:\n - 400 Bad Request: Invalid update data\n - 401 Unauthorized: Missing or invalid JWT token\n - 404 Not Found: Note does not exist or does not belong to user's tenant\n - 500 Internal Server Error: Database operation failed\n\n Related: Notes Feature", "operationId": "updateNotePatch", "parameters": [ { "description": "Typed ID with prefix 'N'", "in": "path", "name": "note_id", "required": true, "schema": { "description": "Typed ID with prefix 'N'", "title": "Note Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NoteUpdate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NoteResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Update note (partial update)", "tags": [ "notes" ] }, "put": { "description": "Update note fields using PUT (full resource replace).\n\n Request (all fields optional):\n {\n \"title\": \"Updated title\",\n \"content\": \"Updated content\",\n \"note_type\": \"wifi\",\n \"is_sensitive\": false\n }\n\n Only provided fields are updated.\n\n Error Responses:\n - 400 Bad Request: Invalid update data\n - 401 Unauthorized: Missing or invalid JWT token\n - 404 Not Found: Note does not exist or does not belong to user's tenant\n - 500 Internal Server Error: Database operation failed\n\n Related: Notes Feature", "operationId": "updateNotePut", "parameters": [ { "description": "Typed ID with prefix 'N'", "in": "path", "name": "note_id", "required": true, "schema": { "description": "Typed ID with prefix 'N'", "title": "Note Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NoteUpdate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NoteResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Update note (full replace)", "tags": [ "notes" ] } }, "/api/v1/notes/{note_id}/append-markdown": { "post": { "description": "Append markdown to a note's body via Yjs CRDT operations.\n\nCanonical MCP append path. Replaces the legacy \"PATCH content\" flow\n(TIDY-9874) that round-tripped through a lossy XML-tagged plain_text\nprojection and silently destroyed wikiLinks, embeddedBlocks, and\nformatting marks.\n\nRow-level delegation (TIDY-19325): the caller's own note is written as the\ncaller even when the MCP adapter names its owner, and an owner's note is\nwritten under their ``notes`` read_write grant with the caller credited.\nA read-only grant is a 403 naming the grant; no grant is a 404.", "operationId": "appendMarkdownToNote", "parameters": [ { "description": "Typed ID with prefix 'N'", "in": "path", "name": "note_id", "required": true, "schema": { "description": "Typed ID with prefix 'N'", "title": "Note Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } }, { "in": "header", "name": "X-Tidy-Acting-Principal", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tidy-Acting-Principal" } }, { "in": "header", "name": "X-Internal-Service", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service" } }, { "in": "header", "name": "X-Internal-Service-Key", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service-Key" } }, { "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "maxLength": 128, "title": "Idempotency-Key" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NoteAppendMarkdownRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NoteResponse" } } }, "description": "Successful Response", "headers": { "X-Tidy-Op-Id": { "schema": { "type": "string" } }, "X-Tidy-Op-Outcome": { "description": "replayed: this Idempotency-Key had already landed; nothing was written again", "schema": { "enum": [ "applied", "replayed" ], "type": "string" } } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentConflictResponse" } } }, "description": "collab_liveness_unprovable (retry the same key) or idempotency_key_reused", "headers": { "Retry-After": { "schema": { "type": "integer" } }, "X-Tidy-Op-Id": { "schema": { "type": "string" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Append markdown to note body (Yjs-aware, TIDY-9874)", "tags": [ "notes" ] } }, "/api/v1/notes/{note_id}/append-markdown/status": { "get": { "description": "The status read for an append whose answer was lost — the journal\nroute's twin: anyone who can read the note may ask.", "operationId": "getNoteAppendMarkdownStatus", "parameters": [ { "description": "Typed ID with prefix 'N'", "in": "path", "name": "note_id", "required": true, "schema": { "description": "Typed ID with prefix 'N'", "title": "Note Id", "type": "string" } }, { "description": "The Idempotency-Key the write was sent with.", "in": "query", "name": "operation_key", "required": true, "schema": { "description": "The Idempotency-Key the write was sent with.", "maxLength": 128, "minLength": 1, "title": "Operation Key", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentOperationStatus" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Did a keyed markdown append land in this note? (TIDY-18493)", "tags": [ "notes" ], "x-local-capability": "cloud" } }, "/api/v1/notes/{note_id}/approve": { "post": { "description": "Approve a note that was flagged for review.\n\n Sets requires_review=false, reviewed_at=NOW().\n\n Returns the updated note.\n\n Error Responses:\n - 401 Unauthorized: Missing or invalid JWT token\n - 404 Not Found: Note does not exist or does not belong to user's tenant\n - 500 Internal Server Error: Database operation failed\n\n Related: Notes Review Feature", "operationId": "approveNote", "parameters": [ { "in": "path", "name": "note_id", "required": true, "schema": { "title": "Note Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NoteResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Approve note", "tags": [ "notes" ] } }, "/api/v1/notes/{note_id}/archive": { "post": { "description": "Archive a note (sets archived_at timestamp).\n\n Archived notes are hidden from the main view but can be restored.\n Access archived notes from Settings > Archived Notes.\n\n Returns success message.\n\n Error Responses:\n - 401 Unauthorized: Missing or invalid JWT token\n - 404 Not Found: Note does not exist or does not belong to user's tenant\n - 500 Internal Server Error: Database operation failed\n\n Related: KCC-2979 (Note swipe gestures)", "operationId": "archiveNote", "parameters": [ { "in": "path", "name": "note_id", "required": true, "schema": { "title": "Note Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Archivenote", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Archive note", "tags": [ "notes" ] } }, "/api/v1/notes/{note_id}/backlinks": { "get": { "description": "Legacy endpoint — redirects to /notes/{note_id}/linked-references.", "operationId": "getBacklinksRedirect", "parameters": [ { "in": "path", "name": "note_id", "required": true, "schema": { "title": "Note Id", "type": "string" } } ], "responses": { "301": { "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Legacy redirect to linked-references (TIDY-4327)", "tags": [ "notes" ] } }, "/api/v1/notes/{note_id}/compact": { "post": { "description": "Replace all update rows with a single compacted snapshot.", "operationId": "compactUpdates", "parameters": [ { "in": "path", "name": "note_id", "required": true, "schema": { "title": "Note Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NoteCompactCreate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NoteUpdateResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Compact all updates into a single snapshot", "tags": [ "notes" ] } }, "/api/v1/notes/{note_id}/content": { "put": { "description": "Save note content with optimistic locking. Returns 409 on version conflict.", "operationId": "saveContent", "parameters": [ { "description": "Typed ID with prefix 'N'", "in": "path", "name": "note_id", "required": true, "schema": { "description": "Typed ID with prefix 'N'", "title": "Note Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContentSaveRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContentSaveResponse" } } }, "description": "Successful Response" }, "409": { "content": { "application/problem+json": {} }, "description": "Version conflict — the note changed between this caller's read and its write. RFC 9457 problem+json with `code: \"conflict\"` and `error: \"version_conflict\"`; `current_version` and `current_content` carry the newer state so the caller can rebase without a second round trip." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Save content with version check", "tags": [ "notes" ] } }, "/api/v1/notes/{note_id}/drawing-preview": { "put": { "operationId": "uploadDrawingPreview", "parameters": [ { "description": "Typed ID with prefix 'N'", "in": "path", "name": "note_id", "required": true, "schema": { "description": "Typed ID with prefix 'N'", "title": "Note Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DrawingPreviewResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Upload a sanitised SVG preview for a drawing note", "tags": [ "notes" ] } }, "/api/v1/notes/{note_id}/embed-block": { "post": { "description": "Insert an embeddedBlock referencing a primitive row into a note body.\n\nYjs-aware incremental write (pycrdt) — the document is never rebuilt from\nplain text. The embed is captured by the whole-doc linked_references\nre-sync (TIDY-9849), so a backlink row is created for the embedded row.", "operationId": "embedBlockInNote", "parameters": [ { "description": "Typed ID with prefix 'N'", "in": "path", "name": "note_id", "required": true, "schema": { "description": "Typed ID with prefix 'N'", "title": "Note Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmbedBlockRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NoteResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Embed a primitive row as an embeddedBlock in a note (Yjs-aware, TIDY-12983)", "tags": [ "notes" ], "x-mcp-skip": true, "x-mcp-skip-reason": "TIDY-12983 assistant-service registry owns the agent tool" } }, "/api/v1/notes/{note_id}/embed-view": { "post": { "description": "Insert a saved database view inline in a note body (B6: embedded, not linked).\n\nYjs-aware incremental write (pycrdt) — the document is never rebuilt from\nplain text. The view renders in the page body instead of being merely\nlinked from the project nav, closing the connective-tissue gap the S10\nblueprint orchestrator wires (TIDY-14305).", "operationId": "embedViewInNote", "parameters": [ { "description": "Typed ID with prefix 'N'", "in": "path", "name": "note_id", "required": true, "schema": { "description": "Typed ID with prefix 'N'", "title": "Note Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmbedViewRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NoteResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Embed a saved database view as a `database` node in a note body (TIDY-14305)", "tags": [ "notes" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "TIDY-14305 assistant-service blueprint orchestrator owns the caller" } }, "/api/v1/notes/{note_id}/inbox-action": { "patch": { "description": "Accept: clears inbox_status (moves to regular notes), applies facets/title. Dismiss: sets inbox_status to 'dismissed'.", "operationId": "inboxAction", "parameters": [ { "in": "path", "name": "note_id", "required": true, "schema": { "title": "Note Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InboxActionRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InboxActionResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Accept or dismiss an inbox item", "tags": [ "note-inbox" ] } }, "/api/v1/notes/{note_id}/linked-references": { "get": { "description": "Get all pages/primitives that link TO this note via wiki links.", "operationId": "getLinkedReferences", "parameters": [ { "in": "path", "name": "note_id", "required": true, "schema": { "title": "Note Id", "type": "string" } }, { "description": "Filter linked references by title or excerpt text", "in": "query", "name": "search", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter linked references by title or excerpt text", "title": "Search" } }, { "description": "Max results", "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "description": "Max results", "maximum": 200, "minimum": 1, "title": "Limit", "type": "integer" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Getlinkedreferences", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "The linked-reference read FAILED — problem+json with `code: links_unavailable` (retryable). Distinct from a 200 carrying an empty list, which means there genuinely are no backlinks (TIDY-16299)." } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get linked references for a note (TIDY-3971, TIDY-4327)", "tags": [ "notes" ] } }, "/api/v1/notes/{note_id}/memory-interpretation": { "get": { "operationId": "getNoteMemoryInterpretation", "parameters": [ { "description": "Typed ID with prefix 'N'", "in": "path", "name": "note_id", "required": true, "schema": { "description": "Typed ID with prefix 'N'", "title": "Note Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemoryInterpretationResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Whether a note contributed to the memory substrate", "tags": [ "memory", "memory" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/notes/{note_id}/memory-interpretation/promote": { "post": { "description": "Set ``interpretation_override`` and republish the note to memory.\n\nThe escape hatch for \"the agent actually wrote something important\". The\nrepublish is what makes the promotion take effect: the gate reads the\noverride on the next pass and lets the note through.", "operationId": "promoteNoteMemoryInterpretation", "parameters": [ { "description": "Typed ID with prefix 'N'", "in": "path", "name": "note_id", "required": true, "schema": { "description": "Typed ID with prefix 'N'", "title": "Note Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemoryInterpretationResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Promote a gated note into the memory interpretation tier", "tags": [ "memory", "memory" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/notes/{note_id}/move": { "post": { "operationId": "moveNote", "parameters": [ { "in": "path", "name": "note_id", "required": true, "schema": { "title": "Note Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MoveRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MoveResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Move a note to another project (or personal scope)", "tags": [ "move" ] } }, "/api/v1/notes/{note_id}/original": { "get": { "description": "Streams the original imported document (DOCX/XLSX/PPTX) from Supabase Storage with Content-Disposition: attachment for browser download. Only notes created via the Office import flow have an original file. Absorbs the SvelteKit BFF (TIDY-7383).", "operationId": "downloadNoteOriginal", "parameters": [ { "description": "Note UUID", "in": "path", "name": "note_id", "required": true, "schema": { "description": "Note UUID", "title": "Note Id", "type": "string" } } ], "responses": { "200": { "content": { "application/octet-stream": {} }, "description": "Original file bytes" }, "400": { "description": "Not an imported note" }, "404": { "description": "Note or original file not found" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Download original imported file for a note", "tags": [ "notes" ] } }, "/api/v1/notes/{note_id}/pin": { "delete": { "description": "Remove the calling account's navigator pin on this note.\n\nIdempotent — DELETE against an unpinned note returns 204 with no\nrow removed, matching the standard idempotent-DELETE contract.", "operationId": "unpinNote", "parameters": [ { "description": "Typed ID with prefix 'N'", "in": "path", "name": "note_id", "required": true, "schema": { "description": "Typed ID with prefix 'N'", "title": "Note Id", "type": "string" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Unpin a note for the calling account", "tags": [ "notes" ] }, "post": { "description": "Pin a note into the calling account's navigator pinned-items list.\n\nValidates the note exists in the caller's tenant (404 on miss to\navoid leaking cross-tenant existence). Idempotent: the natural-key\nunique index absorbs replays from the offline-queue drain.", "operationId": "pinNote", "parameters": [ { "description": "Typed ID with prefix 'N'", "in": "path", "name": "note_id", "required": true, "schema": { "description": "Typed ID with prefix 'N'", "title": "Note Id", "type": "string" } } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PinResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Pin a note for the calling account", "tags": [ "notes" ] } }, "/api/v1/notes/{note_id}/reject": { "post": { "description": "Reject a note that was flagged for review.\n\n Performs soft delete (sets deleted_at timestamp).\n\n Returns success message.\n\n Error Responses:\n - 401 Unauthorized: Missing or invalid JWT token\n - 404 Not Found: Note does not exist or does not belong to user's tenant\n - 500 Internal Server Error: Database operation failed\n\n Related: Notes Review Feature", "operationId": "rejectNote", "parameters": [ { "in": "path", "name": "note_id", "required": true, "schema": { "title": "Note Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Rejectnote", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Reject note", "tags": [ "notes" ] } }, "/api/v1/notes/{note_id}/restore": { "post": { "description": "Restore an archived or deleted note.\n\n Clears both archived_at and deleted_at timestamps.\n\n Returns the restored note.\n\n Error Responses:\n - 401 Unauthorized: Missing or invalid JWT token\n - 404 Not Found: Note does not exist or does not belong to user's tenant\n - 500 Internal Server Error: Database operation failed\n\n Related: KCC-2979 (Note swipe gestures - undo support)", "operationId": "restoreNote", "parameters": [ { "in": "path", "name": "note_id", "required": true, "schema": { "title": "Note Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NoteResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Restore note", "tags": [ "notes" ] } }, "/api/v1/notes/{note_id}/sheet-data": { "get": { "description": "Read one spreadsheet note under the caller's member-visible predicate.\n\nA note the caller cannot see and a note that does not exist both 404, with\nthe same body — this surface never confirms that another member's note\nexists. Everything else is a 200 whose ``status`` says what happened.", "operationId": "getNoteSheetData", "parameters": [ { "description": "Typed ID with prefix 'N'", "in": "path", "name": "note_id", "required": true, "schema": { "description": "Typed ID with prefix 'N'", "title": "Note Id", "type": "string" } }, { "description": "Sheet name to read. Defaults to the first sheet in the workbook.", "in": "query", "name": "sheet", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Sheet name to read. Defaults to the first sheet in the workbook.", "title": "Sheet" } }, { "description": "A1 window to read, e.g. 'A1:D20'. Omit for metadata only.", "in": "query", "name": "range", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "A1 window to read, e.g. 'A1:D20'. Omit for metadata only.", "title": "Range" } }, { "description": "Defined name to read instead of an A1 range (mutually exclusive with `range`).", "in": "query", "name": "defined_name", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Defined name to read instead of an A1 range (mutually exclusive with `range`).", "title": "Defined Name" } }, { "description": "Table name to read instead of an A1 range. Reads the table's CURRENT rectangle, so the window follows the table as rows are appended.", "in": "query", "name": "table", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Table name to read instead of an A1 range. Reads the table's CURRENT rectangle, so the window follows the table as rows are appended.", "title": "Table" } }, { "description": "Treat the window's first row as column headers.", "in": "query", "name": "header_row", "required": false, "schema": { "default": true, "description": "Treat the window's first row as column headers.", "title": "Header Row", "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SheetDataResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Read a spreadsheet note's sheets, defined names and cell values", "tags": [ "notes" ], "x-local-capability": "cloud" } }, "/api/v1/notes/{note_id}/updates": { "get": { "description": "Get all update chunks for a note, ordered by created_at.", "operationId": "getNoteUpdates", "parameters": [ { "in": "path", "name": "note_id", "required": true, "schema": { "title": "Note Id", "type": "string" } }, { "description": "Incremental sync: only updates after this timestamp", "in": "query", "name": "since", "required": false, "schema": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "Incremental sync: only updates after this timestamp", "title": "Since" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/NoteUpdateResponse" }, "title": "Response Getnoteupdates", "type": "array" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get all update chunks for a note", "tags": [ "notes" ] }, "post": { "description": "Append a Yjs update chunk. INSERT-only for conflict-free sync.", "operationId": "createNoteUpdate", "parameters": [ { "in": "path", "name": "note_id", "required": true, "schema": { "title": "Note Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NoteUpdateCreate" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NoteUpdateResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Append a Yjs update chunk", "tags": [ "notes" ] } }, "/api/v1/notes/{note_id}/versions": { "get": { "operationId": "listNoteVersions", "parameters": [ { "description": "Note UUID", "in": "path", "name": "note_id", "required": true, "schema": { "description": "Note UUID", "title": "Note Id", "type": "string" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "maximum": 50, "minimum": 1, "title": "Limit", "type": "integer" } }, { "in": "query", "name": "offset", "required": false, "schema": { "default": 0, "minimum": 0, "title": "Offset", "type": "integer" } }, { "description": "Closed-enum parent type. Required when the UUID is ambiguous.", "in": "query", "name": "primitive_type", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Closed-enum parent type. Required when the UUID is ambiguous.", "title": "Primitive Type" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VersionList" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List version snapshots for a note", "tags": [ "notes" ] }, "post": { "description": "Creates a new note_versions row. The caller must supply the Yjs document bytes as hex (content_hash is required for idempotency). If a recent snapshot already has the same content_hash and no explicit name is provided, returns 204 (the existing snapshot stands). Used by the server-mediated SvelteKit BFF for restore and manual-checkpoint flows (the BFF owns the Yjs read; this endpoint owns the durable write). Keeps 50 most recent versions and purges older entries automatically.", "operationId": "createNoteVersion", "parameters": [ { "description": "Note UUID", "in": "path", "name": "note_id", "required": true, "schema": { "description": "Note UUID", "title": "Note Id", "type": "string" } }, { "description": "Closed-enum parent type. Required when the UUID is ambiguous.", "in": "query", "name": "primitive_type", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Closed-enum parent type. Required when the UUID is ambiguous.", "title": "Primitive Type" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateVersionRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NoteVersion" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Create a version snapshot from caller-supplied yjs_state", "tags": [ "notes" ] } }, "/api/v1/notes/{note_id}/versions/{version_id}/state": { "get": { "description": "Returns the stored yjs_state as hex for server-mediated restore workflows (SvelteKit BFF shim that still owns the Yjs revert logic). Only accessible to tenant members.", "operationId": "getNoteVersionState", "parameters": [ { "description": "Note UUID", "in": "path", "name": "note_id", "required": true, "schema": { "description": "Note UUID", "title": "Note Id", "type": "string" } }, { "description": "Version UUID", "in": "path", "name": "version_id", "required": true, "schema": { "description": "Version UUID", "title": "Version Id", "type": "string" } }, { "description": "Closed-enum parent type. Required when the UUID is ambiguous.", "in": "query", "name": "primitive_type", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Closed-enum parent type. Required when the UUID is ambiguous.", "title": "Primitive Type" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VersionRow" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Fetch a single version snapshot including yjs_state bytes", "tags": [ "notes" ] } }, "/api/v1/notes/{note_id}/wiki-links/sync": { "post": { "description": "DELETE-then-INSERT replaces all `linked_references` rows sourced from\n wiki-link sync (link_source IN 'wiki_link_sync', 'content_embed') for\n the given note, with the provided set. Rows authored by other sources\n (llm_extracted, user_created, etc.) are preserved.\n\n Called by the Yjs wiki-link sync path on the client after doc edits.", "operationId": "syncNoteWikiLinks", "parameters": [ { "description": "Note UUID", "in": "path", "name": "note_id", "required": true, "schema": { "description": "Note UUID", "title": "Note Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WikiLinkSyncRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WikiLinkSyncResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Atomically replace wiki-link rows for a note", "tags": [ "links" ] } }, "/api/v1/notification-preferences": { "get": { "operationId": "getPreferences", "parameters": [ { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotificationPreferencesResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get notification preferences", "tags": [ "notification-preferences", "Notification Preferences" ] }, "patch": { "operationId": "updatePreferences", "parameters": [ { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotificationPreferencesUpdate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotificationPreferencesResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Update notification preferences", "tags": [ "notification-preferences", "Notification Preferences" ] } }, "/api/v1/notifications": { "get": { "description": "List paginated notifications for the authenticated user.\n\n``unread_only=true`` restricts the feed to rows with ``read_at IS NULL``.\nWhen it is set, ``total`` counts the rows MATCHING THE FILTER (the unread\nones, not all rows) so offset paging over the filtered feed is exact;\n``unread_count`` keeps its meaning either way.", "operationId": "listNotifications2", "parameters": [ { "in": "query", "name": "limit", "required": false, "schema": { "default": 20, "maximum": 100, "minimum": 1, "title": "Limit", "type": "integer" } }, { "in": "query", "name": "offset", "required": false, "schema": { "default": 0, "minimum": 0, "title": "Offset", "type": "integer" } }, { "in": "query", "name": "unread_only", "required": false, "schema": { "default": false, "title": "Unread Only", "type": "boolean" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserNotificationListResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List notifications", "tags": [ "user-notifications", "user-notifications" ] } }, "/api/v1/notifications/chat-keyword": { "post": { "description": "Persist one client-side keyword match as a ``chat_keyword`` notification.", "operationId": "recordChatKeyword", "parameters": [ { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatKeywordRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatMentionResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Record a Matrix chat keyword match as a user notification", "tags": [ "chat-keyword", "chat-keyword-notifications" ] } }, "/api/v1/notifications/chat-mention": { "post": { "description": "Persist one Matrix highlight event as a ``chat_mention`` notification.\n\nThe frontend matrix highlight bridge calls this when ``matrix-js-sdk``\nclassifies a timeline event as a highlight for the current user.\n\nFlow:\n 1. Resolve caller account -> Matrix MXID via ``matrix_users``. If the\n caller has no linked, active MXID return 403 (sanity guard — should\n not occur post matrix-token issuance).\n 2. Build ``metadata.dedupe_key = \"chat:{event_id}\"``. The partial\n unique index from migration 479 (shared with comment_mention)\n enforces idempotency.\n 3. UPSERT one ``user_notifications`` row.\n - Insert -> 201 with the new id, ``deduped=false``.\n - Conflict -> 200 with the existing id, ``deduped=true``.\n\nTenant + account come from the JWT — never from the request body.\nSnippet is bounded by the Pydantic model (max 1000 chars); >1000\nreturns 400 before reaching this handler.", "operationId": "recordChatMention", "parameters": [ { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatMentionRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatMentionResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Record a Matrix chat @mention as a user notification", "tags": [ "user-notifications", "user-notifications" ] } }, "/api/v1/notifications/count": { "get": { "description": "Return the number of unread notifications.", "operationId": "getUnreadCount", "parameters": [ { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnreadCountResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get unread notification count", "tags": [ "user-notifications", "user-notifications" ] } }, "/api/v1/notifications/preferences": { "get": { "operationId": "getNotificationPreferences", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WideNotificationPreferences" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get wide notification preferences", "tags": [ "notifications", "Notifications" ] }, "put": { "description": "The one write path for ``notification_preferences`` (TIDY-18062).\n\nThe narrow ``/notifications/sms/settings`` PUT is the same row through a\nsecond door; it now serves only until its traffic measures zero. Consent\nsemantics come from ``resolve_sms_consent_write`` — shared with the narrow\nrouter, so the rule exists once. Two reconciliations landed with that\nsharing, both toward the narrow lane's behaviour (the one the SMS setup flow\nexercises and TIDY-18057 pinned):\n\n* Disabling SMS no longer revokes consent. The wide lane used to zero\n ``sms_consent_given``/``sms_consent_timestamp`` on ``sms_enabled: false``;\n the narrow lane preserves them, the setup card's own confirm text promises\n \"Your authorization stays on file\", and TIDY-18057's regression test asserts\n the audit trail survives a disable-only PUT. Nulling consent from an admin\n preferences save (which echoes the whole GET body, ``sms_enabled`` included)\n was silently destroying TCPA evidence.\n* An omitted or explicitly-null ``sms_enabled`` preserves the stored value\n and, on a fresh row, creates it DISABLED rather than inheriting the\n column's legacy ``DEFAULT true``. The wide lane used to write ``false`` for\n an explicit null and let a fresh insert take the default true — so the\n phone-only first step enabled SMS, which is precisely what TIDY-18057\n removed from the narrow lane.\n\nA body with no value in it is a 400 naming the accepted fields, raised before\nany write; partial bodies remain preserve-on-omit.", "operationId": "updateNotificationPreferences", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateWidePreferencesRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WideNotificationPreferencesUpdateResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Update wide notification preferences", "tags": [ "notifications", "Notifications" ] } }, "/api/v1/notifications/read-all": { "post": { "description": "Mark all unread notifications as read for the authenticated user.", "operationId": "markAllRead", "parameters": [ { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Markallread", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Mark all notifications as read", "tags": [ "user-notifications", "user-notifications" ] } }, "/api/v1/notifications/recipe-open": { "post": { "description": "Marks attention-ledger rows opened for the calling account: one row by ledger_id, or every bundled row of a digest by digest_id.", "operationId": "markRecipeNotificationOpened", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecipeOpenRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecipeOpenResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Mark recipe notification(s) opened", "tags": [ "notifications" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/notifications/send-raw": { "post": { "description": "Send a single SMS without template rendering. Used by the tidy_sms_send MCP tool and by agency callers. Tenant is taken from the JWT — never from the request body. The response is returned only after notification-service has accepted the message.", "operationId": "sendRawSms", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendRawSmsRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendRawSmsResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Send a single raw SMS (no template)", "tags": [ "notifications" ] } }, "/api/v1/notifications/sms/settings": { "get": { "deprecated": true, "description": "DEPRECATED (TIDY-18062) — use GET /api/v1/notifications/preferences, which returns the same SMS fields on the full preferences surface. Behaviour here is unchanged and it keeps serving; note the two differ on a fresh operator: this route CREATES a default row (whose ``sms_enabled`` therefore takes the column's legacy ``DEFAULT true``), while the canonical GET reads the row as it is and answers defaults without writing. Removal is gated on the deprecation WARNING measuring empty (conditions posted on TIDY-18062).", "operationId": "getSmsSettings", "parameters": [ { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SMSSettingsResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get SMS notification settings", "tags": [ "notifications" ] }, "put": { "deprecated": true, "description": "DEPRECATED (TIDY-18062) — use PUT /api/v1/notifications/preferences, which writes the same ``notification_preferences`` row, is a strict superset of these four SMS fields, and now returns the written row too (``{success, preferences}``). Behaviour here is unchanged and it keeps serving; removal is gated on the deprecation WARNING measuring empty on dev1 and QA (conditions posted on TIDY-18062). Partial bodies are preserve-on-omit; a body with no values in it is a 400 naming the accepted fields, on this door and the canonical one.", "operationId": "updateSmsSettings", "parameters": [ { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SMSSettingsUpdate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SMSSettingsResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Update SMS notification settings", "tags": [ "notifications" ] } }, "/api/v1/notifications/{notification_id}": { "delete": { "description": "Dismiss one notification — the row leaves the caller's bell feed.\n\n`user_notifications` carries no dismissed state: the retention sweep\nalready treats a read row as dismissed and deletes it once the account's\nwindow expires (`services/api/.../notification_retention.py`). A\nuser-initiated dismiss is that same disposal, immediately.", "operationId": "dismissNotification", "parameters": [ { "in": "path", "name": "notification_id", "required": true, "schema": { "title": "Notification Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Dismiss notification", "tags": [ "user-notifications", "user-notifications" ], "x-local-capability": "cloud", "x-mcp-skip": true }, "get": { "description": "Fetch one of the caller's own notifications by id (TIDY-19463).\n\nDeclared after ``/count`` so the static route keeps winning. Scoping\nmatches :func:`mark_read` — tenant + account come from the JWT, so\nanother member's row is indistinguishable from a missing one (404).", "operationId": "getNotification", "parameters": [ { "in": "path", "name": "notification_id", "required": true, "schema": { "format": "uuid", "title": "Notification Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserNotificationResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get one notification", "tags": [ "user-notifications", "user-notifications" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/notifications/{notification_id}/read": { "post": { "description": "Mark a single notification as read by setting read_at.", "operationId": "markRead", "parameters": [ { "in": "path", "name": "notification_id", "required": true, "schema": { "title": "Notification Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserNotificationResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Mark notification as read", "tags": [ "user-notifications", "user-notifications" ] } }, "/api/v1/notifications/{notification_id}/unread": { "post": { "description": "Return a notification to the unread state by clearing read_at.\n\nThe inverse of :func:`mark_read`: a row read by mistake belongs back in\nthe unread count rather than needing a separate saved-for-later concept\n(TIDY-15643).", "operationId": "markUnread", "parameters": [ { "in": "path", "name": "notification_id", "required": true, "schema": { "title": "Notification Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserNotificationResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Mark notification as unread", "tags": [ "user-notifications", "user-notifications" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/oauth-callback/launch": { "post": { "description": "Hand the provider URL only to a browser signed in as the minting member (TIDY-19315).\n\nThe desktop app's consent runs in the system browser. Before that browser\nmay start the provider ceremony, its own Tidy session must be the member\nand workspace that minted the state; then it receives the per-state nonce\ncookie the callback demands. Anyone else — a forwarded launch link, another\nbrowser profile on the same machine — is refused, and nothing is planted.", "operationId": "launchOAuthConnect", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthLaunchRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthLaunchResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Bind a desktop provider connect to this browser's Tidy member", "tags": [ "oauth", "oauth" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/oauth-callback/resume": { "post": { "description": "Run a parked callback for the member who started it (TIDY-19315).\n\nThe key is only ever handed to the browser that finished the ceremony, and\nit resolves only under the minting member's own session: a desktop signed\nin as anyone else addresses a key that does not exist, and consumes nothing.", "operationId": "resumeOAuthCallback", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthResumeRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthResumeResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Finish a provider connect the desktop app started", "tags": [ "oauth", "oauth" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/oauth/authorize/approve": { "post": { "description": "Mint a one-time code + return the redirect URL for the client to follow.", "operationId": "approveAuthorize", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApproveRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApproveAuthorizeResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Approve Authorize", "tags": [ "oauth" ] } }, "/api/v1/oauth/authorize/describe": { "get": { "description": "Validate the authorize request and return everything the consent UI needs.\n\nDoes NOT mint a code; that happens at `/approve` after the user says yes.\n\n`scope` is optional (RFC 6749 §3.3, TIDY-8880): when omitted the\nrequest defaults to the full set of scopes the client was registered\nwith. This matches Auth0 / Okta / Keycloak behavior and keeps generic\nOAuth 2.1 clients (OpenWebUI etc.) working without per-client scope\nknowledge.\n\n`resource` is optional (TIDY-8880): MCP clients send the RFC 8707\nindicator explicitly; generic OAuth 2.1 clients omit it. When absent\nwe bind the request to the canonical `<issuer>/api/v1` audience.", "operationId": "describeAuthorize", "parameters": [ { "in": "query", "name": "client_id", "required": true, "schema": { "title": "Client Id", "type": "string" } }, { "in": "query", "name": "redirect_uri", "required": true, "schema": { "title": "Redirect Uri", "type": "string" } }, { "in": "query", "name": "state", "required": true, "schema": { "title": "State", "type": "string" } }, { "in": "query", "name": "code_challenge", "required": true, "schema": { "title": "Code Challenge", "type": "string" } }, { "in": "query", "name": "code_challenge_method", "required": true, "schema": { "title": "Code Challenge Method", "type": "string" } }, { "in": "query", "name": "scope", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Scope" } }, { "in": "query", "name": "resource", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Resource" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DescribeAuthorizeResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Describe Authorize", "tags": [ "oauth" ] } }, "/api/v1/oauth/callback": { "post": { "description": "Single callback for all OAuth flows. Validates state and delegates to the provider.", "operationId": "unifiedOauthCallback", "parameters": [ { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnifiedOAuthCallbackRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnifiedOAuthCallbackResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Unified OAuth callback", "tags": [ "oauth" ] } }, "/api/v1/oauth/device/approve": { "post": { "description": "Mark a pending device_code authorized + bind it to this user/tenant.\n\nCapability-gated: requires `connect_external_agent` in the user's\ntenant (D9). The token minted at the next agent poll will carry this\nuser's account_id + tenant_id as `sub`/`tenant_id` claims.", "operationId": "approveDeviceCode", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeviceConsentRequest" } } }, "required": true }, "responses": { "204": { "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Approve Device Code", "tags": [ "oauth" ] } }, "/api/v1/oauth/device/deny": { "post": { "description": "Mark a pending device_code denied. NOT capability-gated — every\nuser MUST be able to refuse a request even if they can't approve it.", "operationId": "denyDeviceCode", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeviceConsentRequest" } } }, "required": true }, "responses": { "204": { "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Deny Device Code", "tags": [ "oauth" ] } }, "/api/v1/oauth/device/describe": { "get": { "description": "Describe a pending device-code so the consent UI can render.\n\nTIDY-19735: the first member to look a pending code up claims it (a code\nbound to someone else reads as unknown), every lookup spends from a\nbudget and an unknown code costs double, and the response says who asked.", "operationId": "describeDeviceCode", "parameters": [ { "in": "query", "name": "user_code", "required": true, "schema": { "title": "User Code", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeviceDescribeResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Describe Device Code", "tags": [ "oauth" ] } }, "/api/v1/onboarding/advance": { "post": { "description": "Single source of truth for step advancement (TIDY-7073). Call this after completing any step other than 'context' and 'plan' (which advance atomically via their own endpoints). Idempotent: from_step == current -> advance; from_step < current -> no write; from_step > current -> 409. Terminal transition writes onboarding_completed_at = NOW().", "operationId": "advanceOnboardingStep", "parameters": [ { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdvanceRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdvanceResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Advance the onboarding step", "tags": [ "onboarding" ] } }, "/api/v1/onboarding/context": { "post": { "description": "Persist the user's chosen context (personal / household / business) and\n atomically advance onboarding_step from 'tenant'/'context' to the chosen\n context's next step.\n\n Single UPDATE writes both columns — no half-state where account_type is\n set but onboarding_step still says 'tenant'. Replaying the same\n account_type after advance updates marketing consent and returns 200.\n Returns 409 only when account_type would change after leaving context.", "operationId": "setOnboardingContext", "parameters": [ { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContextRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContextResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Set onboarding context", "tags": [ "onboarding" ] } }, "/api/v1/onboarding/family": { "get": { "description": "List family members previously saved during onboarding for the current tenant.\n\n Used by the onboarding wizard to rehydrate the family step when a user\n returns to it after navigating away.\n\n Related: 011-auth-user-onboarding T035, TIDY-7366", "operationId": "listFamilyMembers", "parameters": [ { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_service__routers__onboarding__models__FamilyMembersListResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List family members", "tags": [ "onboarding" ] }, "post": { "description": "Add family members during onboarding.\n\n This creates contact records for family members (spouse, children).\n These contacts will be linked to extracted events and communications.\n\n Family members are integrated with the primitive-reconciliation system\n for contact matching.\n\n Related: 011-auth-user-onboarding T035", "operationId": "addFamilyMembers", "parameters": [ { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FamilyMembersRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FamilyMembersResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Add family members", "tags": [ "onboarding" ] } }, "/api/v1/onboarding/identity": { "post": { "description": "Claim an email identity for the tenant.\n\n Creates or updates the mailbox token with the chosen local part.\n The full email address will be {local_part}@{domain}.\n\n Related: 011-auth-user-onboarding", "operationId": "claimIdentity", "parameters": [ { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityClaimRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityClaimResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Claim email identity", "tags": [ "onboarding" ] } }, "/api/v1/onboarding/identity/check": { "get": { "description": "Check if an email local part is available.\n\n Performs case-insensitive check against existing mailbox tokens.\n\n Related: 011-auth-user-onboarding", "operationId": "checkIdentityAvailability", "parameters": [ { "in": "query", "name": "local_part", "required": true, "schema": { "title": "Local Part", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityCheckResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Check email identity availability", "tags": [ "onboarding" ] } }, "/api/v1/onboarding/identity/suggestions": { "get": { "description": "Get suggested email local parts based on the tenant's display name.\n\n Returns up to 5 suggestions that are currently available.\n\n Related: 011-auth-user-onboarding", "operationId": "getIdentitySuggestions", "parameters": [ { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentitySuggestionsResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get email identity suggestions", "tags": [ "onboarding" ] } }, "/api/v1/onboarding/plan": { "post": { "description": "Verify and atomically consume one persisted onboarding checkout.", "operationId": "selectPlan", "parameters": [ { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlanSelectionRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlanSelectionResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Consume the tenant's exact persisted onboarding Checkout Session", "tags": [ "onboarding" ] } }, "/api/v1/onboarding/providers/{provider}": { "put": { "description": "Record the user's onboarding decision for one email provider. `decision=connected` requires a `connection_id` owned by the caller whose plugin is active/working for that provider. Zoho additionally requires a verified IMAP app password on that connection (`has_app_password=true`, set only after a successful IMAP LOGIN check); otherwise the call returns 400.", "operationId": "recordOnboardingProviderDecision", "parameters": [ { "in": "path", "name": "provider", "required": true, "schema": { "enum": [ "google", "microsoft", "zoho", "apple", "yahoo", "fastmail", "generic_imap" ], "title": "Provider", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderDecisionRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": { "enum": [ "offered", "connected", "skipped" ], "type": "string" }, "title": "Response Recordonboardingproviderdecision", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Record Provider Decision", "tags": [ "onboarding" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/onboarding/status": { "get": { "description": "Get the current user's onboarding progress.\n\n Returns the current step in the wizard and which steps have been completed.\n\n Steps (canonical order, TIDY-5995):\n 1. connect - Email provider connection (step 1 after signup)\n 2. plan - Plan tier selected\n 3. team - Team setup (optional)\n 4. family - Family members added (optional)\n 5. identity - Claim a custom email identity (optional)\n 6. calendar - Calendar connected or feed enabled (optional)\n 7. notifications - Notification preferences (optional)\n 8. complete - Onboarding finished\n\n Related: 011-auth-user-onboarding T033", "operationId": "getOnboardingStatus", "parameters": [ { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OnboardingStatusResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get onboarding status", "tags": [ "onboarding" ] } }, "/api/v1/openapi.json": { "get": { "description": "Returns the committed OpenAPI 3.1 spec. This is the canonical public contract — SDKs, the MCP adapter, and partner integrations all generate from it.", "operationId": "getOpenapiSpec", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Getopenapispec", "type": "object" } } }, "description": "Successful Response" } }, "summary": "Public OpenAPI 3.1 specification", "tags": [ "meta", "meta" ] } }, "/api/v1/org-chart/my-team": { "get": { "description": "The people and employees directly above and below you on the workspace's team Org chart, and beside you under the same manager, as every member sees it, with their account ids and an employee's @handle. Pass project_id to see who of them belongs to that project (you must belong to it, own it or administer the workspace). Answering in a project room or channel, the room's own project is read, and whether each is in the room.", "operationId": "getMyTeam", "parameters": [ { "description": "Typed ID with prefix 'P' (or bare UUID during deprecation)", "in": "query", "name": "project_id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Typed ID with prefix 'P' (or bare UUID during deprecation)", "title": "Project Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MyTeamResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Your team: your manager, direct reports and peers on the Org chart", "tags": [ "organizations", "Organizations" ], "x-local-capability": "cloud" } }, "/api/v1/organizations": { "get": { "description": "List all organizations for authenticated user's tenant with optional filtering.\n\n Query Parameters:\n type: Filter by organization type (school, team, club, etc.)\n search: Search in name and description fields\n requires_review: Filter by review status (true/false)\n limit: Max results (1-1000), default: 100\n offset: Pagination offset, default: 0\n\n Returns:\n {\n \"organizations\": [...],\n \"count\": 15\n }\n\n Multi-Tenant Isolation: Only returns organizations for user's tenant.\n\n Related: Organizations Feature", "operationId": "listOrganizations", "parameters": [ { "in": "query", "name": "type", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Type" } }, { "in": "query", "name": "search", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Search" } }, { "description": "Filter by address book UUID", "in": "query", "name": "address_book", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by address book UUID", "title": "Address Book" } }, { "in": "query", "name": "requires_review", "required": false, "schema": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Requires Review" } }, { "description": "TIDY-18527: order before paging. Omitted: by name.", "in": "query", "name": "sort", "required": false, "schema": { "anyOf": [ { "pattern": "^(name_asc|name_desc|created_desc|created_asc|updated_desc)$", "type": "string" }, { "type": "null" } ], "description": "TIDY-18527: order before paging. Omitted: by name.", "title": "Sort" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 100, "maximum": 1000, "minimum": 1, "title": "Limit", "type": "integer" } }, { "in": "query", "name": "offset", "required": false, "schema": { "default": 0, "minimum": 0, "title": "Offset", "type": "integer" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Listorganizations", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List organizations with filtering", "tags": [ "organizations", "Organizations" ] }, "post": { "description": "Create a new organization.\n\n Request:\n {\n \"name\": \"Lincoln Elementary\",\n \"type\": \"school\",\n \"website\": \"https://lincoln.edu\",\n \"email\": \"info@lincoln.edu\",\n \"phone\": \"+15551234567\",\n \"address\": \"123 Main St, Springfield, IL\",\n \"description\": \"Local elementary school\"\n }\n\n Response (201 Created):\n {\n \"id\": \"a1b2c3d4-...\",\n \"tenant_id\": \"tenant-uuid\",\n \"name\": \"Lincoln Elementary\",\n ...\n }\n\n Error Responses:\n - 400 Bad Request: Invalid organization data (empty name, etc.)\n - 401 Unauthorized: Missing or invalid JWT token\n - 404 Not Found: No tenant associated with account\n - 500 Internal Server Error: Database operation failed\n\n Related: Organizations Feature", "operationId": "createOrganization", "parameters": [ { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationCreate" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Create new organization", "tags": [ "organizations" ] } }, "/api/v1/organizations/clusters": { "post": { "description": "Cluster the caller-visible duplicate pairs; each cluster suggests a survivor.", "operationId": "detectOrganizationClusters", "parameters": [ { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationClusterRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationClustersResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Detect transitive clusters of duplicate organizations", "tags": [ "organizations", "Organization Merge" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Human-confirmed organization dedup review flow — not an agent workflow." } }, "/api/v1/organizations/duplicates": { "get": { "description": "Scored duplicate organization pairs with reasons, strongest first.", "operationId": "getOrganizationDuplicates", "parameters": [ { "in": "query", "name": "min_confidence", "required": false, "schema": { "anyOf": [ { "maximum": 1.0, "minimum": 0.0, "type": "number" }, { "type": "null" } ], "title": "Min Confidence" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 100, "maximum": 500, "minimum": 1, "title": "Limit", "type": "integer" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationDuplicatesResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get potential duplicate organization pairs", "tags": [ "organizations", "Organization Merge" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Human-confirmed organization dedup review flow — not an agent workflow." } }, "/api/v1/organizations/duplicates/dismiss": { "post": { "description": "Mark a pair as 'not duplicates' so it stops appearing in scans.", "operationId": "dismissOrganizationDuplicatePair", "parameters": [ { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationDismissRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Dismissorganizationduplicatepair", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Dismiss an organization pair as not duplicates", "tags": [ "organizations", "Organization Merge" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Human-confirmed organization dedup review flow — not an agent workflow." } }, "/api/v1/organizations/duplicates/dismissed": { "get": { "description": "Pairs this tenant dismissed, newest first.", "operationId": "getDismissedOrganizationPairs", "parameters": [ { "in": "query", "name": "limit", "required": false, "schema": { "default": 100, "maximum": 500, "minimum": 1, "title": "Limit", "type": "integer" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationDismissedListResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get dismissed organization duplicate pairs", "tags": [ "organizations", "Organization Merge" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Human-confirmed organization dedup review flow — not an agent workflow." } }, "/api/v1/organizations/duplicates/dismissed/{dismissal_id}": { "delete": { "description": "Reconsider a dismissed pair so it appears in duplicate scans again.", "operationId": "restoreDismissedOrganizationPair", "parameters": [ { "in": "path", "name": "dismissal_id", "required": true, "schema": { "title": "Dismissal Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Restoredismissedorganizationpair", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Restore a dismissed organization pair", "tags": [ "organizations", "Organization Merge" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Human-confirmed organization dedup review flow — not an agent workflow." } }, "/api/v1/organizations/duplicates/match": { "post": { "description": "Create-time \"Did you mean …?\" candidates for a draft (TIDY-15513).\n\nScores at tier 1 AND tier 2 (D9) with the same engine detection uses (D1).\nRead-only and advisory: the caller may always create the new row anyway (D2).", "operationId": "matchOrganizationDraft", "parameters": [ { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationDraftMatchRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationDraftMatchResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Match an unsaved organization draft against existing organizations", "tags": [ "organizations", "Organization Merge" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Human-confirmed organization dedup review flow — not an agent workflow." } }, "/api/v1/organizations/filters/types": { "get": { "description": "Get list of unique organization types across all organizations for filter dropdown.\n\n Returns:\n [\"club\", \"medical\", \"school\", \"team\"]\n\n Related: Organizations Feature", "operationId": "getFilterTypes", "parameters": [ { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "type": "string" }, "title": "Response Getfiltertypes", "type": "array" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get unique organization types for filter dropdown", "tags": [ "organizations", "Organizations" ] } }, "/api/v1/organizations/merge": { "post": { "description": "Fold every loser into the survivor atomically; returns the ``merge_id``.", "operationId": "executeOrganizationMerge", "parameters": [ { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationMergeRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationMergeResult" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Execute an organization merge", "tags": [ "organizations", "Organization Merge" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Human-confirmed organization dedup review flow — not an agent workflow." } }, "/api/v1/organizations/merge/batch": { "post": { "description": "Each merge is its own transaction — one refusal never aborts the others.", "operationId": "executeOrganizationBatchMerge", "parameters": [ { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationBatchMergeRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationBatchMergeResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Execute several independent organization merges", "tags": [ "organizations", "Organization Merge" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Human-confirmed organization dedup review flow — not an agent workflow." } }, "/api/v1/organizations/merge/preview": { "post": { "description": "Field resolutions, residual entries, logo decision and transfer counts (R3).", "operationId": "previewOrganizationMerge", "parameters": [ { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationMergePreviewRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationMergePreview" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Preview an organization merge (writes nothing)", "tags": [ "organizations", "Organization Merge" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Human-confirmed organization dedup review flow — not an agent workflow." } }, "/api/v1/organizations/merge/{merge_id}/undo": { "post": { "description": "Restore every participant to its exact pre-merge row (R8).", "operationId": "undoOrganizationMerge", "parameters": [ { "in": "path", "name": "merge_id", "required": true, "schema": { "title": "Merge Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationMergeUndoResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Undo an organization merge", "tags": [ "organizations", "Organization Merge" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Human-confirmed organization dedup review flow — not an agent workflow." } }, "/api/v1/organizations/{organization_id}": { "delete": { "description": "Soft delete organization (sets deleted_at timestamp).\n\n Organization is not permanently removed from database.\n Preserved for audit trail.\n\n Returns 204 No Content on success.\n\n Error Responses:\n - 401 Unauthorized: Missing or invalid JWT token\n - 404 Not Found: Organization does not exist or does not belong to user's tenant\n - 500 Internal Server Error: Database operation failed\n\n Related: Organizations Feature", "operationId": "deleteOrganization", "parameters": [ { "description": "Typed ID with prefix 'O'", "in": "path", "name": "organization_id", "required": true, "schema": { "description": "Typed ID with prefix 'O'", "title": "Organization Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Delete organization", "tags": [ "organizations" ] }, "get": { "description": "Retrieve details for a specific organization including linked contacts.\n\n Response:\n {\n \"id\": \"a1b2c3d4-...\",\n \"tenant_id\": \"tenant-uuid\",\n \"name\": \"Lincoln Elementary\",\n \"type\": \"school\",\n ...\n \"contacts\": [\n {\n \"contact_id\": \"...\",\n \"contact_name\": \"Jane Smith\",\n \"relationship_type\": \"works_at\",\n \"role\": \"Teacher\",\n \"is_primary\": true\n }\n ]\n }\n\n Error Responses:\n - 401 Unauthorized: Missing or invalid JWT token\n - 404 Not Found: Organization does not exist or does not belong to user's tenant\n - 500 Internal Server Error: Database operation failed\n\n Related: Organizations Feature", "operationId": "getOrganization", "parameters": [ { "description": "Typed ID with prefix 'O'", "in": "path", "name": "organization_id", "required": true, "schema": { "description": "Typed ID with prefix 'O'", "title": "Organization Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationWithContacts" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get organization details", "tags": [ "organizations" ] }, "patch": { "description": "Update organization fields using PATCH (partial update).\n\n Request (all fields optional):\n {\n \"description\": \"Updated description\"\n }\n\n Only provided fields are updated.\n\n Error Responses:\n - 400 Bad Request: Invalid update data\n - 401 Unauthorized: Missing or invalid JWT token\n - 404 Not Found: Organization does not exist or does not belong to user's tenant\n - 500 Internal Server Error: Database operation failed\n\n Related: Organizations Feature", "operationId": "updateOrganizationPatch", "parameters": [ { "description": "Typed ID with prefix 'O'", "in": "path", "name": "organization_id", "required": true, "schema": { "description": "Typed ID with prefix 'O'", "title": "Organization Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationUpdate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Update organization (partial update)", "tags": [ "organizations" ] }, "put": { "description": "Update organization fields using PUT (full resource replace).\n\n Request (all fields optional):\n {\n \"name\": \"Lincoln Elementary School\",\n \"type\": \"school\",\n \"website\": \"https://lincoln-elementary.edu\"\n }\n\n Only provided fields are updated.\n\n Error Responses:\n - 400 Bad Request: Invalid update data\n - 401 Unauthorized: Missing or invalid JWT token\n - 404 Not Found: Organization does not exist or does not belong to user's tenant\n - 500 Internal Server Error: Database operation failed\n\n Related: Organizations Feature", "operationId": "updateOrganizationPut", "parameters": [ { "description": "Typed ID with prefix 'O'", "in": "path", "name": "organization_id", "required": true, "schema": { "description": "Typed ID with prefix 'O'", "title": "Organization Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationUpdate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Update organization (full replace)", "tags": [ "organizations" ] } }, "/api/v1/organizations/{organization_id}/approve": { "post": { "description": "Approve an organization that was flagged for review.\n\n Sets requires_review=false, reviewed_at=NOW().\n\n Returns the updated organization.\n\n Error Responses:\n - 401 Unauthorized: Missing or invalid JWT token\n - 404 Not Found: Organization does not exist or does not belong to user's tenant\n - 500 Internal Server Error: Database operation failed\n\n Related: Organizations Review Feature", "operationId": "approveOrganization", "parameters": [ { "description": "Typed ID with prefix 'O'", "in": "path", "name": "organization_id", "required": true, "schema": { "description": "Typed ID with prefix 'O'", "title": "Organization Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Approve organization", "tags": [ "organizations" ] } }, "/api/v1/organizations/{organization_id}/contact-suggestions/dismissals": { "post": { "description": "Persist the caller's dismissal of a client-computed contact suggestion. Idempotent: repeating the same match_key returns 200 with the existing row instead of 201.", "operationId": "dismissOrganizationContactSuggestion", "parameters": [ { "description": "Typed ID with prefix 'O'", "in": "path", "name": "organization_id", "required": true, "schema": { "description": "Typed ID with prefix 'O'", "title": "Organization Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuggestionDismissalCreate" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuggestionDismissalResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Dismiss a suggested contact for an organization", "tags": [ "organizations", "Organizations" ], "x-local-capability": "outbox", "x-mcp-skip": true, "x-mcp-skip-reason": "Org suggestion UI flow — rows are local-first synced." } }, "/api/v1/organizations/{organization_id}/contact-suggestions/dismissals/{match_key}": { "delete": { "description": "Delete the caller's own dismissal row. Owner-only; 404 otherwise.", "operationId": "undismissOrganizationContactSuggestion", "parameters": [ { "description": "Opaque suggestion identity — contact:<contact_id> or sender:<lowercased from_address>", "in": "path", "name": "match_key", "required": true, "schema": { "description": "Opaque suggestion identity — contact:<contact_id> or sender:<lowercased from_address>", "maxLength": 400, "minLength": 1, "title": "Match Key", "type": "string" } }, { "description": "Typed ID with prefix 'O'", "in": "path", "name": "organization_id", "required": true, "schema": { "description": "Typed ID with prefix 'O'", "title": "Organization Id", "type": "string" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Un-dismiss a suggested contact", "tags": [ "organizations", "Organizations" ], "x-local-capability": "outbox", "x-mcp-skip": true, "x-mcp-skip-reason": "Org suggestion UI flow — rows are local-first synced." } }, "/api/v1/organizations/{organization_id}/contact-suggestions/linked": { "post": { "description": "Echo back the subset of the submitted contact ids and email addresses that already have a membership row on this organization — including memberships whose contact row does not sync to the caller (another member's private or pending_review contact). The response is strictly a subset of the request: no name, id, or address the caller did not submit is ever disclosed.", "operationId": "probeOrganizationContactSuggestionLinks", "parameters": [ { "description": "Typed ID with prefix 'O'", "in": "path", "name": "organization_id", "required": true, "schema": { "description": "Typed ID with prefix 'O'", "title": "Organization Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuggestionLinkProbe" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuggestionLinkProbeResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Which suggested candidates are already members", "tags": [ "organizations", "Organizations" ], "x-mcp-skip": true, "x-mcp-skip-reason": "Org suggestion UI flow — echoes the caller's own candidates." } }, "/api/v1/organizations/{organization_id}/convert-to-contact": { "post": { "description": "Convert a pending-review organization into a contact.\n\n This is restricted to review-stage entities so existing relationship data\n is not orphaned on already-promoted records.", "operationId": "convertOrganization", "parameters": [ { "in": "path", "name": "organization_id", "required": true, "schema": { "title": "Organization Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityConversionResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Convert organization to contact", "tags": [ "organizations" ] } }, "/api/v1/organizations/{organization_id}/history": { "get": { "description": "Get edit history entries for a single organization.", "operationId": "getOrganizationHistory", "parameters": [ { "description": "Typed ID with prefix 'O'", "in": "path", "name": "organization_id", "required": true, "schema": { "description": "Typed ID with prefix 'O'", "title": "Organization Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationEditHistoryResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get organization edit history", "tags": [ "organizations", "Organizations" ] } }, "/api/v1/organizations/{organization_id}/history/{change_set_id}/restore": { "post": { "description": "Restore a prior organization change-set.", "operationId": "restoreOrganizationChangeSet", "parameters": [ { "in": "path", "name": "change_set_id", "required": true, "schema": { "title": "Change Set Id", "type": "string" } }, { "description": "Typed ID with prefix 'O'", "in": "path", "name": "organization_id", "required": true, "schema": { "description": "Typed ID with prefix 'O'", "title": "Organization Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Restore organization from edit history", "tags": [ "organizations", "Organizations" ] } }, "/api/v1/organizations/{organization_id}/mappings": { "get": { "description": "The caller's OWN domain/sender → organization mappings for this organization. Mappings are member-owned; another member's mappings are never returned.", "operationId": "listOrganizationMappings", "parameters": [ { "description": "Typed ID with prefix 'O'", "in": "path", "name": "organization_id", "required": true, "schema": { "description": "Typed ID with prefix 'O'", "title": "Organization Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationMappingListResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List the caller's sender/domain mappings for an organization", "tags": [ "organizations", "Organizations" ], "x-local-capability": "local", "x-mcp-skip": true, "x-mcp-skip-reason": "Org mapping management UI flow — rows are local-first synced." }, "post": { "description": "Claim a domain (kind='domain') or a specific sender address (kind='sender') for this organization. Values are normalized server-side. Freemail domains (gmail.com, outlook.com, …) return 422 ``freemail_domain`` — map the specific sender instead. A value the caller already mapped to a different organization returns 409 ``mapping_exists`` with the current org's id/name; retry with ``reassign=true`` to move the mapping.", "operationId": "createOrganizationMapping", "parameters": [ { "description": "Typed ID with prefix 'O'", "in": "path", "name": "organization_id", "required": true, "schema": { "description": "Typed ID with prefix 'O'", "title": "Organization Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationMappingCreate" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationMappingResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Map a domain or sender to an organization", "tags": [ "organizations", "Organizations" ], "x-local-capability": "outbox", "x-mcp-skip": true, "x-mcp-skip-reason": "Org mapping management UI flow — rows are local-first synced." } }, "/api/v1/organizations/{organization_id}/mappings/{mapping_id}": { "delete": { "description": "Delete the caller's own mapping row. Owner-only; 404 otherwise.", "operationId": "deleteOrganizationMapping", "parameters": [ { "description": "Typed ID with prefix 'O'", "in": "path", "name": "organization_id", "required": true, "schema": { "description": "Typed ID with prefix 'O'", "title": "Organization Id", "type": "string" } }, { "description": "Mapping row id (UUID)", "in": "path", "name": "mapping_id", "required": true, "schema": { "description": "Mapping row id (UUID)", "title": "Mapping Id", "type": "string" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Remove a sender/domain mapping", "tags": [ "organizations", "Organizations" ], "x-local-capability": "outbox", "x-mcp-skip": true, "x-mcp-skip-reason": "Org mapping management UI flow — rows are local-first synced." } }, "/api/v1/organizations/{organization_id}/members": { "get": { "description": "Members of the organization visible to the caller, each with its title (role), affiliation type, reporting line (parent_membership_id), and org-primary-contact flag. Membership rows sync locally; agents read them from local SQLite.", "operationId": "listOrganizationMembers", "parameters": [ { "description": "Typed ID with prefix 'O'", "in": "path", "name": "organization_id", "required": true, "schema": { "description": "Typed ID with prefix 'O'", "title": "Organization Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationMemberListResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List an organization's members", "tags": [ "organizations", "Organizations" ], "x-local-capability": "local", "x-mcp-skip": true, "x-mcp-skip-reason": "Org membership management UI flow — rows are local-first synced." }, "post": { "description": "Link a contact to the organization with an optional title (role) and affiliation type. Idempotent: when the contact is already a member the existing membership is returned with 200 (never duplicated). Removing a membership never deletes the contact.", "operationId": "addOrganizationMember", "parameters": [ { "description": "Typed ID with prefix 'O'", "in": "path", "name": "organization_id", "required": true, "schema": { "description": "Typed ID with prefix 'O'", "title": "Organization Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationMemberCreate" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationMemberResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Add a member to an organization", "tags": [ "organizations", "Organizations" ], "x-local-capability": "outbox", "x-mcp-skip": true, "x-mcp-skip-reason": "Org membership management UI flow — rows are local-first synced." } }, "/api/v1/organizations/{organization_id}/members/{membership_id}": { "delete": { "description": "Delete the membership link ONLY — the contact is never deleted. Any members reporting to this one are orphaned to root (their parent_membership_id is set null).", "operationId": "removeOrganizationMember", "parameters": [ { "description": "Typed ID with prefix 'O'", "in": "path", "name": "organization_id", "required": true, "schema": { "description": "Typed ID with prefix 'O'", "title": "Organization Id", "type": "string" } }, { "description": "Membership row id (UUID)", "in": "path", "name": "membership_id", "required": true, "schema": { "description": "Membership row id (UUID)", "title": "Membership Id", "type": "string" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Remove a member from an organization", "tags": [ "organizations", "Organizations" ], "x-local-capability": "outbox", "x-mcp-skip": true, "x-mcp-skip-reason": "Org membership management UI flow — rows are local-first synced." }, "patch": { "description": "Update a membership's role/relationship_type, set or clear its reporting line (parent_membership_id — must be another membership of the SAME org; pass null to detach to root), and set/unset the org's primary contact. A parent from a different org returns 422 ``invalid_parent``; a parent that would create a cycle (including self-parent) returns 422 ``hierarchy_cycle``. Setting a primary contact atomically clears the previous one; setting is_primary makes this the contact's primary organization and clears their previous one.", "operationId": "updateOrganizationMember", "parameters": [ { "description": "Typed ID with prefix 'O'", "in": "path", "name": "organization_id", "required": true, "schema": { "description": "Typed ID with prefix 'O'", "title": "Organization Id", "type": "string" } }, { "description": "Membership row id (UUID)", "in": "path", "name": "membership_id", "required": true, "schema": { "description": "Membership row id (UUID)", "title": "Membership Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationMemberUpdate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationMemberResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Edit a membership (title, affiliation, reporting line, primary contact)", "tags": [ "organizations", "Organizations" ], "x-local-capability": "outbox", "x-mcp-skip": true, "x-mcp-skip-reason": "Org membership management UI flow — rows are local-first synced." } }, "/api/v1/organizations/{organization_id}/merge-history": { "get": { "description": "Organizations merged away into this survivor (F1).\n\nServed from ``organization_merge_history`` rows — the name is the loser's\ndisplay name AT MERGE TIME, never parsed out of residual prose or aliases.\nUndone merges are excluded.", "operationId": "getOrganizationMergeHistory", "parameters": [ { "description": "Typed ID with prefix 'O'", "in": "path", "name": "organization_id", "required": true, "schema": { "description": "Typed ID with prefix 'O'", "title": "Organization Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationMergeHistoryResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Merge provenance for an organization", "tags": [ "organizations", "Organization Merge" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Human-confirmed organization dedup review flow — not an agent workflow." } }, "/api/v1/organizations/{organization_id}/photo": { "delete": { "description": "Clear the organization's uploaded-photo slot (photo_url + thumbnail).\n ``identity_source`` is nulled only when it was 'photo', returning identity\n resolution to automatic (logo → icon → default building).", "operationId": "deleteOrganizationPhoto", "parameters": [ { "description": "Typed ID with prefix 'O'", "in": "path", "name": "organization_id", "required": true, "schema": { "description": "Typed ID with prefix 'O'", "title": "Organization Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Deleteorganizationphoto", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Clear the organization's uploaded photo", "tags": [ "organizations", "Organizations" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Avatar/photo management UI flow — not an agent workflow." }, "post": { "description": "Upload a photo for an organization (multipart/form-data, 'file' field).\n\n Accepts jpg, png, webp up to 5MB. Stores a resized main image plus an\n inline square thumbnail and sets ``identity_source='photo'`` so the\n uploaded photo becomes the displayed identity.\n\n Response:\n {\n \"photo_url\": \"<storage path>\",\n \"photo_thumbnail\": \"<base64 jpeg, square, <8KB>\",\n \"identity_source\": \"photo\"\n }", "operationId": "uploadOrganizationPhoto", "parameters": [ { "description": "Typed ID with prefix 'O'", "in": "path", "name": "organization_id", "required": true, "schema": { "description": "Typed ID with prefix 'O'", "title": "Organization Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/Body_uploadOrganizationPhoto" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Uploadorganizationphoto", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Upload an organization photo", "tags": [ "organizations", "Organizations" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Avatar/photo management UI flow — not an agent workflow." } }, "/api/v1/organizations/{organization_id}/reject": { "post": { "description": "Reject an organization that was flagged for review.\n\n Performs soft delete (sets deleted_at timestamp).\n\n Returns success message.\n\n Error Responses:\n - 401 Unauthorized: Missing or invalid JWT token\n - 404 Not Found: Organization does not exist or does not belong to user's tenant\n - 500 Internal Server Error: Database operation failed\n\n Related: Organizations Review Feature", "operationId": "rejectOrganization", "parameters": [ { "description": "Typed ID with prefix 'O'", "in": "path", "name": "organization_id", "required": true, "schema": { "description": "Typed ID with prefix 'O'", "title": "Organization Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Rejectorganization", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Reject organization", "tags": [ "organizations" ] } }, "/api/v1/pats": { "get": { "operationId": "listPats", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListPATsResponse" } } }, "description": "Successful Response" } }, "summary": "List Own Pats", "tags": [ "pats", "pats" ] }, "post": { "operationId": "createPat", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePATRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePATResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Create Pat", "tags": [ "pats", "pats" ] } }, "/api/v1/pats/agent": { "delete": { "description": "Bulk-revoke every ``client_kind='agent'`` PAT for the calling account.\n\nThe desktop sign-out / session-revocation path (TIDY-13875 R3 edge case)\ninvalidates all CLI-agent credentials in one call. User webhook PATs are\nleft untouched. Declared BEFORE the ``/{pat_id}`` route so the literal\n``agent`` segment is not captured as a pat_id.", "operationId": "revokeAllAgentPats", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevokeAgentPatsResponse" } } }, "description": "Successful Response" } }, "summary": "Revoke All Agent Pats", "tags": [ "pats", "pats" ], "x-mcp-skip": true } }, "/api/v1/pats/{pat_id}": { "delete": { "operationId": "revokePat", "parameters": [ { "in": "path", "name": "pat_id", "required": true, "schema": { "title": "Pat Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevokePATResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Revoke Pat", "tags": [ "pats", "pats" ] } }, "/api/v1/photos": { "post": { "description": "Validate, store, and persist one photo; publish for processing.\n\nA malformed ``client_analysis`` envelope is a 422 (``invalid_client_analysis``).", "operationId": "ingestPhoto", "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/Body_ingestPhoto" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PhotoIngestResponse" } } }, "description": "Successful Response" }, "410": { "description": "client_upload_id_gone: the member removed this photo; the key cannot recreate it" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Ingest a photo", "tags": [ "photos", "photos" ], "x-mcp-skip": true, "x-mcp-skip-reason": "Multipart binary upload from web/mobile capture; not an agent tool." } }, "/api/v1/photos/extract-from-email": { "post": { "description": "The user's explicit click admits these attachments to the curated\ncorpus (D10/D2) — fetch, ingest, auto-collage (>1 new), journal landing.", "operationId": "extractPhotosFromEmail", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailPhotoExtractRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailPhotoExtractResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Extract email attachments into the photo pipeline", "tags": [ "photos", "photos" ], "x-mcp-skip": true, "x-mcp-skip-reason": "Explicit in-context email-surface action (D10); not an agent tool." } }, "/api/v1/photos/{photo_id}": { "delete": { "description": "Soft-delete a photo + cascade to its faces. S3 original is RETAINED.", "operationId": "deletePhoto", "parameters": [ { "in": "path", "name": "photo_id", "required": true, "schema": { "format": "uuid", "title": "Photo Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PhotoDeleteResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Soft-delete a photo", "tags": [ "photos", "photos" ], "x-mcp-skip": true, "x-mcp-skip-reason": "User-initiated photo deletion from the UI; not an agent tool." }, "patch": { "description": "Set or clear the caption on a member-visible photo (TIDY-15490).\n\nOBO write: a delegated caption edit requires a ``read_write`` ``photos``\ngrant (``need_write=True``). With only a read grant (or none) the write\nfalls back to the caller's own visibility — a principal-private photo is a\n404, never a leak, never a 403 (R4). The audit row is written in the same\ntransaction as the mutation (audit-before-act / R7).", "operationId": "updatePhotoCaption", "parameters": [ { "in": "path", "name": "photo_id", "required": true, "schema": { "format": "uuid", "title": "Photo Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PhotoCaptionUpdateRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PhotoCaptionResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Update a photo's caption", "tags": [ "photos", "photos" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Photo-library UI edit surface; delegates reach it via the generic HTTP path (TIDY-15490 R6)." } }, "/api/v1/photos/{photo_id}/export": { "get": { "description": "Return the original image with ``PersonInImage`` XMP for the people the\nEXPORTING member can see (R29). Names for contacts outside the exporter's\nvisibility are never embedded.\n\nTIDY-15490 — OBO read: with an active ``photos`` read grant the export runs\nunder the principal's visibility; without one it falls back to the caller\n(404 on a principal-private photo), never widening (R4).", "operationId": "exportPhoto", "parameters": [ { "in": "path", "name": "photo_id", "required": true, "schema": { "format": "uuid", "title": "Photo Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "image/jpeg": {} }, "description": "Image with PersonInImage XMP" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Export a photo with visible people names embedded", "tags": [ "photos", "photos" ], "x-mcp-skip": true, "x-mcp-skip-reason": "Binary image download with embedded metadata; not an agent tool." } }, "/api/v1/photos/{photo_id}/faces": { "get": { "operationId": "listPhotoFaces", "parameters": [ { "in": "path", "name": "photo_id", "required": true, "schema": { "format": "uuid", "title": "Photo Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FaceListResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List Photo Faces", "tags": [ "photo-faces", "photo-faces" ], "x-mcp-skip": true, "x-mcp-skip-reason": "Face-recognition UI surface (overlays/markers/people rail); not an agent tool." } }, "/api/v1/pipeline/entitlement": { "get": { "description": "Current-cycle email-pipeline utilization + ladder stage for the caller.", "operationId": "getPipelineEntitlement", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PipelineEntitlementResponse" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Pipeline Entitlement", "tags": [ "pipeline-entitlement", "pipeline-entitlement" ], "x-mcp-skip": true } }, "/api/v1/plugin-events/{plugin_id}": { "post": { "operationId": "receivePluginEvent", "parameters": [ { "in": "path", "name": "plugin_id", "required": true, "schema": { "title": "Plugin Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PluginEventReceipt" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Deliver an event to a plugin — the body is the event; the plugin's scheme authenticates it", "tags": [ "plugins" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "The public door an outside sender delivers to; never called on a member's behalf." } }, "/api/v1/plugin-events/{plugin_id}/{secret}": { "post": { "operationId": "receivePluginEventWithUrlSecret", "parameters": [ { "in": "path", "name": "plugin_id", "required": true, "schema": { "title": "Plugin Id", "type": "string" } }, { "in": "path", "name": "secret", "required": true, "schema": { "title": "Secret", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PluginEventReceipt" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Deliver an event to a plugin whose secret is the last segment of its URL", "tags": [ "plugins" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "The public door an outside sender delivers to; never called on a member's behalf." } }, "/api/v1/plugin-lends/{grant_id}": { "delete": { "operationId": "revokePluginLend", "parameters": [ { "in": "path", "name": "grant_id", "required": true, "schema": { "title": "Grant Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PluginLend" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Revoke a lend and withdraw every shipment made under it", "tags": [ "access" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Lending is a first-party Access surface; grants and tokens are never assistant-callable." } }, "/api/v1/plugin-lends/{grant_id}/ship": { "post": { "operationId": "shipPluginLend", "parameters": [ { "in": "path", "name": "grant_id", "required": true, "schema": { "title": "Grant Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShipRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PluginShipment" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Ship a standing lend to the employee's workshop", "tags": [ "access" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Lending is a first-party Access surface; grants and tokens are never assistant-callable." } }, "/api/v1/plugin-shipments/{shipment_id}": { "delete": { "operationId": "revokePluginShipment", "parameters": [ { "in": "path", "name": "shipment_id", "required": true, "schema": { "title": "Shipment Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PluginShipment" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Withdraw one shipment without revoking the lend", "tags": [ "access" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Lending is a first-party Access surface; grants and tokens are never assistant-callable." } }, "/api/v1/plugins": { "get": { "operationId": "listPlugins", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PluginsResponse" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List the plugins the member may see", "tags": [ "plugins" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Plugin custody is a first-party settings surface; the assistant reads plugins local-first." } }, "/api/v1/plugins/api-key": { "post": { "operationId": "connectApiKeyPlugin", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PluginApiKeyConnect" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PluginsResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Connect a built-in API with its own key, or replace that key", "tags": [ "plugins" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Plugin custody is a first-party settings surface; the assistant reads plugins local-first." } }, "/api/v1/plugins/catalog": { "get": { "operationId": "listPluginCatalog", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PluginCatalogResponse" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "The plugin catalogue — every app Tidy can connect", "tags": [ "plugins" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Plugin custody is a first-party settings surface; the assistant reads plugins local-first." } }, "/api/v1/plugins/connect-link": { "get": { "operationId": "getPluginConnectLink", "parameters": [ { "description": "A catalogue kind, e.g. github", "in": "query", "name": "kind", "required": true, "schema": { "description": "A catalogue kind, e.g. github", "maxLength": 80, "minLength": 1, "title": "Kind", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PluginConnectLinkResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Where the member connects a catalogue plugin themselves", "tags": [ "plugins" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "An assistant's or employee's door: the Tidy Assistant's tidy_plugins tool and an employee's runtime token call it; a member connects plugins in Plugins." } }, "/api/v1/plugins/custom-webhook": { "post": { "operationId": "createCustomWebhookPlugin", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomWebhookCreate" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PluginEventsSecretResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Make a Custom webhook plugin — its door, and how deliveries prove themselves", "tags": [ "plugins" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "A plugin's Events are a first-party settings surface; rules bind to them through the automations tools." } }, "/api/v1/plugins/integration-families": { "get": { "operationId": "getIntegrationFamilies", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationFamiliesResponse" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "The one integration each of Tidy's mail, calendar, drive and source-control tools reaches for the caller", "tags": [ "plugins" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "An assistant's or employee's door: the Tidy Assistant's tidy_plugins tool and an employee's runtime token call it; a member connects plugins in Plugins." } }, "/api/v1/plugins/setup": { "post": { "operationId": "setUpPluginForMember", "parameters": [ { "in": "header", "name": "X-Tidy-Acting-Principal", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tidy-Acting-Principal" } }, { "in": "header", "name": "X-Internal-Service", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service" } }, { "in": "header", "name": "X-Internal-Service-Key", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service-Key" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PluginSetupCreate" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PluginSetupResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "An assistant or employee sets a plugin up for the member; the member enters any secret", "tags": [ "plugins" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "An assistant's or employee's door: the Tidy Assistant's tidy_plugins tool and an employee's runtime token call it; a member connects plugins in Plugins." } }, "/api/v1/plugins/sign-in": { "post": { "operationId": "startPluginSignIn", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PluginSignInStart" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PluginSignInStartResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Start signing a built-in API in with its provider (Sign in with Todoist)", "tags": [ "plugins" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Plugin custody is a first-party settings surface; the assistant reads plugins local-first." } }, "/api/v1/plugins/usable": { "get": { "operationId": "listUsablePlugins", "parameters": [ { "in": "header", "name": "X-Tidy-Acting-Principal", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tidy-Acting-Principal" } }, { "in": "header", "name": "X-Internal-Service", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service" } }, { "in": "header", "name": "X-Internal-Service-Key", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service-Key" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsablePluginsResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "The plugins an assistant or employee may use, as it reads them — never a value", "tags": [ "plugins" ], "x-local-capability": "cloud" } }, "/api/v1/plugins/webhook-destination": { "post": { "operationId": "saveWebhookDestination", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDestinationSave" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PluginsResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Connect a webhook destination — its URL, how deliveries prove themselves and the secret — or change one", "tags": [ "plugins" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Plugin custody is a first-party settings surface; rules send through the automations tools." } }, "/api/v1/plugins/{plugin_id}": { "delete": { "operationId": "removePlugin", "parameters": [ { "in": "path", "name": "plugin_id", "required": true, "schema": { "title": "Plugin Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PluginRemovedResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Remove — disconnect, revoke the vault credential, tombstone the row", "tags": [ "plugins" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Plugin custody is a first-party settings surface; the assistant reads plugins local-first." } }, "/api/v1/plugins/{plugin_id}/destination": { "get": { "operationId": "getWebhookDestination", "parameters": [ { "in": "path", "name": "plugin_id", "required": true, "schema": { "title": "Plugin Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDestination" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "A webhook destination: where it posts, how it proves itself, on or off, its last delivery", "tags": [ "plugins" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Plugin custody is a first-party settings surface; rules send through the automations tools." }, "patch": { "operationId": "setWebhookDestinationEnabled", "parameters": [ { "in": "path", "name": "plugin_id", "required": true, "schema": { "title": "Plugin Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDestinationEnabled" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDestination" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Turn a webhook destination off — every send naming it is refused — or back on", "tags": [ "plugins" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Plugin custody is a first-party settings surface; rules send through the automations tools." } }, "/api/v1/plugins/{plugin_id}/destination/test": { "post": { "operationId": "testWebhookDestination", "parameters": [ { "in": "path", "name": "plugin_id", "required": true, "schema": { "title": "Plugin Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDestinationTestResult" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Send {\"event\": \"test\"} the way a rule sends, and answer what the destination said", "tags": [ "plugins" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Plugin custody is a first-party settings surface; rules send through the automations tools." } }, "/api/v1/plugins/{plugin_id}/events": { "get": { "operationId": "getPluginEvents", "parameters": [ { "in": "path", "name": "plugin_id", "required": true, "schema": { "title": "Plugin Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PluginEventsResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "A plugin's Events: its URL, verification and event types", "tags": [ "plugins" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "A plugin's Events are a first-party settings surface; rules bind to them through the automations tools." }, "patch": { "operationId": "updatePluginEvents", "parameters": [ { "in": "path", "name": "plugin_id", "required": true, "schema": { "title": "Plugin Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PluginEventsUpdate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PluginEventsSecretResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Change how deliveries prove themselves, rotate the secret, or turn the door off", "tags": [ "plugins" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "A plugin's Events are a first-party settings surface; rules bind to them through the automations tools." } }, "/api/v1/plugins/{plugin_id}/events/deliveries": { "get": { "operationId": "listPluginEventDeliveries", "parameters": [ { "in": "path", "name": "plugin_id", "required": true, "schema": { "title": "Plugin Id", "type": "string" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "title": "Limit", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/PluginEventDeliveryResponse" }, "title": "Response Listplugineventdeliveries", "type": "array" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "The delivery log: what arrived, whether it was accepted, and why not", "tags": [ "plugins" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "A plugin's Events are a first-party settings surface; rules bind to them through the automations tools." } }, "/api/v1/plugins/{plugin_id}/events/door": { "post": { "operationId": "openPluginEventsDoor", "parameters": [ { "in": "path", "name": "plugin_id", "required": true, "schema": { "title": "Plugin Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PluginEventsDoorOpen" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PluginEventsResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Turn a built-in plugin's events on — with the provider's secret, or waiting for its verification token", "tags": [ "plugins" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "A plugin's Events are a first-party settings surface; rules bind to them through the automations tools." } }, "/api/v1/plugins/{plugin_id}/events/types": { "post": { "operationId": "createPluginEventType", "parameters": [ { "in": "path", "name": "plugin_id", "required": true, "schema": { "title": "Plugin Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PluginEventTypeCreate" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PluginEventTypeResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Add an event — from a pasted sample, or listening for a test delivery", "tags": [ "plugins" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "A plugin's Events are a first-party settings surface; rules bind to them through the automations tools." } }, "/api/v1/plugins/{plugin_id}/events/types/{event_type_id}": { "delete": { "operationId": "deletePluginEventType", "parameters": [ { "in": "path", "name": "plugin_id", "required": true, "schema": { "title": "Plugin Id", "type": "string" } }, { "in": "path", "name": "event_type_id", "required": true, "schema": { "title": "Event Type Id", "type": "string" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Delete an event — the rules that fire on it are paused, saying why", "tags": [ "plugins" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "A plugin's Events are a first-party settings surface; rules bind to them through the automations tools." }, "patch": { "operationId": "updatePluginEventType", "parameters": [ { "in": "path", "name": "plugin_id", "required": true, "schema": { "title": "Plugin Id", "type": "string" } }, { "in": "path", "name": "event_type_id", "required": true, "schema": { "title": "Event Type Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PluginEventTypeUpdate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PluginEventTypeResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Edit an event: its fields, routing, workflows and assign-employee action", "tags": [ "plugins" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "A plugin's Events are a first-party settings surface; rules bind to them through the automations tools." } }, "/api/v1/plugins/{plugin_id}/events/types/{event_type_id}/mapping-runs": { "get": { "operationId": "listPayloadMappingRuns", "parameters": [ { "in": "path", "name": "plugin_id", "required": true, "schema": { "title": "Plugin Id", "type": "string" } }, { "in": "path", "name": "event_type_id", "required": true, "schema": { "title": "Event Type Id", "type": "string" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 20, "title": "Limit", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/PayloadMappingRunResponse" }, "title": "Response Listpayloadmappingruns", "type": "array" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List Mapping Runs", "tags": [ "plugins" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/plugins/{plugin_id}/events/types/{event_type_id}/mappings": { "get": { "operationId": "listPayloadMappings", "parameters": [ { "in": "path", "name": "plugin_id", "required": true, "schema": { "title": "Plugin Id", "type": "string" } }, { "in": "path", "name": "event_type_id", "required": true, "schema": { "title": "Event Type Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/PayloadMappingResponse" }, "title": "Response Listpayloadmappings", "type": "array" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List Mappings", "tags": [ "plugins" ], "x-local-capability": "cloud", "x-mcp-skip": true }, "post": { "operationId": "createPayloadMapping", "parameters": [ { "in": "path", "name": "plugin_id", "required": true, "schema": { "title": "Plugin Id", "type": "string" } }, { "in": "path", "name": "event_type_id", "required": true, "schema": { "title": "Event Type Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayloadMappingCreate" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayloadMappingResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Create Mapping", "tags": [ "plugins" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/plugins/{plugin_id}/events/types/{event_type_id}/mappings/{mapping_id}": { "delete": { "operationId": "deletePayloadMapping", "parameters": [ { "in": "path", "name": "plugin_id", "required": true, "schema": { "title": "Plugin Id", "type": "string" } }, { "in": "path", "name": "event_type_id", "required": true, "schema": { "title": "Event Type Id", "type": "string" } }, { "in": "path", "name": "mapping_id", "required": true, "schema": { "title": "Mapping Id", "type": "string" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Delete Mapping", "tags": [ "plugins" ], "x-local-capability": "cloud", "x-mcp-skip": true }, "patch": { "operationId": "updatePayloadMapping", "parameters": [ { "in": "path", "name": "plugin_id", "required": true, "schema": { "title": "Plugin Id", "type": "string" } }, { "in": "path", "name": "event_type_id", "required": true, "schema": { "title": "Event Type Id", "type": "string" } }, { "in": "path", "name": "mapping_id", "required": true, "schema": { "title": "Mapping Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayloadMappingUpdate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayloadMappingResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Update Mapping", "tags": [ "plugins" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/plugins/{plugin_id}/events/types/{event_type_id}/sample": { "post": { "operationId": "setPluginEventSample", "parameters": [ { "in": "path", "name": "plugin_id", "required": true, "schema": { "title": "Plugin Id", "type": "string" } }, { "in": "path", "name": "event_type_id", "required": true, "schema": { "title": "Event Type Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PluginEventSample" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PluginEventTypeResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Paste a sample — the event's fields are inferred from it", "tags": [ "plugins" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "A plugin's Events are a first-party settings surface; rules bind to them through the automations tools." } }, "/api/v1/plugins/{plugin_id}/lend": { "post": { "operationId": "lendPlugin", "parameters": [ { "in": "path", "name": "plugin_id", "required": true, "schema": { "title": "Plugin Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LendRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LendResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Lend a plugin to an employee under a capability scope", "tags": [ "access" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Lending is a first-party Access surface; grants and tokens are never assistant-callable." } }, "/api/v1/plugins/{plugin_id}/reauth": { "post": { "operationId": "reauthPlugin", "parameters": [ { "in": "path", "name": "plugin_id", "required": true, "schema": { "title": "Plugin Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PluginReauthResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Sign in again — where the client re-runs this plugin's sign-in", "tags": [ "plugins" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Plugin custody is a first-party settings surface; the assistant reads plugins local-first." } }, "/api/v1/plugins/{plugin_id}/setup": { "patch": { "operationId": "updatePluginSetupForMember", "parameters": [ { "in": "path", "name": "plugin_id", "required": true, "schema": { "title": "Plugin Id", "type": "string" } }, { "in": "header", "name": "X-Tidy-Acting-Principal", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tidy-Acting-Principal" } }, { "in": "header", "name": "X-Internal-Service", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service" } }, { "in": "header", "name": "X-Internal-Service-Key", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service-Key" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PluginSetupUpdate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PluginSetupResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "An assistant or employee changes a plugin the member owns — never its secret or sharing", "tags": [ "plugins" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "An assistant's or employee's door: the Tidy Assistant's tidy_plugins tool and an employee's runtime token call it; a member connects plugins in Plugins." } }, "/api/v1/plugins/{plugin_id}/sheets": { "get": { "operationId": "getPluginSheets", "parameters": [ { "in": "path", "name": "plugin_id", "required": true, "schema": { "title": "Plugin Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PluginSheetsResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "A Google plugin's picked sheets, their columns, and whether Tidy is watching them", "tags": [ "plugins" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "A Google plugin's Sheets section is a first-party settings surface; rules use its sheets through the automations tools (Find, Append and Update row)." } }, "/api/v1/plugins/{plugin_id}/sheets/pick": { "post": { "operationId": "pickPluginSheets", "parameters": [ { "in": "path", "name": "plugin_id", "required": true, "schema": { "title": "Plugin Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PluginSheetsPickRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PluginSheetsPickResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Open Google's Picker to pick spreadsheets this Google plugin may read and write", "tags": [ "plugins" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "A Google plugin's Sheets section is a first-party settings surface; rules use its sheets through the automations tools (Find, Append and Update row)." } }, "/api/v1/plugins/{plugin_id}/sheets/{sheet_id}": { "delete": { "operationId": "removePluginSheet", "parameters": [ { "in": "path", "name": "plugin_id", "required": true, "schema": { "title": "Plugin Id", "type": "string" } }, { "in": "path", "name": "sheet_id", "required": true, "schema": { "title": "Sheet Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PluginSheetsResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Stop using a picked sheet; the rules on its events pause and say why", "tags": [ "plugins" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "A Google plugin's Sheets section is a first-party settings surface; rules use its sheets through the automations tools (Find, Append and Update row)." }, "patch": { "operationId": "updatePluginSheet", "parameters": [ { "in": "path", "name": "plugin_id", "required": true, "schema": { "title": "Plugin Id", "type": "string" } }, { "in": "path", "name": "sheet_id", "required": true, "schema": { "title": "Sheet Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PluginSheetUpdate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PluginSheetsResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Change a picked sheet's tab, header row or key column", "tags": [ "plugins" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "A Google plugin's Sheets section is a first-party settings surface; rules use its sheets through the automations tools (Find, Append and Update row)." } }, "/api/v1/plugins/{plugin_id}/sheets/{sheet_id}/read": { "post": { "operationId": "readPluginSheet", "parameters": [ { "in": "path", "name": "plugin_id", "required": true, "schema": { "title": "Plugin Id", "type": "string" } }, { "in": "path", "name": "sheet_id", "required": true, "schema": { "title": "Sheet Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PluginSheetsResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Read a picked sheet now — and watch its spreadsheet again if Tidy stopped", "tags": [ "plugins" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "A Google plugin's Sheets section is a first-party settings surface; rules use its sheets through the automations tools (Find, Append and Update row)." } }, "/api/v1/plugins/{plugin_id}/sheets/{sheet_id}/tabs": { "get": { "operationId": "listPluginSheetTabs", "parameters": [ { "in": "path", "name": "plugin_id", "required": true, "schema": { "title": "Plugin Id", "type": "string" } }, { "in": "path", "name": "sheet_id", "required": true, "schema": { "title": "Sheet Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/PluginSheetTab" }, "title": "Response Listpluginsheettabs", "type": "array" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "The tabs of a picked sheet's spreadsheet", "tags": [ "plugins" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "A Google plugin's Sheets section is a first-party settings surface; rules use its sheets through the automations tools (Find, Append and Update row)." }, "post": { "operationId": "addPluginSheetTab", "parameters": [ { "in": "path", "name": "plugin_id", "required": true, "schema": { "title": "Plugin Id", "type": "string" } }, { "in": "path", "name": "sheet_id", "required": true, "schema": { "title": "Sheet Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PluginSheetTabAdd" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PluginSheetsResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Pick another tab of a spreadsheet already picked", "tags": [ "plugins" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "A Google plugin's Sheets section is a first-party settings surface; rules use its sheets through the automations tools (Find, Append and Update row)." } }, "/api/v1/plugins/{plugin_id}/verify": { "post": { "operationId": "verifyPlugin", "parameters": [ { "in": "path", "name": "plugin_id", "required": true, "schema": { "title": "Plugin Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PluginsResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Check the stored credential and flip the plugin's status", "tags": [ "plugins" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Plugin custody is a first-party settings surface; the assistant reads plugins local-first." } }, "/api/v1/podcast/corpus-search": { "get": { "description": "Hybrid corpus search with RRF + V1 ranking.\n\ntidy-tenant-wide-justified: the podcast corpus is a global platform asset\n(D75/D92); this reads the shared index only — no per-tenant primitive row\npayload leaves the service.", "operationId": "searchPodcastCorpus", "parameters": [ { "in": "query", "name": "q", "required": true, "schema": { "maxLength": 500, "minLength": 1, "title": "Q", "type": "string" } }, { "in": "query", "name": "scope", "required": false, "schema": { "default": "corpus", "enum": [ "corpus", "show" ], "title": "Scope", "type": "string" } }, { "in": "query", "name": "show_id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Show Id" } }, { "in": "query", "name": "include_ads", "required": false, "schema": { "default": false, "title": "Include Ads", "type": "boolean" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cursor" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CorpusSearchResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Search Podcast Corpus", "tags": [ "podcast-corpus-search" ], "x-mcp-skip": true, "x-mcp-skip-reason": "Podcast-workspace search-bar surface (S3 UI); not an MCP agent workflow. Corpus discovery happens in the podcast app, not via tools." } }, "/api/v1/podcast/corpus-stats": { "get": { "description": "What the global podcast corpus holds: totals, entity types, the most\nmentioned entities and the most transcribed shows.\n\ntidy-tenant-wide-justified: the podcast corpus is a global platform asset\n(D75/D92); these are aggregates over the shared catalog tables only — no\nper-tenant row is read.", "operationId": "getPodcastCorpusStats", "parameters": [ { "in": "query", "name": "entity_type", "required": false, "schema": { "anyOf": [ { "enum": [ "person", "organization", "product", "book" ], "type": "string" }, { "type": "null" } ], "title": "Entity Type" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CorpusStatsResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Podcast Corpus Stats", "tags": [ "podcast-corpus-search" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Podcast-workspace Corpus tab summary (TIDY-19383); not an MCP agent workflow, like the corpus search beside it." } }, "/api/v1/podcast/corpus/episodes/{episode_id}/ensure-transcript-note": { "post": { "description": "Materialize (idempotently) the per-tenant follow-along transcript NOTE for\na GLOBAL/corpus episode and return its note id (R-P4.12).\n\nThe corpus episode page calls this on open. The writeback receiver is\nGLOBAL-only (D81) and cannot write a per-tenant note; PowerSync syncs `notes`\nonly to their own tenant — so the note is materialized lazily here, in the\ncaller's tenant, from the GLOBAL episode's current transcript version, reusing\nthe EXISTING ``upsert_episode_transcript_note`` writer (one note shape, one\nwriter). The resulting row + Yjs body then sync down via PowerSync and the\npage renders FollowAlongText. Idempotent: a repeat call replaces only the\nmanaged body and returns the same note id.", "operationId": "ensureCorpusTranscriptNote", "parameters": [ { "in": "path", "name": "episode_id", "required": true, "schema": { "format": "uuid", "title": "Episode Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnsureTranscriptNoteResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Materialize the caller-tenant transcript note for a corpus episode", "tags": [ "podcast" ], "x-mcp-skip": true } }, "/api/v1/podcast/cuts": { "get": { "operationId": "listPodcastCuts", "parameters": [ { "in": "query", "name": "subscription_id", "required": false, "schema": { "anyOf": [ { "maxLength": 36, "minLength": 36, "type": "string" }, { "type": "null" } ], "title": "Subscription Id" } }, { "in": "query", "name": "episode_id", "required": false, "schema": { "anyOf": [ { "maxLength": 36, "minLength": 36, "type": "string" }, { "type": "null" } ], "title": "Episode Id" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 100, "maximum": 500, "minimum": 1, "title": "Limit", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PodcastCutListResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List podcast cuts for current account", "tags": [ "podcast", "podcast" ] }, "post": { "description": "Create a podcast cut + its `notes` row in one transaction; publish\n`cut.materialize` after commit. Returns 201 immediately — the AI\nextraction runs asynchronously (S3).\n\nA global-episode cut is the user-initiated transcription request path.\nBefore creating it, the credit pool is gated (402 pool_exhausted /\ncheckpoint_required — the per-tier daily-caps framework folded into the\ncredit pool in TIDY-12057; ASR cost is metered by the debit pipeline) and a\nglobal per-caller in-flight concurrency guard protects shared ASR compute.\nPersonal cuts never create a transcription job, so they skip the gate.", "operationId": "createPodcastCut", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PodcastCutCreateRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PodcastCutResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Capture a quick/deep podcast cut", "tags": [ "podcast", "podcast" ] } }, "/api/v1/podcast/cuts/{cut_id}": { "delete": { "description": "Cleanup-aware delete. When Phase 2 has run, also strips the episode-page\ntransclusion + journal back-ref + linked_references rows.", "operationId": "deletePodcastCut", "parameters": [ { "in": "path", "name": "cut_id", "required": true, "schema": { "format": "uuid", "title": "Cut Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PodcastCutDeleteResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Delete (undo) a podcast cut and clean up embeds", "tags": [ "podcast", "podcast" ] } }, "/api/v1/podcast/cuts/{cut_id}/finalize-deep-cut": { "post": { "description": "Merge user's framing into the note's properties.original_notes and\nrepublish ``cut.materialize`` so the AI sees it. 400 if not deep. A\nlate finalize after a prior materialization resets the cut to a\nnon-terminal status and reruns extraction with the user's framing.", "operationId": "finalizePodcastDeepCut", "parameters": [ { "in": "path", "name": "cut_id", "required": true, "schema": { "format": "uuid", "title": "Cut Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FinalizeDeepCutRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PodcastCutResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Submit Deep Cut composer text", "tags": [ "podcast", "podcast" ] } }, "/api/v1/podcast/cuts/{cut_id}/regenerate": { "post": { "description": "Reset status to ``extracting`` and republish ``cut.materialize``.\nReads CURRENT preferences.", "operationId": "regeneratePodcastCut", "parameters": [ { "in": "path", "name": "cut_id", "required": true, "schema": { "format": "uuid", "title": "Cut Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PodcastCutResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Re-run AI extraction for an existing cut", "tags": [ "podcast", "podcast" ] } }, "/api/v1/podcast/cuts/{cut_id}/upgrade-transcript-version": { "post": { "description": "Opt-in (D69): move the cut's transcript pin to the episode's current\nversion, recompute the canonical window, and re-run AI extraction. No-op if\nalready current.", "operationId": "upgradePodcastCutTranscriptVersion", "parameters": [ { "in": "path", "name": "cut_id", "required": true, "schema": { "format": "uuid", "title": "Cut Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PodcastCutResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Re-pin a cut to the latest transcript version (opt-in)", "tags": [ "podcast", "podcast" ] } }, "/api/v1/podcast/discovery/categories": { "get": { "description": "Return globally synced podcast categories.", "operationId": "listPodcastDiscoveryCategories", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PodcastDiscoveryCategoriesResponse" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List podcast discovery categories", "tags": [ "podcast-search" ] } }, "/api/v1/podcast/discovery/podchaser": { "get": { "description": "Return Podchaser top podcasts with categories.", "operationId": "listPodchaserDiscovery", "parameters": [ { "description": "Filter by category slug", "in": "query", "name": "category", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by category slug", "title": "Category" } }, { "description": "Filter by sort type: rating or popular", "in": "query", "name": "sort_type", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by sort type: rating or popular", "title": "Sort Type" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 500, "maximum": 2000, "minimum": 1, "title": "Limit", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PodchaserDiscoveryResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Podchaser top podcasts and categories", "tags": [ "podcast-search" ] } }, "/api/v1/podcast/discovery/trending": { "get": { "description": "Return globally synced podcast trending rows.", "operationId": "listPodcastDiscoveryTrending", "parameters": [ { "in": "query", "name": "limit", "required": false, "schema": { "default": 5000, "maximum": 5000, "minimum": 1, "title": "Limit", "type": "integer" } }, { "in": "query", "name": "category_id", "required": false, "schema": { "anyOf": [ { "minimum": 1, "type": "integer" }, { "type": "null" } ], "title": "Category Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PodcastDiscoveryTrendingListResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List podcast discovery trending entries", "tags": [ "podcast-search" ] } }, "/api/v1/podcast/drafts": { "get": { "operationId": "listPodcastDrafts", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PodcastDraftListResponse" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List podcast episode drafts", "tags": [ "podcast" ] }, "post": { "operationId": "createPodcastDraft", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PodcastDraftCreateRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PodcastDraftResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Create podcast episode draft", "tags": [ "podcast" ] } }, "/api/v1/podcast/drafts/{draft_id}": { "delete": { "operationId": "deletePodcastDraft", "parameters": [ { "in": "path", "name": "draft_id", "required": true, "schema": { "format": "uuid", "title": "Draft Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Delete podcast episode draft", "tags": [ "podcast" ] }, "get": { "operationId": "getPodcastDraft", "parameters": [ { "in": "path", "name": "draft_id", "required": true, "schema": { "format": "uuid", "title": "Draft Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PodcastDraftResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get podcast episode draft", "tags": [ "podcast" ] }, "patch": { "operationId": "updatePodcastDraft", "parameters": [ { "in": "path", "name": "draft_id", "required": true, "schema": { "format": "uuid", "title": "Draft Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PodcastDraftPatchRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PodcastDraftResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Autosave podcast episode draft", "tags": [ "podcast" ] } }, "/api/v1/podcast/drafts/{draft_id}/generate": { "post": { "operationId": "generatePodcastDraft", "parameters": [ { "in": "path", "name": "draft_id", "required": true, "schema": { "format": "uuid", "title": "Draft Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PodcastDraftSubmitResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Generate podcast episode from a draft", "tags": [ "podcast" ] } }, "/api/v1/podcast/entities/{entity_id}/claim": { "post": { "description": "Claim a corpus entity as a contact, linking contacts.podcast_entity_id.\n\nEither creates a new caller-owned contact pre-filled from the entity, OR\nlinks an existing caller-visible contact (when ``contact_id`` is supplied).\nThe FK link is persisted and audited; the global entity is untouched.", "operationId": "claimPodcastEntityAsContact", "parameters": [ { "in": "path", "name": "entity_id", "required": true, "schema": { "title": "Entity Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClaimEntityRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClaimEntityResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Claim Entity As Contact", "tags": [ "podcast-entities" ] } }, "/api/v1/podcast/entities/{entity_id}/timeline": { "get": { "description": "The entity record, its shows, and its chronological cross-corpus mention\ntimeline + co-appearances.\n\nThe mention set is subscription-agnostic (the whole corpus, newest first),\nkeyset-paged on ``(episode_published_at DESC, id)``. Co-appearances (entities\nsharing the focal entity's episodes) are computed once for the focal entity,\nnot per page. An id that names no corpus entity is a 404 — every\nco-appearance this endpoint returns resolves here (TIDY-19387).\n\ntidy-tenant-wide-justified: GLOBAL podcast corpus (D75) — no tenant column, no\nmember-owned payload.", "operationId": "getPodcastEntityTimeline", "parameters": [ { "in": "path", "name": "entity_id", "required": true, "schema": { "title": "Entity Id", "type": "string" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 200, "maximum": 500, "minimum": 1, "title": "Limit", "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cursor" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityTimelineResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Entity Timeline", "tags": [ "podcast-catalog" ], "x-mcp-skip": true, "x-mcp-skip-reason": "Podcast-workspace read surface (episode hub / entity page); not an MCP agent workflow. Agent corpus discovery uses searchPodcastCorpus." } }, "/api/v1/podcast/ephemeral-sync": { "post": { "operationId": "syncPodcastEphemeralEpisode", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PodcastEphemeralSyncRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PodcastEphemeralSyncResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Sync one preview episode without saving the podcast subscription", "tags": [ "podcast-subscriptions" ] } }, "/api/v1/podcast/episodes": { "get": { "operationId": "listPodcastEpisodes", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PodcastEpisodeListResponse" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List generated podcast episodes", "tags": [ "podcast" ] } }, "/api/v1/podcast/episodes/enrichment": { "get": { "description": "Batch-resolve episode hub content + enrichment signals by guid or global id.\n\ntidy-tenant-wide-justified: reads the GLOBAL podcast catalog (D75) only — no\ntenant column, no member-owned row payload leaves the service.", "operationId": "getPodcastEpisodeEnrichment", "parameters": [ { "description": "RSS guids to resolve (repeat the param). Batch key for the detail-view badges + rail guid->id map.", "in": "query", "name": "guids", "required": false, "schema": { "description": "RSS guids to resolve (repeat the param). Batch key for the detail-view badges + rail guid->id map.", "items": { "type": "string" }, "title": "Guids", "type": "array" } }, { "description": "Global episode ids to resolve (repeat the param). Batch key for the episode hub deep-linked by global id.", "in": "query", "name": "global_ids", "required": false, "schema": { "description": "Global episode ids to resolve (repeat the param). Batch key for the episode hub deep-linked by global id.", "items": { "type": "string" }, "title": "Global Ids", "type": "array" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EpisodeEnrichmentResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Episode Enrichment", "tags": [ "podcast-catalog" ], "x-mcp-skip": true, "x-mcp-skip-reason": "Podcast-workspace read surface (episode hub / entity page); not an MCP agent workflow. Agent corpus discovery uses searchPodcastCorpus." } }, "/api/v1/podcast/episodes/{episode_id}/audio": { "get": { "operationId": "streamPodcastAudio", "parameters": [ { "description": "Typed ID with prefix 'D'", "in": "path", "name": "episode_id", "required": true, "schema": { "description": "Typed ID with prefix 'D'", "title": "Episode Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Streampodcastaudio", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Stream generated podcast episode audio", "tags": [ "podcast" ] } }, "/api/v1/podcast/episodes/{episode_id}/fingerprint": { "get": { "description": "Return the gzipped canonical TAFP fingerprint blob for a global episode.\n\nThe web follow-along matcher (TIDY-11848) inflates this reference once per\nepisode and localizes the live audio tap against it to derive the live\ncanonical offset. 404 when the episode has no completed fingerprint — the\nclient then stays on the identity/approx single degraded path. The blob is\nthe corpus-shared, gzipped self-describing crate format; the algo version is\nsurfaced in a response header for cheap client-side staleness handling.", "operationId": "getPodcastEpisodeFingerprint", "parameters": [ { "description": "Typed ID with prefix 'D'", "in": "path", "name": "episode_id", "required": true, "schema": { "description": "Typed ID with prefix 'D'", "title": "Episode Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Getpodcastepisodefingerprint", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Serve the canonical audio fingerprint for follow-along matching", "tags": [ "podcast" ], "x-mcp-skip": true } }, "/api/v1/podcast/episodes/{episode_id}/player-transcript": { "get": { "description": "Return the player transcript (mapped to ms) + chapter markers for an\nepisode (TIDY-12399 / TIDY-A-951 / TIDY-12686).\n\n``episode_id`` may be a global corpus id (``podcast_global_episodes.id`` —\ncorpus-played episodes), a per-tenant external id\n(``podcast_external_episodes.id`` — subscription/queue playback), or a\nper-tenant GENERATED episode (``podcast_episodes.id``, TIDY-15702), whose\ntranscript is the projection of the script we rendered rather than an ASR\noutput. The generated branch is checked first and is tenant-scoped through\n``podcast_episodes``; since TIDY-16145 it ALSO accepts the generated\nepisode's subscription mirror id (the external row whose guid is\n``tidy-generated-<podcast_episodes.id>``), which is the id the queue and\nthe episode list actually hand the player. The other two resolve through\nthe shared\n``resolve_episode_transcript`` helper to the global episode's CURRENT\ntranscript version\n(``podcast_transcript_versions.transcript_json``, whisperx-shaped, seconds)\nand the (deliberately-not-synced) ``podcast_global_episodes.chapters``\ncolumn. Segments and chapters are mapped to ms via the shared\n``podcast_transcript_mapping`` helpers (the admin transcript viewer shares\nthe same segment source).\n\n404 when the id resolves to no episode, or the episode has no current\ntranscript version. The external id-space is tenant-scoped by the resolver;\nthe global corpus is tenant-agnostic (D81) so the ``tenant_id`` dep enforces\nauthentication only for that branch.", "operationId": "getPodcastEpisodePlayerTranscript", "parameters": [ { "description": "Typed ID with prefix 'D'", "in": "path", "name": "episode_id", "required": true, "schema": { "description": "Typed ID with prefix 'D'", "title": "Episode Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EpisodeTranscriptResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Transcript segments + chapters for the in-app podcast player", "tags": [ "podcast" ], "x-mcp-skip": true } }, "/api/v1/podcast/episodes/{external_episode_id}/note": { "get": { "operationId": "getPodcastEpisodeNote", "parameters": [ { "in": "path", "name": "external_episode_id", "required": true, "schema": { "format": "uuid", "title": "External Episode Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EpisodeNoteResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Resolve the episode page note id", "tags": [ "podcast", "podcast" ] } }, "/api/v1/podcast/episodes/{external_episode_id}/transcript": { "get": { "operationId": "getPodcastEpisodeTranscript", "parameters": [ { "in": "path", "name": "external_episode_id", "required": true, "schema": { "format": "uuid", "title": "External Episode Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TranscriptNoteResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Resolve the transcript page note id", "tags": [ "podcast", "podcast" ] } }, "/api/v1/podcast/episodes/{external_episode_id}/transcript/retranscribe": { "post": { "operationId": "retranscribePodcastEpisode", "parameters": [ { "in": "path", "name": "external_episode_id", "required": true, "schema": { "format": "uuid", "title": "External Episode Id", "type": "string" } }, { "in": "query", "name": "subscription_id", "required": true, "schema": { "maxLength": 36, "minLength": 36, "title": "Subscription Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetranscribeResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Trigger fresh transcription for an episode", "tags": [ "podcast", "podcast" ] } }, "/api/v1/podcast/episodes/{global_id}/mentions": { "get": { "description": "Promoted entity mentions (entities + roles + timestamps) for one episode.\n\ntidy-tenant-wide-justified: GLOBAL podcast corpus (D75) — no tenant column, no\nmember-owned payload.", "operationId": "getPodcastEpisodeMentions", "parameters": [ { "in": "path", "name": "global_id", "required": true, "schema": { "title": "Global Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EpisodeMentionsResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Episode Mentions", "tags": [ "podcast-catalog" ], "x-mcp-skip": true, "x-mcp-skip-reason": "Podcast-workspace read surface (episode hub / entity page); not an MCP agent workflow. Agent corpus discovery uses searchPodcastCorpus." } }, "/api/v1/podcast/feed-preview/episodes": { "get": { "operationId": "previewPodcastFeedEpisodes", "parameters": [ { "in": "query", "name": "rss_feed_url", "required": true, "schema": { "maxLength": 2000, "minLength": 1, "title": "Rss Feed Url", "type": "string" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 100, "maximum": 200, "minimum": 1, "title": "Limit", "type": "integer" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PodcastExternalEpisodeListResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Preview feed episodes without subscribing", "tags": [ "podcast-subscriptions" ] } }, "/api/v1/podcast/feed/artwork": { "patch": { "description": "Copy the chosen image into the show's own artwork object and publish it.\n\nThe stored value is a STABLE, absolute, token-scoped feed-artwork URL, never\na signed URL and never the caller's private user-files path — the feed is\nread by podcast clients for years, and none of them can present the\ncaller's bearer token (TIDY-17834 / D4). The same transaction projects that\nURL onto the caller's personal subscription row, so the list and detail\nsurfaces update without waiting for a feed poll.", "operationId": "setPodcastFeedArtwork", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PodcastFeedArtworkRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PodcastFeedSettingsResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Set the podcast show's cover art", "tags": [ "podcast-feed" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/podcast/feed/regenerate-token": { "post": { "operationId": "regeneratePodcastFeedToken", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PodcastFeedRegenerateResponse" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Regenerate podcast feed token", "tags": [ "podcast-feed" ] } }, "/api/v1/podcast/feed/settings": { "get": { "operationId": "getPodcastFeedSettings", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PodcastFeedSettingsResponse" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get podcast feed settings", "tags": [ "podcast-feed" ] } }, "/api/v1/podcast/feed/{token}": { "get": { "operationId": "getPodcastFeed", "parameters": [ { "in": "path", "name": "token", "required": true, "schema": { "title": "Token", "type": "string" } } ], "responses": { "200": { "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Public podcast RSS feed", "tags": [ "podcast-feed" ] } }, "/api/v1/podcast/feed/{token}/artwork/{revision}": { "get": { "description": "Serve the feed's own cover art to unauthenticated podcast clients.\n\nNo bearer auth: the feed token IS the capability, exactly as it is for the\nRSS document itself. The token selects one active `podcast_feeds` row, the\nrevision must equal the hash that row stores, and only that row's own\n`artwork_storage_path` is streamed. The caller supplies no storage ref, no\nfile id and no path, so this endpoint can never become a proxy for an\narbitrary private object — `/api/v1/storage/user-files/...` stays bearer\nauthenticated and member-scoped.", "operationId": "getPodcastFeedArtwork", "parameters": [ { "in": "path", "name": "token", "required": true, "schema": { "title": "Token", "type": "string" } }, { "in": "path", "name": "revision", "required": true, "schema": { "title": "Revision", "type": "string" } } ], "responses": { "200": { "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Public podcast cover art", "tags": [ "podcast-feed" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/podcast/generate": { "post": { "operationId": "generatePodcast", "parameters": [ { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PodcastGenerateRequest" } } }, "required": true }, "responses": { "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PodcastGenerateResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Enqueue podcast generation request", "tags": [ "podcast" ] } }, "/api/v1/podcast/jobs/{job_id}": { "get": { "operationId": "getPodcastJobStatus", "parameters": [ { "in": "path", "name": "job_id", "required": true, "schema": { "format": "uuid", "title": "Job Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PodcastJobStatusResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get podcast generation job status", "tags": [ "podcast" ] } }, "/api/v1/podcast/jobs/{job_id}/retry": { "post": { "description": "Re-enqueue a failed generation using the original job's parameters.\n\nA failed podcast used to be a dead end: the notification said only that\ngeneration failed, and there was nothing to click to try again. The job row\nalready stores every parameter the request was built from, so a retry is a\nfaithful replay rather than asking the user to rebuild their selection.\n\nRouted through ``generate_podcast`` on purpose — entitlement gating, quota,\nand dispatch stay in ONE place instead of being duplicated here.\n\nOnly the job's owner (or a delegate reading for them) can see or replay it\n(TIDY-19534); anyone else gets the same 404 as a job that does not exist.", "operationId": "retryPodcastJob", "parameters": [ { "in": "path", "name": "job_id", "required": true, "schema": { "format": "uuid", "title": "Job Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PodcastGenerateResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Retry a failed podcast generation job", "tags": [ "podcast" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/podcast/opml/export": { "get": { "operationId": "exportPodcastSubscriptionsOpml", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Exportpodcastsubscriptionsopml", "type": "object" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Export current podcast subscriptions to OPML", "tags": [ "podcast-opml" ] } }, "/api/v1/podcast/opml/import": { "post": { "description": "Validate the upload, create a job, and return 202 immediately.\n\nThe per-feed fetch/import runs off-request in a background worker so the\nimport survives the client navigating away. Clients poll\n``GET /podcast/opml/import/{job_id}`` for progress + final counts.", "operationId": "importPodcastSubscriptionsOpml", "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/Body_importPodcastSubscriptionsOpml" } } }, "required": true }, "responses": { "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PodcastOpmlImportJobResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Start an OPML podcast import as a background job", "tags": [ "podcast-opml" ] } }, "/api/v1/podcast/opml/import/{job_id}": { "get": { "operationId": "getPodcastOpmlImportJob", "parameters": [ { "in": "path", "name": "job_id", "required": true, "schema": { "title": "Job Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PodcastOpmlImportJobResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get OPML import job progress and final counts", "tags": [ "podcast-opml" ], "x-mcp-skip": true, "x-mcp-skip-reason": "Client-side progress polling for an async import job; not an agent surface." } }, "/api/v1/podcast/playlists": { "get": { "operationId": "listPodcastPlaylists", "parameters": [ { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PodcastPlaylistListResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List the member's podcast playlists", "tags": [ "podcast-playlists" ], "x-local-capability": "local" }, "post": { "operationId": "createPodcastPlaylist", "parameters": [ { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PodcastPlaylistCreateRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PodcastPlaylistResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Create a podcast playlist, optionally with its episodes", "tags": [ "podcast-playlists" ], "x-local-capability": "cloud" } }, "/api/v1/podcast/playlists/{playlist_id}": { "delete": { "operationId": "deletePodcastPlaylist", "parameters": [ { "in": "path", "name": "playlist_id", "required": true, "schema": { "format": "uuid", "title": "Playlist Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PodcastPlaylistDeleteResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Delete a podcast playlist (its episodes stay in their subscriptions)", "tags": [ "podcast-playlists" ], "x-local-capability": "cloud", "x-mcp-skip": true }, "get": { "operationId": "getPodcastPlaylist", "parameters": [ { "in": "path", "name": "playlist_id", "required": true, "schema": { "format": "uuid", "title": "Playlist Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PodcastPlaylistResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get a podcast playlist with its episodes", "tags": [ "podcast-playlists" ], "x-local-capability": "local" } }, "/api/v1/podcast/playlists/{playlist_id}/apply": { "post": { "operationId": "applyPodcastPlaylistToQueue", "parameters": [ { "in": "path", "name": "playlist_id", "required": true, "schema": { "format": "uuid", "title": "Playlist Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PodcastPlaylistApplyRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PodcastPlaylistApplyResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Add a playlist to the play queue: top (play next), bottom (play last) or replace", "tags": [ "podcast-playlists" ], "x-local-capability": "cloud" } }, "/api/v1/podcast/playlists/{playlist_id}/items": { "post": { "operationId": "addPodcastPlaylistItems", "parameters": [ { "in": "path", "name": "playlist_id", "required": true, "schema": { "format": "uuid", "title": "Playlist Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PodcastPlaylistItemsAddRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PodcastPlaylistResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Append episodes to a podcast playlist", "tags": [ "podcast-playlists" ], "x-local-capability": "cloud" } }, "/api/v1/podcast/preferences": { "get": { "operationId": "getPodcastPreferences", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PodcastPreferencesResponse" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get podcast capture preferences for the current account", "tags": [ "podcast", "podcast" ] }, "patch": { "operationId": "patchPodcastPreferences", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PodcastPreferencesPatchRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PodcastPreferencesResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Update podcast capture preferences (UPSERT)", "tags": [ "podcast", "podcast" ] } }, "/api/v1/podcast/queue": { "get": { "operationId": "listPodcastQueue", "parameters": [ { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PodcastQueueListResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List persistent podcast queue items for current user", "tags": [ "podcast-queue" ] } }, "/api/v1/podcast/queue/current": { "post": { "operationId": "setPodcastQueueCurrent", "parameters": [ { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PodcastQueueCurrentRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PodcastQueueListResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Set current queue item", "tags": [ "podcast-queue" ] } }, "/api/v1/podcast/queue/items": { "post": { "operationId": "addPodcastQueueItem", "parameters": [ { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PodcastQueueInsertRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PodcastQueueListResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Add an episode to queue (play now / play next / add queue)", "tags": [ "podcast-queue" ] } }, "/api/v1/podcast/queue/items/{queue_item_id}": { "delete": { "operationId": "deletePodcastQueueItem", "parameters": [ { "in": "path", "name": "queue_item_id", "required": true, "schema": { "format": "uuid", "title": "Queue Item Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PodcastQueueListResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Remove a queue item", "tags": [ "podcast-queue" ] }, "patch": { "operationId": "patchPodcastQueueItem", "parameters": [ { "in": "path", "name": "queue_item_id", "required": true, "schema": { "format": "uuid", "title": "Queue Item Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PodcastQueueUpdateRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PodcastQueueItemResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Update queue item playback state", "tags": [ "podcast-queue" ] } }, "/api/v1/podcast/queue/items/{queue_item_id}/complete": { "post": { "description": "Single semantic operation (TIDY-12690): mark the episode behind this queue\nitem completed (durable — ``podcast_external_episodes.is_completed`` plus the\nlisten-progress correlate for Tidy-generated episodes) AND remove it from the\nqueue, advancing playback to the next item when the completed item was\ncurrent. Idempotent: completing an already-removed item returns the current\nqueue with ``already_completed=true``. The mobile client calls this from the\noverflow menu / mini-player tray and on auto-complete at playback end.\n\nTIDY-15882: an optional ``retain_position_seconds`` keeps the listen position\nwhere the listener left off instead of snapping it to the episode duration —\nthe skip-to-next-in-the-car meaning of completion (abandoned, not finished).", "operationId": "completePodcastQueueItem", "parameters": [ { "in": "path", "name": "queue_item_id", "required": true, "schema": { "format": "uuid", "title": "Queue Item Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/PodcastQueueCompleteRequest" }, { "type": "null" } ], "title": "Body" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PodcastQueueCompleteResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Mark the queue item's episode completed and remove it from the queue", "tags": [ "podcast-queue" ], "x-mcp-skip": true } }, "/api/v1/podcast/queue/reorder": { "post": { "operationId": "reorderPodcastQueue", "parameters": [ { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PodcastQueueReorderRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PodcastQueueListResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Reorder queue items", "tags": [ "podcast-queue" ] } }, "/api/v1/podcast/queue/transcription-batches": { "get": { "operationId": "listPodcastQueueTranscriptionBatches", "parameters": [ { "in": "query", "name": "limit", "required": false, "schema": { "default": 20, "maximum": 100, "minimum": 1, "title": "Limit", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PodcastQueueTranscriptionBatchListResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List recent transcription batches for current queue account", "tags": [ "podcast-queue" ] }, "post": { "operationId": "createPodcastQueueTranscriptionBatch", "parameters": [ { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PodcastQueueTranscriptionBatchCreateRequest" } } }, "required": true }, "responses": { "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PodcastQueueTranscriptionBatchResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Submit selected queue items to a transcription batch", "tags": [ "podcast-queue" ] } }, "/api/v1/podcast/queue/transcription-batches/{batch_id}": { "get": { "operationId": "getPodcastQueueTranscriptionBatch", "parameters": [ { "in": "path", "name": "batch_id", "required": true, "schema": { "format": "uuid", "title": "Batch Id", "type": "string" } }, { "description": "Accepted for backward compatibility; ignored. Ledger results arrive via the writeback receiver (push), so there is nothing to sync-on-read.", "in": "query", "name": "refresh", "required": false, "schema": { "default": true, "description": "Accepted for backward compatibility; ignored. Ledger results arrive via the writeback receiver (push), so there is nothing to sync-on-read.", "title": "Refresh", "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PodcastQueueTranscriptionBatchResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get transcription batch status for selected queue items", "tags": [ "podcast-queue" ] } }, "/api/v1/podcast/ratings": { "get": { "description": "Get Podchaser ratings for a podcast by title.", "operationId": "getPodcastRatings", "parameters": [ { "in": "query", "name": "title", "required": true, "schema": { "title": "Title", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PodchaserRatingResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Podcast Ratings", "tags": [ "podcast-ratings" ] } }, "/api/v1/podcast/search": { "get": { "description": "Search podcasts via Podcast Index or resolve Apple URLs via iTunes Lookup.", "operationId": "searchPodcasts", "parameters": [ { "description": "Search term or Apple Podcast URL", "in": "query", "name": "q", "required": true, "schema": { "description": "Search term or Apple Podcast URL", "maxLength": 500, "minLength": 1, "title": "Q", "type": "string" } }, { "description": "Maximum number of results to return for keyword search", "in": "query", "name": "limit", "required": false, "schema": { "default": 20, "description": "Maximum number of results to return for keyword search", "maximum": 40, "minimum": 1, "title": "Limit", "type": "integer" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PodcastSearchResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Search podcasts and resolve Apple Podcast links", "tags": [ "podcast-search" ] } }, "/api/v1/podcast/sources/{source_type}/{source_id}/metadata": { "get": { "operationId": "getPodcastSourceMetadata", "parameters": [ { "in": "path", "name": "source_type", "required": true, "schema": { "enum": [ "email", "note" ], "title": "Source Type", "type": "string" } }, { "in": "path", "name": "source_id", "required": true, "schema": { "format": "uuid", "title": "Source Id", "type": "string" } }, { "in": "query", "name": "source_ids", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Source Ids" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PodcastSourceMetadataResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get podcast source metadata", "tags": [ "podcast" ] } }, "/api/v1/podcast/subscriptions": { "get": { "operationId": "listPodcastSubscriptions", "parameters": [ { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PodcastSubscriptionListResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List podcast subscriptions for tenant", "tags": [ "podcast-subscriptions" ] }, "post": { "operationId": "createPodcastSubscription", "parameters": [ { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PodcastSubscriptionCreateRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PodcastSubscriptionResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Subscribe to podcast RSS feed and fetch initial episodes", "tags": [ "podcast-subscriptions" ] } }, "/api/v1/podcast/subscriptions/personal/ensure": { "post": { "operationId": "ensurePersonalPodcastSubscription", "parameters": [ { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PodcastSubscriptionResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Ensure the caller owns their default Tidy personal podcast subscription", "tags": [ "podcast-subscriptions" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/podcast/subscriptions/{subscription_id}": { "delete": { "operationId": "deletePodcastSubscription", "parameters": [ { "in": "path", "name": "subscription_id", "required": true, "schema": { "format": "uuid", "title": "Subscription Id", "type": "string" } }, { "description": "Clear downloaded episode markers when unsubscribing", "in": "query", "name": "purge_downloads", "required": false, "schema": { "default": false, "description": "Clear downloaded episode markers when unsubscribing", "title": "Purge Downloads", "type": "boolean" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PodcastSubscriptionDeleteResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Unsubscribe from podcast feed", "tags": [ "podcast-subscriptions" ] }, "patch": { "operationId": "updatePodcastSubscription", "parameters": [ { "in": "path", "name": "subscription_id", "required": true, "schema": { "format": "uuid", "title": "Subscription Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PodcastSubscriptionUpdateRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PodcastSubscriptionResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Update subscription settings", "tags": [ "podcast-subscriptions" ] } }, "/api/v1/podcast/subscriptions/{subscription_id}/auto-download": { "post": { "operationId": "runSubscriptionAutoDownloadNow", "parameters": [ { "in": "path", "name": "subscription_id", "required": true, "schema": { "format": "uuid", "title": "Subscription Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PodcastAutoDownloadRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PodcastAutoDownloadResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Run auto-download now for newest episodes", "tags": [ "podcast-subscriptions" ] } }, "/api/v1/podcast/subscriptions/{subscription_id}/episodes": { "get": { "operationId": "getSubscriptionEpisodes", "parameters": [ { "in": "path", "name": "subscription_id", "required": true, "schema": { "format": "uuid", "title": "Subscription Id", "type": "string" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 200, "maximum": 500, "minimum": 1, "title": "Limit", "type": "integer" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PodcastExternalEpisodeListResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List synced external episodes for subscription", "tags": [ "podcast-subscriptions" ] } }, "/api/v1/podcast/subscriptions/{subscription_id}/episodes/search": { "get": { "operationId": "searchSubscriptionEpisodeInventory", "parameters": [ { "in": "path", "name": "subscription_id", "required": true, "schema": { "format": "uuid", "title": "Subscription Id", "type": "string" } }, { "in": "query", "name": "q", "required": true, "schema": { "maxLength": 250, "minLength": 1, "title": "Q", "type": "string" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 100, "maximum": 200, "minimum": 1, "title": "Limit", "type": "integer" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PodcastExternalEpisodeListResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Search episodes within one subscribed podcast", "tags": [ "podcast-subscriptions" ] } }, "/api/v1/podcast/subscriptions/{subscription_id}/episodes/{episode_id}/audio": { "get": { "operationId": "streamSubscriptionEpisodeAudio", "parameters": [ { "in": "path", "name": "subscription_id", "required": true, "schema": { "format": "uuid", "title": "Subscription Id", "type": "string" } }, { "in": "path", "name": "episode_id", "required": true, "schema": { "format": "uuid", "title": "Episode Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Streamsubscriptionepisodeaudio", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Stream podcast episode audio (downloaded copy preferred)", "tags": [ "podcast-subscriptions" ] } }, "/api/v1/podcast/subscriptions/{subscription_id}/episodes/{episode_id}/download": { "post": { "operationId": "downloadSubscriptionEpisodeNow", "parameters": [ { "in": "path", "name": "subscription_id", "required": true, "schema": { "format": "uuid", "title": "Subscription Id", "type": "string" } }, { "in": "path", "name": "episode_id", "required": true, "schema": { "format": "uuid", "title": "Episode Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PodcastEpisodeDownloadRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PodcastEpisodeDownloadResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Download a podcast episode for offline playback", "tags": [ "podcast-subscriptions" ] } }, "/api/v1/podcast/subscriptions/{subscription_id}/episodes/{episode_id}/playback": { "patch": { "operationId": "updateSubscriptionEpisodePlayback", "parameters": [ { "in": "path", "name": "subscription_id", "required": true, "schema": { "format": "uuid", "title": "Subscription Id", "type": "string" } }, { "in": "path", "name": "episode_id", "required": true, "schema": { "format": "uuid", "title": "Episode Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PodcastEpisodePlaybackUpdateRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PodcastExternalEpisodeResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Update episode playback position/completion state", "tags": [ "podcast-subscriptions" ] } }, "/api/v1/podcast/subscriptions/{subscription_id}/poll": { "post": { "operationId": "pollSubscriptionNow", "parameters": [ { "in": "path", "name": "subscription_id", "required": true, "schema": { "format": "uuid", "title": "Subscription Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PodcastSubscriptionPollResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Poll subscription RSS feed immediately", "tags": [ "podcast-subscriptions" ] } }, "/api/v1/podcast/subscriptions/{subscription_id}/preferences": { "get": { "operationId": "getPodcastSubscriptionPreferences", "parameters": [ { "in": "path", "name": "subscription_id", "required": true, "schema": { "format": "uuid", "title": "Subscription Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PodcastSubscriptionPreferencesResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get per-subscription podcast preference overrides", "tags": [ "podcast", "podcast" ], "x-mcp-skip": true }, "put": { "operationId": "putPodcastSubscriptionPreferences", "parameters": [ { "in": "path", "name": "subscription_id", "required": true, "schema": { "format": "uuid", "title": "Subscription Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PodcastSubscriptionPreferencesPutRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PodcastSubscriptionPreferencesResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Replace per-subscription podcast preference overrides", "tags": [ "podcast", "podcast" ], "x-mcp-skip": true } }, "/api/v1/podcast/subscriptions/{subscription_id}/purge": { "post": { "operationId": "purgeSubscriptionEpisodesNow", "parameters": [ { "in": "path", "name": "subscription_id", "required": true, "schema": { "format": "uuid", "title": "Subscription Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PodcastPurgeResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Purge old completed episodes using subscription retention settings", "tags": [ "podcast-subscriptions" ] } }, "/api/v1/podcast/voices": { "get": { "operationId": "getPodcastVoiceCatalog", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PodcastVoiceCatalogResponse" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get podcast voice catalog", "tags": [ "podcast" ] } }, "/api/v1/preferences/daily-activity-summary": { "get": { "description": "Return the caller's stored Daily Activity Summary settings (defaults if\nnone stored yet).", "operationId": "getDailyActivitySummarySettings", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DailyActivitySummarySettingsResponse" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Daily Activity Summary Settings", "tags": [ "user-preferences" ], "x-mcp-skip": true }, "put": { "description": "Partially update + clamp the caller's settings, upsert, and return the\nfull normalized object.", "operationId": "updateDailyActivitySummarySettings", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DailyActivitySummarySettingsUpdate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DailyActivitySummarySettingsResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Update Daily Activity Summary Settings", "tags": [ "user-preferences" ], "x-mcp-skip": true } }, "/api/v1/preferences/theme/cookie": { "get": { "description": "Re-stamp the ``tidy-theme`` cookie from the current DB row.\n\nReturns the snapshot in the body so callers can verify the stamp\nlanded (helpful for tests and observability).", "operationId": "refreshThemeCookie", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Refreshthemecookie", "type": "object" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Refresh Theme Cookie", "tags": [ "user-preferences" ], "x-mcp-skip": true } }, "/api/v1/presentation-designs": { "get": { "description": "Return every system design plus the tenant designs the caller may see.\n\nSystem rows (tenant_id NULL) are always included. Tenant rows run through\nthe canonical member-visible predicate: the caller's own rows, ownerless\nrows, and shared/tenant rows. Private rows owned by other members are\nexcluded — no ad hoc visibility SQL.", "operationId": "listPresentationDesigns", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PresentationDesignListResponse" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List presentation designs visible to the caller", "tags": [ "presentation-designs" ], "x-mcp-skip": true }, "post": { "description": "Create a tenant/private design owned by the caller. The `design` payload is\nvalidated against the D11 schema (missing palette/typeScale/layouts, unknown\ntop-level keys, or a cellStyles palette reference that doesn't resolve all\nraise 422). System designs cannot be created here — `visibility='system'` is\nrejected by the request model.\n\nThe caller is stamped as `owner_id` and the conflict UPDATE branch never\nwrites it, so an upsert over an existing row cannot transfer ownership.\n\nThat branch carries the SAME member rule PATCH and DELETE carry\n(TIDY-19131). It used to restate `tenant_id` + `is_system` alone, which\nmade this the one door in a three-door write surface a co-member could\nwalk through: member B POSTing member A's id rewrote the row — name,\ndescription, design, `forked_from_id`, and `visibility`, so B could flip\nA's PRIVATE design to `shared` and thereby unlock PATCH and DELETE on it\ntoo, since those gate on exactly that column.\n\nA conflict branch whose WHERE fails writes nothing and returns nothing,\nwhich is two different refusals, so the no-op asks which one it was:\n\n* the id belongs to ANOTHER tenant → 409, unchanged;\n* the id belongs to THIS tenant but the caller may not write it → 404\n \"Presentation design not found\", PATCH's and DELETE's exact answer.\n Fail closed and non-enumerating: a 403 would confirm the row exists.\n\nA SYSTEM id (tenant_id NULL) also lands on that 404 rather than PATCH's\n403 \"System designs are read-only\". The 403 comes from `_reject_if_system`,\na pre-read this path deliberately does not have — the refusal here reads\nthe conflicting row's tenant and nothing else. 404 replaces a 409 that\nlied about a row living \"in another tenant\" when it lives in none.", "operationId": "createPresentationDesign", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePresentationDesignRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PresentationDesignResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Create a presentation design", "tags": [ "presentation-designs" ], "x-mcp-skip": true } }, "/api/v1/presentation-designs/{design_id}": { "delete": { "description": "Soft-delete a design (sets deleted_at). System rows return 403.", "operationId": "deletePresentationDesign", "parameters": [ { "in": "path", "name": "design_id", "required": true, "schema": { "title": "Design Id", "type": "string" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Delete a presentation design", "tags": [ "presentation-designs" ], "x-mcp-skip": true }, "patch": { "description": "Update name/description/design/visibility. System rows return 403.", "operationId": "updatePresentationDesign", "parameters": [ { "in": "path", "name": "design_id", "required": true, "schema": { "title": "Design Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdatePresentationDesignRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PresentationDesignResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Update a presentation design", "tags": [ "presentation-designs" ], "x-mcp-skip": true } }, "/api/v1/presentation-publications/{pub_id}": { "delete": { "description": "Soft-delete: the publisher or a tenant Owner/Admin may retire a version.\n\nAfter delete the row stops syncing and every asset endpoint 404s.", "operationId": "deletePublication", "parameters": [ { "in": "path", "name": "pub_id", "required": true, "schema": { "title": "Pub Id", "type": "string" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Soft-delete a publication (publisher or tenant admin)", "tags": [ "presentation-publications", "presentation-publications" ], "x-mcp-skip": true } }, "/api/v1/presentation-publications/{pub_id}/assets": { "get": { "description": "Return the publication with short-lived signed PNG + PPTX URLs.\n\nThe row itself arrives on the client via PowerSync; this endpoint mints the\nper-request signed asset URLs the viewer renders. Other tenants get 404.", "operationId": "getPublicationAssets", "parameters": [ { "in": "path", "name": "pub_id", "required": true, "schema": { "title": "Pub Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PresentationPublication" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Signed URLs for a publication's frozen slides + PPTX", "tags": [ "presentation-publications", "presentation-publications" ], "x-mcp-skip": true } }, "/api/v1/presentation-publications/{pub_id}/assets/{asset}": { "get": { "description": "Redirect `<n>.png` / `deck.pptx` to a short-lived signed URL.\n\nTenant-member gated (other tenants → 404). The signed URL carries its own\nauth so the redirect target needs no bearer.", "operationId": "getPublicationAsset", "parameters": [ { "in": "path", "name": "pub_id", "required": true, "schema": { "title": "Pub Id", "type": "string" } }, { "in": "path", "name": "asset", "required": true, "schema": { "title": "Asset", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Redirect to a signed URL for one frozen asset", "tags": [ "presentation-publications", "presentation-publications" ], "x-mcp-skip": true } }, "/api/v1/presentations/{note_id}": { "get": { "description": "Return the manifest with signed PNG URLs + a `stale` flag.\n\nNo manifest yet → synchronous first-view render. A stale manifest is served\nAS-IS with `stale: true` (the client POSTs render to refresh) — last-good\nsemantics, never blank, never a partial (R20).", "operationId": "getPresentationManifest", "parameters": [ { "in": "path", "name": "note_id", "required": true, "schema": { "title": "Note Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PresentationManifest" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get the slide-image manifest for a presentation", "tags": [ "presentations", "presentations" ], "x-mcp-skip": true } }, "/api/v1/presentations/{note_id}/design": { "patch": { "description": "Set ``notes.presentation_design_id``. Not a body content field — the\nTIDY-12978 whole-body guard never sees it. A non-null design must be visible\nto the tenant (system row or the tenant's own).", "operationId": "setPresentationDesign", "parameters": [ { "in": "path", "name": "note_id", "required": true, "schema": { "title": "Note Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetDesignRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SlideSurgeryOkResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Apply a presentation design to the deck", "tags": [ "presentations", "presentations" ], "x-mcp-skip": true } }, "/api/v1/presentations/{note_id}/publish": { "post": { "description": "Render every slide + flatten a PPTX as the publisher, freeze both to the\npublication's own storage prefix, and write an immutable publication row.\n\nFails loud and whole — a non-settling render is a 502, a mid-publish deck\nedit is a 409, a deck with no renderable slides is a 422. No partial\npublications.", "operationId": "publishPresentation", "parameters": [ { "in": "path", "name": "note_id", "required": true, "schema": { "title": "Note Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublishDeckRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PresentationPublication" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Publish a frozen snapshot of a presentation", "tags": [ "presentation-publications", "presentation-publications" ], "x-mcp-skip": true } }, "/api/v1/presentations/{note_id}/render": { "post": { "description": "Render slides via doc-service and (by default) refresh the manifest cache.\n\n`persist=false` returns short-lived signed URLs without touching the cache\n(agent-loop ephemeral renders). A non-settling render fails loud (502).", "operationId": "renderPresentation", "parameters": [ { "in": "path", "name": "note_id", "required": true, "schema": { "title": "Note Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RenderPresentationRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PresentationManifest" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Render a presentation's slides to images", "tags": [ "presentations", "presentations" ], "x-mcp-skip": true } }, "/api/v1/presentations/{note_id}/slides/delete": { "post": { "operationId": "deletePresentationSlide", "parameters": [ { "in": "path", "name": "note_id", "required": true, "schema": { "title": "Note Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SlideDeleteRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SlideSurgeryOkResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Delete a single slide", "tags": [ "presentations", "presentations" ], "x-mcp-skip": true } }, "/api/v1/presentations/{note_id}/slides/insert-image": { "post": { "description": "Drop an already-stored image into the target cell, named either by its\nstable storage-proxy src (POST /images/generate returns the path) or by its\nfile id (a generation pipeline holds ids, not paths — TIDY-15713). Either\nway the image NODE is built here, in the editor's real attribute shape, so\nno caller has to guess it.", "operationId": "insertPresentationSlideImage", "parameters": [ { "in": "path", "name": "note_id", "required": true, "schema": { "title": "Note Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InsertSlideImageRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SlideSurgeryOkResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Insert a stored image into a slide cell", "tags": [ "presentations", "presentations" ], "x-mcp-skip": true } }, "/api/v1/presentations/{note_id}/slides/insert-svg": { "post": { "description": "Sanitize the agent-drawn SVG (strip scripts / foreignObjects / external\nrefs), store it as a file, and embed it as an image node in the target cell\n(D13 chart/graphic channel).", "operationId": "insertPresentationSlideSvg", "parameters": [ { "in": "path", "name": "note_id", "required": true, "schema": { "title": "Note Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InsertSlideSvgRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SlideSurgeryOkResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Sanitize and insert an SVG graphic into a slide cell", "tags": [ "presentations", "presentations" ], "x-mcp-skip": true } }, "/api/v1/presentations/{note_id}/slides/move": { "post": { "operationId": "movePresentationSlide", "parameters": [ { "in": "path", "name": "note_id", "required": true, "schema": { "title": "Note Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SlideMoveRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SlideSurgeryOkResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Move a slide to a new position", "tags": [ "presentations", "presentations" ], "x-mcp-skip": true } }, "/api/v1/presentations/{note_id}/slides/read": { "post": { "description": "Return the deck's slide structure (per-slide outline + cell layout) plus\nthe active design id. The assistant reads this before authoring.", "operationId": "readPresentationSlides", "parameters": [ { "in": "path", "name": "note_id", "required": true, "schema": { "title": "Note Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SlideDeckReadResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Read a presentation's slide structure", "tags": [ "presentations", "presentations" ], "x-mcp-skip": true } }, "/api/v1/presentations/{note_id}/slides/upsert": { "post": { "operationId": "upsertPresentationSlide", "parameters": [ { "in": "path", "name": "note_id", "required": true, "schema": { "title": "Note Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SlideUpsertRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SlideSurgeryOkResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Insert or replace a single slide", "tags": [ "presentations", "presentations" ], "x-mcp-skip": true } }, "/api/v1/primitive-history/{entry_id}/revert": { "post": { "operationId": "revertPrimitiveHistoryField", "parameters": [ { "in": "path", "name": "entry_id", "required": true, "schema": { "format": "uuid", "title": "Entry Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrimitiveHistoryRevertRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrimitiveHistoryRevertResponse" } } }, "description": "Successful Response" }, "409": { "description": "The field has changed since this entry" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Put one recorded field back to its value before a change", "tags": [ "activities" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "A person's undo from an item's History tab. Employees change fields through their own update tools, which the journal records." } }, "/api/v1/primitives": { "get": { "description": "List a facet's instances with the member-visible predicate applied,\nregardless of which primitive table stores them. ``properties`` is the\nfacet-scoped value view (facet_data bucket / properties / custom_properties).", "operationId": "listPrimitiveInstances", "parameters": [ { "description": "Facet whose instances to list (required).", "in": "query", "name": "facet_slug", "required": true, "schema": { "description": "Facet whose instances to list (required).", "minLength": 1, "title": "Facet Slug", "type": "string" } }, { "description": "Facet-membership scope: 'exact' (default) matches rows carrying this facet only; 'inheritors' also matches rows of any facet that transitively inherits from it (tenant definitions shadow global).", "in": "query", "name": "facet_scope", "required": false, "schema": { "default": "exact", "description": "Facet-membership scope: 'exact' (default) matches rows carrying this facet only; 'inheritors' also matches rows of any facet that transitively inherits from it (tenant definitions shadow global).", "enum": [ "exact", "inheritors" ], "title": "Facet Scope", "type": "string" } }, { "description": "Max instances to return", "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "description": "Max instances to return", "maximum": 200, "minimum": 1, "title": "Limit", "type": "integer" } }, { "description": "Pagination offset", "in": "query", "name": "offset", "required": false, "schema": { "default": 0, "description": "Pagination offset", "minimum": 0, "title": "Offset", "type": "integer" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrimitiveInstanceListResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List instances of a facet", "tags": [ "primitives", "primitives" ], "x-local-capability": "cloud" }, "post": { "description": "Create an instance of ANY facet — the server resolves the facet's\n``target_table`` (inheritance honored, never a silent default) and\ndelegates to that table's canonical creator. Unsupported or unresolvable\ntargets fail loud (422) before anything is written.", "operationId": "createPrimitiveInstance", "parameters": [ { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrimitiveInstanceCreateRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrimitiveInstanceCreateResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Create a primitive instance for any facet", "tags": [ "primitives", "primitives" ], "x-local-capability": "cloud" } }, "/api/v1/primitives/search": { "get": { "description": "Search tenant-scoped primitives by type and text query.", "operationId": "searchPrimitives", "parameters": [ { "in": "query", "name": "type", "required": true, "schema": { "enum": [ "contact", "task", "event", "email", "organization", "reminder", "podcast_episode" ], "title": "Type", "type": "string" } }, { "in": "query", "name": "q", "required": true, "schema": { "maxLength": 200, "minLength": 1, "title": "Q", "type": "string" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 10, "maximum": 50, "minimum": 1, "title": "Limit", "type": "integer" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Searchprimitives", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Search primitives for slash-command linking", "tags": [ "primitives" ] } }, "/api/v1/primitives/{id}/linked-references": { "get": { "description": "Canonical typed-ID route (TIDY-8940 / D13). The path id is a typed\n primitive ID (``<P>-<uuid>``); the primitive type is derived from\n the prefix. Bare UUIDs are accepted during the deprecation window\n only when ``?type=<primitive_type>`` is supplied — otherwise the\n request returns 422 because there's no other way to know which\n target_type to query.\n\n Query Parameters:\n - type: Optional primitive type (required only with bare UUID)\n - limit: Max results (1-200), default: 50\n - cursor: Pagination cursor\n - search: Optional filter by source title, display text, or excerpt\n - provenance_status: Optional filter (precise, legacy_container)\n - source_container_type: Optional source surface filter", "operationId": "getPrimitiveLinkedReferencesCollapsed", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "title": "Id", "type": "string" } }, { "description": "Primitive type (required only when path id is a bare UUID)", "in": "query", "name": "type", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Primitive type (required only when path id is a bare UUID)", "title": "Type" } }, { "description": "Max results", "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "description": "Max results", "maximum": 200, "minimum": 1, "title": "Limit", "type": "integer" } }, { "description": "Pagination cursor", "in": "query", "name": "cursor", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pagination cursor", "title": "Cursor" } }, { "description": "Filter by source title or excerpt text", "in": "query", "name": "search", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by source title or excerpt text", "title": "Search" } }, { "description": "Filter by provenance status (precise, legacy_container)", "in": "query", "name": "provenance_status", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by provenance status (precise, legacy_container)", "title": "Provenance Status" } }, { "description": "Filter by source container type", "in": "query", "name": "source_container_type", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by source container type", "title": "Source Container Type" } }, { "description": "Include references from archived activities (badged via source_archived)", "in": "query", "name": "include_archived", "required": false, "schema": { "default": false, "description": "Include references from archived activities (badged via source_archived)", "title": "Include Archived", "type": "boolean" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResolvedLinkedReferenceListResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "The linked-reference read FAILED — problem+json with `code: links_unavailable` (retryable). Distinct from a 200 carrying an empty list, which means the primitive genuinely has no links. Before TIDY-16299 a failed read answered 200 + [] and the two were indistinguishable." } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get canonical linked references for a primitive (typed-id collapsed)", "tags": [ "links" ] } }, "/api/v1/primitives/{primitive_type}/{primitive_id}/linked-references": { "get": { "deprecated": true, "description": "DEPRECATED (TIDY-8940 / D13). Use ``GET /api/v1/primitives/{id}/linked-references``\n with a typed primitive ID instead. This endpoint is preserved during\n the deprecation window so unmigrated clients continue to work; every\n call emits a ``boundary.legacy_uuid`` warning so observability can\n drive the cutover.\n\n Returns authored linked-reference rows for a primitive target from\n the canonical ``linked_references`` table.\n\n Query Parameters:\n - limit: Max results (1-200), default: 50\n - cursor: Pagination cursor\n - search: Optional filter by source title, display text, or excerpt\n - provenance_status: Optional filter (precise, legacy_container)\n - source_container_type: Optional source surface filter", "operationId": "getPrimitiveLinkedReferences", "parameters": [ { "in": "path", "name": "primitive_type", "required": true, "schema": { "title": "Primitive Type", "type": "string" } }, { "in": "path", "name": "primitive_id", "required": true, "schema": { "title": "Primitive Id", "type": "string" } }, { "description": "Max results", "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "description": "Max results", "maximum": 200, "minimum": 1, "title": "Limit", "type": "integer" } }, { "description": "Pagination cursor", "in": "query", "name": "cursor", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pagination cursor", "title": "Cursor" } }, { "description": "Filter by source title or excerpt text", "in": "query", "name": "search", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by source title or excerpt text", "title": "Search" } }, { "description": "Filter by provenance status (precise, legacy_container)", "in": "query", "name": "provenance_status", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by provenance status (precise, legacy_container)", "title": "Provenance Status" } }, { "description": "Filter by source container type (note, task, contact, event, email)", "in": "query", "name": "source_container_type", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by source container type (note, task, contact, event, email)", "title": "Source Container Type" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResolvedLinkedReferenceListResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "The linked-reference read FAILED — problem+json with `code: links_unavailable` (retryable). Distinct from a 200 carrying an empty list, which means the primitive genuinely has no links. Before TIDY-16299 a failed read answered 200 + [] and the two were indistinguishable." } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get canonical linked references for a primitive (DEPRECATED — use collapsed route)", "tags": [ "links" ] } }, "/api/v1/primitives/{primitive_type}/{primitive_id}/provenance": { "get": { "description": "The generation record(s) behind this primitive, with sources resolved.\n\nA primitive nobody generated returns an empty list, not a 404 — \"this was\nnot generated\" is an answer, and the panel renders nothing for it.", "operationId": "getPrimitiveProvenance", "parameters": [ { "description": "Primitive type; one of ['contact', 'email', 'event', 'file', 'journal', 'note', 'organization', 'photo', 'podcast_episode', 'project', 'record', 'task']", "in": "path", "name": "primitive_type", "required": true, "schema": { "description": "Primitive type; one of ['contact', 'email', 'event', 'file', 'journal', 'note', 'organization', 'photo', 'podcast_episode', 'project', 'record', 'task']", "title": "Primitive Type", "type": "string" } }, { "description": "Typed id (e.g. N-<uuid>) or bare UUID", "in": "path", "name": "primitive_id", "required": true, "schema": { "description": "Typed id (e.g. N-<uuid>) or bare UUID", "title": "Primitive Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrimitiveProvenanceResponse" } } }, "description": "Successful Response" }, "404": { "description": "No such primitive FOR THIS CALLER. A primitive the caller may not see is indistinguishable from one that does not exist — a 403 would confirm the row." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "What a generated primitive was built from", "tags": [ "links" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/primitives/{primitive_type}/{primitive_id}/related": { "get": { "description": "Returns full primitive objects that are linked to the specified primitive.\n\n Path Parameters:\n - primitive_type: Type of the source primitive\n - primitive_id: ID of the source primitive\n\n Query Parameters:\n - related_type: Type of related primitives to fetch (required)\n - limit: Max results (1-50), default: 10\n - cursor: Pagination cursor\n\n Returns primitives with summary details including link_type.", "operationId": "getRelatedPrimitives", "parameters": [ { "in": "path", "name": "primitive_type", "required": true, "schema": { "title": "Primitive Type", "type": "string" } }, { "in": "path", "name": "primitive_id", "required": true, "schema": { "title": "Primitive Id", "type": "string" } }, { "description": "Type of related primitives to fetch", "in": "query", "name": "related_type", "required": true, "schema": { "description": "Type of related primitives to fetch", "title": "Related Type", "type": "string" } }, { "description": "Max results", "in": "query", "name": "limit", "required": false, "schema": { "default": 10, "description": "Max results", "maximum": 50, "minimum": 1, "title": "Limit", "type": "integer" } }, { "description": "Pagination cursor", "in": "query", "name": "cursor", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pagination cursor", "title": "Cursor" } }, { "description": "Include archived activities among related primitives", "in": "query", "name": "include_archived", "required": false, "schema": { "default": false, "description": "Include archived activities among related primitives", "title": "Include Archived", "type": "boolean" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelatedPrimitivesResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "The linked-reference read FAILED — problem+json with `code: links_unavailable` (retryable). Distinct from a 200 carrying an empty list, which means the primitive genuinely has no links. Before TIDY-16299 a failed read answered 200 + [] and the two were indistinguishable." } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get related primitives with details", "tags": [ "links" ] } }, "/api/v1/primitives/{typed_id}": { "get": { "description": "Fetch one instance by typed id (the prefix routes the primitive table).\nRows invisible to the caller return 404 — existence is never leaked.", "operationId": "getPrimitiveInstance", "parameters": [ { "in": "path", "name": "typed_id", "required": true, "schema": { "title": "Typed Id", "type": "string" } }, { "description": "Disambiguates the facet value view when the row carries multiple facet associations (422 without it in that case).", "in": "query", "name": "facet_slug", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Disambiguates the facet value view when the row carries multiple facet associations (422 without it in that case).", "title": "Facet Slug" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrimitiveInstanceItem" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get one primitive instance by typed id", "tags": [ "primitives", "primitives" ], "x-local-capability": "cloud" }, "patch": { "description": "Merge ``properties`` per-key into the facet's value store (an explicit\nnull clears a key) and/or update the display title — always through the\ntarget's canonical update path.", "operationId": "updatePrimitiveInstance", "parameters": [ { "in": "path", "name": "typed_id", "required": true, "schema": { "title": "Typed Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrimitiveInstanceUpdateRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrimitiveInstanceItem" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Update a primitive instance (per-key merge)", "tags": [ "primitives", "primitives" ], "x-local-capability": "cloud" } }, "/api/v1/primitives/{typed_id}/content/edits": { "get": { "description": "The newest recorded edit batches for this primitive, with revert\neligibility.\n\nVersion history joins these onto its rows by ``version_id`` to decide\nwhether to offer \"Revert this edit\". A batch whose inverse record has\nexpired, or that a revert already undid, reports ``revertible: false`` with\nthe reason — the affordance is hidden rather than failing on click.", "operationId": "listPrimitiveContentEditBatches", "parameters": [ { "in": "path", "name": "typed_id", "required": true, "schema": { "title": "Typed Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrimitiveContentEditBatchList" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List a primitive's recorded content-edit batches", "tags": [ "primitives" ], "x-local-capability": "cloud", "x-mcp-skip": true }, "post": { "description": "All operations apply atomically through the one commit gate.\n\nEvery collaborative prose body reaches this one endpoint — tasks, notes\n(pages, documents, presentations), journals, contact notes, calendar\nYour Notes, organizations and projects — plus the spreadsheet and record\nlanes. The typed id selects the registry entry; there is no\nper-primitive route.\n\nIdentical completed retries return 200 with ``duplicate=true``. Empty\n``replace_span.new`` is invalid — use ``delete_span``. To rewrite one part\nof a body, ``replace_section`` swaps the blocks under ONE heading for new\nmarkdown and leaves every other block, embed and link as it was — never\na whole-body replace (TIDY-19511). With no heading to scope the part,\n``replace_blocks`` does the same for the run of lines from the one holding\n``start`` through the one holding ``end`` (TIDY-19614). A field-keyed\nprimitive (``R-``) requires ``field``, the rich-text property to edit. A\nbody Tidy generates on a schedule refuses with ``protected_range``.", "operationId": "applyPrimitiveContentEdits", "parameters": [ { "in": "path", "name": "typed_id", "required": true, "schema": { "title": "Typed Id", "type": "string" } }, { "in": "header", "name": "X-Tidy-Acting-Principal", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tidy-Acting-Principal" } }, { "in": "header", "name": "X-Internal-Service", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service" } }, { "in": "header", "name": "X-Internal-Service-Key", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service-Key" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrimitiveContentEditsRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrimitiveContentEditsResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Apply surgical CRDT edits to a primitive's collaborative content", "tags": [ "primitives" ], "x-local-capability": "cloud", "x-tidy-content-edit-field-keyed-note": "These prefixes address ONE named property rather than a whole collaborative document — `field` is required for them and refused for every other prefix. R- edits a record's rich_text property ({html, markdown}); records are not Yjs documents.", "x-tidy-content-edit-field-keyed-prefixes": [ "R" ], "x-tidy-content-edit-scopes": { "A": "tasks:write", "C": "contacts:write", "J": "notes:write", "N": "notes:write", "O": "contacts:write", "P": "projects:write", "R": "primitives:write", "V": "calendar:write" }, "x-tidy-content-edit-scopes-note": "Prefix→scope until every prefix converges on one generic scope. The runtime primitive registry is authoritative and this map is rendered from it: each prefix requires the write scope its own primitive's update surface already requires (A- tasks:write, N-/J- notes:write, C-/O- contacts:write, V- calendar:write, P- projects:write, R- primitives:write). A prefix's row kinds always agree on the scope, so the gate runs before the parent row is read." } }, "/api/v1/primitives/{typed_id}/content/edits/{batch_id}/revert": { "post": { "description": "Undo exactly this batch by applying its recorded inverse operations.\n\nThe revert runs through the SAME coordinator and collab commit gate as any\nother edit — live room, atomic, its own attributed version row — so later\nhuman edits elsewhere in the document survive untouched.\n\n409 ``conflict`` and nothing is written when the revert cannot be applied\ncleanly: a human edited inside the span it would undo, the batch was\nalready reverted, or an inverse no longer matches. There is never a partial\nrevert and never an automatic fall back to whole-document restore — that\nstays an explicit, separate action in version history.", "operationId": "revertPrimitiveContentEditBatch", "parameters": [ { "in": "path", "name": "typed_id", "required": true, "schema": { "title": "Typed Id", "type": "string" } }, { "description": "The recorded batch to undo", "in": "path", "name": "batch_id", "required": true, "schema": { "description": "The recorded batch to undo", "format": "uuid", "title": "Batch Id", "type": "string" } }, { "in": "header", "name": "X-Tidy-Acting-Principal", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tidy-Acting-Principal" } }, { "in": "header", "name": "X-Internal-Service", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service" } }, { "in": "header", "name": "X-Internal-Service-Key", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service-Key" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrimitiveContentEditRevertRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrimitiveContentEditRevertResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Surgically revert one recorded content-edit batch", "tags": [ "primitives" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-tidy-content-edit-scopes": { "A": "tasks:write", "C": "contacts:write", "J": "notes:write", "N": "notes:write", "O": "contacts:write", "P": "projects:write", "R": "primitives:write", "V": "calendar:write" } } }, "/api/v1/profile/coaching": { "get": { "description": "Get authenticated user's coaching preferences.\n\n Returns current coaching settings including:\n - coaching_enabled: Whether coaching features are active\n - coaching_modules: List of enabled coaching modules\n - coaching_goals: Free-form goals per domain\n\n **Authentication Required**: Valid JWT token in Authorization header\n\n **Response (200 OK)**:\n ```json\n {\n \"coaching_enabled\": true,\n \"coaching_modules\": [\"wellness\", \"productivity\"],\n \"coaching_goals\": {\n \"emotional\": \"Reduce anxiety\",\n \"professional\": \"Deep work focus\",\n \"relationships\": \"Better listener\"\n },\n \"updated_at\": \"2025-01-06T10:30:00Z\"\n }\n ```\n\n Related: KCC-3085", "operationId": "getCoachingPreferences", "parameters": [ { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CoachingPreferencesResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get coaching preferences", "tags": [ "coaching" ] }, "put": { "description": "Update authenticated user's coaching preferences.\n\n Updates any combination of coaching fields. All fields are optional.\n\n **Authentication Required**: Valid JWT token in Authorization header\n\n **Request Body**:\n ```json\n {\n \"coaching_enabled\": true,\n \"coaching_modules\": [\"wellness\", \"productivity\"],\n \"coaching_goals\": {\n \"emotional\": \"Reduce anxiety\",\n \"professional\": \"Deep work focus\",\n \"relationships\": \"Better listener\"\n }\n }\n ```\n\n **Valid Coaching Modules**:\n - wellness\n - productivity\n - relationships\n - parenting\n\n **Response (200 OK)**: Updated CoachingPreferencesResponse object\n\n Related: KCC-3085", "operationId": "updateCoachingPreferences", "parameters": [ { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CoachingPreferencesUpdate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CoachingPreferencesResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Update coaching preferences", "tags": [ "coaching" ] } }, "/api/v1/profiles/me": { "get": { "description": "Get authenticated user's profile with family members and mailbox email.\n\n Returns complete user profile including:\n - Personal information (name, DOB, phone)\n - Email address from OAuth provider (read-only)\n - Unique mailbox email for inbox routing\n - All family members (spouse, children)\n\n All PII fields are decrypted if encryption is enabled.\n\n **Authentication Required**: Valid JWT token in Authorization header\n\n **Response (200 OK)**:\n ```json\n {\n \"account_id\": \"550e8400-e29b-41d4-a716-446655440000\",\n \"tenant_id\": \"7c9e6679-7425-40de-944b-e07fc1f90ae7\",\n \"full_name\": \"Jane Smith\",\n \"email\": \"jane@gmail.com\",\n \"date_of_birth\": \"1985-06-15\",\n \"phone_number\": \"+1-555-123-4567\",\n \"mailbox_email\": \"smith@mail.tidy.engineering\",\n \"family_members\": [\n {\n \"id\": \"uuid\",\n \"full_name\": \"John Smith\",\n \"relationship\": \"spouse\",\n \"gender\": \"male\",\n \"date_of_birth\": \"1983-03-20\"\n }\n ],\n \"created_at\": \"2025-11-15T10:30:00Z\",\n \"updated_at\": \"2025-11-15T10:30:00Z\"\n }\n ```\n\n **Error Responses**:\n - 401 Unauthorized: Missing or invalid JWT token\n - 404 Not Found: Profile doesn't exist (auto-creates default profile)\n - 500 Internal Server Error: Database operation failed\n\n Related: oauth-authentication-spec.md Feature 3.2", "operationId": "getProfile2", "parameters": [ { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserProfileResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get user profile", "tags": [ "profile" ] }, "patch": { "description": "Update authenticated user's profile information.\n\n Updates any combination of profile fields. All fields are optional.\n PII fields are encrypted before storage if encryption is enabled.\n\n **Authentication Required**: Valid JWT token in Authorization header\n\n **Request Body**:\n ```json\n {\n \"full_name\": \"Jane Doe Smith\",\n \"date_of_birth\": \"1985-06-15\",\n \"phone_number\": \"+1-555-999-8888\"\n }\n ```\n\n All fields are optional. Only provided fields will be updated. An unknown\n field is a 400 naming the accepted ones; the member's place is the home\n location (`PUT /api/v1/profiles/me/location`), not a postal address.\n\n **Response (200 OK)**: Updated UserProfileResponse object\n\n **Error Responses**:\n - 400 Bad Request: Invalid input data (validation error)\n - 401 Unauthorized: Missing or invalid JWT token\n - 404 Not Found: Profile doesn't exist\n - 500 Internal Server Error: Database operation failed\n\n Related: oauth-authentication-spec.md Feature 3.2", "operationId": "updateProfile", "parameters": [ { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserProfileUpdate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserProfileResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Update user profile", "tags": [ "profile" ] }, "post": { "description": "Create authenticated user's profile with initial data.\n\n This endpoint explicitly creates a user profile. Use this when:\n - User completes onboarding and wants to save profile data\n - Application requires explicit profile creation instead of auto-create\n\n **Authentication Required**: Valid JWT token in Authorization header\n\n **Request Body**:\n ```json\n {\n \"full_name\": \"Jane Smith\",\n \"date_of_birth\": \"1985-06-15\",\n \"phone_number\": \"+1-555-123-4567\"\n }\n ```\n\n All fields are optional. Minimal request can be empty `{}`. An unknown\n field is a 400 naming the accepted ones; the member's place is the home\n location (`PUT /api/v1/profiles/me/location`), not a postal address.\n\n **Response (201 Created)**: UserProfileResponse object\n\n **Error Responses**:\n - 400 Bad Request: Invalid input data (validation error)\n - 401 Unauthorized: Missing or invalid JWT token\n - 409 Conflict: Profile already exists for this user\n - 500 Internal Server Error: Database operation failed\n\n Related: 011-auth-user-onboarding T029", "operationId": "createProfile", "parameters": [ { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserProfileCreate" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserProfileResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Create user profile", "tags": [ "profile" ] } }, "/api/v1/profiles/me/avatar": { "delete": { "description": "Clear the stored profile avatar for the authenticated account.", "operationId": "deleteProfileAvatar", "parameters": [ { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Deleteprofileavatar", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Remove user profile avatar", "tags": [ "profile" ] }, "post": { "description": "Upload a profile avatar for the authenticated account.\n\n Accepts JPG, PNG, and WebP images up to 5MB. The uploaded image is resized\n and stored in object storage, and the resulting storage path is saved to\n `accounts.avatar_url`.", "operationId": "uploadProfileAvatar", "parameters": [ { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/Body_uploadProfileAvatar" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Uploadprofileavatar", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Upload user profile avatar", "tags": [ "profile" ] } }, "/api/v1/profiles/me/avatar-schema": { "post": { "description": "Persist (or clear, with a null body) the authenticated account's vector\n avatar schema. Stored on `accounts.avatar_schema` and projected onto the\n user's member-contact rows so the shared representation resolver shows the\n same self avatar to the user and every other member. Pass `null` to clear\n and fall back to the profile photo / default.", "operationId": "setProfileAvatarSchema", "parameters": [ { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AvatarSchemaBody" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Setprofileavatarschema", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Set the user's self vector-avatar", "tags": [ "profile" ], "x-mcp-skip": true } }, "/api/v1/profiles/me/avatar/convert": { "post": { "description": "Maps the authenticated account's current profile photo (accounts.avatar_url)\n into the avatar JSON schema via one vision-LLM call (structured extraction,\n never image generation). Returns the schema for the shared creator to\n pre-load and tweak — it is NOT auto-saved; the user reviews then saves via\n POST /profiles/me/avatar-schema. Cached by photo content hash. 400 when the\n account has no profile photo; 422 when the mapping fails.", "operationId": "convertProfilePhotoToAvatar", "parameters": [ { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProfileAvatarConvertResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Convert the user's profile photo into an avatar schema", "tags": [ "profile" ], "x-mcp-skip": true } }, "/api/v1/profiles/me/family": { "post": { "description": "Add a new family member (spouse, child, or other) to user's profile.\n\n PII fields (name, date of birth) are encrypted at rest if encryption is enabled.\n\n **Authentication Required**: Valid JWT token in Authorization header\n\n **Request Body**:\n ```json\n {\n \"full_name\": \"Sarah Smith\",\n \"relationship\": \"child\",\n \"gender\": \"female\",\n \"date_of_birth\": \"2018-04-22\"\n }\n ```\n\n **Field Constraints**:\n - `full_name`: Required, 1-255 characters\n - `relationship`: Required, one of: `spouse`, `child`, `other`\n - `gender`: Optional, one of: `male`, `female`, `other`, `prefer_not_to_say`\n - `date_of_birth`: Optional, ISO 8601 date (YYYY-MM-DD)\n\n **Response (201 Created)**:\n ```json\n {\n \"id\": \"uuid\",\n \"tenant_id\": \"tenant-uuid\",\n \"created_by\": \"account-uuid\",\n \"full_name\": \"Sarah Smith\",\n \"relationship\": \"child\",\n \"gender\": \"female\",\n \"date_of_birth\": \"2018-04-22\",\n \"created_at\": \"2025-11-15T10:30:00Z\",\n \"updated_at\": \"2025-11-15T10:30:00Z\"\n }\n ```\n\n **Error Responses**:\n - 400 Bad Request: Invalid input data (validation error)\n - 401 Unauthorized: Missing or invalid JWT token\n - 500 Internal Server Error: Database operation failed\n\n Related: oauth-authentication-spec.md Feature 3.3", "operationId": "createFamilyMember", "parameters": [ { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_service__models__profile__FamilyMemberCreate" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_service__models__profile__FamilyMemberResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Create family member", "tags": [ "profile" ] } }, "/api/v1/profiles/me/family/{member_id}": { "delete": { "description": "Delete a family member from user's profile.\n\n Security check ensures member belongs to user's tenant before deletion.\n Operation is permanent and cannot be undone.\n\n **Authentication Required**: Valid JWT token in Authorization header\n\n **Path Parameters**:\n - `member_id`: UUID of family member to delete\n\n **Response (204 No Content)**: Empty response on success\n\n **Error Responses**:\n - 401 Unauthorized: Missing or invalid JWT token\n - 403 Forbidden: Member belongs to different tenant\n - 404 Not Found: Family member not found\n - 500 Internal Server Error: Database operation failed\n\n Related: oauth-authentication-spec.md Feature 3.3", "operationId": "deleteFamilyMember", "parameters": [ { "in": "path", "name": "member_id", "required": true, "schema": { "title": "Member Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Delete family member", "tags": [ "profile" ] }, "patch": { "description": "Update an existing family member's information.\n\n All fields are optional. Only provided fields will be updated.\n Security check ensures member belongs to user's tenant.\n\n **Authentication Required**: Valid JWT token in Authorization header\n\n **Path Parameters**:\n - `member_id`: UUID of family member to update\n\n **Request Body**:\n ```json\n {\n \"full_name\": \"Sarah Jane Smith\",\n \"relationship\": \"child\",\n \"gender\": \"female\",\n \"date_of_birth\": \"2018-04-22\"\n }\n ```\n\n All fields are optional.\n\n **Response (200 OK)**: Updated FamilyMemberResponse object\n\n **Error Responses**:\n - 400 Bad Request: Invalid input data (validation error)\n - 401 Unauthorized: Missing or invalid JWT token\n - 403 Forbidden: Member belongs to different tenant\n - 404 Not Found: Family member not found\n - 500 Internal Server Error: Database operation failed\n\n Related: oauth-authentication-spec.md Feature 3.3", "operationId": "updateFamilyMember", "parameters": [ { "in": "path", "name": "member_id", "required": true, "schema": { "title": "Member Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FamilyMemberUpdate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_service__models__profile__FamilyMemberResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Update family member", "tags": [ "profile" ] } }, "/api/v1/profiles/me/history": { "get": { "operationId": "getMyProfileHistory", "parameters": [ { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Getmyprofilehistory", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Profile History", "tags": [ "profile" ] } }, "/api/v1/profiles/me/history/{change_set_id}/restore": { "post": { "operationId": "restoreMyProfileHistoryChangeSet", "parameters": [ { "in": "path", "name": "change_set_id", "required": true, "schema": { "title": "Change Set Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserProfileResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Restore Profile History Change Set", "tags": [ "profile" ] } }, "/api/v1/profiles/me/location": { "delete": { "description": "Remove the authenticated user's home location (and with it local weather).", "operationId": "clearLocation", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LocationResponse" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Clear home location", "tags": [ "profile" ], "x-local-capability": "cloud", "x-mcp-skip": true }, "get": { "description": "The authenticated user's home location; every field null when none is set.", "operationId": "getLocation", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LocationResponse" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get home location", "tags": [ "profile" ], "x-local-capability": "cloud", "x-mcp-skip": true }, "put": { "description": "Update user's home location for weather and travel time features.\n\n Location is stored in the accounts table and used for:\n - Weather forecast lookup (NWS API)\n - Travel time calculations to events\n\n **Authentication Required**: Valid JWT token in Authorization header\n\n **Request Body**:\n ```json\n {\n \"latitude\": 41.6215,\n \"longitude\": -72.7457,\n \"address\": \"Berlin, CT\",\n \"zip_code\": \"06037\"\n }\n ```\n\n Related: KCC-2711 (Weather Card), KCC-2712 (Travel Time Card)", "operationId": "updateLocation", "parameters": [ { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LocationUpdate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LocationResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Update home location", "tags": [ "profile" ] } }, "/api/v1/project-root-jobs/{job_id}/git-credential": { "post": { "operationId": "getProjectRootGitCredential", "parameters": [ { "in": "path", "name": "job_id", "required": true, "schema": { "format": "uuid", "title": "Job Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RootGitCredentialRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RootGitCredentialResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Get Project Root Git Credential", "tags": [ "project-roots" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/project-root-jobs/{job_id}/github-token": { "post": { "description": "TIDY-19564 — the read-only clone credential for a workshop's own\nProject Root, bounded to one in-flight `root.ensure` and its repository\n(`services/project_root_clone_access.py` holds the whole gate).", "operationId": "mintProjectRootCloneGitHubToken", "parameters": [ { "in": "path", "name": "job_id", "required": true, "schema": { "format": "uuid", "title": "Job Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GitHubAgentTokenRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GitHubInstallationTokenResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Mint Project Root Clone Github Token", "tags": [ "project-roots" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/project-root-snapshots/{snapshot_id}/upload": { "post": { "operationId": "uploadProjectRootSnapshotFile", "parameters": [ { "in": "path", "name": "snapshot_id", "required": true, "schema": { "format": "uuid", "title": "Snapshot Id", "type": "string" } }, { "in": "query", "name": "path", "required": true, "schema": { "maxLength": 4096, "minLength": 1, "title": "Path", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SnapshotUploadResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Upload Snapshot File", "tags": [ "project-roots" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/project-suggestions": { "get": { "description": "Get all pending project suggestions for the authenticated user.\n\n Returns suggestions that:\n - Belong to the user's tenant\n - Have status = 'pending'\n\n Response (200 OK):\n {\n \"suggestions\": [\n {\n \"id\": \"uuid\",\n \"suggested_name\": \"Kitchen Renovation\",\n \"suggested_type\": \"household\",\n \"suggested_keywords\": [\"renovation\", \"contractor\"],\n \"confidence\": 0.85,\n \"source_excerpt\": \"Email about kitchen quote...\",\n \"created_at\": \"2026-01-19T10:00:00Z\"\n }\n ],\n \"total\": 1\n }\n\n Error Responses:\n - 401 Unauthorized: Missing or invalid JWT token\n - 500 Internal Server Error: Database operation failed\n\n Related: KCC-3459 (web app AI suggestions display)", "operationId": "listPendingSuggestions", "parameters": [ { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListSuggestionsResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List pending project suggestions", "tags": [ "project-suggestions" ] } }, "/api/v1/project-suggestions/approve": { "post": { "description": "Quickly approve a project suggestion using its suggested name, type, and keywords.\n\n Request:\n {\n \"suggestion_id\": \"uuid\",\n \"backfill\": true,\n \"days_back\": 90\n }\n\n Response (201 Created):\n {\n \"project_id\": \"uuid\",\n \"name\": \"Suggested Project Name\",\n \"linked_count\": 15,\n \"message\": \"Project created with 15 items linked (12 from backfill)\"\n }\n\n When backfill=true, searches past emails, tasks, and events for matching\n keywords and links them to the new project. Limited to 500 items max.\n\n Error Responses:\n - 400 Bad Request: Suggestion already processed\n - 401 Unauthorized: Missing or invalid JWT token\n - 404 Not Found: Suggestion not found\n - 500 Internal Server Error: Database operation failed\n\n Related: KCC-3459 (quick approve + backfill requirement)", "operationId": "quickApproveSuggestion", "parameters": [ { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuickApproveRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateProjectFromSuggestionResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Quick approve suggestion using defaults", "tags": [ "project-suggestions" ] } }, "/api/v1/project-suggestions/{suggestion_id}/backfill-preview": { "get": { "description": "Preview how many items would be linked if backfill is enabled.\n\n Shows counts by type (emails, tasks, events) without creating any links.\n Use this to help users decide if they want to enable backfill before approving.\n\n Path Parameters:\n suggestion_id: UUID of the suggestion\n\n Query Parameters:\n days_back: Number of days to search back (default: 90)\n\n Response (200 OK):\n {\n \"emails\": 25,\n \"tasks\": 8,\n \"events\": 12,\n \"total\": 45,\n \"capped_at\": null\n }\n\n If total exceeds 500, capped_at will show the limit.\n\n Error Responses:\n - 401 Unauthorized: Missing or invalid JWT token\n - 404 Not Found: Suggestion not found\n - 500 Internal Server Error: Database operation failed\n\n Related: KCC-3459 (safeguard - preview before applying)", "operationId": "getBackfillPreview", "parameters": [ { "in": "path", "name": "suggestion_id", "required": true, "schema": { "title": "Suggestion Id", "type": "string" } }, { "description": "Days to search back", "in": "query", "name": "days_back", "required": false, "schema": { "default": 90, "description": "Days to search back", "maximum": 365, "minimum": 1, "title": "Days Back", "type": "integer" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BackfillPreviewResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Preview backfill item counts", "tags": [ "project-suggestions" ] } }, "/api/v1/projects": { "get": { "description": "List all projects for authenticated user's tenant with optional filtering.\n\n Query Parameters:\n status: Filter by status (active, archived, completed, or 'all')\n type: Filter by project type (activity, goal, recurring, event, household)\n search: Text search on project name\n child_id: Filter by primary family member UUID (not an item id)\n limit: Max results (1-1000), default: 100\n offset: Pagination offset, default: 0\n\n Returns:\n {\n \"projects\": [...],\n \"count\": 15\n }\n\n By default, only active projects are returned. Use status=all to include archived.\n\n Multi-Tenant Isolation: Only returns projects for user's tenant.\n\n Related: Project Context Detection (KCC-3213)", "operationId": "listProjects", "parameters": [ { "in": "query", "name": "status", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Status" } }, { "in": "query", "name": "type", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Type" } }, { "in": "query", "name": "search", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Search" } }, { "description": "Family-member id (not an item id)", "in": "query", "name": "child_id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Family-member id (not an item id)", "title": "Child Id" } }, { "description": "TIDY-18527: order before paging. Omitted: most recently updated first.", "in": "query", "name": "sort", "required": false, "schema": { "anyOf": [ { "pattern": "^(name_asc|name_desc|created_desc|created_asc|updated_desc)$", "type": "string" }, { "type": "null" } ], "description": "TIDY-18527: order before paging. Omitted: most recently updated first.", "title": "Sort" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 100, "maximum": 1000, "minimum": 1, "title": "Limit", "type": "integer" } }, { "in": "query", "name": "offset", "required": false, "schema": { "default": 0, "minimum": 0, "title": "Offset", "type": "integer" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Listprojects", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List projects with filtering", "tags": [ "projects", "Projects" ] }, "post": { "description": "Create a new project.\n\n Projects group related items (emails, tasks, events, contacts, notes)\n around activities like sports seasons, renovations, or school years.\n\n Request:\n {\n \"name\": \"Soccer Fall 2026\",\n \"description\": \"Harrison's soccer season\",\n \"project_type\": \"activity\",\n \"start_date\": \"2026-08-15\",\n \"end_date\": \"2026-11-15\",\n \"keywords\": [\"soccer\", \"practice\", \"game\"],\n \"color\": \"#22c55e\"\n }\n\n Response (201 Created):\n Full project object with auto-generated id and timestamps.\n\n Error Responses:\n - 400 Bad Request: Invalid project data (empty name, etc.)\n - 401 Unauthorized: Missing or invalid JWT token\n - 404 Not Found: No tenant associated with account\n - 500 Internal Server Error: Database operation failed\n\n Related: Project Context Detection (KCC-3213)", "operationId": "createProject", "parameters": [ { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectCreate" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Create new project", "tags": [ "projects" ] } }, "/api/v1/projects/check-duplicate": { "get": { "description": "Check if a project name has near-duplicates using fuzzy matching.\n\n Uses PostgreSQL pg_trgm extension for similarity comparison.\n Threshold: similarity > 0.6 triggers a warning.\n\n Query Parameters:\n - name: Project name to check (required)\n - exclude_id: Project ID to exclude from results (optional, for updates)\n\n Response (200 OK):\n {\n \"similar_projects\": [\n {\n \"id\": \"uuid\",\n \"name\": \"Soccer Fall Season\",\n \"similarity_score\": 0.75,\n \"status\": \"active\",\n \"project_type\": \"activity\"\n }\n ],\n \"has_duplicates\": true\n }\n\n Use this before creating a project to warn users about potential duplicates.\n\n Error Responses:\n - 400 Bad Request: Name is empty\n - 401 Unauthorized: Missing or invalid JWT token\n - 500 Internal Server Error: Database operation failed\n\n Related: KCC-3706 (near-duplicate prevention)", "operationId": "checkDuplicate2", "parameters": [ { "description": "Project name to check", "in": "query", "name": "name", "required": true, "schema": { "description": "Project name to check", "minLength": 1, "title": "Name", "type": "string" } }, { "description": "Project ID to exclude (for updates)", "in": "query", "name": "exclude_id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Project ID to exclude (for updates)", "title": "Exclude Id" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_service__services__project_dedup_service__CheckDuplicateResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Check for near-duplicate projects", "tags": [ "projects" ] } }, "/api/v1/projects/from-suggestion": { "post": { "description": "Create a new project from an approved suggestion.\n\n Request:\n {\n \"suggestion_id\": \"uuid\",\n \"name\": \"Kitchen Renovation\",\n \"project_type\": \"household\",\n \"keywords\": [\"renovation\", \"contractor\", \"kitchen\"],\n \"selected_email_ids\": [\"uuid1\", \"uuid2\"]\n }\n\n Response (201 Created):\n {\n \"project_id\": \"uuid\",\n \"name\": \"Kitchen Renovation\",\n \"linked_count\": 3,\n \"message\": \"Project created with 3 related emails linked\"\n }\n\n The suggestion is marked as 'approved' and the associated feed card\n is archived. Selected emails are linked to the new project.\n\n Error Responses:\n - 400 Bad Request: Invalid data or suggestion already processed\n - 401 Unauthorized: Missing or invalid JWT token\n - 404 Not Found: Suggestion not found\n - 500 Internal Server Error: Database operation failed\n\n Related: KCC-3473, KCC-A-108", "operationId": "createProjectFromSuggestion", "parameters": [ { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateProjectFromSuggestionRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateProjectFromSuggestionResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Create project from approved suggestion", "tags": [ "project-suggestions" ] } }, "/api/v1/projects/merge": { "post": { "description": "Merge multiple projects into a target project.\n\n All linked items (emails, tasks, events, contacts, notes) from source\n projects are moved to the target project. Source projects are archived\n with a note indicating which project they were merged into.\n\n Request:\n {\n \"source_ids\": [\"uuid1\", \"uuid2\"],\n \"target_id\": \"uuid3\"\n }\n\n Response (200 OK):\n {\n \"merged_count\": 2,\n \"items_moved\": 45,\n \"target_id\": \"uuid3\",\n \"archived_projects\": [\"uuid1\", \"uuid2\"]\n }\n\n The merge is reversible: unarchiving a source project shows which project\n it was merged into in the description.\n\n Error Responses:\n - 400 Bad Request: Invalid request (target in sources, empty sources)\n - 401 Unauthorized: Missing or invalid JWT token\n - 404 Not Found: One or more projects not found\n - 500 Internal Server Error: Database operation failed\n\n Related: KCC-3706 (project merge capability)", "operationId": "mergeProjects", "parameters": [ { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_service__services__project_dedup_service__MergeRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MergeResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Merge multiple projects into one", "tags": [ "projects" ] } }, "/api/v1/projects/suggestions/{suggestion_id}/dismiss": { "post": { "description": "Dismiss a project suggestion with optional permanent block.\n\n Path Parameters:\n suggestion_id: UUID of the suggestion to dismiss\n\n Request:\n {\n \"never_suggest_again\": false\n }\n\n Response (200 OK):\n {\n \"status\": \"rejected\",\n \"cooldown_until\": \"2026-02-19T00:00:00Z\"\n }\n\n If never_suggest_again=true, similar suggestions are permanently blocked.\n If never_suggest_again=false, a 30-day cooldown applies before the topic\n can be suggested again.\n\n Error Responses:\n - 400 Bad Request: Suggestion already processed\n - 401 Unauthorized: Missing or invalid JWT token\n - 404 Not Found: Suggestion not found\n - 500 Internal Server Error: Database operation failed\n\n Related: KCC-3473, KCC-A-108", "operationId": "dismissSuggestion3", "parameters": [ { "in": "path", "name": "suggestion_id", "required": true, "schema": { "title": "Suggestion Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DismissSuggestionRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_service__models__project__DismissSuggestionResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Dismiss project suggestion", "tags": [ "project-suggestions" ] } }, "/api/v1/projects/suggestions/{suggestion_id}/related-emails": { "get": { "description": "Get emails related to a project suggestion for preview before approval.\n\n Path Parameters:\n suggestion_id: UUID of the suggestion\n\n Query Parameters:\n days_back: Number of days to search back (default: 30)\n\n Response (200 OK):\n {\n \"suggestion_id\": \"uuid\",\n \"related_emails\": [\n {\n \"id\": \"uuid\",\n \"subject\": \"Re: Kitchen contractor quote\",\n \"sender\": \"contractor@example.com\",\n \"received_at\": \"2026-01-15T10:00:00Z\",\n \"match_score\": 0.85,\n \"match_reason\": \"keyword: contractor, renovation\"\n }\n ],\n \"total\": 5\n }\n\n Related emails are matched using:\n - Sender domain from the source email\n - Keywords from the suggestion\n - Subject similarity (pg_trgm)\n\n Error Responses:\n - 401 Unauthorized: Missing or invalid JWT token\n - 404 Not Found: Suggestion not found\n - 500 Internal Server Error: Database operation failed\n\n Related: KCC-3473, KCC-A-108", "operationId": "getRelatedEmails", "parameters": [ { "in": "path", "name": "suggestion_id", "required": true, "schema": { "title": "Suggestion Id", "type": "string" } }, { "description": "Days to search back", "in": "query", "name": "days_back", "required": false, "schema": { "default": 30, "description": "Days to search back", "maximum": 365, "minimum": 1, "title": "Days Back", "type": "integer" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelatedEmailsResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get related emails for preview", "tags": [ "project-suggestions" ] } }, "/api/v1/projects/{project_id}": { "delete": { "description": "Archive a project (soft delete by setting status to 'archived').\n\n Project is not permanently removed from database.\n Links to items are preserved for historical reference.\n\n Returns 204 No Content on success.\n\n Error Responses:\n - 401 Unauthorized: Missing or invalid JWT token\n - 404 Not Found: Project does not exist or does not belong to user's tenant\n - 500 Internal Server Error: Database operation failed\n\n Related: Project Context Detection (KCC-3213)", "operationId": "deleteProject", "parameters": [ { "description": "Typed ID with prefix 'P'", "in": "path", "name": "project_id", "required": true, "schema": { "description": "Typed ID with prefix 'P'", "title": "Project Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Archive project", "tags": [ "projects" ] }, "get": { "description": "Retrieve details for a specific project including linked item counts.\n\n Response:\n {\n \"id\": \"a1b2c3d4-...\",\n \"tenant_id\": \"tenant-uuid\",\n \"name\": \"Soccer Fall 2026\",\n \"description\": \"Harrison's soccer season\",\n \"project_type\": \"activity\",\n \"status\": \"active\",\n ...\n \"stats\": {\n \"email_count\": 45,\n \"task_count\": 12,\n \"event_count\": 8,\n \"contact_count\": 5,\n \"note_count\": 3,\n \"total_links\": 73\n }\n }\n\n Error Responses:\n - 401 Unauthorized: Missing or invalid JWT token\n - 404 Not Found: Project does not exist or does not belong to user's tenant\n - 500 Internal Server Error: Database operation failed\n\n Related: Project Context Detection (KCC-3213)", "operationId": "getProject", "parameters": [ { "description": "Typed ID with prefix 'P'", "in": "path", "name": "project_id", "required": true, "schema": { "description": "Typed ID with prefix 'P'", "title": "Project Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get project details", "tags": [ "projects" ] }, "patch": { "description": "Update project fields using PATCH (partial update).\n\n Request (all fields optional):\n {\n \"completion_percentage\": 50\n }\n\n Only provided fields are updated. Commonly used for progress updates.\n\n Error Responses:\n - 400 Bad Request: Invalid update data\n - 401 Unauthorized: Missing or invalid JWT token\n - 404 Not Found: Project does not exist or does not belong to user's tenant\n - 500 Internal Server Error: Database operation failed\n\n Related: Project Context Detection (KCC-3213)", "operationId": "updateProjectPatch", "parameters": [ { "description": "Typed ID with prefix 'P'", "in": "path", "name": "project_id", "required": true, "schema": { "description": "Typed ID with prefix 'P'", "title": "Project Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectUpdate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Update project (partial update)", "tags": [ "projects" ] }, "put": { "description": "Update project fields using PUT (full resource replace).\n\n Request (all fields optional):\n {\n \"name\": \"Soccer Fall 2026 - Updated\",\n \"completion_percentage\": 75,\n \"status\": \"completed\"\n }\n\n Only provided fields are updated.\n\n Error Responses:\n - 400 Bad Request: Invalid update data\n - 401 Unauthorized: Missing or invalid JWT token\n - 404 Not Found: Project does not exist or does not belong to user's tenant\n - 500 Internal Server Error: Database operation failed\n\n Related: Project Context Detection (KCC-3213)", "operationId": "updateProjectPut", "parameters": [ { "description": "Typed ID with prefix 'P'", "in": "path", "name": "project_id", "required": true, "schema": { "description": "Typed ID with prefix 'P'", "title": "Project Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectUpdate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Update project (full replace)", "tags": [ "projects" ] } }, "/api/v1/projects/{project_id}/agent-scratchpad": { "get": { "operationId": "getAgentScratchpad", "parameters": [ { "description": "Typed ID with prefix 'P'", "in": "path", "name": "project_id", "required": true, "schema": { "description": "Typed ID with prefix 'P'", "title": "Project Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScratchpadResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Read the project's pinned Agent Work scratchpad", "tags": [ "agent-scratchpad" ], "x-local-capability": "cloud", "x-mcp-skip": true }, "put": { "operationId": "setAgentScratchpad", "parameters": [ { "description": "Typed ID with prefix 'P'", "in": "path", "name": "project_id", "required": true, "schema": { "description": "Typed ID with prefix 'P'", "title": "Project Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScratchpadSetRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScratchpadResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Create/replace the project's pinned Agent Work scratchpad body", "tags": [ "agent-scratchpad" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/projects/{project_id}/assign": { "post": { "description": "Bulk assign content items to a project. Only project owner or tenant admin.", "operationId": "bulkAssign", "parameters": [ { "description": "Typed ID with prefix 'P'", "in": "path", "name": "project_id", "required": true, "schema": { "description": "Typed ID with prefix 'P'", "title": "Project Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkAssignRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkAssignResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Bulk assign content to project", "tags": [ "project-members" ] } }, "/api/v1/projects/{project_id}/channel": { "post": { "description": "Idempotently provision the project's default channel (TIDY-15190 R9).\n\nCreation provisions the channel by default; this covers pre-existing\nprojects (lazy provisioning from the project workstation). Re-calling for\na project that already has a channel returns the existing room unchanged.", "operationId": "ensureProjectChannel", "parameters": [ { "description": "Typed ID with prefix 'P'", "in": "path", "name": "project_id", "required": true, "schema": { "description": "Typed ID with prefix 'P'", "title": "Project Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MatrixChannelToggleResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Ensure the project's default channel exists", "tags": [ "projects" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/projects/{project_id}/classification-rules": { "patch": { "description": "Update classification rules on a project. Only project owner or tenant admin.", "operationId": "updateClassificationRules", "parameters": [ { "description": "Typed ID with prefix 'P'", "in": "path", "name": "project_id", "required": true, "schema": { "description": "Typed ID with prefix 'P'", "title": "Project Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClassificationRulesUpdate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Updateclassificationrules", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Update classification rules", "tags": [ "project-members" ] } }, "/api/v1/projects/{project_id}/coverage-report": { "get": { "description": "The `tidy evidence verify` read: coverage ladder + evidence gap queries\n(requirements without commits/validation, work without requirements, done\ntasks without passing validation, regressions on Verified).", "operationId": "getProjectCoverageReport", "parameters": [ { "description": "Typed ID with prefix 'P'", "in": "path", "name": "project_id", "required": true, "schema": { "description": "Typed ID with prefix 'P'", "title": "Project Id", "type": "string" } }, { "description": "Scope the report to one requirement (A-<uuid>)", "in": "query", "name": "activity_id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Scope the report to one requirement (A-<uuid>)", "title": "Activity Id" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 200, "maximum": 500, "minimum": 1, "title": "Limit", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CoverageReport" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Compact coverage verifier report for a project", "tags": [ "links" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/projects/{project_id}/deliverables": { "post": { "description": "Create the file at v1, or append v(N+1) to the file already at this path.\n\nNever mints a second file for the same (project, path) — that is D12, and\nthe partial unique index behind it makes it true under concurrency too.", "operationId": "publishDeliverable", "parameters": [ { "description": "Typed ID with prefix 'P'", "in": "path", "name": "project_id", "required": true, "schema": { "description": "Typed ID with prefix 'P'", "title": "Project Id", "type": "string" } } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/Body_publishDeliverable" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublishDeliverableResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Publish a deliverable into a project's Files shelf", "tags": [ "deliverables" ], "x-local-capability": "cloud" } }, "/api/v1/projects/{project_id}/files": { "get": { "description": "List membership rows joined to member-visible file metadata.", "operationId": "listProjectFiles", "parameters": [ { "description": "Typed ID with prefix 'P'", "in": "path", "name": "project_id", "required": true, "schema": { "description": "Typed ID with prefix 'P'", "title": "Project Id", "type": "string" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 100, "maximum": 500, "minimum": 1, "title": "Limit", "type": "integer" } }, { "in": "query", "name": "offset", "required": false, "schema": { "default": 0, "minimum": 0, "title": "Offset", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectFileListResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List a project's files (membership-authoritative)", "tags": [ "projects" ], "x-local-capability": "cloud", "x-mcp-skip": true }, "post": { "description": "Create a membership row. Idempotent — re-associating returns the existing row.", "operationId": "associateProjectFile", "parameters": [ { "description": "Typed ID with prefix 'P'", "in": "path", "name": "project_id", "required": true, "schema": { "description": "Typed ID with prefix 'P'", "title": "Project Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectFileAssociateRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectFileMembershipResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Associate an existing file into a project (no move, no copy)", "tags": [ "projects" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/projects/{project_id}/files/{file_id}": { "delete": { "description": "Delete the membership ONLY. File deletion stays on the My Files delete path.", "operationId": "disassociateProjectFile", "parameters": [ { "description": "Typed ID with prefix 'P'", "in": "path", "name": "project_id", "required": true, "schema": { "description": "Typed ID with prefix 'P'", "title": "Project Id", "type": "string" } }, { "description": "Typed ID with prefix 'F'", "in": "path", "name": "file_id", "required": true, "schema": { "description": "Typed ID with prefix 'F'", "title": "File Id", "type": "string" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Remove a file's project association (canonical file untouched)", "tags": [ "projects" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/projects/{project_id}/generate-highlight": { "post": { "description": "Generate and persist a manual Project Highlight run.", "operationId": "generateProjectHighlight", "parameters": [ { "in": "path", "name": "project_id", "required": true, "schema": { "title": "Project Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectHighlightGenerateResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Generate Project Highlight", "tags": [ "project-highlights" ] } }, "/api/v1/projects/{project_id}/history": { "get": { "operationId": "getProjectHistory", "parameters": [ { "description": "Typed ID with prefix 'P'", "in": "path", "name": "project_id", "required": true, "schema": { "description": "Typed ID with prefix 'P'", "title": "Project Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Getprojecthistory", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get project edit history", "tags": [ "projects" ] } }, "/api/v1/projects/{project_id}/history/{change_set_id}/restore": { "post": { "operationId": "restoreProjectHistoryChangeSet", "parameters": [ { "in": "path", "name": "change_set_id", "required": true, "schema": { "title": "Change Set Id", "type": "string" } }, { "description": "Typed ID with prefix 'P'", "in": "path", "name": "project_id", "required": true, "schema": { "description": "Typed ID with prefix 'P'", "title": "Project Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Restore a project edit history change set", "tags": [ "projects" ] } }, "/api/v1/projects/{project_id}/items": { "get": { "description": "Get all items linked to a project.\n\n Query Parameters:\n type: Filter by item type (email, task, event, calendar_event, contact, note, news_update)\n limit: Max results (1-1000), default: 100\n offset: Pagination offset, default: 0\n\n Returns:\n {\n \"items\": [\n {\n \"id\": \"link-uuid\",\n \"primitive_type\": \"task\",\n \"primitive_id\": \"task-uuid\",\n \"link_source\": \"user_assigned\",\n \"confidence\": 1.0,\n \"created_at\": \"2026-01-15T10:00:00Z\"\n }\n ],\n \"count\": 15\n }\n\n Error Responses:\n - 401 Unauthorized: Missing or invalid JWT token\n - 404 Not Found: Project does not exist\n - 500 Internal Server Error: Database operation failed\n\n Related: Project Context Detection (KCC-3213)", "operationId": "getProjectItems", "parameters": [ { "description": "Typed ID with prefix 'P'", "in": "path", "name": "project_id", "required": true, "schema": { "description": "Typed ID with prefix 'P'", "title": "Project Id", "type": "string" } }, { "in": "query", "name": "type", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Type" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 100, "maximum": 1000, "minimum": 1, "title": "Limit", "type": "integer" } }, { "in": "query", "name": "offset", "required": false, "schema": { "default": 0, "minimum": 0, "title": "Offset", "type": "integer" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Getprojectitems", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get linked items", "tags": [ "projects", "Projects" ] }, "post": { "description": "Link an item (email, task, event, contact, note) to a project.\n\n Request:\n {\n \"primitive_type\": \"task\",\n \"primitive_id\": \"task-uuid-here\"\n }\n\n Response (201 Created):\n {\n \"id\": \"link-uuid\",\n \"primitive_type\": \"task\",\n \"primitive_id\": \"task-uuid\",\n \"link_source\": \"user_assigned\",\n \"confidence\": 1.0,\n \"created_at\": \"2026-01-15T10:00:00Z\"\n }\n\n If the same item is already linked, the existing link is updated\n (confidence increased if higher, source updated).\n\n Error Responses:\n - 400 Bad Request: Invalid item type or missing fields\n - 401 Unauthorized: Missing or invalid JWT token\n - 404 Not Found: Project does not exist\n - 500 Internal Server Error: Database operation failed\n\n Related: Project Context Detection (KCC-3213)", "operationId": "linkItemToProject", "parameters": [ { "description": "Typed ID with prefix 'P'", "in": "path", "name": "project_id", "required": true, "schema": { "description": "Typed ID with prefix 'P'", "title": "Project Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectLinkCreate" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectLinkResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Link item to project", "tags": [ "projects" ] } }, "/api/v1/projects/{project_id}/items/{primitive_type}/{primitive_id}": { "delete": { "description": "Remove a link between an item and a project.\n\n Path Parameters:\n project_id: Project UUID\n primitive_type: Type of item (email, task, event, calendar_event, contact, note, news_update)\n primitive_id: UUID of the item\n\n Returns 204 No Content on success.\n\n Error Responses:\n - 401 Unauthorized: Missing or invalid JWT token\n - 404 Not Found: Link does not exist\n - 500 Internal Server Error: Database operation failed\n\n Related: Project Context Detection (KCC-3213)", "operationId": "unlinkItemFromProject", "parameters": [ { "in": "path", "name": "primitive_type", "required": true, "schema": { "title": "Primitive Type", "type": "string" } }, { "in": "path", "name": "primitive_id", "required": true, "schema": { "title": "Primitive Id", "type": "string" } }, { "description": "Typed ID with prefix 'P'", "in": "path", "name": "project_id", "required": true, "schema": { "description": "Typed ID with prefix 'P'", "title": "Project Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Unlink item from project", "tags": [ "projects" ] } }, "/api/v1/projects/{project_id}/matrix-channel": { "get": { "description": "Return whether a Matrix channel is linked to this project.\n\nTIDY-19557: the project must be visible to the caller (404 otherwise), and\nthe room's identity is the channel's members' to know — anyone else who\ncan see the project learns only that it has a channel.", "operationId": "getMatrixChannel", "parameters": [ { "description": "Typed ID with prefix 'P'", "in": "path", "name": "project_id", "required": true, "schema": { "description": "Typed ID with prefix 'P'", "title": "Project Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MatrixChannelToggleResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Matrix channel status for a project", "tags": [ "projects" ] }, "post": { "description": "Enable or disable the Matrix chat channel for a project.\n\nWhen enabled: creates a Matrix room (or re-links an existing one).\nWhen disabled: hides the channel (unlinks from project, room preserved).", "operationId": "toggleMatrixChannel", "parameters": [ { "description": "Typed ID with prefix 'P'", "in": "path", "name": "project_id", "required": true, "schema": { "description": "Typed ID with prefix 'P'", "title": "Project Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MatrixChannelToggleRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MatrixChannelToggleResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Toggle Matrix channel for a project", "tags": [ "projects" ] } }, "/api/v1/projects/{project_id}/members": { "get": { "description": "Get project owner + members.", "operationId": "listMembers2", "parameters": [ { "description": "Typed ID with prefix 'P'", "in": "path", "name": "project_id", "required": true, "schema": { "description": "Typed ID with prefix 'P'", "title": "Project Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/MemberResponse" }, "title": "Response Listmembers2", "type": "array" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List project members", "tags": [ "project-members" ] }, "post": { "description": "Add a member to a project. Its owner or a workspace admin can add anyone; a\nmember of the project can add an employee on their own team (their direct reports\non the Org chart) when the person that employee works for is in the project too.", "operationId": "addMember", "parameters": [ { "description": "Typed ID with prefix 'P'", "in": "path", "name": "project_id", "required": true, "schema": { "description": "Typed ID with prefix 'P'", "title": "Project Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemberCreate" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemberResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Add member to project", "tags": [ "project-members" ] } }, "/api/v1/projects/{project_id}/members/{user_id}": { "delete": { "description": "Remove a member from a project. Only project owner or tenant admin can remove.", "operationId": "removeMember3", "parameters": [ { "in": "path", "name": "user_id", "required": true, "schema": { "title": "User Id", "type": "string" } }, { "description": "Typed ID with prefix 'P'", "in": "path", "name": "project_id", "required": true, "schema": { "description": "Typed ID with prefix 'P'", "title": "Project Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Remove member from project", "tags": [ "project-members" ] } }, "/api/v1/projects/{project_id}/repo-link": { "delete": { "description": "The project keeps working without a repo — that is the point of D9.", "operationId": "deleteProjectRepoLink", "parameters": [ { "description": "Typed ID with prefix 'P'", "in": "path", "name": "project_id", "required": true, "schema": { "description": "Typed ID with prefix 'P'", "title": "Project Id", "type": "string" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Unlink a project's repository", "tags": [ "source-control" ], "x-local-capability": "cloud", "x-mcp-skip": true }, "get": { "description": "404 when unlinked — linkage is optional per project (D9).", "operationId": "getProjectRepoLink", "parameters": [ { "description": "Typed ID with prefix 'P'", "in": "path", "name": "project_id", "required": true, "schema": { "description": "Typed ID with prefix 'P'", "title": "Project Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectRepoLinkResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Read a project's linked repository", "tags": [ "source-control" ], "x-local-capability": "cloud", "x-mcp-skip": true }, "put": { "description": "One row per project: re-linking updates it in place, never duplicates.", "operationId": "setProjectRepoLink", "parameters": [ { "description": "Typed ID with prefix 'P'", "in": "path", "name": "project_id", "required": true, "schema": { "description": "Typed ID with prefix 'P'", "title": "Project Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectRepoLinkRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectRepoLinkResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Link (or re-link) a project to a repository", "tags": [ "source-control" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/projects/{project_id}/requirements-coverage": { "get": { "description": "Coverage for every visible requirement in a project, plus gaps:\nrequirements with no implementing work and work with no requirement links.", "operationId": "getProjectRequirementsCoverage", "parameters": [ { "description": "Typed ID with prefix 'P'", "in": "path", "name": "project_id", "required": true, "schema": { "description": "Typed ID with prefix 'P'", "title": "Project Id", "type": "string" } }, { "description": "Max requirements", "in": "query", "name": "limit", "required": false, "schema": { "default": 100, "description": "Max requirements", "maximum": 500, "minimum": 1, "title": "Limit", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectRequirementsCoverage" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Batch requirement coverage + gap queries for a project", "tags": [ "links" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/projects/{project_id}/root-clone-access": { "get": { "description": "TIDY-19564 preflight: a live GitHub capability check, not primitive\ndata — the same member gate the workshop's clone meets, with a bounded\nread-only mint whose token is discarded.", "operationId": "getProjectRootCloneAccess", "parameters": [ { "description": "Typed ID with prefix 'P'", "in": "path", "name": "project_id", "required": true, "schema": { "description": "Typed ID with prefix 'P'", "title": "Project Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectRootCloneAccessResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Project Root Clone Access", "tags": [ "project-roots" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/projects/{project_id}/runtime-root": { "post": { "operationId": "resolveProjectRuntimeRoot", "parameters": [ { "description": "Typed ID with prefix 'P'", "in": "path", "name": "project_id", "required": true, "schema": { "description": "Typed ID with prefix 'P'", "title": "Project Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RuntimeRootResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Resolve Project Runtime Root", "tags": [ "project-roots" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/projects/{project_id}/scm-objects/pin": { "post": { "description": "D9 pin-on-reference: live-fetch the object at the provider, upsert it\nwith ``sync_source='pinned'``, and return it in the suggest-row shape so\nthe picker inserts it without a second call. Errors are verbatim: a\nforeign/unparseable URL or a provider 404 names the truth instead of\nfabricating an object (R5).", "operationId": "pinScmObject", "parameters": [ { "description": "Typed ID with prefix 'P'", "in": "path", "name": "project_id", "required": true, "schema": { "description": "Typed ID with prefix 'P'", "title": "Project Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PinScmObjectRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScmObjectSuggestRow" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Pin a provider object into the index by pasting its URL", "tags": [ "scm-objects" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/projects/{project_id}/scm-objects/suggest": { "get": { "description": "The picker's typeahead (R7): a prefix query (natural key and title)\nover one project the caller can see. A database outage answers 503 with an\nhonest message — the picker shows it verbatim; an empty-success would lie\nabout the repository (D13/R7).", "operationId": "suggestScmObjects", "parameters": [ { "description": "Typed ID with prefix 'P'", "in": "path", "name": "project_id", "required": true, "schema": { "description": "Typed ID with prefix 'P'", "title": "Project Id", "type": "string" } }, { "in": "query", "name": "q", "required": false, "schema": { "default": "", "maxLength": 200, "title": "Q", "type": "string" } }, { "in": "query", "name": "kind", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Kind" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 10, "maximum": 25, "minimum": 1, "title": "Limit", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScmObjectSuggestResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Suggest SCM objects of a project's linked repository", "tags": [ "scm-objects" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/projects/{project_id}/summary": { "get": { "operationId": "getProjectSummary", "parameters": [ { "in": "path", "name": "project_id", "required": true, "schema": { "title": "Project Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectSummaryResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Read Project Summary", "tags": [ "project-summary" ], "x-local-capability": "cloud" } }, "/api/v1/projects/{project_id}/unassign": { "post": { "description": "Bulk unassign content items from a project. Only project owner or tenant admin.", "operationId": "bulkUnassign", "parameters": [ { "description": "Typed ID with prefix 'P'", "in": "path", "name": "project_id", "required": true, "schema": { "description": "Typed ID with prefix 'P'", "title": "Project Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkAssignRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkAssignResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Bulk unassign content from project", "tags": [ "project-members" ] } }, "/api/v1/projects/{project_id}/workshops/{workshop_id}/read": { "post": { "operationId": "readProjectWorkshopFiles", "parameters": [ { "in": "path", "name": "workshop_id", "required": true, "schema": { "format": "uuid", "title": "Workshop Id", "type": "string" } }, { "description": "Typed ID with prefix 'P'", "in": "path", "name": "project_id", "required": true, "schema": { "description": "Typed ID with prefix 'P'", "title": "Project Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkshopReadRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkshopReadResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Read Project Workshop Files", "tags": [ "project-roots" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/projects/{project_id}/workshops/{workshop_id}/root": { "delete": { "operationId": "detachProjectWorkshopRoot", "parameters": [ { "in": "path", "name": "workshop_id", "required": true, "schema": { "format": "uuid", "title": "Workshop Id", "type": "string" } }, { "description": "Typed ID with prefix 'P'", "in": "path", "name": "project_id", "required": true, "schema": { "description": "Typed ID with prefix 'P'", "title": "Project Id", "type": "string" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Detach Project Workshop Root", "tags": [ "project-roots" ], "x-local-capability": "cloud", "x-mcp-skip": true }, "post": { "operationId": "ensureProjectWorkshopRoot", "parameters": [ { "in": "path", "name": "workshop_id", "required": true, "schema": { "format": "uuid", "title": "Workshop Id", "type": "string" } }, { "description": "Typed ID with prefix 'P'", "in": "path", "name": "project_id", "required": true, "schema": { "description": "Typed ID with prefix 'P'", "title": "Project Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectRootCommandResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Ensure Project Workshop Root", "tags": [ "project-roots" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/projects/{project_id}/workshops/{workshop_id}/root/expose": { "post": { "operationId": "exposeProjectWorkshopRoot", "parameters": [ { "in": "path", "name": "workshop_id", "required": true, "schema": { "format": "uuid", "title": "Workshop Id", "type": "string" } }, { "description": "Typed ID with prefix 'P'", "in": "path", "name": "project_id", "required": true, "schema": { "description": "Typed ID with prefix 'P'", "title": "Project Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectRootExposeRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectRootCommandResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Expose Project Workshop Root", "tags": [ "project-roots" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/projects/{project_id}/workshops/{workshop_id}/root/inspect": { "post": { "description": "Look at an existing directory on the box, through the privileged helper.\n\nNothing is exposed and nothing on the machine changes: this is the\nquestion. The answer lands on the Project Root row, which the client reads\nfrom its own SQLite like every other read (TIDY-18247).", "operationId": "inspectProjectWorkshopRoot", "parameters": [ { "in": "path", "name": "workshop_id", "required": true, "schema": { "format": "uuid", "title": "Workshop Id", "type": "string" } }, { "description": "Typed ID with prefix 'P'", "in": "path", "name": "project_id", "required": true, "schema": { "description": "Typed ID with prefix 'P'", "title": "Project Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectRootInspectRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectRootCommandResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Inspect Project Workshop Root", "tags": [ "project-roots" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/projects/{project_id}/workshops/{workshop_id}/snapshots": { "post": { "operationId": "snapshotProjectWorkshopFiles", "parameters": [ { "in": "path", "name": "workshop_id", "required": true, "schema": { "format": "uuid", "title": "Workshop Id", "type": "string" } }, { "description": "Typed ID with prefix 'P'", "in": "path", "name": "project_id", "required": true, "schema": { "description": "Typed ID with prefix 'P'", "title": "Project Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SnapshotRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SnapshotResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Snapshot Project Files", "tags": [ "project-roots" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/projects/{project_id}/workshops/{workshop_id}/write": { "post": { "description": "Save one text file in the project's Project Root on a workshop, live.", "operationId": "writeProjectWorkshopFile", "parameters": [ { "in": "path", "name": "workshop_id", "required": true, "schema": { "format": "uuid", "title": "Workshop Id", "type": "string" } }, { "description": "Typed ID with prefix 'P'", "in": "path", "name": "project_id", "required": true, "schema": { "description": "Typed ID with prefix 'P'", "title": "Project Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkshopFileWriteRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkshopFileWriteResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Write Project Workshop File", "tags": [ "project-roots" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/providers/": { "get": { "description": "List provider connections owned by the current account.", "operationId": "listConnections", "parameters": [ { "in": "query", "name": "include_disconnected", "required": false, "schema": { "default": false, "title": "Include Disconnected", "type": "boolean" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/ProviderConnectionResponse" }, "title": "Response Listconnections", "type": "array" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List provider connections", "tags": [ "providers", "providers" ] } }, "/api/v1/providers/connect/imap": { "post": { "description": "Connect a provider via IMAP credentials.", "operationId": "connectImap", "parameters": [ { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderConnectImapRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderConnectionResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Connect provider via IMAP", "tags": [ "providers", "providers" ] } }, "/api/v1/providers/connect/oauth": { "post": { "description": "Initiate OAuth flow for a provider. Generates auth URL and stores state.", "operationId": "connectOauth", "parameters": [ { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthConnectRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthConnectResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Connect provider via OAuth", "tags": [ "providers", "providers" ] } }, "/api/v1/providers/idle-status": { "get": { "description": "Return the IMAP IDLE supervisor's current connection status.\n\nTIDY-17696 S2: the supervisors run in the `worker` process role and\npublish their status to Redis; this `http`-role route reads it back. An\nabsent or expired key, or an unreachable Redis, yields the not-running\nliteral — never a stale ``running: true`` and never a 5xx.", "operationId": "idleStatus", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Idlestatus", "type": "object" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "IMAP IDLE supervisor status", "tags": [ "providers", "providers" ] } }, "/api/v1/providers/{connection_id}": { "delete": { "description": "Disconnect a provider connection (soft delete).", "operationId": "disconnectProvider", "parameters": [ { "in": "path", "name": "connection_id", "required": true, "schema": { "title": "Connection Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Disconnect provider", "tags": [ "providers", "providers" ] }, "get": { "description": "Get a single provider connection by ID.", "operationId": "getConnectionEndpoint", "parameters": [ { "in": "path", "name": "connection_id", "required": true, "schema": { "title": "Connection Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderConnectionResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get provider connection", "tags": [ "providers", "providers" ] } }, "/api/v1/providers/{connection_id}/alias-preferences": { "patch": { "description": "Update which aliases are visible in the compose From picker. Hiding the address that is the default sending address clears that default in the same write.", "operationId": "updateAliasPreferences", "parameters": [ { "in": "path", "name": "connection_id", "required": true, "schema": { "title": "Connection Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AliasPreferencesRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AliasPreferencesResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Update alias visibility preferences", "tags": [ "providers", "providers" ] } }, "/api/v1/providers/{connection_id}/aliases": { "get": { "description": "Returns all aliases for the connection including visibility settings.", "operationId": "listAliases", "parameters": [ { "in": "path", "name": "connection_id", "required": true, "schema": { "title": "Connection Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AliasPreferencesResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List email aliases", "tags": [ "providers", "providers" ] }, "put": { "description": "Replace the aliases a mailbox sends as. An IMAP mailbox has no provider discovery, so these are the member's own list; an address already on the mailbox keeps its compose visibility. Hand-kept aliases survive a later discovery.", "operationId": "updateAliases", "parameters": [ { "in": "path", "name": "connection_id", "required": true, "schema": { "title": "Connection Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManualAliasesRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AliasPreferencesResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Set the mailbox's aliases", "tags": [ "providers", "providers" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "A mailbox's send-as list is a first-party Settings → Connections control." } }, "/api/v1/providers/{connection_id}/app-password": { "delete": { "description": "Remove the stored app-specific password from a provider connection.\n\n\"Sign in again\" PRESERVES ``app_password`` so users do not have to dig it\nout of provider settings on every OAuth refresh (TIDY-7730); a deliberate\nDisconnect revokes the whole credential (TIDY-19201). This endpoint is the\nexplicit path to wipe just the password while staying connected (e.g. the\nuser rotated it on the provider side).\n\nRemoves ``app_password`` and ``carddav_app_password`` keys from the\nplugin's vault document while leaving OAuth tokens intact. A mailbox that\nsigns in with the app password — ``auth_method = 'app_password'`` (generic\nIMAP, Apple) — or Zoho, which relies on it for IMAP IDLE new-mail\nnotification, is marked as needing user action until the member enters\none again. A Google/Microsoft OAuth mailbox keeps working on its tokens\nand is not marked (owner decision, TIDY-19169 D3).", "operationId": "clearAppPassword", "parameters": [ { "in": "path", "name": "connection_id", "required": true, "schema": { "title": "Connection Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Clearapppassword", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Clear stored app-specific password", "tags": [ "providers", "providers" ] }, "post": { "description": "Store an app-specific password for IMAP connections.\n\nMerges the app_password into the plugin's vault document without\nclobbering OAuth tokens. Every IMAP-family password is proved against the\nmail server first — Zoho's IMAP authentication and INBOX access, a generic\nIMAP or Apple mailbox's login (TIDY-19279) — before saving, resetting\nhealth, or dismissing the setup reminder. Failed verification leaves the\nprior credentials and actionable state intact.\n\nZoho uses this credential for IMAP IDLE new-mail notification only; the\nactual message fetch still runs through the Zoho REST API.", "operationId": "storeAppPassword", "parameters": [ { "in": "path", "name": "connection_id", "required": true, "schema": { "title": "Connection Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppPasswordRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Storeapppassword", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Store app-specific password for IMAP", "tags": [ "providers", "providers" ] } }, "/api/v1/providers/{connection_id}/app-password/skip": { "post": { "description": "Persist the journal notice and paired bell entry atomically before skipping.", "operationId": "skipProviderAppPassword", "parameters": [ { "in": "path", "name": "connection_id", "required": true, "schema": { "title": "Connection Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": { "type": "string" }, "title": "Response Skipproviderapppassword", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Remind me to finish Zoho IMAP setup", "tags": [ "providers", "providers" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/providers/{connection_id}/calendar-configs": { "get": { "description": "List calendar source configurations for a provider connection.\n\nAuto-discovers calendars from the provider if none exist yet.", "operationId": "listCalendarConfigs", "parameters": [ { "in": "path", "name": "connection_id", "required": true, "schema": { "title": "Connection Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/CalendarSourceConfigResponse" }, "title": "Response Listcalendarconfigs", "type": "array" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List calendar configs for connection", "tags": [ "providers", "providers" ] } }, "/api/v1/providers/{connection_id}/calendar-configs/select": { "put": { "description": "Toggle which calendars are selected for syncing.", "operationId": "selectCalendars", "parameters": [ { "in": "path", "name": "connection_id", "required": true, "schema": { "title": "Connection Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CalendarSelectRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Selectcalendars", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Toggle calendar selection", "tags": [ "providers", "providers" ] } }, "/api/v1/providers/{connection_id}/carddav/credentials": { "post": { "description": "Merge a Contacts-scoped app password into the plugin's vault document.\n\nNEVER logs or returns the password value. Optionally persists the\nprovided ``carddav_url`` on the provider connection, and lifts the\nCardDAV auth-failure cooldown the previous password earned. The\nmailbox's own status is untouched: a CardDAV password never reconnects\na mailbox that needs its sign-in password or tokens again.", "operationId": "storeCarddavCredentials", "parameters": [ { "in": "path", "name": "connection_id", "required": true, "schema": { "title": "Connection Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CardDAVCredentialsRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CardDAVCredentialsResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Store dedicated CardDAV app password", "tags": [ "providers", "providers" ] } }, "/api/v1/providers/{connection_id}/carddav/status": { "get": { "description": "Return one row per (connection_id, address_book) from carddav_sync_state.", "operationId": "getCarddavStatus", "parameters": [ { "in": "path", "name": "connection_id", "required": true, "schema": { "title": "Connection Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CardDAVStatusResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Per-address-book CardDAV sync state", "tags": [ "providers", "providers" ] } }, "/api/v1/providers/{connection_id}/carddav/sync": { "post": { "description": "Synchronously runs the CardDAV sync for the given connection.\n\n5-minute timeout returns 504. Underlying sync handles its own errors\nand records them via ``carddav_sync_state.last_error``.", "operationId": "syncCarddav", "parameters": [ { "in": "path", "name": "connection_id", "required": true, "schema": { "title": "Connection Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CardDAVSyncResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Trigger CardDAV contact sync for a connection", "tags": [ "providers", "providers" ] } }, "/api/v1/providers/{connection_id}/carddav/test": { "post": { "description": "Perform a CardDAV PROPFIND to verify credentials and list address books.\n\nReturns 200 regardless of CardDAV-protocol outcome; the discriminated\n``{success, address_books, error}`` shape lets the UI distinguish\ninfra failures from domain failures without error-status noise.", "operationId": "testCarddav", "parameters": [ { "in": "path", "name": "connection_id", "required": true, "schema": { "title": "Connection Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CardDAVTestRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CardDAVTestResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Test CardDAV credentials and enumerate address books", "tags": [ "providers", "providers" ] } }, "/api/v1/providers/{connection_id}/delta-sync": { "post": { "description": "Trigger a delta sync using Gmail history.list for a provider connection.\n\nAccepts both JWT auth (user-initiated) and internal service auth\n(pubsub_worker-initiated via X-Internal-Service-Key).", "operationId": "triggerDeltaSync", "parameters": [ { "in": "path", "name": "connection_id", "required": true, "schema": { "title": "Connection Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeltaSyncResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Trigger delta sync", "tags": [ "providers", "providers" ] } }, "/api/v1/providers/{connection_id}/discover-aliases": { "get": { "description": "Triggers alias discovery from the provider API and persists results.", "operationId": "discoverAliases", "parameters": [ { "in": "path", "name": "connection_id", "required": true, "schema": { "title": "Connection Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Discoveraliases", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Discover email aliases", "tags": [ "providers", "providers" ] } }, "/api/v1/providers/{connection_id}/email-configs": { "get": { "description": "List email source configurations for a provider connection.", "operationId": "listEmailConfigs", "parameters": [ { "in": "path", "name": "connection_id", "required": true, "schema": { "title": "Connection Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/EmailSourceConfigResponse" }, "title": "Response Listemailconfigs", "type": "array" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List email configs for connection", "tags": [ "providers", "providers" ] } }, "/api/v1/providers/{connection_id}/first-run-sync": { "post": { "description": "Start three-phase first-run sync for a new email connection.\n\nOnly triggers if last_sync_at IS NULL (prevents re-triggering).\nRuns as a background task with supervisor retry.", "operationId": "triggerFirstRunSync", "parameters": [ { "in": "path", "name": "connection_id", "required": true, "schema": { "title": "Connection Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FirstRunSyncResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Trigger first-run sync", "tags": [ "providers", "providers" ] } }, "/api/v1/providers/{connection_id}/labels": { "get": { "description": "List email labels/folders for a provider connection.", "operationId": "listLabels2", "parameters": [ { "in": "path", "name": "connection_id", "required": true, "schema": { "title": "Connection Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/Label" }, "title": "Response Listlabels2", "type": "array" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List email labels", "tags": [ "providers", "providers" ] } }, "/api/v1/providers/{connection_id}/refresh": { "post": { "description": "Refresh OAuth tokens for a provider connection.", "operationId": "refreshTokens", "parameters": [ { "in": "path", "name": "connection_id", "required": true, "schema": { "title": "Connection Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Refreshtokens", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Refresh OAuth tokens", "tags": [ "providers", "providers" ] } }, "/api/v1/providers/{connection_id}/register-alias": { "post": { "description": "Register an email alias as a send-as address with Gmail. Google Workspace aliases auto-verify. Non-Workspace aliases require email verification and may fail.", "operationId": "registerAlias", "parameters": [ { "in": "path", "name": "connection_id", "required": true, "schema": { "title": "Connection Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegisterAliasRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Registeralias", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Register a send-as alias with the provider", "tags": [ "providers", "providers" ] } }, "/api/v1/providers/{connection_id}/sync": { "post": { "description": "Trigger email and/or calendar sync for a provider connection.", "operationId": "triggerSync", "parameters": [ { "in": "path", "name": "connection_id", "required": true, "schema": { "title": "Connection Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SyncRequest", "default": { "sync_type": "all" } } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SyncResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Trigger sync", "tags": [ "providers", "providers" ] } }, "/api/v1/providers/{connection_id}/sync-status": { "get": { "description": "Unified sync status showing header/body/enrichment phase progress.", "operationId": "getSyncStatus", "parameters": [ { "in": "path", "name": "connection_id", "required": true, "schema": { "title": "Connection Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_service__routers__first_run_sync__SyncStatusResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get sync status", "tags": [ "providers", "providers" ] } }, "/api/v1/providers/{connection_id}/watch": { "post": { "description": "Register Gmail push notifications (users.watch) for a provider connection.\n\nCalled after initial OAuth connect and periodically for renewal by the\ningestion-service watch renewal timer.\n\nAccepts both JWT auth and internal service auth.", "operationId": "registerWatch", "parameters": [ { "in": "path", "name": "connection_id", "required": true, "schema": { "title": "Connection Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WatchRequest", "default": {} } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WatchResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Register push notifications", "tags": [ "providers", "providers" ] } }, "/api/v1/public/booking-pages/{slug}": { "get": { "operationId": "getPublicBookingPage", "parameters": [ { "in": "path", "name": "slug", "required": true, "schema": { "title": "Slug", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicBookingPageResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Get Public Booking Page", "tags": [ "public-bookings", "public-bookings" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/public/booking-pages/{slug}/slots": { "get": { "operationId": "getPublicBookingSlots", "parameters": [ { "in": "path", "name": "slug", "required": true, "schema": { "title": "Slug", "type": "string" } }, { "in": "query", "name": "from", "required": false, "schema": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "From" } }, { "in": "query", "name": "to", "required": false, "schema": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "To" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SlotsResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Get Public Booking Slots", "tags": [ "public-bookings", "public-bookings" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/public/bookings": { "post": { "operationId": "createPublicBooking", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicBookingCreate" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingConfirmationResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Create Public Booking", "tags": [ "public-bookings", "public-bookings" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/public/bookings/{token}": { "get": { "operationId": "getPublicBooking", "parameters": [ { "in": "path", "name": "token", "required": true, "schema": { "title": "Token", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManageBookingResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Get Public Booking", "tags": [ "public-bookings", "public-bookings" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/public/bookings/{token}/cancel": { "post": { "operationId": "cancelPublicBooking", "parameters": [ { "in": "path", "name": "token", "required": true, "schema": { "title": "Token", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManageBookingResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Cancel Public Booking", "tags": [ "public-bookings", "public-bookings" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/public/bookings/{token}/reschedule": { "post": { "operationId": "reschedulePublicBooking", "parameters": [ { "in": "path", "name": "token", "required": true, "schema": { "title": "Token", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RescheduleRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManageBookingResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Reschedule Public Booking", "tags": [ "public-bookings", "public-bookings" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/public/campaigns/assets/{asset_id}": { "get": { "operationId": "getPublicCampaignAsset", "parameters": [ { "in": "path", "name": "asset_id", "required": true, "schema": { "title": "Asset Id", "type": "string" } } ], "responses": { "200": { "content": { "application/octet-stream": {} }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Tokened public campaign email asset", "tags": [ "public-campaigns" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/public/forms/assets/{asset_id}": { "get": { "operationId": "getPublicFormAsset", "parameters": [ { "in": "path", "name": "asset_id", "required": true, "schema": { "title": "Asset Id", "type": "string" } } ], "responses": { "200": { "content": { "application/octet-stream": {} }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Publication-scoped public page asset", "tags": [ "public-forms", "public-forms" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/public/forms/r/{row_token}": { "get": { "description": "The per-row link (TIDY-16834 / AC2).\n\nSame published bundle, same protections, same renderer — the only addition\nis prefill, and it draws ONLY the publication's granted fields. An ungranted\nfield is never read out of the row, so it can neither be shown nor round-trip\nback through a submission.", "operationId": "getPublicRowFormPage", "parameters": [ { "in": "path", "name": "row_token", "required": true, "schema": { "title": "Row Token", "type": "string" } } ], "responses": { "200": { "content": { "text/html": { "schema": { "type": "string" } } }, "description": "Successful Response" }, "404": { "content": { "text/html": {} }, "description": "Not Found" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Published form page bound to one row, with grant-scoped prefill", "tags": [ "public-forms", "public-forms" ], "x-local-capability": "cloud", "x-mcp-skip": true }, "post": { "operationId": "submitPublicRowForm", "parameters": [ { "in": "path", "name": "row_token", "required": true, "schema": { "title": "Row Token", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicFormSubmitResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Submit a row-bound published form — applies to the bound row", "tags": [ "public-forms", "public-forms" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/public/forms/{token}": { "get": { "operationId": "getPublicFormPage", "parameters": [ { "in": "path", "name": "token", "required": true, "schema": { "title": "Token", "type": "string" } } ], "responses": { "200": { "content": { "text/html": { "schema": { "type": "string" } } }, "description": "Successful Response" }, "404": { "content": { "text/html": {} }, "description": "Not Found" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Server-rendered published form page", "tags": [ "public-forms", "public-forms" ], "x-local-capability": "cloud", "x-mcp-skip": true }, "post": { "operationId": "submitPublicForm", "parameters": [ { "in": "path", "name": "token", "required": true, "schema": { "title": "Token", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicFormSubmitResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Submit a published form (layered protections, target_table-routed)", "tags": [ "public-forms", "public-forms" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/public/forms/{token}/submissions": { "post": { "operationId": "submitPublicFormSubmission", "parameters": [ { "in": "path", "name": "token", "required": true, "schema": { "title": "Token", "type": "string" } } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicFormSubmitResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Submit a published first-class form", "tags": [ "public-forms", "public-forms" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/public/signature-requests/{token}": { "get": { "operationId": "getPublicSigningContext", "parameters": [ { "in": "path", "name": "token", "required": true, "schema": { "maxLength": 128, "minLength": 32, "title": "Token", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicSigningContext" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Load a signing page by single-use token", "tags": [ "e-signature-public" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Public token-scoped signing surface — not an agent tool." } }, "/api/v1/public/signature-requests/{token}/sign": { "post": { "operationId": "submitPublicSignature", "parameters": [ { "in": "path", "name": "token", "required": true, "schema": { "maxLength": 128, "minLength": 32, "title": "Token", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitSignatureRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitSignatureResult" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Submit a signature for a signing token", "tags": [ "e-signature-public" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Public token-scoped signing surface — not an agent tool." } }, "/api/v1/public/unsubscribe/{unsub_token}": { "get": { "description": "Landing page: one click total, or the confirmation when already done.", "operationId": "getPublicUnsubscribe", "parameters": [ { "in": "path", "name": "unsub_token", "required": true, "schema": { "title": "Unsub Token", "type": "string" } } ], "responses": { "200": { "content": { "text/html": { "schema": { "type": "string" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Tokened unsubscribe landing page", "tags": [ "public-unsubscribe", "public-unsubscribe" ], "x-local-capability": "cloud", "x-mcp-skip": true }, "post": { "description": "Immediate suppression, 200 always for known tokens (RFC 8058).", "operationId": "postPublicUnsubscribe", "parameters": [ { "in": "path", "name": "unsub_token", "required": true, "schema": { "title": "Unsub Token", "type": "string" } } ], "responses": { "200": { "content": { "text/html": { "schema": { "type": "string" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "RFC 8058 one-click + landing-page confirm", "tags": [ "public-unsubscribe", "public-unsubscribe" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/public/workspace-templates": { "get": { "description": "Public list of PUBLISHED templates (summary projection, no definition).", "operationId": "listPublicWorkspaceTemplates", "parameters": [ { "description": "Filter by family (business|personal)", "in": "query", "name": "family", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by family (business|personal)", "title": "Family" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/PublicWorkspaceTemplateListItem" }, "title": "Response Listpublicworkspacetemplates", "type": "array" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "List Public Workspace Templates", "tags": [ "public-workspace-templates", "public-workspace-templates" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/public/workspace-templates/{slug}": { "get": { "description": "Public detail for a PUBLISHED template (summary projection, no definition).", "operationId": "getPublicWorkspaceTemplate", "parameters": [ { "in": "path", "name": "slug", "required": true, "schema": { "title": "Slug", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicWorkspaceTemplateResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Get Public Workspace Template", "tags": [ "public-workspace-templates", "public-workspace-templates" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/query-authoring/capabilities": { "get": { "description": "The authoring vocabulary an agent needs BEFORE authoring, bounded.\n\nEvery section but ``facets`` is a fixed-size registry; ``facets`` pages, so\na tenant with a thousand facet definitions still returns a promptable\nresponse. Actions are stamped with whether THIS caller's grant covers them\n— a token-bounded principal sees a smaller set of verbs than a session.", "operationId": "getQueryAuthoringCapabilities", "parameters": [ { "description": "Slices to return; omit for all. Valid: query, fields, formulas, view_types, charts, forms, containers, actions, facets. An unknown name is a 422 listing the valid alternatives.", "in": "query", "name": "sections", "required": false, "schema": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "description": "Slices to return; omit for all. Valid: query, fields, formulas, view_types, charts, forms, containers, actions, facets. An unknown name is a 422 listing the valid alternatives.", "title": "Sections" } }, { "description": "Facet page offset.", "in": "query", "name": "facet_offset", "required": false, "schema": { "default": 0, "description": "Facet page offset.", "minimum": 0, "title": "Facet Offset", "type": "integer" } }, { "description": "Facet page size.", "in": "query", "name": "facet_limit", "required": false, "schema": { "default": 50, "description": "Facet page size.", "maximum": 200, "minimum": 1, "title": "Facet Limit", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueryAuthoringCapabilitiesResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Inspect the canonical query/formula/container authoring vocabulary", "tags": [ "query-authoring", "query-authoring" ], "x-local-capability": "cloud" } }, "/api/v1/query-authoring/operations/{operation_id}": { "get": { "description": "Read one operation the CALLING principal created (TIDY-15409 D32).\n\nSweeps its own stale lease before reading, which is what lets a retry\nladder make progress with no scheduler behind it: a pending operation past\nthe timeout reads back ``failed_retryable`` and the next attempt can reclaim\nit. Another principal's operation is a 404, not a 403 — the id space is not\nenumerable.", "operationId": "getAgentArtifactOperationStatus", "parameters": [ { "in": "path", "name": "operation_id", "required": true, "schema": { "format": "uuid", "title": "Operation Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentArtifactOperationStatusResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Status of one agent artifact operation (creator-scoped)", "tags": [ "query-authoring", "query-authoring" ], "x-local-capability": "cloud" } }, "/api/v1/query-authoring/preview": { "post": { "description": "Validate a QuerySpec V1 and return the ordered sample the persisted\nview would show — the assistant's pre/post-authoring proof. READ ONLY.", "operationId": "previewRecordsQuery", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueryPreviewRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueryPreviewResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Validate and preview an ordered records query (side-effect free)", "tags": [ "query-authoring", "query-authoring" ], "x-local-capability": "cloud" } }, "/api/v1/ranking/cohort-events": { "post": { "description": "Ingest a bounded batch of ranking outcome events for the caller.", "operationId": "ingestRankingCohortEvents", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CohortEventBatch" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CohortEventBatchResult" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Ingest Cohort Events", "tags": [ "ranking" ], "x-local-capability": "outbox", "x-mcp-skip": true, "x-mcp-skip-reason": "Client telemetry ingestion; not an agent-callable tool." } }, "/api/v1/recipe-behavior/suppress": { "post": { "description": "Suppress (\"don't do again\") or attenuate (\"less like this\") a behavior.", "operationId": "suppressRecipeBehavior", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuppressRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuppressionEntry" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Suppress Recipe Behavior", "tags": [ "recipe-behavior", "recipe-behavior" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "TIDY-14829 web trust chrome consumes; MCP behavior controls ride the epic's platform work." } }, "/api/v1/recipe-behavior/suppressions": { "get": { "description": "The caller's active suppressions, grouped in outcome language.", "operationId": "listRecipeBehaviorSuppressions", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuppressionListResponse" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List Recipe Behavior Suppressions", "tags": [ "recipe-behavior", "recipe-behavior" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "TIDY-14829 web trust chrome consumes; MCP behavior controls ride the epic's platform work." } }, "/api/v1/recipe-behavior/suppressions/{suppression_id}": { "delete": { "description": "Explicitly revoke a suppression (the renewed-consent act) — own rows only.", "operationId": "revokeRecipeBehaviorSuppression", "parameters": [ { "in": "path", "name": "suppression_id", "required": true, "schema": { "format": "uuid", "title": "Suppression Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuppressionRevokeResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Revoke Recipe Behavior Suppression", "tags": [ "recipe-behavior", "recipe-behavior" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "TIDY-14829 web trust chrome consumes; MCP behavior controls ride the epic's platform work." } }, "/api/v1/recipe-outputs/feedback": { "post": { "description": "Capture one explicit/implicit signal against a run or one of its outputs.", "operationId": "captureRecipeOutputFeedback", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeedbackRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeedbackResult" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Capture Recipe Output Feedback", "tags": [ "recipe-outputs", "recipe-outputs" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "TIDY-14829 web trust chrome consumes; MCP feedback rides the epic's platform work." } }, "/api/v1/recipe-outputs/feedback/batch": { "post": { "description": "Implicit-signal batch capture (read/expand/link-follow …).\n\nPer-item isolation: every event succeeds/fails independently; per-item\nfailures come back in the response body (status='failed' + error_code),\nnever as a batch-level 5xx (TIDY-14827 re-fix).", "operationId": "captureRecipeOutputFeedbackBatch", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeedbackBatchRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeedbackBatchResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Capture Recipe Output Feedback Batch", "tags": [ "recipe-outputs", "recipe-outputs" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "TIDY-14829 web trust chrome consumes; MCP feedback rides the epic's platform work." } }, "/api/v1/recipe-outputs/undo": { "post": { "description": "Roll back a recipe run's output(s) — CAS-guarded, writer-mediated.", "operationId": "undoRecipeOutput", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UndoRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UndoResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Undo Recipe Output", "tags": [ "recipe-outputs", "recipe-outputs" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "TIDY-14828 web trust chrome consumes; MCP undo rides the epic's platform work." } }, "/api/v1/recipe-outputs/{primitive_type}/{primitive_id}/why": { "get": { "description": "Outcome-level evidence for every recipe change that touched a primitive.", "operationId": "getRecipeOutputWhy", "parameters": [ { "in": "path", "name": "primitive_type", "required": true, "schema": { "title": "Primitive Type", "type": "string" } }, { "in": "path", "name": "primitive_id", "required": true, "schema": { "format": "uuid", "title": "Primitive Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhyResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Recipe Output Why", "tags": [ "recipe-outputs", "recipe-outputs" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "TIDY-14828 web trust chrome consumes; MCP why rides the epic's platform work." } }, "/api/v1/recipes/preferences": { "get": { "description": "List the caller's recipe preferences across all recipes.", "operationId": "listRecipePreferences", "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/RecipePreferenceResponse" }, "title": "Response Listrecipepreferences", "type": "array" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List Recipe Preferences", "tags": [ "recipes", "recipes" ] } }, "/api/v1/recipes/{recipe_slug}/preferences": { "post": { "description": "Pause or resume a recipe for the calling user.", "operationId": "setRecipePreference", "parameters": [ { "in": "path", "name": "recipe_slug", "required": true, "schema": { "title": "Recipe Slug", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecipePreferenceUpdate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecipePreferenceResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Set Recipe Preference", "tags": [ "recipes", "recipes" ] } }, "/api/v1/records": { "get": { "description": "List records the user owns or that are shared/tenant-visible.", "operationId": "listRecords", "parameters": [ { "description": "Filter by facet slug", "in": "query", "name": "facet_slug", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by facet slug", "title": "Facet Slug" } }, { "description": "Max records to return", "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "description": "Max records to return", "maximum": 200, "minimum": 1, "title": "Limit", "type": "integer" } }, { "description": "Pagination offset", "in": "query", "name": "offset", "required": false, "schema": { "default": 0, "description": "Pagination offset", "minimum": 0, "title": "Offset", "type": "integer" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordListResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List records", "tags": [ "records", "records" ] }, "post": { "description": "Create a new record owned by the authenticated user.\n\nAccepts an optional client-supplied `id` so PowerSync CRUD uploads that\nalready allocated the UUID locally (e.g. /record slash command, TIDY-7048)\ncan persist under the same ID the local-first client embedded in TipTap.", "operationId": "createRecord", "parameters": [ { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } }, { "in": "header", "name": "X-Tidy-Sync-Origin", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tidy-Sync-Origin" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordCreateRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Create a record", "tags": [ "records", "records" ] } }, "/api/v1/records/batch": { "post": { "description": "Create up to 50 records in one call. Row identity =\nUUIDv5(tenant, facet, key) — retries with the same keys UPDATE the same\nrows (``created|updated|unchanged`` per row). Secret-shaped property keys\nare rejected per row with remodeling guidance; values are never logged.", "operationId": "batchCreateRecords", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordBatchCreateRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordBatchCreateResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Batch-create custom records (bounded, idempotent by key)", "tags": [ "query-authoring", "query-authoring" ], "x-local-capability": "cloud" } }, "/api/v1/records/{record_id}": { "delete": { "description": "Soft-delete a record. Must be owner, the record must be shared/tenant-visible,\nor the caller holds its owner's read_write records grant.", "operationId": "deleteRecord", "parameters": [ { "description": "Typed ID with prefix 'R'", "in": "path", "name": "record_id", "required": true, "schema": { "description": "Typed ID with prefix 'R'", "title": "Record Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Soft-delete a record", "tags": [ "records", "records" ] }, "get": { "description": "Get a single record by ID. Must be owner, the record must be\nshared/tenant-visible, or the caller holds its owner's records grant.", "operationId": "getRecord", "parameters": [ { "description": "Typed ID with prefix 'R'", "in": "path", "name": "record_id", "required": true, "schema": { "description": "Typed ID with prefix 'R'", "title": "Record Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get record by ID", "tags": [ "records", "records" ] }, "patch": { "description": "Partially update a record. Must be owner, the record must be\nshared/tenant-visible, or the caller holds its owner's read_write records grant.\n\nTwo properties-write shapes, BOTH merged into the stored bag under a row\nlock — a PATCH never wipes keys it does not carry (TIDY-14488):\n * `properties` — RFC 7386-style merge-patch: top-level keys merge\n into the stored bag; an explicit JSON `null` value DELETES that key;\n omitted keys are preserved. (Full-bag REPLACE is a POST-create-only\n semantic — creation supplies the whole object.)\n * `properties_delta` — ONLY the changed keys; merged atomically\n (`properties || delta`) so two writers editing DIFFERENT fields never\n clobber each other (same-field concurrency = last-write-wins). `null`\n values are STORED as null (TIDY-14390 / P15 sync-transport contract).\nBoth validate only the incoming keys and run the server-authoritative form\ncontract: checklist audit stamping (P17) and flat derived-key recompute (P16).", "operationId": "updateRecord", "parameters": [ { "description": "Typed ID with prefix 'R'", "in": "path", "name": "record_id", "required": true, "schema": { "description": "Typed ID with prefix 'R'", "title": "Record Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } }, { "in": "header", "name": "X-Tidy-Sync-Origin", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tidy-Sync-Origin" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordUpdateRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Update a record", "tags": [ "records", "records" ] } }, "/api/v1/records/{record_id}/field-reminder": { "put": { "description": "Opt a record's datetime field in/out of a reminder that fires AT the\nstored timestamp (TIDY-14226 R5). One idempotent binding per\n(record, field, owner); edits to the field move the reminder, clearing the\nfield cancels it — never a duplicated timestamp or shadow task.", "operationId": "setRecordFieldReminder", "parameters": [ { "description": "Typed ID with prefix 'R'", "in": "path", "name": "record_id", "required": true, "schema": { "description": "Typed ID with prefix 'R'", "title": "Record Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordFieldReminderRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordFieldReminderResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Bind or clear a datetime-field reminder", "tags": [ "records", "records" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/records/{record_id}/form-submissions": { "post": { "description": "Validate + execute one html_block form submission as the interacting member.\n\nModes (fixed by the block author, never overridable at embed time — D2):\n * ``create`` — insert a new record of ``form_target_facet``, owned by the\n caller. Verbatim maps validated answers; ``form_ai_expand`` runs them\n through the extraction lane first (extracted wins; ``_form_raw`` keeps\n the originals).\n * ``self`` — replace the block's own ``properties.form_state`` (owner only).", "operationId": "submitHtmlBlockForm", "parameters": [ { "description": "Typed ID with prefix 'R'", "in": "path", "name": "record_id", "required": true, "schema": { "description": "Typed ID with prefix 'R'", "title": "Record Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FormSubmissionRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FormSubmissionResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Submit an html_block form", "tags": [ "records", "records" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Host-only mutation seam for the sandboxed html_block document; the browser bridge posts collected values here. Not an agent tool — an agent creates target-facet entities directly via createRecord." } }, "/api/v1/records/{record_id}/study/progress": { "get": { "description": "Every card of this deck the caller has studied, theirs only.", "operationId": "listStudyProgress", "parameters": [ { "description": "Typed ID with prefix 'R'", "in": "path", "name": "record_id", "required": true, "schema": { "description": "Typed ID with prefix 'R'", "title": "Record Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StudyProgressListResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get the caller's study progress for a deck", "tags": [ "study", "study" ], "x-local-capability": "local", "x-mcp-skip": true } }, "/api/v1/records/{record_id}/study/review": { "post": { "description": "Write one card review. The deck record is not touched.", "operationId": "recordStudyReview", "parameters": [ { "description": "Typed ID with prefix 'R'", "in": "path", "name": "record_id", "required": true, "schema": { "description": "Typed ID with prefix 'R'", "title": "Record Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StudyReviewRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StudyProgressResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Record a graded card review", "tags": [ "study", "study" ], "x-local-capability": "outbox", "x-mcp-skip": true } }, "/api/v1/records/{record_id}/study/session": { "post": { "description": "Record that a session was finished (R17 observability).", "operationId": "recordStudySession", "parameters": [ { "description": "Typed ID with prefix 'R'", "in": "path", "name": "record_id", "required": true, "schema": { "description": "Typed ID with prefix 'R'", "title": "Record Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StudySessionRequest" } } }, "required": true }, "responses": { "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StudySessionResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Record a completed study or quiz session", "tags": [ "study", "study" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/references/gather": { "post": { "description": "Gather member-visible references for a structural FilterGroup.", "operationId": "gatherReferences", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReferenceGatherRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReferenceGatherResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Post Gather References", "tags": [ "references" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Consumed by the Tidy assistant's gather tool via the member's OBO bearer; the assistant tool is the agent surface, not a standalone SDK/MCP workflow." } }, "/api/v1/references/handed": { "post": { "description": "Record what a live turn's message cited, under the human the turn is bound to.", "operationId": "recordHandedReferences", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HandedReferencesRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HandedReferencesResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Record the references an employee's turn was handed", "tags": [ "references" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Called by an employee's connector as a turn starts, with its runtime credential; not an agent tool." } }, "/api/v1/references/{typed_id}": { "get": { "description": "Read the row a two-letter typed id names, under the caller's visibility.", "operationId": "getReference", "parameters": [ { "in": "path", "name": "typed_id", "required": true, "schema": { "title": "Typed Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReferenceReadResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Read a referenceable row by typed id", "tags": [ "references" ], "x-local-capability": "cloud" } }, "/api/v1/references/{typed_id}/handed": { "get": { "description": "The title and sender of a reference handed to the caller, or the same 404\nas an id that names nothing: only an id handed to THIS caller answers.\n\n`tidy_fetch` asks this once its read of the id has failed, to say \"you don't\nhave access to <title>; ask <sender>\" instead of \"not found\".", "operationId": "getHandedReference", "parameters": [ { "in": "path", "name": "typed_id", "required": true, "schema": { "title": "Typed Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HandedReferenceResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "How a reference was handed to the caller in a message", "tags": [ "references" ], "x-local-capability": "cloud" } }, "/api/v1/relationship-types": { "get": { "description": "Return builtin + tenant custom + observed vocabulary (D3).", "operationId": "listRelationshipTypes", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelationshipTypesResponse" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List the merged relationship-type vocabulary", "tags": [ "relationship-types" ], "x-mcp-skip": true }, "post": { "description": "Create a custom relationship type. 409 on duplicate label in tenant.", "operationId": "createRelationshipType", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelationshipTypeCreate" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelationshipTypeRecord" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Create a tenant relationship type", "tags": [ "relationship-types" ], "x-mcp-skip": true } }, "/api/v1/relationship-types/{type_id}": { "delete": { "description": "Soft delete: existing links keep their self-contained ``predicate`` text.", "operationId": "deleteRelationshipType", "parameters": [ { "in": "path", "name": "type_id", "required": true, "schema": { "title": "Type Id", "type": "string" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Soft-delete a tenant relationship type", "tags": [ "relationship-types" ], "x-mcp-skip": true } }, "/api/v1/reminder-preferences": { "get": { "description": "Get user reminder preferences\n\nCreates default preferences if they don't exist.\n\n**Response**: UserReminderPreferencesResponse", "operationId": "getPreferences2", "parameters": [ { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserReminderPreferencesResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Preferences", "tags": [ "reminder-preferences" ] }, "patch": { "description": "Update user reminder preferences\n\nCreates preferences with updated values if they don't exist.\n\n**Request Body**: UserReminderPreferencesUpdate\n**Response**: Updated UserReminderPreferencesResponse", "operationId": "updatePreferences2", "parameters": [ { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserReminderPreferencesUpdate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserReminderPreferencesResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Update Preferences", "tags": [ "reminder-preferences" ] } }, "/api/v1/reminder-templates": { "get": { "description": "Get all reminder templates (system and user templates)\n\n**Response**: List of ReminderTemplateResponse objects", "operationId": "getTemplates", "parameters": [ { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/ReminderTemplateResponse" }, "title": "Response Gettemplates", "type": "array" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Templates", "tags": [ "reminder-templates" ] }, "post": { "description": "Create a new reminder template\n\n**Request Body**: ReminderTemplateCreate\n**Response**: Created ReminderTemplateResponse", "operationId": "createReminderTemplate", "parameters": [ { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReminderTemplateCreate" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReminderTemplateResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Create Template", "tags": [ "reminder-templates" ] } }, "/api/v1/reminder-templates/{template_id}": { "delete": { "description": "Delete a reminder template (user templates only)\n\n**Path Parameters**:\n- template_id: UUID of the template\n\n**Response**: 204 No Content\n**Errors**:\n- 404: Template not found or is a system template", "operationId": "deleteReminderTemplate", "parameters": [ { "in": "path", "name": "template_id", "required": true, "schema": { "title": "Template Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Delete Template", "tags": [ "reminder-templates" ] }, "get": { "description": "Get a single reminder template by ID\n\n**Path Parameters**:\n- template_id: UUID of the template\n\n**Response**: ReminderTemplateResponse object\n**Errors**:\n- 404: Template not found", "operationId": "getTemplateById", "parameters": [ { "in": "path", "name": "template_id", "required": true, "schema": { "title": "Template Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReminderTemplateResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Template By Id", "tags": [ "reminder-templates" ] }, "patch": { "description": "Update a reminder template (user templates only)\n\n**Path Parameters**:\n- template_id: UUID of the template\n\n**Request Body**: ReminderTemplateUpdate\n**Response**: Updated ReminderTemplateResponse\n**Errors**:\n- 404: Template not found or is a system template", "operationId": "updateReminderTemplate", "parameters": [ { "in": "path", "name": "template_id", "required": true, "schema": { "title": "Template Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReminderTemplateUpdate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReminderTemplateResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Update Template", "tags": [ "reminder-templates" ] } }, "/api/v1/reminders": { "get": { "description": "List all reminders for the authenticated user with optional filtering.\n\n Query Parameters:\n - status: Optional status filter (pending, sent, cancelled, failed)\n - limit: Max results to return (default 50, max 100)\n - offset: Pagination offset (default 0)\n\n Response (200 OK):\n {\n \"reminders\": [\n {\n \"id\": \"a1b2c3d4-e5f6-4789-abcd-ef1234567890\",\n \"account_id\": \"11111111-1111-1111-1111-111111111111\",\n \"title\": \"Soccer practice at Lincoln Park\",\n \"reminder_date\": \"2025-11-20T09:00:00Z\",\n \"status\": \"pending\",\n ...\n }\n ],\n \"count\": 15\n }\n\n Results sorted by reminder_date DESC (newest first).\n\n Error Responses:\n - 401 Unauthorized: Missing or invalid JWT token\n - 500 Internal Server Error: Database operation failed\n\n Related: Reminder CRUD Operations Feature", "operationId": "listReminders", "parameters": [ { "description": "Filter by status", "in": "query", "name": "status", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by status", "title": "Status" } }, { "description": "Max results", "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "description": "Max results", "maximum": 100, "minimum": 1, "title": "Limit", "type": "integer" } }, { "description": "Pagination offset", "in": "query", "name": "offset", "required": false, "schema": { "default": 0, "description": "Pagination offset", "minimum": 0, "title": "Offset", "type": "integer" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Listreminders", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List reminders", "tags": [ "reminders" ] }, "post": { "description": "Create a new reminder for the authenticated user.\n\n Used by:\n 1. **Manual Creation**: User creates reminder via dashboard UI\n 2. **LLM Extraction**: Extractor service creates reminder from email content\n\n Request:\n {\n \"title\": \"Soccer practice at Lincoln Park\",\n \"description\": \"Don't forget water bottle and shin guards\",\n \"reminder_date\": \"2025-11-20T09:00:00Z\",\n \"delivery_methods\": \"push,email\",\n \"metadata\": {\n \"email\": \"parent@example.com\"\n }\n }\n\n Response (201 Created):\n {\n \"id\": \"a1b2c3d4-e5f6-4789-abcd-ef1234567890\",\n \"account_id\": \"11111111-1111-1111-1111-111111111111\",\n \"title\": \"Soccer practice at Lincoln Park\",\n \"description\": \"Don't forget water bottle and shin guards\",\n \"reminder_date\": \"2025-11-20T09:00:00Z\",\n \"delivery_methods\": \"push,email\",\n \"status\": \"pending\",\n \"metadata\": {\n \"email\": \"parent@example.com\"\n },\n \"source_type\": \"manual\",\n \"source_id\": null,\n \"created_at\": \"2025-11-19T14:30:22.123Z\",\n \"updated_at\": \"2025-11-19T14:30:22.123Z\",\n \"sent_at\": null\n }\n\n Validation Rules:\n - title: Required, 1-500 characters\n - reminder_date: Required, ISO 8601 datetime\n - delivery_methods: Optional, defaults to 'push'\n - metadata: Optional, JSON object for delivery config\n\n Error Responses:\n - 400 Bad Request: Invalid title, date, or metadata\n - 401 Unauthorized: Missing or invalid JWT token\n - 500 Internal Server Error: Database operation failed\n\n Related: Reminder CRUD Operations Feature", "operationId": "createReminder", "parameters": [ { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReminderCreate" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReminderResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Create new reminder", "tags": [ "reminders" ] } }, "/api/v1/reminders/parse": { "post": { "description": "Parse reminder text into one or more datetime candidates.\n\nThe API always returns a structured response. On parse failures, `success`\nis `false` with a recoverable `error` message for UI editing.", "operationId": "parseReminderText", "parameters": [ { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReminderParseRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReminderParseResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Parse reminder text into normalized datetime candidates", "tags": [ "reminder-parse" ] } }, "/api/v1/reminders/{reminder_id}": { "delete": { "description": "Delete a reminder (hard delete).\n\n Path Parameters:\n - reminder_id: UUID of the reminder to delete\n\n Response (204 No Content):\n No response body on success.\n\n Note: This performs a hard delete. If you want to cancel a reminder\n but keep the record, use PATCH to update status to 'cancelled' instead.\n\n Error Responses:\n - 401 Unauthorized: Missing or invalid JWT token\n - 404 Not Found: Reminder not found or not owned by user\n - 500 Internal Server Error: Database operation failed\n\n Related: Reminder CRUD Operations Feature", "operationId": "deleteReminder", "parameters": [ { "description": "Typed ID with prefix 'Y'", "in": "path", "name": "reminder_id", "required": true, "schema": { "description": "Typed ID with prefix 'Y'", "title": "Reminder Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Delete reminder", "tags": [ "reminders" ] }, "get": { "description": "Get a single reminder by ID.\n\n Path Parameters:\n - reminder_id: UUID of the reminder\n\n Response (200 OK):\n {\n \"id\": \"a1b2c3d4-e5f6-4789-abcd-ef1234567890\",\n \"account_id\": \"11111111-1111-1111-1111-111111111111\",\n \"title\": \"Soccer practice at Lincoln Park\",\n ...\n }\n\n Error Responses:\n - 401 Unauthorized: Missing or invalid JWT token\n - 404 Not Found: Reminder not found or not owned by user\n - 500 Internal Server Error: Database operation failed\n\n Related: Reminder CRUD Operations Feature", "operationId": "getReminder", "parameters": [ { "description": "Typed ID with prefix 'Y'", "in": "path", "name": "reminder_id", "required": true, "schema": { "description": "Typed ID with prefix 'Y'", "title": "Reminder Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReminderResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get reminder details", "tags": [ "reminders" ] }, "patch": { "description": "Update an existing reminder (partial update).\n\n Path Parameters:\n - reminder_id: UUID of the reminder to update\n\n Request (all fields optional):\n {\n \"title\": \"Updated title\",\n \"reminder_date\": \"2025-11-21T10:00:00Z\",\n \"status\": \"cancelled\"\n }\n\n Response (200 OK):\n {\n \"id\": \"a1b2c3d4-e5f6-4789-abcd-ef1234567890\",\n \"account_id\": \"11111111-1111-1111-1111-111111111111\",\n \"title\": \"Updated title\",\n \"reminder_date\": \"2025-11-21T10:00:00Z\",\n \"status\": \"cancelled\",\n ...\n }\n\n Common Update Scenarios:\n - Reschedule: Update reminder_date\n - Cancel: Update status to 'cancelled'\n - Change delivery: Update delivery_methods and metadata\n\n Error Responses:\n - 400 Bad Request: Invalid update data\n - 401 Unauthorized: Missing or invalid JWT token\n - 404 Not Found: Reminder not found or not owned by user\n - 500 Internal Server Error: Database operation failed\n\n Related: Reminder CRUD Operations Feature", "operationId": "updateReminder", "parameters": [ { "description": "Typed ID with prefix 'Y'", "in": "path", "name": "reminder_id", "required": true, "schema": { "description": "Typed ID with prefix 'Y'", "title": "Reminder Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReminderUpdate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReminderResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Update reminder", "tags": [ "reminders" ] } }, "/api/v1/research-skills": { "post": { "description": "Verify → compile → package. Returns the created skill + verification counts.", "operationId": "packageResearchSkill", "parameters": [ { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PackageExpertiseRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PackageExpertiseResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Package research findings into a verified skill", "tags": [ "research-skills", "research-skills" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Assistant-orchestrated research→skill packaging (become-an-expert skill calls it after the research subagent); not a standalone MCP tool." } }, "/api/v1/research/runs": { "get": { "description": "Current state of the caller's research runs (newest first), or one run.", "operationId": "listResearchRuns", "parameters": [ { "in": "query", "name": "run_id", "required": false, "schema": { "anyOf": [ { "maxLength": 64, "type": "string" }, { "type": "null" } ], "title": "Run Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResearchRunList" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List Research Runs", "tags": [ "web-research" ], "x-local-capability": "cloud" }, "post": { "description": "Dispatch deep open-web research; returns at once with a run id.\n\nA research run spends inference, so it is credit-gated like any other\nbig-ticket initiation (402 on an exhausted pool or a checkpoint).", "operationId": "startResearchRun", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResearchRunStartRequest" } } }, "required": true }, "responses": { "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResearchRunStarted" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Start Research Run", "tags": [ "web-research" ], "x-local-capability": "cloud" } }, "/api/v1/research/runs/{run_id}/report": { "get": { "description": "Read a landed report: its outline by default, one section on request.", "operationId": "readResearchRunReport", "parameters": [ { "in": "path", "name": "run_id", "required": true, "schema": { "title": "Run Id", "type": "string" } }, { "description": "A heading (or index) from the outline.", "in": "query", "name": "section", "required": false, "schema": { "anyOf": [ { "maxLength": 200, "type": "string" }, { "type": "null" } ], "description": "A heading (or index) from the outline.", "title": "Section" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResearchReport" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Read Research Run Report", "tags": [ "web-research" ], "x-local-capability": "cloud" } }, "/api/v1/review/all": { "get": { "description": "List all extracted primitives (admin view, not just those requiring review).", "operationId": "listAllPrimitives", "parameters": [ { "description": "Filter by type: CalendarEvent, Task, Note, Contact", "in": "query", "name": "type_filter", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by type: CalendarEvent, Task, Note, Contact", "title": "Type Filter" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 100, "maximum": 500, "minimum": 1, "title": "Limit", "type": "integer" } }, { "in": "query", "name": "offset", "required": false, "schema": { "default": 0, "minimum": 0, "title": "Offset", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReviewListResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List All Primitives", "tags": [ "review", "review-legacy" ] } }, "/api/v1/review/approval/batch/approve": { "post": { "description": "Batch approve multiple primitives.\n\nBody:\n {\"items\": [{\"type\": \"task\", \"id\": \"uuid\"}, {\"type\": \"note\", \"id\": \"uuid\"}]}\n\nReturns:\n {\"processed\": 5, \"failed\": 0, \"errors\": []}", "operationId": "batchApprove", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Batch Approve", "tags": [ "review", "review-batch" ] } }, "/api/v1/review/approval/batch/reject": { "post": { "description": "Batch reject multiple primitives.\n\nBody:\n {\"items\": [{\"type\": \"task\", \"id\": \"uuid\"}, {\"type\": \"note\", \"id\": \"uuid\"}]}\n\nReturns:\n {\"processed\": 5, \"failed\": 0, \"errors\": []}", "operationId": "batchReject", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Batch Reject", "tags": [ "review", "review-batch" ] } }, "/api/v1/review/approval/calendar_event/{item_id}/approve": { "post": { "description": "Approve a calendar event, optionally onto a destination calendar\n(TIDY-15323 approval_destination).", "operationId": "approveCalendarEvent2", "parameters": [ { "in": "path", "name": "item_id", "required": true, "schema": { "title": "Item Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/ApprovalApproveRequest" }, { "type": "null" } ], "title": "Body" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalActionResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Approve Calendar Event", "tags": [ "review", "review-approval" ] } }, "/api/v1/review/approval/calendar_event/{item_id}/reject": { "post": { "description": "Reject a calendar event.", "operationId": "rejectCalendarEvent2", "parameters": [ { "in": "path", "name": "item_id", "required": true, "schema": { "title": "Item Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RejectRequest" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalActionResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Reject Calendar Event", "tags": [ "review", "review-approval" ] } }, "/api/v1/review/approval/contact/{item_id}/approve": { "post": { "description": "Approve a contact (promotes to visible).", "operationId": "approveContact2", "parameters": [ { "in": "path", "name": "item_id", "required": true, "schema": { "title": "Item Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalActionResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Approve Contact", "tags": [ "review", "review-approval" ] } }, "/api/v1/review/approval/contact/{item_id}/reject": { "post": { "description": "Reject a contact (hides but keeps for dedup).", "operationId": "rejectContact2", "parameters": [ { "in": "path", "name": "item_id", "required": true, "schema": { "title": "Item Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RejectRequest" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalActionResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Reject Contact", "tags": [ "review", "review-approval" ] } }, "/api/v1/review/approval/counts": { "get": { "description": "Get counts of pending approvals grouped by type and date.\n\nReturns:\n {\n \"today\": {\"task\": 3, \"note\": 1},\n \"older\": {\"task\": 5, \"reminder\": 2},\n \"total\": 11\n }", "operationId": "getApprovalCounts", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalCountsResponse" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Approval Counts", "tags": [ "review", "review-pending" ] } }, "/api/v1/review/approval/note/{item_id}/approve": { "post": { "description": "Approve a note.", "operationId": "approveNote2", "parameters": [ { "in": "path", "name": "item_id", "required": true, "schema": { "title": "Item Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalActionResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Approve Note", "tags": [ "review", "review-approval" ] } }, "/api/v1/review/approval/note/{item_id}/reject": { "post": { "description": "Reject a note.", "operationId": "rejectNote2", "parameters": [ { "in": "path", "name": "item_id", "required": true, "schema": { "title": "Item Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RejectRequest" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalActionResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Reject Note", "tags": [ "review", "review-approval" ] } }, "/api/v1/review/approval/organization/{item_id}/approve": { "post": { "description": "Approve an organization (TIDY-15323 — generic approval surface).", "operationId": "approveOrganizationGeneric", "parameters": [ { "in": "path", "name": "item_id", "required": true, "schema": { "title": "Item Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalActionResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Approve Organization Generic", "tags": [ "review", "review-approval" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/review/approval/organization/{item_id}/reject": { "post": { "description": "Reject an organization (TIDY-15323 — generic approval surface).", "operationId": "rejectOrganizationGeneric", "parameters": [ { "in": "path", "name": "item_id", "required": true, "schema": { "title": "Item Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RejectRequest" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalActionResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Reject Organization Generic", "tags": [ "review", "review-approval" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/review/approval/pending": { "get": { "description": "List all primitives pending approval.\n\nGroups by date (today first, then older).\nIncludes source link info (email subject, sender).", "operationId": "listPendingApprovals", "parameters": [ { "description": "Filter by type: task, note, reminder, contact, calendar_event", "in": "query", "name": "type_filter", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by type: task, note, reminder, contact, calendar_event", "title": "Type Filter" } }, { "description": "Filter by date: today, older", "in": "query", "name": "date_filter", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by date: today, older", "title": "Date Filter" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "maximum": 200, "minimum": 1, "title": "Limit", "type": "integer" } }, { "in": "query", "name": "offset", "required": false, "schema": { "default": 0, "minimum": 0, "title": "Offset", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalListResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List Pending Approvals", "tags": [ "review", "review-pending" ] } }, "/api/v1/review/approval/rejected": { "get": { "description": "List all rejected primitives.\n\nReturns items with approval_status='rejected' across all primitive types.\nSupports filtering by type and searching by title.", "operationId": "getRejectedItems", "parameters": [ { "description": "Filter by primitive type", "in": "query", "name": "type_filter", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by primitive type", "title": "Type Filter" } }, { "description": "Search by title", "in": "query", "name": "search", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Search by title", "title": "Search" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "maximum": 200, "minimum": 1, "title": "Limit", "type": "integer" } }, { "in": "query", "name": "offset", "required": false, "schema": { "default": 0, "minimum": 0, "title": "Offset", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RejectedListResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Rejected Items", "tags": [ "review", "review-rejected" ] } }, "/api/v1/review/approval/reminder/{item_id}/approve": { "post": { "description": "Approve a reminder.", "operationId": "approveReminder", "parameters": [ { "in": "path", "name": "item_id", "required": true, "schema": { "title": "Item Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalActionResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Approve Reminder", "tags": [ "review", "review-approval" ] } }, "/api/v1/review/approval/reminder/{item_id}/reject": { "post": { "description": "Reject a reminder.", "operationId": "rejectReminder", "parameters": [ { "in": "path", "name": "item_id", "required": true, "schema": { "title": "Item Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RejectRequest" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalActionResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Reject Reminder", "tags": [ "review", "review-approval" ] } }, "/api/v1/review/approval/source/by-primitive/{primitive_type}/{primitive_id}": { "get": { "description": "Get source-email details for a specific extracted primitive.\n\nResolves the source via ``linked_references`` (TIDY-7539 / S7) instead\nof the deprecated ``<table>.source_id`` columns. The link is written by\nthe extraction writers at primitive-creation time (S6 / TIDY-7538).\nIf no link exists (manual primitive, or older primitive pending the\nS8 backfill), returns 404 — matching the previous behaviour for\nprimitives with NULL source_id.", "operationId": "getSourceByPrimitive", "parameters": [ { "in": "path", "name": "primitive_type", "required": true, "schema": { "title": "Primitive Type", "type": "string" } }, { "in": "path", "name": "primitive_id", "required": true, "schema": { "title": "Primitive Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SourceDetailResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Source By Primitive", "tags": [ "review", "review-source" ] } }, "/api/v1/review/approval/source/{trace_id}": { "get": { "description": "Get source details for a primitive by trace_id.\n\nReturns email/file details that generated the primitive.\nEnables \"View Source\" functionality in the approval UI.", "operationId": "getSourceDetails", "parameters": [ { "in": "path", "name": "trace_id", "required": true, "schema": { "title": "Trace Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SourceDetailResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Source Details", "tags": [ "review", "review-source" ] } }, "/api/v1/review/approval/task/{item_id}/approve": { "post": { "description": "Approve a task.", "operationId": "approveTask", "parameters": [ { "in": "path", "name": "item_id", "required": true, "schema": { "title": "Item Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalActionResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Approve Task", "tags": [ "review", "review-approval" ] } }, "/api/v1/review/approval/task/{item_id}/reject": { "post": { "description": "Reject a task.", "operationId": "rejectTask", "parameters": [ { "in": "path", "name": "item_id", "required": true, "schema": { "title": "Item Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RejectRequest" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalActionResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Reject Task", "tags": [ "review", "review-approval" ] } }, "/api/v1/review/approval/{primitive_type}/{item_id}": { "delete": { "description": "Permanently delete a rejected primitive.\n\nThis is a destructive action and cannot be undone.\nOnly works on items with rejected status.", "operationId": "deleteRejectedItem", "parameters": [ { "in": "path", "name": "primitive_type", "required": true, "schema": { "enum": [ "task", "note", "reminder", "contact", "calendar_event" ], "title": "Primitive Type", "type": "string" } }, { "in": "path", "name": "item_id", "required": true, "schema": { "title": "Item Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Deleterejecteditem", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Delete Rejected Item", "tags": [ "review", "review-rejected" ] } }, "/api/v1/review/approval/{primitive_type}/{item_id}/dismiss": { "post": { "description": "Record a per-user 'not now' marker for a pending row.\n\nDistinct from reject: the row STAYS pending_review (and out of\ncross-member sync); only the dismissing member's approvalUnit banner\nhides. Idempotent — one marker per member per entity.", "operationId": "dismissPendingPrimitive", "parameters": [ { "in": "path", "name": "primitive_type", "required": true, "schema": { "title": "Primitive Type", "type": "string" } }, { "in": "path", "name": "item_id", "required": true, "schema": { "title": "Item Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalDismissResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Dismiss Pending Primitive", "tags": [ "review", "review-approval" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/review/approval/{primitive_type}/{item_id}/restore": { "post": { "description": "Restore a rejected primitive to pending_review status.\n\nThe item will appear in the Approval feed again for re-evaluation.", "operationId": "restoreRejectedItem", "parameters": [ { "in": "path", "name": "primitive_type", "required": true, "schema": { "enum": [ "task", "note", "reminder", "contact", "calendar_event", "organization" ], "title": "Primitive Type", "type": "string" } }, { "in": "path", "name": "item_id", "required": true, "schema": { "title": "Item Id", "type": "string" } }, { "description": "Explicitly approve a rejected contact or organization in place", "in": "query", "name": "approve", "required": false, "schema": { "default": false, "description": "Explicitly approve a rejected contact or organization in place", "title": "Approve", "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestoreResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Restore Rejected Item", "tags": [ "review", "review-rejected" ] } }, "/api/v1/review/contact/{item_id}/approve": { "post": { "description": "Approve a contact (KCC-3223: promotes shadow/pending_review to promoted).", "operationId": "approveContact3", "parameters": [ { "description": "Typed ID with prefix 'C'", "in": "path", "name": "item_id", "required": true, "schema": { "description": "Typed ID with prefix 'C'", "title": "Item Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Approvecontact3", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Approve Contact", "tags": [ "review", "review-legacy" ] } }, "/api/v1/review/contact/{item_id}/reject": { "post": { "description": "Reject a contact (KCC-3223: sets visibility='rejected', can re-trigger later).", "operationId": "rejectContact3", "parameters": [ { "description": "Typed ID with prefix 'C'", "in": "path", "name": "item_id", "required": true, "schema": { "description": "Typed ID with prefix 'C'", "title": "Item Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Rejectcontact3", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Reject Contact", "tags": [ "review", "review-legacy" ] } }, "/api/v1/review/contacts/bulk": { "post": { "description": "Bulk approve or dismiss (TIDY-7557 / TIDY-7567).\n\nPer-item processing — one item's failure does not roll back others.\nEach child invocation gets its own span (review.contacts.{approve,dismiss})\nso dashboards see per-item duration even in bulk mode. Returns\nsucceeded ids + per-item errors.", "operationId": "bulkContactReview", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactBulkRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactBulkResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Bulk Contact Review", "tags": [ "review", "review-contacts" ] } }, "/api/v1/review/contacts/{contact_id}/approve": { "post": { "description": "Approve a contact with optional destination picker (TIDY-7557).\n\nDefault (no body, or body with kind='keep_private'): approve the\ncontact at its current owner_id/visibility. Other kinds:\n - share_to_container: insert linked_references row to the container\n - promote_global: set owner_type='account', visibility='shared'", "operationId": "approveContactWithDestination", "parameters": [ { "in": "path", "name": "contact_id", "required": true, "schema": { "title": "Contact Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/ContactApprovalRequest" }, { "type": "null" } ], "title": "Body" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactApprovalResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Approve Contact With Destination", "tags": [ "review", "review-contacts" ] } }, "/api/v1/review/contacts/{contact_id}/dismiss": { "post": { "description": "Dismiss a pending contact + remember the rejection (TIDY-7557).\n\nSets approval_status='rejected' on the contact and writes per-user\ndismissal-memory rows so the extractor (TIDY-7556) skips matching\nre-extractions for this owner.\n\nTIDY-8071: optional `thumb` body folds the negative extraction-quality\nsignal into the dismiss gesture (Contacts Inbox thumbs-down).", "operationId": "dismissContact", "parameters": [ { "in": "path", "name": "contact_id", "required": true, "schema": { "title": "Contact Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/ContactDismissRequest" }, { "type": "null" } ], "title": "Body" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactDismissResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Dismiss Contact", "tags": [ "review", "review-contacts" ] } }, "/api/v1/review/contacts/{contact_id}/undo-dismiss": { "post": { "description": "Reverse a dismiss (TIDY-7557 / TIDY-7567): contact returns to\npending_review and the dismissal-memory rows scoped to this contact\nare deleted.", "operationId": "undoDismissContact", "parameters": [ { "in": "path", "name": "contact_id", "required": true, "schema": { "title": "Contact Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactUndoDismissResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Undo Dismiss Contact", "tags": [ "review", "review-contacts" ] } }, "/api/v1/review/counts": { "get": { "description": "Get counts of items needing review by type.", "operationId": "getReviewCounts", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReviewCountsResponse" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Review Counts", "tags": [ "review", "review-legacy" ] } }, "/api/v1/review/event/{item_id}/approve": { "post": { "description": "Approve a calendar event.", "operationId": "approveEvent", "parameters": [ { "description": "Typed ID with prefix 'V'", "in": "path", "name": "item_id", "required": true, "schema": { "description": "Typed ID with prefix 'V'", "title": "Item Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Approveevent", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Approve Event", "tags": [ "review", "review-legacy" ] } }, "/api/v1/review/event/{item_id}/reject": { "post": { "description": "Reject a calendar event.\n\nPreserves the legacy guardrail: once an event is 'approved', it cannot\nbe rejected via this endpoint. (ReviewStatusWriter's IS DISTINCT FROM\nalready blocks re-rejects; we still need the approved-guard explicitly.)", "operationId": "rejectEvent", "parameters": [ { "description": "Typed ID with prefix 'V'", "in": "path", "name": "item_id", "required": true, "schema": { "description": "Typed ID with prefix 'V'", "title": "Item Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Rejectevent", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Reject Event", "tags": [ "review", "review-legacy" ] } }, "/api/v1/review/note/{item_id}/approve": { "post": { "description": "Approve a note.", "operationId": "approveNote3", "parameters": [ { "description": "Typed ID with prefix 'N'", "in": "path", "name": "item_id", "required": true, "schema": { "description": "Typed ID with prefix 'N'", "title": "Item Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Approvenote3", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Approve Note", "tags": [ "review", "review-legacy" ] } }, "/api/v1/review/note/{item_id}/reject": { "post": { "description": "Reject a note (sets approval_status='rejected' and soft-deletes).\n\nEvery note Reject soft-deletes (TIDY-19718, the writer's notes config).", "operationId": "rejectNote3", "parameters": [ { "description": "Typed ID with prefix 'N'", "in": "path", "name": "item_id", "required": true, "schema": { "description": "Typed ID with prefix 'N'", "title": "Item Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Rejectnote3", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Reject Note", "tags": [ "review", "review-legacy" ] } }, "/api/v1/review/organization/{item_id}/approve": { "post": { "description": "Approve an organization.", "operationId": "approveOrganization2", "parameters": [ { "description": "Typed ID with prefix 'O'", "in": "path", "name": "item_id", "required": true, "schema": { "description": "Typed ID with prefix 'O'", "title": "Item Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Approveorganization2", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Approve Organization", "tags": [ "review", "review-legacy" ] } }, "/api/v1/review/organization/{item_id}/reject": { "post": { "description": "Reject an organization while retaining its identity for dedup.", "operationId": "rejectOrganization2", "parameters": [ { "description": "Typed ID with prefix 'O'", "in": "path", "name": "item_id", "required": true, "schema": { "description": "Typed ID with prefix 'O'", "title": "Item Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Rejectorganization2", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Reject Organization", "tags": [ "review", "review-legacy" ] } }, "/api/v1/review/pending": { "get": { "description": "List all items requiring review across all types.", "operationId": "listPendingReviews", "parameters": [ { "description": "Filter by type: CalendarEvent, Task, Note, Contact, Organization", "in": "query", "name": "type_filter", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by type: CalendarEvent, Task, Note, Contact, Organization", "title": "Type Filter" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 100, "maximum": 500, "minimum": 1, "title": "Limit", "type": "integer" } }, { "in": "query", "name": "offset", "required": false, "schema": { "default": 0, "minimum": 0, "title": "Offset", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReviewListResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List Pending Reviews", "tags": [ "review", "review-legacy" ] } }, "/api/v1/review/task/{item_id}/approve": { "post": { "description": "Approve a task.", "operationId": "approveTask2", "parameters": [ { "description": "Typed ID with prefix 'A'", "in": "path", "name": "item_id", "required": true, "schema": { "description": "Typed ID with prefix 'A'", "title": "Item Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Approvetask2", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Approve Task", "tags": [ "review", "review-legacy" ] } }, "/api/v1/review/task/{item_id}/reject": { "post": { "description": "Reject (soft delete) a task.", "operationId": "rejectTask2", "parameters": [ { "description": "Typed ID with prefix 'A'", "in": "path", "name": "item_id", "required": true, "schema": { "description": "Typed ID with prefix 'A'", "title": "Item Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Rejecttask2", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Reject Task", "tags": [ "review", "review-legacy" ] } }, "/api/v1/sandbox": { "get": { "operationId": "getSandboxMeta", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxMetaResponse" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Sandbox", "tags": [ "sandbox", "sandbox" ] } }, "/api/v1/sandbox-elevations/{elevation_id}/allow": { "post": { "operationId": "allowSandboxElevation", "parameters": [ { "in": "path", "name": "elevation_id", "required": true, "schema": { "format": "uuid", "title": "Elevation Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxElevationAllow" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxElevation" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Allow an employee's sandbox request — once, in its project, or for the employee", "tags": [ "workshops" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "A person decides sandbox access in Tidy, never through a tool." } }, "/api/v1/sandbox-elevations/{elevation_id}/deny": { "post": { "operationId": "denySandboxElevation", "parameters": [ { "in": "path", "name": "elevation_id", "required": true, "schema": { "format": "uuid", "title": "Elevation Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxElevation" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Deny an employee's sandbox request", "tags": [ "workshops" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "A person decides sandbox access in Tidy, never through a tool." } }, "/api/v1/sandbox-elevations/{elevation_id}/revoke": { "post": { "operationId": "revokeSandboxElevation", "parameters": [ { "in": "path", "name": "elevation_id", "required": true, "schema": { "format": "uuid", "title": "Elevation Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxElevation" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Take a sandbox approval back and stop the containers it allowed", "tags": [ "workshops" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "A person decides sandbox access in Tidy, never through a tool." } }, "/api/v1/sandbox/reset": { "post": { "description": "Wipe + re-seed the caller's sandbox tenant. Idempotent.", "operationId": "resetSandbox", "responses": { "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxResetResponse" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Reset Sandbox", "tags": [ "sandbox", "sandbox" ] } }, "/api/v1/saved-messages": { "get": { "operationId": "listSavedMessages", "parameters": [ { "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "maximum": 100, "minimum": 1, "title": "Limit", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SavedMessagesPage" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List Saved Messages", "x-mcp-skip": true } }, "/api/v1/saved-searches": { "get": { "description": "List all saved searches for the current user, sorted by use count.", "operationId": "listSavedSearches", "parameters": [ { "in": "query", "name": "limit", "required": false, "schema": { "default": 20, "maximum": 100, "minimum": 1, "title": "Limit", "type": "integer" } }, { "in": "query", "name": "offset", "required": false, "schema": { "default": 0, "minimum": 0, "title": "Offset", "type": "integer" } }, { "description": "If set, only return saved searches with this scope.", "in": "query", "name": "scope", "required": false, "schema": { "anyOf": [ { "enum": [ "global", "chat", "notes", "mail", "tasks", "podcast" ], "type": "string" }, { "type": "null" } ], "description": "If set, only return saved searches with this scope.", "title": "Scope" } }, { "description": "If set, only return saved searches scoped to this room (matches room_id_filter exactly).", "in": "query", "name": "room_id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "If set, only return saved searches scoped to this room (matches room_id_filter exactly).", "title": "Room Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SavedSearchListResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List saved searches", "tags": [ "saved-searches", "Saved Searches" ] }, "post": { "description": "Save a search query for quick access.", "operationId": "createSavedSearch", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SavedSearchCreate" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SavedSearchResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Create saved search", "tags": [ "saved-searches", "Saved Searches" ] } }, "/api/v1/saved-searches/{search_id}": { "delete": { "description": "Delete a saved search.", "operationId": "deleteSavedSearch", "parameters": [ { "in": "path", "name": "search_id", "required": true, "schema": { "format": "uuid", "title": "Search Id", "type": "string" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Delete saved search", "tags": [ "saved-searches", "Saved Searches" ] }, "patch": { "description": "Update a saved search's name, query, or description.", "operationId": "updateSavedSearch", "parameters": [ { "in": "path", "name": "search_id", "required": true, "schema": { "format": "uuid", "title": "Search Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SavedSearchUpdate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SavedSearchResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Update saved search", "tags": [ "saved-searches", "Saved Searches" ] } }, "/api/v1/saved-searches/{search_id}/use": { "post": { "description": "Increment use count and update last_used_at timestamp.", "operationId": "recordSearchUsage", "parameters": [ { "in": "path", "name": "search_id", "required": true, "schema": { "format": "uuid", "title": "Search Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SavedSearchResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Record search usage", "tags": [ "saved-searches", "Saved Searches" ] } }, "/api/v1/saved-views": { "get": { "description": "Return saved views for a tenant. Optional filters:\n- `facet_slug`: narrow to one facet\n- `entity_type`: narrow to a discriminator (e.g. 'calendar' for\n multi-facet calendar custom views — TIDY-7564)", "operationId": "listSavedViews", "parameters": [ { "in": "query", "name": "facet_slug", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Facet Slug" } }, { "in": "query", "name": "entity_type", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Entity Type" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "additionalProperties": true, "type": "object" }, "title": "Response Listsavedviews", "type": "array" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List saved views for a facet", "tags": [ "saved-views" ] }, "post": { "description": "Create or upsert a saved view (idempotent on `id`).\n\nWhen `id` is provided (PowerSync CRUD upload path), an UPSERT runs so\na retry after a lost ACK doesn't insert a duplicate. When `id` is\nomitted (REST clients), a fresh UUID is generated by the table default.", "operationId": "createSavedView", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSavedViewRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Createsavedview", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Create a saved view", "tags": [ "saved-views" ] } }, "/api/v1/saved-views/{view_id}": { "delete": { "description": "Delete a saved view.", "operationId": "deleteSavedView", "parameters": [ { "in": "path", "name": "view_id", "required": true, "schema": { "title": "View Id", "type": "string" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Delete a saved view", "tags": [ "saved-views" ] }, "put": { "description": "Update an existing saved view (partial fields). Bound to both PUT and\nPATCH so PowerSync's CRUD upload — which issues PATCH for UPDATEs —\ncan persist edits without a method-not-allowed (TIDY-7564).", "operationId": "updateSavedView", "parameters": [ { "in": "path", "name": "view_id", "required": true, "schema": { "title": "View Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSavedViewRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Updatesavedview", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Update a saved view", "tags": [ "saved-views" ] } }, "/api/v1/saved-views/{view_id}/move": { "post": { "operationId": "moveSavedView", "parameters": [ { "in": "path", "name": "view_id", "required": true, "schema": { "title": "View Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MoveRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MoveResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Re-allocate container_seq for a saved view (personal scope only)", "tags": [ "move" ] } }, "/api/v1/scheduled-jobs": { "post": { "operationId": "create_scheduled_job_api_v1_scheduled_jobs_post", "parameters": [ { "in": "header", "name": "X-Tidy-Acting-Principal", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tidy-Acting-Principal" } }, { "in": "header", "name": "X-Internal-Service", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service" } }, { "in": "header", "name": "X-Internal-Service-Key", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service-Key" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScheduledJobCreate" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScheduledJobCreated" } } }, "description": "Successful Response" }, "410": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrowserRunsRetiredProblem" } } }, "description": "Gone" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Create Scheduled Job", "tags": [ "activities" ], "x-local-capability": "cloud" } }, "/api/v1/scheduled-jobs/{job_id}/consent": { "post": { "description": "Accept or decline deliveries from a job someone else pointed at you.\n\nOnly the recipient may answer, and only once the job actually named them —\nthe ``consent_recipient_account_id`` on the facet IS the authorization, so\nthere is no separate grant to keep in step with it.\n\nA decline pauses DELIVERY, not the job: its fires keep happening and keep\nbeing logged as `skipped: consent`, so accepting later resumes a duty that\nwas still running rather than resurrecting a dead one.", "operationId": "record_scheduled_job_consent_api_v1_scheduled_jobs__job_id__consent_post", "parameters": [ { "description": "Typed ID with prefix 'A'", "in": "path", "name": "job_id", "required": true, "schema": { "description": "Typed ID with prefix 'A'", "title": "Job Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConsentDecisionBody" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConsentRecorded" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Record Scheduled Job Consent", "tags": [ "activities" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Recipient's own consent decision — an assistant must never answer a delivery-consent prompt on the user's behalf." } }, "/api/v1/scheduled-jobs/{job_id}/run": { "post": { "description": "Run one piece of scheduled work immediately (TIDY-17346 / D10).\n\nManual is the ONLY non-schedule trigger scheduled work has — jobs gain no\nevent triggers (D10). The run itself rides the machinery a scheduled fire\nalready uses: the box claims the `scheduled_job_fires` slot, checks consent\nand its turn budget, and records the fire as `manual`. Nothing here is a\nsecond fire path.\n\nAuthorization is the caller's own member-visible predicate on the job item,\nthe canonical helper and not a hand-rolled ownership check.", "operationId": "run_scheduled_job_now_api_v1_scheduled_jobs__job_id__run_post", "parameters": [ { "description": "Typed ID with prefix 'A'", "in": "path", "name": "job_id", "required": true, "schema": { "description": "Typed ID with prefix 'A'", "title": "Job Id", "type": "string" } } ], "responses": { "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunRequested" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Run Scheduled Job Now", "tags": [ "activities" ], "x-local-capability": "cloud" } }, "/api/v1/scm-objects/search": { "get": { "description": "THE one search surface (D12): the federated-search lane, the\n``repo_object_search`` MCP tool, and any future surface call ONE query\nservice, which owns the project-visibility gate (D5).\n\nA text query matches titles, author and repository full text and natural\nkeys (a SHA prefix, a PR number, a path) in one Postgres query with every\nfilter, the tombstone exclusion and the project gate. With no text, the\nsame query answers deterministic questions (\"what changed in src/ in\nJuly?\"). A database outage answers 503 verbatim — never an empty success\nthat would read as \"nothing matches\" (D13/R7).", "operationId": "searchScmObjects", "parameters": [ { "in": "query", "name": "q", "required": false, "schema": { "default": "", "maxLength": 200, "title": "Q", "type": "string" } }, { "in": "query", "name": "kind", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Kind" } }, { "in": "query", "name": "state", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "State" } }, { "in": "query", "name": "author", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Author" } }, { "in": "query", "name": "repo", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Repo" } }, { "in": "query", "name": "since", "required": false, "schema": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Since" } }, { "in": "query", "name": "until", "required": false, "schema": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Until" } }, { "in": "query", "name": "path", "required": false, "schema": { "anyOf": [ { "maxLength": 500, "type": "string" }, { "type": "null" } ], "title": "Path" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 20, "maximum": 50, "minimum": 1, "title": "Limit", "type": "integer" } }, { "description": "Typed ID with prefix 'P' (or bare UUID during deprecation)", "in": "query", "name": "project_id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Typed ID with prefix 'P' (or bare UUID during deprecation)", "title": "Project Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScmObjectSearchResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Search the SCM-object index across the caller's visible projects", "tags": [ "scm-objects" ], "x-local-capability": "cloud" } }, "/api/v1/scm-objects/{scm_object_id}": { "get": { "operationId": "getScmObject", "parameters": [ { "description": "Typed ID with prefix 'S'", "in": "path", "name": "scm_object_id", "required": true, "schema": { "description": "Typed ID with prefix 'S'", "title": "Scm Object Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScmObjectResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Read one SCM object's indexed metadata and its native URL", "tags": [ "scm-objects" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/scm-objects/{scm_object_id}/content": { "get": { "description": "Live provider content (R5): nothing stored, everything fetched per call\nwith a repo-scoped token minted INSIDE the fetch (D7) — the token never\nappears in this response and is never logged. Oversized content is capped\nwith an honest ``truncated`` flag. Provider errors reach the caller\nverbatim — there is no cached-copy fallback (a stale copy would read as\nthe truth about the repository, which R5 forbids).", "operationId": "fetchScmObjectContent", "parameters": [ { "description": "Typed ID with prefix 'S'", "in": "path", "name": "scm_object_id", "required": true, "schema": { "description": "Typed ID with prefix 'S'", "title": "Scm Object Id", "type": "string" } }, { "description": "Byte cap for the returned content; excess is flagged via truncated.", "in": "query", "name": "max_bytes", "required": false, "schema": { "default": 262144, "description": "Byte cap for the returned content; excess is flagged via truncated.", "maximum": 4194304, "minimum": 1024, "title": "Max Bytes", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScmObjectContentResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Fetch one SCM object's live content from its provider", "tags": [ "scm-objects" ], "x-local-capability": "cloud" } }, "/api/v1/scm-objects/{scm_object_id}/diff": { "get": { "description": "The object's changes in the diff model both clients already render.\n\nTIDY-17350 (S11): a work item's commit chip is clickable INTO Tidy, on web\nand on Android, and both surfaces decode this one shape — the same\n``NormalizedDiff`` the VE read-RPC produces. The parse and the secret\nredaction happen HERE, once: a client-side lane would be a rule that only\nholds on the client that implemented it.\n\nVisibility is the SCM read gate (D5) — not-found and not-visible answer\nidentically. Provider verdicts reach the caller verbatim (R5); an object\nkind with no diff (an issue) is a named 409, never an empty diff.", "operationId": "fetchScmObjectDiff", "parameters": [ { "description": "Typed ID with prefix 'S'", "in": "path", "name": "scm_object_id", "required": true, "schema": { "description": "Typed ID with prefix 'S'", "title": "Scm Object Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScmObjectDiffResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Fetch one SCM object's changes as a normalized, redacted diff", "tags": [ "scm-objects" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/scm-objects/{scm_object_id}/go": { "get": { "operationId": "resolveScmObjectUrl", "parameters": [ { "description": "Typed ID with prefix 'S'", "in": "path", "name": "scm_object_id", "required": true, "schema": { "description": "Typed ID with prefix 'S'", "title": "Scm Object Id", "type": "string" } } ], "responses": { "302": { "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Redirect to the SCM object's native provider URL", "tags": [ "scm-objects" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/screening/senders": { "get": { "description": "List senders with optional status filter, pagination, and sorting.", "operationId": "listSenders", "parameters": [ { "in": "query", "name": "status", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Status" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "maximum": 200, "minimum": 1, "title": "Limit", "type": "integer" } }, { "in": "query", "name": "offset", "required": false, "schema": { "default": 0, "minimum": 0, "title": "Offset", "type": "integer" } }, { "in": "query", "name": "sort_by", "required": false, "schema": { "default": "last_seen_at", "pattern": "^(email_count|last_seen_at|screened_at)$", "title": "Sort By", "type": "string" } }, { "in": "header", "name": "X-Trace-Id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SenderListResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List Senders", "tags": [ "screening" ] } }, "/api/v1/screening/senders/decide": { "post": { "description": "Apply an approve / allow-once / block / unblock decision keyed by sender address.\n\nTIDY-13573: the Defense Replay hover card acts on avatars whose sender has no\nsender_screening row — the provider-spam short-circuit settles those emails\nbefore the bouncer's sender gate inserts a pending row. This endpoint upserts\nthe row (creating it as pending when absent) and then runs the SAME decision\ncore as the id-keyed approve / allow-once / block endpoints, so the outcome is\nbyte-equivalent regardless of whether the sender already had a queue row.", "operationId": "decideScreeningSender", "parameters": [ { "in": "header", "name": "X-Trace-Id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DecideSenderRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DecideSenderResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Decide Screening Sender", "tags": [ "screening" ] } }, "/api/v1/screening/senders/{sender_id}": { "patch": { "description": "Update a sender's forced category by writing the unified defense rule.\n\nTIDY-13030 (S10): the legacy per-sender override columns were dropped. A\nforced-category edit is now persisted solely as a Sentinel rule in the\nunified engine (the bouncer's only source of truth); the legacy per-sender\nrouting override was fully retired (no reader remained).", "operationId": "updateSenderRule", "parameters": [ { "in": "path", "name": "sender_id", "required": true, "schema": { "format": "uuid", "title": "Sender Id", "type": "string" } }, { "in": "header", "name": "X-Trace-Id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SenderRuleUpdate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SenderRuleResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Update Sender Rule", "tags": [ "screening" ] } }, "/api/v1/screening/senders/{sender_id}/allow-once": { "post": { "description": "Approve current emails from a sender without approving the sender for future emails.", "operationId": "allowOnceSender", "parameters": [ { "in": "path", "name": "sender_id", "required": true, "schema": { "format": "uuid", "title": "Sender Id", "type": "string" } }, { "in": "header", "name": "X-Trace-Id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/ApproveSenderRequest" }, { "type": "null" } ], "title": "Body" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AllowOnceResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Allow Once Sender", "tags": [ "screening" ] } }, "/api/v1/screening/senders/{sender_id}/approve": { "post": { "description": "Approve a sender and route their existing emails to inbox splits.", "operationId": "approveSender", "parameters": [ { "in": "path", "name": "sender_id", "required": true, "schema": { "format": "uuid", "title": "Sender Id", "type": "string" } }, { "in": "header", "name": "X-Trace-Id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/ApproveSenderRequest" }, { "type": "null" } ], "title": "Body" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApproveResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Approve Sender", "tags": [ "screening" ] } }, "/api/v1/screening/senders/{sender_id}/block": { "post": { "description": "Block a sender (by address or domain).", "operationId": "blockSender", "parameters": [ { "in": "path", "name": "sender_id", "required": true, "schema": { "format": "uuid", "title": "Sender Id", "type": "string" } }, { "in": "header", "name": "X-Trace-Id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BlockRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BlockResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Block Sender", "tags": [ "screening" ] } }, "/api/v1/screening/senders/{sender_id}/preview": { "get": { "description": "Fetch body preview content for one sender on demand.", "operationId": "getSenderPreview", "parameters": [ { "in": "path", "name": "sender_id", "required": true, "schema": { "format": "uuid", "title": "Sender Id", "type": "string" } }, { "in": "header", "name": "X-Trace-Id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SenderPreviewResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Sender Preview", "tags": [ "screening" ] } }, "/api/v1/screening/senders/{sender_id}/unblock": { "post": { "description": "Unblock a previously blocked sender. Restores their emails to approved status.", "operationId": "unblockSender", "parameters": [ { "in": "path", "name": "sender_id", "required": true, "schema": { "format": "uuid", "title": "Sender Id", "type": "string" } }, { "in": "header", "name": "X-Trace-Id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnblockResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Unblock Sender", "tags": [ "screening" ] } }, "/api/v1/screening/stats": { "get": { "description": "Get screening status counts for the current tenant.", "operationId": "getScreeningStats", "parameters": [ { "in": "header", "name": "X-Trace-Id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScreeningStatsResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Screening Stats", "tags": [ "screening" ] } }, "/api/v1/search": { "get": { "operationId": "globalChatSearch", "parameters": [ { "description": "Search query", "in": "query", "name": "q", "required": true, "schema": { "description": "Search query", "maxLength": 1000, "minLength": 1, "title": "Q", "type": "string" } }, { "description": "Search scope. chat = chat-only; global = all sources (chat first).", "in": "query", "name": "scope", "required": false, "schema": { "default": "chat", "description": "Search scope. chat = chat-only; global = all sources (chat first).", "enum": [ "global", "chat", "notes", "mail", "tasks" ], "title": "Scope", "type": "string" } }, { "description": "Sender filter — name / matrix id / email.", "in": "query", "name": "from", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Sender filter — name / matrix id / email.", "title": "From" } }, { "description": "Room filter — channel name or room_id.", "in": "query", "name": "in", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Room filter — channel name or room_id.", "title": "In" } }, { "description": "Convenience alias for `in` (no aliasing collision).", "in": "query", "name": "room", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Convenience alias for `in` (no aliasing collision).", "title": "Room" } }, { "description": "Convenience alias for `from`.", "in": "query", "name": "from_user", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Convenience alias for `from`.", "title": "From User" } }, { "in": "query", "name": "before", "required": false, "schema": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Before" } }, { "in": "query", "name": "after", "required": false, "schema": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "After" } }, { "in": "query", "name": "has", "required": false, "schema": { "items": { "enum": [ "embed", "attachment" ], "type": "string" }, "title": "Has", "type": "array" } }, { "in": "query", "name": "type", "required": false, "schema": { "items": { "enum": [ "message", "file", "embed", "person", "channel" ], "type": "string" }, "title": "Type", "type": "array" } }, { "description": "Reference saved-search row (S5).", "in": "query", "name": "saved_search_id", "required": false, "schema": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "description": "Reference saved-search row (S5).", "title": "Saved Search Id" } }, { "in": "query", "name": "has_embed", "required": false, "schema": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Has Embed" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 20, "maximum": 100, "minimum": 1, "title": "Limit", "type": "integer" } }, { "in": "query", "name": "offset", "required": false, "schema": { "default": 0, "minimum": 0, "title": "Offset", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GlobalSearchResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Hybrid chat search across BM25 + semantic, grouped by result type", "tags": [ "search", "search" ] } }, "/api/v1/search/click": { "post": { "operationId": "recordSearchClick", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClickRequest" } } }, "required": true }, "responses": { "204": { "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Record a click on a chat search result", "tags": [ "search", "search" ] } }, "/api/v1/search/federated": { "post": { "operationId": "federatedSearch", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FederatedSearchRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FederatedSearchResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Cross-account federated search", "tags": [ "federated-search" ] } }, "/api/v1/search/relationships/{entity_uuid}": { "get": { "description": "Authenticated proxy to memory-service's internal /api/v1/memory/relationships/{entity_uuid}. Resolves tenant + user from the JWT and forwards with X-Internal-Service headers.", "operationId": "entityRelationships", "parameters": [ { "in": "path", "name": "entity_uuid", "required": true, "schema": { "title": "Entity Uuid", "type": "string" } }, { "in": "query", "name": "depth", "required": false, "schema": { "default": 2, "maximum": 3, "minimum": 1, "title": "Depth", "type": "integer" } }, { "description": "Include the MENTIONS/co-mention provenance + document reference bulk. Off by default — semantic-first view (TIDY-13601 S7).", "in": "query", "name": "include_provenance", "required": false, "schema": { "default": false, "description": "Include the MENTIONS/co-mention provenance + document reference bulk. Off by default — semantic-first view (TIDY-13601 S7).", "title": "Include Provenance", "type": "boolean" } }, { "in": "query", "name": "co_occurrence_limit", "required": false, "schema": { "default": 15, "maximum": 150, "minimum": 0, "title": "Co Occurrence Limit", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "title": "Response Entityrelationships" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Entity relationship graph", "tags": [ "search", "search" ] } }, "/api/v1/search/unified": { "post": { "description": "Merges memory-service federated search (vector + graph + BM25) with api-service FTS (notes, news, contacts, activities, events, emails) and an explicit email canonical fallback. Resolves note titles from Postgres for hits whose `pg_id` maps to the notes table. Tenant isolation is enforced from the authenticated JWT — any `tenant_id` in the request body is ignored.", "operationId": "unifiedSearch", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnifiedSearchRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnifiedSearchResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Unified cross-domain search", "tags": [ "search", "search" ] } }, "/api/v1/secret-file-proposals": { "post": { "operationId": "proposeSecretFile", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretFileProposalCreate" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretFileProposalResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Ask your owner to save a secret file you will upload from a file, never from chat — or to deploy one of their existing secret files, unchanged, to your workshop", "tags": [ "secret-files" ], "x-local-capability": "cloud" } }, "/api/v1/secret-file-proposals/{proposal_id}": { "get": { "operationId": "getSecretFileProposal", "parameters": [ { "in": "path", "name": "proposal_id", "required": true, "schema": { "format": "uuid", "title": "Proposal Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretFileProposalResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Where a secret file you proposed stands — by name, never by value", "tags": [ "secret-files" ], "x-local-capability": "cloud" } }, "/api/v1/secret-file-proposals/{proposal_id}/approve": { "post": { "operationId": "approveSecretFileProposal", "parameters": [ { "in": "path", "name": "proposal_id", "required": true, "schema": { "format": "uuid", "title": "Proposal Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretFileProposalResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Save a proposed secret file as yours, and deploy it if it asked, after a fresh sign-in", "tags": [ "secret-files" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "The owner decides a proposed secret file in Tidy, never through a tool." } }, "/api/v1/secret-file-proposals/{proposal_id}/content": { "put": { "operationId": "uploadSecretFileProposal", "parameters": [ { "in": "path", "name": "proposal_id", "required": true, "schema": { "format": "uuid", "title": "Proposal Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretFileProposalResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Send a proposed secret file's bytes, once, with its upload token", "tags": [ "secret-files" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "The agent's shell sends the file here; through a tool call its bytes would enter the model's context." } }, "/api/v1/secret-file-proposals/{proposal_id}/decline": { "post": { "operationId": "declineSecretFileProposal", "parameters": [ { "in": "path", "name": "proposal_id", "required": true, "schema": { "format": "uuid", "title": "Proposal Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretFileProposalResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Decline a proposed secret file; its upload is deleted", "tags": [ "secret-files" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "The owner decides a proposed secret file in Tidy, never through a tool." } }, "/api/v1/secret-files": { "post": { "operationId": "createSecretFile", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretFileCreate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretFileResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Create a secret file, optionally with its first contents", "tags": [ "secret-files" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "A secret file's values are custody, not context: employees receive them by deploy or lend (TIDY-19604 F2/F4), never through a tool call." } }, "/api/v1/secret-files/{file_id}/check": { "post": { "operationId": "checkSecretFileTargets", "parameters": [ { "in": "path", "name": "file_id", "required": true, "schema": { "title": "File Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretFileTargetSelection" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretFileTargetsResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Compare each target's file on its workshop with the saved file, by hash", "tags": [ "secret-files" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "A secret file's values are custody, not context: employees receive them by deploy or lend (TIDY-19604 F2/F4), never through a tool call." } }, "/api/v1/secret-files/{file_id}/content": { "put": { "operationId": "saveSecretFile", "parameters": [ { "in": "path", "name": "file_id", "required": true, "schema": { "title": "File Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretFileSave" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretFileResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Write a new version of a secret file (replace, merge a paste, or set keys)", "tags": [ "secret-files" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "A secret file's values are custody, not context: employees receive them by deploy or lend (TIDY-19604 F2/F4), never through a tool call." } }, "/api/v1/secret-files/{file_id}/deploy": { "post": { "operationId": "deploySecretFile", "parameters": [ { "in": "path", "name": "file_id", "required": true, "schema": { "title": "File Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretFileTargetSelection" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretFileTargetsResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Write a secret file to its workshop targets after a fresh sign-in (audited)", "tags": [ "secret-files" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "A secret file's values are custody, not context: employees receive them by deploy or lend (TIDY-19604 F2/F4), never through a tool call." } }, "/api/v1/secret-files/{file_id}/lends": { "get": { "operationId": "listSecretFileLends", "parameters": [ { "in": "path", "name": "file_id", "required": true, "schema": { "title": "File Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretFileLendsResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "The virtual employees a secret file is lent to", "tags": [ "secret-files" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "A secret file's values are custody, not context: employees receive them by deploy or lend (TIDY-19604 F2/F4), never through a tool call." }, "post": { "operationId": "lendSecretFile", "parameters": [ { "in": "path", "name": "file_id", "required": true, "schema": { "title": "File Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretFileLendCreate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretFileLendsResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Lend every key of a dotenv secret file to a virtual employee as per-turn env", "tags": [ "secret-files" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "A secret file's values are custody, not context: employees receive them by deploy or lend (TIDY-19604 F2/F4), never through a tool call." } }, "/api/v1/secret-files/{file_id}/lends/{grant_id}": { "delete": { "operationId": "revokeSecretFileLend", "parameters": [ { "in": "path", "name": "file_id", "required": true, "schema": { "title": "File Id", "type": "string" } }, { "in": "path", "name": "grant_id", "required": true, "schema": { "title": "Grant Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretFileLendsResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Stop lending a secret file to a virtual employee (from its next turn)", "tags": [ "secret-files" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "A secret file's values are custody, not context: employees receive them by deploy or lend (TIDY-19604 F2/F4), never through a tool call." } }, "/api/v1/secret-files/{file_id}/reveal": { "post": { "operationId": "revealSecretFile", "parameters": [ { "in": "path", "name": "file_id", "required": true, "schema": { "title": "File Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretFileRevealResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Reveal a secret file's values after a fresh sign-in (audited)", "tags": [ "secret-files" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "A secret file's values are custody, not context: employees receive them by deploy or lend (TIDY-19604 F2/F4), never through a tool call." } }, "/api/v1/secret-files/{file_id}/targets": { "post": { "operationId": "addSecretFileTarget", "parameters": [ { "in": "path", "name": "file_id", "required": true, "schema": { "title": "File Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretFileTargetCreate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretFileTargetsResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Add a workshop location a secret file is deployed to", "tags": [ "secret-files" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "A secret file's values are custody, not context: employees receive them by deploy or lend (TIDY-19604 F2/F4), never through a tool call." } }, "/api/v1/secret-files/{file_id}/targets/{target_id}": { "delete": { "operationId": "removeSecretFileTarget", "parameters": [ { "in": "path", "name": "file_id", "required": true, "schema": { "title": "File Id", "type": "string" } }, { "in": "path", "name": "target_id", "required": true, "schema": { "title": "Target Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretFileTargetsResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Stop deploying a secret file to a location (the file on the workshop stays)", "tags": [ "secret-files" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "A secret file's values are custody, not context: employees receive them by deploy or lend (TIDY-19604 F2/F4), never through a tool call." } }, "/api/v1/security/access-history": { "get": { "description": "View audit trail of data access for the current tenant (owner only).\n\n Shows:\n - Sign in/out events\n - Data access events\n - Support access events\n - Admin actions\n\n Related: 011-auth-user-onboarding T106", "operationId": "getAccessHistory", "parameters": [ { "in": "query", "name": "action", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Action" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "maximum": 200, "minimum": 1, "title": "Limit", "type": "integer" } }, { "in": "query", "name": "offset", "required": false, "schema": { "default": 0, "minimum": 0, "title": "Offset", "type": "integer" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccessHistoryResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "View access history", "tags": [ "security" ] } }, "/api/v1/security/support-access": { "get": { "description": "List all support access overrides for the current tenant (owner only).\n\n Includes active, expired, and revoked overrides.\n\n Related: 011-auth-user-onboarding T093", "operationId": "listSupportOverrides", "parameters": [ { "in": "query", "name": "status", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Status" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "maximum": 100, "minimum": 1, "title": "Limit", "type": "integer" } }, { "in": "query", "name": "offset", "required": false, "schema": { "default": 0, "minimum": 0, "title": "Offset", "type": "integer" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SupportOverridesListResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List support access overrides", "tags": [ "security" ] }, "post": { "description": "Grant time-limited support access to your tenant (owner only).\n\n Creates a support override that allows admins to access tenant data\n for the specified duration. All access is logged.\n\n Duration: 15-480 minutes (default: 60 minutes / 1 hour)\n Auto-expires: Yes, based on duration\n\n Related: 011-auth-user-onboarding T092, T095", "operationId": "createSupportOverride", "parameters": [ { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SupportOverrideCreate" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SupportOverrideResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Grant support access", "tags": [ "security" ] } }, "/api/v1/security/support-access/{override_id}": { "delete": { "description": "Revoke an active support access override (owner only).\n\n Once revoked, support can no longer access tenant data.\n\n Related: 011-auth-user-onboarding T094", "operationId": "revokeSupportOverride", "parameters": [ { "in": "path", "name": "override_id", "required": true, "schema": { "title": "Override Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Revoke support access", "tags": [ "security" ] } }, "/api/v1/selection-handles": { "post": { "description": "Locate the captured span in authoritative state and sign it.", "operationId": "mintSelectionHandle", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SelectionHandleRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SelectionHandleResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Mint a signed, short-lived Process Selection handle", "tags": [ "primitives" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Editor capture action: the caller must supply the covered block ids of a live selection. Agents receive a handle through the assistant seed, or locate by blockId/unique span." } }, "/api/v1/sender-logos/resolve": { "post": { "operationId": "resolveSenderLogo", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SenderLogoResolveRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SenderLogoResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Resolve Sender Logo", "tags": [ "sender-logos" ], "x-mcp-skip": true } }, "/api/v1/sender-logos/{domain}": { "get": { "operationId": "getSenderLogo", "parameters": [ { "in": "path", "name": "domain", "required": true, "schema": { "title": "Domain", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SenderLogoResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Sender Logo", "tags": [ "sender-logos" ], "x-mcp-skip": true } }, "/api/v1/sending-domains": { "get": { "operationId": "listSendingDomains", "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/SendingDomainResponse" }, "title": "Response Listsendingdomains", "type": "array" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List Sending Domains", "tags": [ "sending-domains" ], "x-local-capability": "cloud", "x-mcp-skip": true }, "post": { "description": "Provision the provider identity and return the exact DNS to add.", "operationId": "createSendingDomain", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendingDomainCreate" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendingDomainResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Create Sending Domain", "tags": [ "sending-domains" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/sending-domains/{domain_id}": { "delete": { "operationId": "deleteSendingDomain", "parameters": [ { "in": "path", "name": "domain_id", "required": true, "schema": { "title": "Domain Id", "type": "string" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Delete Sending Domain", "tags": [ "sending-domains" ], "x-local-capability": "cloud", "x-mcp-skip": true }, "get": { "operationId": "getSendingDomain", "parameters": [ { "in": "path", "name": "domain_id", "required": true, "schema": { "title": "Domain Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendingDomainResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Sending Domain", "tags": [ "sending-domains" ], "x-local-capability": "cloud", "x-mcp-skip": true }, "patch": { "operationId": "updateSendingDomain", "parameters": [ { "in": "path", "name": "domain_id", "required": true, "schema": { "title": "Domain Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendingDomainUpdate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendingDomainResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Update Sending Domain", "tags": [ "sending-domains" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/sending-domains/{domain_id}/check": { "post": { "description": "On-demand poll: provider status + live DNS, persisted per record.", "operationId": "checkSendingDomain", "parameters": [ { "in": "path", "name": "domain_id", "required": true, "schema": { "title": "Domain Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendingDomainResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Check Sending Domain", "tags": [ "sending-domains" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/sending-identities": { "get": { "description": "The ONLY from-identity picker source (R23/D7): verified domains only.\n\nThe parameter exists for contract clarity — an unverified domain is never\nan identity, so verified=false returns the same verified-only set.", "operationId": "listSendingIdentities", "parameters": [ { "in": "query", "name": "verified", "required": false, "schema": { "default": true, "title": "Verified", "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/SendingIdentity" }, "title": "Response Listsendingidentities", "type": "array" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List Sending Identities", "tags": [ "sending-domains" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/service-usage/me/web-search": { "get": { "description": "Return current-period web-search usage for the calling user.\n\nCredit-governed (TIDY-12057): `limit`/`remaining` are always None — the\nvalue is a usage total for display; the shared credit pool governs spend.", "operationId": "getMyWebSearchUsage", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebSearchMeSummary" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get My Web Search Usage", "tags": [ "service-usage" ] } }, "/api/v1/service-usage/me/workshop-app-relay": { "get": { "description": "Bytes of your workshop apps Tidy's relay carried today (UTC), both\nways. Counted for the calling viewer only, never capped or charged in credits.", "operationId": "getMyWorkshopAppRelayUsage", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkshopAppRelayUsageSummary" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get My Workshop App Relay Usage", "tags": [ "service-usage" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/service-usage/me/workshop-relay": { "get": { "description": "Bytes Tidy relayed between this workspace's workshops today (UTC),\nagainst the daily allowance. Past it, a relayed transfer pauses until the\nnext UTC day or a raise. Never charged in credits.", "operationId": "getMyWorkshopRelayUsage", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkshopRelayUsageSummary" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get My Workshop Relay Usage", "tags": [ "service-usage" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/settings/public": { "get": { "description": "Return public settings (no auth required). Cached for 60s.", "operationId": "getPublicSettings", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Getpublicsettings", "type": "object" } } }, "description": "Successful Response" } }, "summary": "Get Public Settings", "tags": [ "growth" ] } }, "/api/v1/signals": { "post": { "description": "Append a batch of behavior signals to ``evidence_events``.\n\nIdempotent dedup via ``(tenant_id, client_id, client_event_id)``. Per-event\nerror tolerance — one bad event is logged and dropped, the rest still land.\n``source_actor='user'`` and ``source_user_id`` are server-stamped.", "operationId": "postSignals", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignalBatch" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignalBatchResult" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Post Signals", "tags": [ "signals", "signals" ], "x-mcp-skip": true, "x-mcp-skip-reason": "Fire-and-forget behavior-signal telemetry uploaded by the client outbox flusher; not an agent-facing tool." } }, "/api/v1/signature-requests": { "get": { "operationId": "listSignatureRequests", "parameters": [ { "in": "query", "name": "document_note_id", "required": true, "schema": { "title": "Document Note Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/SignatureRequestResponse" }, "title": "Response Listsignaturerequests", "type": "array" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List signature requests for a document", "tags": [ "e-signature" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "E-signature is a human-confirmed action (facet action / signing page) and a workflow gate — not an ambient agent tool. The assistant may draft signable documents (R38) but never creates a signature request itself." }, "post": { "operationId": "createSignatureRequest", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSignatureRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSignatureRequestResult" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Create and host a document for signing", "tags": [ "e-signature" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "E-signature is a human-confirmed action (facet action / signing page) and a workflow gate — not an ambient agent tool. The assistant may draft signable documents (R38) but never creates a signature request itself." } }, "/api/v1/signature-requests/gate": { "get": { "description": "Return whether a document's signed-state gate passes. Fail closed.\n\nA workflow script calls this to gate on signed-state (e.g. an inspection\ncannot start until its pre-inspection agreement is signed). Anything but a\nsigned document — or any error — blocks.", "operationId": "checkSignatureGate", "parameters": [ { "in": "query", "name": "document_note_id", "required": true, "schema": { "title": "Document Note Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignGateResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Fail-closed signed-state gate for a document", "tags": [ "e-signature" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "E-signature is a human-confirmed action (facet action / signing page) and a workflow gate — not an ambient agent tool. The assistant may draft signable documents (R38) but never creates a signature request itself." } }, "/api/v1/signature-requests/{request_id}": { "get": { "operationId": "getSignatureRequest", "parameters": [ { "in": "path", "name": "request_id", "required": true, "schema": { "title": "Request Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignatureRequestResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get a signature request status + audit trail", "tags": [ "e-signature" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "E-signature is a human-confirmed action (facet action / signing page) and a workflow gate — not an ambient agent tool. The assistant may draft signable documents (R38) but never creates a signature request itself." } }, "/api/v1/signature-requests/{request_id}/remind": { "post": { "operationId": "remindSignatureRequest", "parameters": [ { "in": "path", "name": "request_id", "required": true, "schema": { "title": "Request Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RemindResult" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Re-send the signing link for an open request", "tags": [ "e-signature" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "E-signature is a human-confirmed action (facet action / signing page) and a workflow gate — not an ambient agent tool. The assistant may draft signable documents (R38) but never creates a signature request itself." } }, "/api/v1/skill-collections": { "get": { "operationId": "listSkillCollections", "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/SkillCollectionResponse" }, "title": "Response Listskillcollections", "type": "array" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List Skill Collections", "tags": [ "skill-collections", "skill-collections" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Workspace administration of virtual-employee skill packs." }, "post": { "operationId": "createSkillCollection", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkillCollectionCreate" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkillCollectionDetailResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Create Skill Collection", "tags": [ "skill-collections", "skill-collections" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Workspace administration of virtual-employee skill packs." } }, "/api/v1/skill-collections/assignments/{assignment_id}": { "delete": { "operationId": "unassignSkillCollection", "parameters": [ { "in": "path", "name": "assignment_id", "required": true, "schema": { "title": "Assignment Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkillCollectionDetailResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Unassign Skill Collection", "tags": [ "skill-collections", "skill-collections" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Workspace administration of virtual-employee skill packs." }, "patch": { "operationId": "updateSkillCollectionAssignment", "parameters": [ { "in": "path", "name": "assignment_id", "required": true, "schema": { "title": "Assignment Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkillCollectionAssignmentUpdate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkillCollectionDetailResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Update Skill Collection Assignment", "tags": [ "skill-collections", "skill-collections" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Workspace administration of virtual-employee skill packs." } }, "/api/v1/skill-collections/assignments/{assignment_id}/promote": { "post": { "operationId": "promoteSkillCollectionAssignment", "parameters": [ { "in": "path", "name": "assignment_id", "required": true, "schema": { "title": "Assignment Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkillCollectionDetailResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Promote Skill Collection Assignment", "tags": [ "skill-collections", "skill-collections" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Workspace administration of virtual-employee skill packs." } }, "/api/v1/skill-collections/resolution/employee": { "get": { "description": "The employee's effective skill set, including what is shadowed and why.\n\nThis is the settings surface's read for the shadow marks, and it resolves\nthrough the SAME function the host bundle does — a UI that computed its own\nwinners would eventually disagree with the disk.", "operationId": "getEmployeeSkillResolution", "parameters": [ { "in": "query", "name": "runtime", "required": false, "schema": { "anyOf": [ { "maxLength": 64, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Runtime" } }, { "in": "query", "name": "employee_kind", "required": false, "schema": { "default": "virtual_employee", "title": "Employee Kind", "type": "string" } }, { "in": "query", "name": "employee_account_id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Employee Account Id" } }, { "in": "query", "name": "ai_employee_id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Ai Employee Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmployeeSkillResolutionResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Employee Skill Resolution", "tags": [ "skill-collections", "skill-collections" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Workspace administration of virtual-employee skill packs." } }, "/api/v1/skill-collections/{collection_id}": { "delete": { "operationId": "deleteSkillCollection", "parameters": [ { "in": "path", "name": "collection_id", "required": true, "schema": { "title": "Collection Id", "type": "string" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Delete Skill Collection", "tags": [ "skill-collections", "skill-collections" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Workspace administration of virtual-employee skill packs." }, "get": { "operationId": "getSkillCollection", "parameters": [ { "in": "path", "name": "collection_id", "required": true, "schema": { "title": "Collection Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkillCollectionDetailResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Skill Collection", "tags": [ "skill-collections", "skill-collections" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Workspace administration of virtual-employee skill packs." }, "patch": { "operationId": "updateSkillCollection", "parameters": [ { "in": "path", "name": "collection_id", "required": true, "schema": { "title": "Collection Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkillCollectionUpdate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkillCollectionDetailResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Update Skill Collection", "tags": [ "skill-collections", "skill-collections" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Workspace administration of virtual-employee skill packs." } }, "/api/v1/skill-collections/{collection_id}/assignments": { "post": { "description": "Assign the pack; the plugin access its skills need is approved in the\nsame gesture, or deliberately left pending (TIDY-19802 F2) — the secret\nfiles its skills' keys come from lent with it (TIDY-20019 F9).", "operationId": "assignSkillCollection", "parameters": [ { "in": "path", "name": "collection_id", "required": true, "schema": { "title": "Collection Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkillCollectionAssignmentCreate" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkillCollectionDetailResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Assign Skill Collection", "tags": [ "skill-collections", "skill-collections" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Workspace administration of virtual-employee skill packs." } }, "/api/v1/skill-collections/{collection_id}/grants": { "post": { "operationId": "grantSkillCollection", "parameters": [ { "in": "path", "name": "collection_id", "required": true, "schema": { "title": "Collection Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkillCollectionGrantCreate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkillCollectionDetailResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Grant Skill Collection", "tags": [ "skill-collections", "skill-collections" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Workspace administration of virtual-employee skill packs." } }, "/api/v1/skill-collections/{collection_id}/grants/{grant_id}": { "delete": { "operationId": "revokeSkillCollectionGrant", "parameters": [ { "in": "path", "name": "collection_id", "required": true, "schema": { "title": "Collection Id", "type": "string" } }, { "in": "path", "name": "grant_id", "required": true, "schema": { "title": "Grant Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkillCollectionDetailResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Revoke Skill Collection Grant", "tags": [ "skill-collections", "skill-collections" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Workspace administration of virtual-employee skill packs." } }, "/api/v1/skill-collections/{collection_id}/items": { "put": { "operationId": "setSkillCollectionItems", "parameters": [ { "in": "path", "name": "collection_id", "required": true, "schema": { "title": "Collection Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkillCollectionItemsUpdate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkillCollectionDetailResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Set Skill Collection Items", "tags": [ "skill-collections", "skill-collections" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Workspace administration of virtual-employee skill packs." } }, "/api/v1/skill-collections/{collection_id}/plugin-access": { "get": { "description": "What assigning this pack to the employee needs from you, and what is met.", "operationId": "getSkillCollectionPluginAccessPlan", "parameters": [ { "in": "path", "name": "collection_id", "required": true, "schema": { "title": "Collection Id", "type": "string" } }, { "in": "query", "name": "employee_account_id", "required": true, "schema": { "minLength": 1, "title": "Employee Account Id", "type": "string" } }, { "in": "query", "name": "runtime", "required": false, "schema": { "anyOf": [ { "maxLength": 64, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Runtime" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkillPluginAccessPlan" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Skill Collection Plugin Access Plan", "tags": [ "skill-collections", "skill-collections" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "A person's own Access gesture, step-up bound (TIDY-19802 F2)." } }, "/api/v1/skills": { "get": { "operationId": "listSkills", "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/SkillMetadataResponse" }, "title": "Response Listskills", "type": "array" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List Skills", "tags": [ "skills", "skills" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Catalog listing, deletion, history and execution are editor and assistant surfaces; agents author skills through the skill authoring tools." }, "post": { "operationId": "createSkill", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkillCreate" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkillResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Create Skill", "tags": [ "skills", "skills" ], "x-local-capability": "cloud" } }, "/api/v1/skills/drafts/{draft_id}/publication": { "put": { "description": "Publish a conversation's sealed private skill draft (TIDY-19569 R4d).\n\nCalled by the connector with the ending turn's OWN credential, never the\nruntime PAT. It publishes only when that turn is the employee's owner's DM\nand the owner may make this change: a revision becomes the skill's next\nversion (or a kept conflict when the skill moved past the draft's base); a\nnew skill is registered to this employee alone. Anything else answers\n``pending`` or ``refused`` and writes nothing. Idempotent on the draft: a\nretry under current authority returns the recorded answer (``replayed``).", "operationId": "publishSkillDraft", "parameters": [ { "in": "path", "name": "draft_id", "required": true, "schema": { "pattern": "^[0-9a-f]{64}$", "title": "Draft Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkillDraftPublishRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkillDraftPublicationReceipt" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Publish Skill Draft", "tags": [ "skills", "skills" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "The connector publishes a conversation's sealed skill draft with that turn's own credential when the turn ends; agents author through the skill authoring tools." } }, "/api/v1/skills/employees": { "get": { "description": "The employees the caller may give a skill to (TIDY-19569 R5d).\n\nIts owner, or a member admin, under the same authority every skill route\nresolves: an employee's call reaches its owner's roster only from the\nowner's own DM with it.", "operationId": "listConfigurableEmployees", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfigurableEmployeeList" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List Configurable Employees", "tags": [ "skills", "skills" ], "x-local-capability": "cloud" } }, "/api/v1/skills/employees/{agent_account_id}/harnesses/{runtime}": { "delete": { "description": "Let one harness carry the employee-wide skills again (TIDY-19569 F5).\n\nDrops that harness's own list and nothing else, under the lock a give or a\nsettings save takes, with the same authority over the employee.", "operationId": "useEmployeeWideSkillsOnHarness", "parameters": [ { "in": "path", "name": "agent_account_id", "required": true, "schema": { "format": "uuid", "title": "Agent Account Id", "type": "string" } }, { "in": "path", "name": "runtime", "required": true, "schema": { "maxLength": 32, "minLength": 1, "title": "Runtime", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmployeeHarnessSkillsReset" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Use Employee Wide Skills On Harness", "tags": [ "skills", "skills" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Direct REST door with no MCP tool: the employee's Skills view lets a harness follow the employee-wide skills again." } }, "/api/v1/skills/gives": { "post": { "description": "Give these skills to these employees with the access you approved for\neach, once. Each employee's change is its own transaction; one that is\nrefused changes nothing for that employee and says why.", "operationId": "giveSkills", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkillGivesRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkillGivesResult" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Give Skills", "tags": [ "skills", "skills" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "The Skills catalogue's own gestures — a person's bulk give with its one access approval, workspace tags, and customizing a Tidy skill. Agents give one skill through the skill authoring tools (or ask with a skill_give proposal) and never approve access." } }, "/api/v1/skills/gives/plan": { "post": { "description": "What giving these skills to these employees would do, and what it needs\nfrom you — per employee and list, without writing or holding anything.", "operationId": "planSkillGives", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkillGivesRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkillGivesPlan" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Plan Skill Gives", "tags": [ "skills", "skills" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "The Skills catalogue's own gestures — a person's bulk give with its one access approval, workspace tags, and customizing a Tidy skill. Agents give one skill through the skill authoring tools (or ask with a skill_give proposal) and never approve access." } }, "/api/v1/skills/package": { "post": { "description": "VE-assisted packaging of a local skill into the tenant registry (D4).", "operationId": "packageSkill", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkillPackageRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkillResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Package Skill", "tags": [ "skills", "skills" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Skill asset management surface." } }, "/api/v1/skills/repo-imports": { "post": { "description": "Add the repository at exactly ``commit`` as a published, read-only skill.\n\nThe carried files are packed into one archive stored by its SHA-256;\nworkshops download that archive from Tidy, never from GitHub. The skill is\nfor employees on workshops only: the built-in assistant does not load it,\nand it is never given to an employee on Tidy compute.", "operationId": "importSkillRepo", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkillRepoImportRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkillResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Import Skill Repo", "tags": [ "skills", "skills" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "An owner adds a repository from the Skills library after reading its preview; employees propose one instead (TIDY-20203 F6)." } }, "/api/v1/skills/repo-imports/preview": { "post": { "description": "What adding this repository would carry onto workshops. Nothing is stored.\n\nResolves the branch, tag or default branch to the commit an import pins\n(or shows ``commit`` itself: TIDY-20203 F6's Track in Tidy keeps the\ncommit a workshop's checkout is on), lists every file with whether it is carried, sums the carried size, names\nwhat the repository says it needs, and reports anything that would stop\nthe import.", "operationId": "previewSkillRepoImport", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkillRepoPreviewRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkillRepoPreview" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Preview Skill Repo Import", "tags": [ "skills", "skills" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "An owner adds a repository from the Skills library after reading its preview; employees propose one instead (TIDY-20203 F6)." } }, "/api/v1/skills/self/registrations/{registration_id}": { "put": { "description": "Register a new skill from the employee's managed harness root (TIDY-19569 R3b).\n\nIdempotent on ``registration_id``: the first call creates the central\nskill at v1 and carries it to the author through its own tracked\ncollection; any retry reads that same identity back (``created: false``).\nThe employee comes from the runtime PAT, the installation and workshop from\nits current lease — nothing about the source is taken from the body.", "operationId": "registerSelfSkill", "parameters": [ { "in": "path", "name": "registration_id", "required": true, "schema": { "format": "uuid", "title": "Registration Id", "type": "string" } }, { "in": "header", "name": "X-Tidy-Installation-Id", "required": false, "schema": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "X-Tidy-Installation-Id" } }, { "in": "header", "name": "X-Tidy-Boot-Id", "required": false, "schema": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "X-Tidy-Boot-Id" } }, { "in": "header", "name": "X-Tidy-Consumer-Generation", "required": false, "schema": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "X-Tidy-Consumer-Generation" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkillRegistrationRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkillRegistrationResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Register Self Skill", "tags": [ "skills", "skills" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Skill asset management surface." } }, "/api/v1/skills/self/versions/{skill_id}": { "post": { "description": "The disk→registry half of two-way sync (R5/D11).\n\nThe runtime PAT is the identity. Authorization is derivational: the VE may\nversion exactly the skills that resolve into its own bundle — the same\nmachinery that put the file on its disk decides it may push the edit back.\n\nTIDY-19569: an ``expected_version`` the head has moved past is kept as an\nopen conflict (409 after commit), never applied over the other edit; the\nsame authority resolves one with ``resolves_conflict_versions``. The\nrecorded source is the authenticated employee, never a body-supplied host.\n\nR3b: a gateway that sends its lease headers proves its installation too;\nthe push is then audited with that installation and its workshop. Without\nthem the push is the legacy one, and where it came from stays unknown.", "operationId": "pushSelfSkillVersion", "parameters": [ { "in": "path", "name": "skill_id", "required": true, "schema": { "title": "Skill Id", "type": "string" } }, { "in": "query", "name": "runtime", "required": false, "schema": { "anyOf": [ { "maxLength": 64, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Runtime" } }, { "in": "header", "name": "X-Tidy-Installation-Id", "required": false, "schema": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "X-Tidy-Installation-Id" } }, { "in": "header", "name": "X-Tidy-Boot-Id", "required": false, "schema": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "X-Tidy-Boot-Id" } }, { "in": "header", "name": "X-Tidy-Consumer-Generation", "required": false, "schema": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "X-Tidy-Consumer-Generation" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkillVersionCreate" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkillVersionResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Push Self Skill Version", "tags": [ "skills", "skills" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Skill asset management surface." } }, "/api/v1/skills/self/versions/{skill_id}/{version}": { "get": { "description": "One version's full bundle for the calling VE (TIDY-19569).\n\nThe base a local edit is mapped back onto, and both sides of a conflict the\nVE is asked to resolve — under the same derivational authority as the push.", "operationId": "getSelfSkillVersion", "parameters": [ { "in": "path", "name": "skill_id", "required": true, "schema": { "title": "Skill Id", "type": "string" } }, { "in": "path", "name": "version", "required": true, "schema": { "title": "Version", "type": "integer" } }, { "in": "query", "name": "runtime", "required": false, "schema": { "anyOf": [ { "maxLength": 64, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Runtime" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkillVersionResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Get Self Skill Version", "tags": [ "skills", "skills" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Skill asset management surface." } }, "/api/v1/skills/suggested": { "get": { "description": "Return the caller's reflection-proposed CANDIDATE skills (S5 Suggested).\n\nCandidates are private to their owner (visibility='private',\nlifecycle='candidate', origin='reflection') and are NEVER part of the active\ncatalog. The S6 UI renders these under \"Suggested\" with one-tap promote\n(PATCH /{id}/promote) / dismiss (DELETE).", "operationId": "listSuggestedSkills", "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/SkillMetadataResponse" }, "title": "Response Listsuggestedskills", "type": "array" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List Suggested Skills", "tags": [ "skills", "skills" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Catalog listing, deletion, history and execution are editor and assistant surfaces; agents author skills through the skill authoring tools." } }, "/api/v1/skills/tags/batch": { "post": { "description": "Add and remove tags across a selection of skills you can see, all or\nnone: one skill you cannot see refuses the whole change.", "operationId": "updateSkillTags", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkillTagsBatch" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkillTagsBatchResult" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Update Skill Tags", "tags": [ "skills", "skills" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "The Skills catalogue's own gestures — a person's bulk give with its one access approval, workspace tags, and customizing a Tidy skill. Agents give one skill through the skill authoring tools (or ask with a skill_give proposal) and never approve access." } }, "/api/v1/skills/validation": { "post": { "description": "Check a whole skill exactly as a save or a workshop publication would,\nwriting nothing (TIDY-19569 F5).\n\nAn employee writing a skill as files publishes it only when its turn has\nended, so it could not learn that its YAML was invalid until the next turn.\nThis lets it check the bundle first. It checks the bundle, not whether the\nname is free; the caller is held to the same authority as a save.", "operationId": "validateSkillBundle", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkillValidationRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkillValidationResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Validate Skill Bundle", "tags": [ "skills", "skills" ], "x-local-capability": "cloud" } }, "/api/v1/skills/{skill_id}": { "delete": { "operationId": "deleteSkill", "parameters": [ { "in": "path", "name": "skill_id", "required": true, "schema": { "title": "Skill Id", "type": "string" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Delete Skill", "tags": [ "skills", "skills" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Catalog listing, deletion, history and execution are editor and assistant surfaces; agents author skills through the skill authoring tools." }, "get": { "operationId": "getSkill", "parameters": [ { "in": "path", "name": "skill_id", "required": true, "schema": { "title": "Skill Id", "type": "string" } }, { "in": "query", "name": "published_system", "required": false, "schema": { "default": false, "title": "Published System", "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkillResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Skill", "tags": [ "skills", "skills" ], "x-local-capability": "cloud" }, "patch": { "operationId": "updateSkill", "parameters": [ { "in": "path", "name": "skill_id", "required": true, "schema": { "title": "Skill Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkillUpdate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkillResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Update Skill", "tags": [ "skills", "skills" ], "x-local-capability": "cloud" } }, "/api/v1/skills/{skill_id}/copy": { "post": { "description": "Explicit fork — the only path that duplicates content (D11).", "operationId": "copySkillAsNew", "parameters": [ { "in": "path", "name": "skill_id", "required": true, "schema": { "title": "Skill Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkillCopyRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkillResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Copy Skill As New", "tags": [ "skills", "skills" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Skill asset management surface." } }, "/api/v1/skills/{skill_id}/customize": { "post": { "description": "Make this workspace's own version of a Tidy skill, which its employees\nload in place of Tidy's from now on. Workspace Owners and Admins only.", "operationId": "customizeSkill", "parameters": [ { "in": "path", "name": "skill_id", "required": true, "schema": { "format": "uuid", "title": "Skill Id", "type": "string" } } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkillCustomization" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Customize Skill", "tags": [ "skills", "skills" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "The Skills catalogue's own gestures — a person's bulk give with its one access approval, workspace tags, and customizing a Tidy skill. Agents give one skill through the skill authoring tools (or ask with a skill_give proposal) and never approve access." } }, "/api/v1/skills/{skill_id}/employees/{agent_account_id}": { "delete": { "description": "Untick one skill from an employee's selection, nothing else (TIDY-19569 R5d).\n\nWith ``runtime`` it is unticked in that harness's own list (TIDY-19569 F5).\nA skill a collection or project also gives the employee stays carried.", "operationId": "takeSkillFromEmployee", "parameters": [ { "in": "path", "name": "skill_id", "required": true, "schema": { "format": "uuid", "title": "Skill Id", "type": "string" } }, { "in": "path", "name": "agent_account_id", "required": true, "schema": { "format": "uuid", "title": "Agent Account Id", "type": "string" } }, { "description": "Take it from this one harness's own skill list only.", "in": "query", "name": "runtime", "required": false, "schema": { "anyOf": [ { "maxLength": 32, "minLength": 1, "type": "string" }, { "type": "null" } ], "description": "Take it from this one harness's own skill list only.", "title": "Runtime" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmployeeSkillSelection" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Take Skill From Employee", "tags": [ "skills", "skills" ], "x-local-capability": "cloud" }, "put": { "description": "Give an employee exactly ``version`` of a skill, in one transaction (TIDY-19569 R5d).\n\nPublishes that version if it is not already the published one, then ticks\nthe skill in the employee's selection and nothing else. A newer published\nversion is refused, never given in its place. The employee is checked\nbefore anything is published; a failure at any step leaves nothing behind.\nWith ``runtime`` it is ticked in that harness's own list (TIDY-19569 F5).\n\nTIDY-19802 F2: a version that needs a plugin connection the caller has not\nlent and shipped is given only with their ``plugin_access`` choices, lent\nand shipped in this same transaction (a step-up unwinds all of it), or\ndeliberately ``assign_pending``. Otherwise 409 ``skill_plugin_access_required``\nnames what is missing; an employee's give also asks its owner in Attention.\n\nTIDY-20019 F9: the keys only a secret file answers are part of that plan,\nand ``secret_files`` lends the caller's own file that has them in the\nsame transaction, behind the secret-file lend's recent sign-in.\n\nTIDY-20067 F5 (D2): an agent giving a skill to ANOTHER employee asks for\nit instead (a ``skill_give`` proposal its approver decides on the card);\nan employee's own skill work keeps this door.", "operationId": "giveSkillToEmployee", "parameters": [ { "in": "path", "name": "skill_id", "required": true, "schema": { "format": "uuid", "title": "Skill Id", "type": "string" } }, { "in": "path", "name": "agent_account_id", "required": true, "schema": { "format": "uuid", "title": "Agent Account Id", "type": "string" } }, { "in": "header", "name": "X-Tidy-Acting-Principal", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tidy-Acting-Principal" } }, { "in": "header", "name": "X-Internal-Service", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service" } }, { "in": "header", "name": "X-Internal-Service-Key", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service-Key" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmployeeSkillGive" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmployeeSkillSelection" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Give Skill To Employee", "tags": [ "skills", "skills" ], "x-local-capability": "cloud" } }, "/api/v1/skills/{skill_id}/employees/{agent_account_id}/plugin-access": { "get": { "description": "What giving ``version`` to this employee needs from you, and what is met\n(TIDY-19802 F2). Requirements, readiness and ids only: the connections' and\nworkshops' names are the client's own local-first rows.", "operationId": "getSkillPluginAccessPlan", "parameters": [ { "in": "path", "name": "skill_id", "required": true, "schema": { "format": "uuid", "title": "Skill Id", "type": "string" } }, { "in": "path", "name": "agent_account_id", "required": true, "schema": { "format": "uuid", "title": "Agent Account Id", "type": "string" } }, { "in": "query", "name": "version", "required": true, "schema": { "exclusiveMinimum": 0, "title": "Version", "type": "integer" } }, { "in": "query", "name": "runtime", "required": false, "schema": { "anyOf": [ { "maxLength": 32, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Runtime" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkillPluginAccessPlan" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Skill Plugin Access Plan", "tags": [ "skills", "skills" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "A person's own Access gesture, step-up bound; an assistant's give asks the owner." }, "post": { "description": "Approve the plugin access a skill this employee already carries needs:\na later version's new dependency, or one assigned pending (TIDY-19802 F2).\nThe same choices, checks and transaction as a give, without the give.\n\nTIDY-20019 F9/F11: a secret file lent here unblocks a skill its box\nrefused for a missing key, so the employee's skills are delivered again\nin the same transaction; the box's next receipt answers the ask.", "operationId": "approveSkillPluginAccess", "parameters": [ { "in": "path", "name": "skill_id", "required": true, "schema": { "format": "uuid", "title": "Skill Id", "type": "string" } }, { "in": "path", "name": "agent_account_id", "required": true, "schema": { "format": "uuid", "title": "Agent Account Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkillPluginAccessApprove" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkillPluginAccessResult" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Approve Skill Plugin Access", "tags": [ "skills", "skills" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "A person's own Access gesture, step-up bound; an assistant's give asks the owner." } }, "/api/v1/skills/{skill_id}/execute": { "post": { "description": "Run the skill's referenced workflow in the sandbox (TIDY-11349).\n\nResolves the skill's primary ``skill_workflows`` link and delegates to the\ncanonical workflow dispatch path (``_dispatch_workflow_execution``), which\ncreates the ``workflow_execution_logs`` row, submits the run to Temporal, and\nstamps ``skill_id`` so the run is attributed to this skill. A skill with no\nlinked workflow is a pure-instruction skill and returns 400 — never a silent\nno-op.", "operationId": "executeSkillScript", "parameters": [ { "in": "path", "name": "skill_id", "required": true, "schema": { "title": "Skill Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkillExecuteRequest" } } }, "required": true }, "responses": { "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkillExecuteAccepted" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Execute Skill", "tags": [ "skills", "skills" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Catalog listing, deletion, history and execution are editor and assistant surfaces; agents author skills through the skill authoring tools." } }, "/api/v1/skills/{skill_id}/execute-async": { "post": { "description": "Dispatch a skill's linked workflow as a durable background continuation.\n\nResolves the skill→workflow link (S1) and writes an\n``assistant_continuations`` row so the assistant is re-engaged in\n``conversation_id`` when the run completes (TIDY-11351 / S3). Returns 202\n``{workflow_run_id, continuation_id}``.", "operationId": "executeSkillAsync", "parameters": [ { "in": "path", "name": "skill_id", "required": true, "schema": { "title": "Skill Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkillExecuteAsyncRequest" } } }, "required": true }, "responses": { "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExecuteAsyncAccepted" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Execute Skill Async", "tags": [ "skills", "skills" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Catalog listing, deletion, history and execution are editor and assistant surfaces; agents author skills through the skill authoring tools." } }, "/api/v1/skills/{skill_id}/execution-review": { "post": { "deprecated": true, "operationId": "reviewSkillExecution", "parameters": [ { "in": "path", "name": "skill_id", "required": true, "schema": { "title": "Skill Id", "type": "string" } } ], "responses": { "410": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrowserRunsRetiredProblem" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Review skill execution (retired)", "tags": [ "skills" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Retired skill run surface; the employee runs skills itself." } }, "/api/v1/skills/{skill_id}/links": { "get": { "operationId": "listSkillProjectLinks", "parameters": [ { "in": "path", "name": "skill_id", "required": true, "schema": { "title": "Skill Id", "type": "string" } }, { "in": "query", "name": "published_system", "required": false, "schema": { "default": false, "title": "Published System", "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/SkillProjectLinkResponse" }, "title": "Response Listskillprojectlinks", "type": "array" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List Skill Project Links", "tags": [ "skills", "skills" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Skill asset management surface." }, "post": { "operationId": "linkSkillToProject", "parameters": [ { "in": "path", "name": "skill_id", "required": true, "schema": { "title": "Skill Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkillProjectLinkCreate" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkillProjectLinkResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Link Skill To Project", "tags": [ "skills", "skills" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Skill asset management surface." } }, "/api/v1/skills/{skill_id}/links/{project_id}": { "delete": { "operationId": "unlinkSkillFromProject", "parameters": [ { "in": "path", "name": "skill_id", "required": true, "schema": { "title": "Skill Id", "type": "string" } }, { "description": "Typed ID with prefix 'P'", "in": "path", "name": "project_id", "required": true, "schema": { "description": "Typed ID with prefix 'P'", "title": "Project Id", "type": "string" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Unlink Skill From Project", "tags": [ "skills", "skills" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Skill asset management surface." } }, "/api/v1/skills/{skill_id}/plugin-access/carriers": { "get": { "description": "What every employee carrying this skill needs from you for the version it\ncarries now, where something is still open (TIDY-20019 F10). The editor\nasks it after a save or a promote, so a new key is lent there rather than\nfound missing on a deploy. Only employees you may configure; read-only.", "operationId": "getSkillCarriersPluginAccess", "parameters": [ { "in": "path", "name": "skill_id", "required": true, "schema": { "format": "uuid", "title": "Skill Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkillCarriersPluginAccess" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Skill Carriers Plugin Access", "tags": [ "skills", "skills" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "A person's own Access gesture, step-up bound; an assistant's give asks the owner." } }, "/api/v1/skills/{skill_id}/publish": { "post": { "description": "Promote one version to published (TIDY-17072 D6b).\n\nRequires a clean validation verdict at that version; pins\n``published_version`` so VEs install that snapshot until a newer version is\npromoted. Refuses a slug that collides with a system-tier seed.", "operationId": "publishSkill", "parameters": [ { "in": "path", "name": "skill_id", "required": true, "schema": { "title": "Skill Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkillPublishRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkillResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Publish Skill", "tags": [ "skills", "skills" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "The skill editor's publish control. Agents publish a version only by giving it to an employee: the skill tools' PUT /skills/{id}/employees/{agent}." } }, "/api/v1/skills/{skill_id}/repo-keys": { "put": { "description": "Change which keys a repo skill is lent, whether a turn also finds\nthem in its ``.env``, and (TIDY-20203 F4) what a workshop must have.\n\nThe repository's SKILL.md is not Tidy's to edit, so its keys are declared\nbeside its source (TIDY-20203 F3). A change is a new version on the same\ncommit, published at once, so every employee given the skill is held,\nor installs, on the new keys at its next sync. Owner or admin only (D7).", "operationId": "updateSkillRepoKeys", "parameters": [ { "in": "path", "name": "skill_id", "required": true, "schema": { "format": "uuid", "title": "Skill Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkillRepoKeysUpdate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkillResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Update Skill Repo Keys", "tags": [ "skills", "skills" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "An owner changes which keys a repo skill is lent from its page in the Skills library (TIDY-20203 F3)." } }, "/api/v1/skills/{skill_id}/repo-update": { "post": { "description": "Move a repo skill to the commit its branch names, as reviewed.\n\n``commit`` must be the one the owner reviewed (``upstream.upstream_commit``\nas last read); Tidy never moves a skill to a commit nobody saw. The new\ncommit is carried with the skill's own include/exclude, keys, ``.env``\nchoice and requirements, as a new version published at once: every\nemployee given the skill installs it at its next sync. Owner or admin\nonly (D7).", "operationId": "approveSkillRepoUpdate", "parameters": [ { "in": "path", "name": "skill_id", "required": true, "schema": { "format": "uuid", "title": "Skill Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkillRepoUpdateApprove" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkillResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Approve Skill Repo Update", "tags": [ "skills", "skills" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "An owner reviews and approves a repo skill's update from its page in the Skills library (TIDY-20203 F5)." } }, "/api/v1/skills/{skill_id}/repo-update/check": { "post": { "description": "Read the repository's branch now instead of at the next check.\n\nChanges nothing a workshop has: an update the branch names is shown for\nreview (``upstream``) until an owner approves it. At most once a minute\nper skill. Owner or admin only (D7).", "operationId": "checkSkillRepoUpdate", "parameters": [ { "in": "path", "name": "skill_id", "required": true, "schema": { "format": "uuid", "title": "Skill Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkillResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Check Skill Repo Update", "tags": [ "skills", "skills" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "An owner reviews and approves a repo skill's update from its page in the Skills library (TIDY-20203 F5)." } }, "/api/v1/skills/{skill_id}/reset": { "post": { "description": "Remove the workspace's customization (``skill_id``): its employees load\nTidy's version again. Workspace Owners and Admins only.", "operationId": "resetSkillCustomization", "parameters": [ { "in": "path", "name": "skill_id", "required": true, "schema": { "format": "uuid", "title": "Skill Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkillCustomization" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Reset Skill Customization", "tags": [ "skills", "skills" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "The Skills catalogue's own gestures — a person's bulk give with its one access approval, workspace tags, and customizing a Tidy skill. Agents give one skill through the skill authoring tools (or ask with a skill_give proposal) and never approve access." } }, "/api/v1/skills/{skill_id}/scripts": { "get": { "description": "What a rule's \"Run skill script\" may run of this skill: the scripts of\nits PUBLISHED version and where each runs (TIDY-19604 F7).", "operationId": "listSkillScripts", "parameters": [ { "in": "path", "name": "skill_id", "required": true, "schema": { "title": "Skill Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkillScriptList" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List Skill Scripts", "tags": [ "skills", "skills" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "The rule builder's script picker. Agents build rules through the rule tools, which name the skill and script directly." } }, "/api/v1/skills/{skill_id}/supervised-runs": { "post": { "deprecated": true, "operationId": "beginSkillSupervisedRun", "parameters": [ { "in": "path", "name": "skill_id", "required": true, "schema": { "title": "Skill Id", "type": "string" } } ], "responses": { "410": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrowserRunsRetiredProblem" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Begin skill supervised run (retired)", "tags": [ "skills" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Retired skill run surface; the employee runs skills itself." } }, "/api/v1/skills/{skill_id}/tags": { "put": { "description": "Exactly these workspace tags on a skill you can see.", "operationId": "setSkillTags", "parameters": [ { "in": "path", "name": "skill_id", "required": true, "schema": { "format": "uuid", "title": "Skill Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkillTagsSet" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkillTags" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Set Skill Tags", "tags": [ "skills", "skills" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "The Skills catalogue's own gestures — a person's bulk give with its one access approval, workspace tags, and customizing a Tidy skill. Agents give one skill through the skill authoring tools (or ask with a skill_give proposal) and never approve access." } }, "/api/v1/skills/{skill_id}/unattended-readiness": { "post": { "deprecated": true, "operationId": "enableSkillUnattendedExecution", "parameters": [ { "in": "path", "name": "skill_id", "required": true, "schema": { "title": "Skill Id", "type": "string" } } ], "responses": { "410": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrowserRunsRetiredProblem" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Enable skill unattended execution (retired)", "tags": [ "skills" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Retired skill run surface; the employee runs skills itself." } }, "/api/v1/skills/{skill_id}/unpublish": { "post": { "description": "Withdraw the skill from the provisioning catalogue (TIDY-17072).", "operationId": "unpublishSkill", "parameters": [ { "in": "path", "name": "skill_id", "required": true, "schema": { "title": "Skill Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkillResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Unpublish Skill", "tags": [ "skills", "skills" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Catalog listing, deletion, history and execution are editor and assistant surfaces; agents author skills through the skill authoring tools." } }, "/api/v1/skills/{skill_id}/versions": { "get": { "operationId": "listSkillVersions", "parameters": [ { "in": "path", "name": "skill_id", "required": true, "schema": { "title": "Skill Id", "type": "string" } }, { "in": "query", "name": "published_system", "required": false, "schema": { "default": false, "title": "Published System", "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/SkillVersionResponse" }, "title": "Response Listskillversions", "type": "array" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List Skill Versions", "tags": [ "skills", "skills" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Catalog listing, deletion, history and execution are editor and assistant surfaces; agents author skills through the skill authoring tools." }, "post": { "description": "One atomic new version of the whole asset — the editor/assistant save.", "operationId": "createSkillVersion", "parameters": [ { "in": "path", "name": "skill_id", "required": true, "schema": { "title": "Skill Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkillVersionCreate" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkillVersionResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Create Skill Version", "tags": [ "skills", "skills" ], "x-local-capability": "cloud" } }, "/api/v1/skills/{skill_id}/versions/{version}": { "get": { "description": "One version's FULL bundle; system opt-in is restricted to its public pin.", "operationId": "getSkillVersion", "parameters": [ { "in": "path", "name": "skill_id", "required": true, "schema": { "title": "Skill Id", "type": "string" } }, { "in": "path", "name": "version", "required": true, "schema": { "title": "Version", "type": "integer" } }, { "in": "query", "name": "published_system", "required": false, "schema": { "default": false, "title": "Published System", "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkillVersionResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Skill Version", "tags": [ "skills", "skills" ], "x-local-capability": "cloud" } }, "/api/v1/skills/{skill_id}/versions/{version}/restore": { "post": { "description": "Restore version N as a NEW head version — never a rewrite (R9).", "operationId": "restoreSkillVersion", "parameters": [ { "in": "path", "name": "skill_id", "required": true, "schema": { "title": "Skill Id", "type": "string" } }, { "in": "path", "name": "version", "required": true, "schema": { "title": "Version", "type": "integer" } } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkillVersionResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Restore Skill Version", "tags": [ "skills", "skills" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Catalog listing, deletion, history and execution are editor and assistant surfaces; agents author skills through the skill authoring tools." } }, "/api/v1/slides/convert-note": { "post": { "operationId": "slidesConvertNote", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SlidesConvertNoteRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SlidesConvertNoteResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Convert an existing note into a slide deck using AI", "tags": [ "slides", "slides" ] } }, "/api/v1/source-control/providers": { "get": { "description": "The catalog. Every entry reports its REAL capabilities and auth state.", "operationId": "listSourceControlProviders", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SourceControlProviderListResponse" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List source-control providers and this tenant's connection state", "tags": [ "source-control" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/source-control/providers/{provider_id}/pull-requests": { "post": { "description": "A provider that cannot open PRs yet answers 501 naming itself (R23).\n\nAn employee acting under a plugin lend names its grant in\n``X-Tidy-Plugin-Grant``; the grant must cover ``repo:<full_name>`` on the\ntenant's source-control plugin or the call is 403 naming why — it never\nfalls through to the caller's own standing. Without the header the\nper-employee installation gate inside the provider decides, as before.", "operationId": "createSourceControlPullRequest", "parameters": [ { "in": "path", "name": "provider_id", "required": true, "schema": { "title": "Provider Id", "type": "string" } }, { "in": "header", "name": "X-Tidy-Plugin-Grant", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tidy-Plugin-Grant" } }, { "in": "header", "name": "X-Tidy-Conversation-Id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tidy-Conversation-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PullRequestCreateRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PullRequestCreateResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Open a pull request through a provider", "tags": [ "source-control" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/source-control/providers/{provider_id}/repositories": { "get": { "description": "Live read through the provider — never a cached list (see github_repos).", "operationId": "listSourceControlRepositories", "parameters": [ { "in": "path", "name": "provider_id", "required": true, "schema": { "title": "Provider Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SourceControlRepositoryListResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List the repositories this tenant can reach through a provider", "tags": [ "source-control" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/speech/recordings/{recording_id}/chunks": { "post": { "operationId": "speechRecordingChunkUpload", "parameters": [ { "in": "path", "name": "recording_id", "required": true, "schema": { "title": "Recording Id", "type": "string" } } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/Body_speechRecordingChunkUpload" } } }, "required": true }, "responses": { "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChunkReceiptResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Acknowledge receipt of one Opus recording chunk.", "tags": [ "speech", "speech" ] } }, "/api/v1/speech/recordings/{recording_id}/finalize": { "post": { "operationId": "speechRecordingFinalize", "parameters": [ { "in": "path", "name": "recording_id", "required": true, "schema": { "title": "Recording Id", "type": "string" } } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/Body_speechRecordingFinalize" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FinalizeResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Finalize a recording — forward full audio to whisperx and return the transcript.", "tags": [ "speech", "speech" ] } }, "/api/v1/standing-authorisations": { "get": { "operationId": "listStandingAuthorisations", "parameters": [ { "in": "query", "name": "employee_account_id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Employee Account Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StandingAuthorisationsResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Every standing authority the caller has given", "tags": [ "access" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Standing authority is a first-party Access surface; the assistant reads it local-first." } }, "/api/v1/standing-authorisations/{authorisation_id}/renew": { "post": { "operationId": "renewStandingAuthorisation", "parameters": [ { "in": "path", "name": "authorisation_id", "required": true, "schema": { "title": "Authorisation Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/RenewRequest" }, { "type": "null" } ], "title": "Body" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StandingAuthorisation" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Extend an expired or expiring standing authority", "tags": [ "access" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Standing authority is a first-party Access surface; the assistant reads it local-first." } }, "/api/v1/storage/sign": { "post": { "description": "Returns a short-lived signed URL the browser can place directly in `<img src>` or `<a href>` against a private Supabase Storage object. The browser's image fetcher cannot attach `Authorization: Bearer`, so the only viable render path for private buckets is a signed URL. Bearer-required, validates bucket allow-list, caps `expires_in_seconds` at 86400 (1 day). TIDY-8409.", "operationId": "storageSign", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StorageSignRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StorageSignResponse" } } }, "description": "Signed URL issued" }, "400": { "description": "Invalid path (traversal or empty)" }, "401": { "description": "Missing or invalid bearer" }, "403": { "description": "Bucket not in allow-list" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "500": { "description": "Storage signing failed" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Mint a signed URL for a private-bucket object", "tags": [ "storage" ] } }, "/api/v1/storage/sign-batch": { "post": { "description": "Batch variant of `POST /storage/sign`. Accepts up to 100 bucket+path pairs and returns one response item per request item, in input order. Per-item Supabase failures surface as `signed_url=null` plus an `error` short-code without failing the whole batch. Whole-request validation (bucket allow-list, path traversal) is enforced up front and returns 400/403. Bearer-required, caps `expires_in_seconds` at 86400, and caps server-side fan-out to Supabase at 10 concurrent sign calls. TIDY-8440.", "operationId": "storageSignBatch", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StorageSignBatchRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StorageSignBatchResponse" } } }, "description": "Batch processed (per-item errors may be present)" }, "400": { "description": "Empty batch, oversized batch, or invalid path" }, "401": { "description": "Missing or invalid bearer" }, "403": { "description": "Bucket not in allow-list" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "500": { "description": "Storage signing not configured" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Mint signed URLs for up to 100 private-bucket objects in one call", "tags": [ "storage" ] } }, "/api/v1/storage/{full_path}": { "get": { "description": "Streams objects from a private Supabase Storage bucket using the api-service's service-role key. The first path segment is the bucket name; the remaining segments are the object path. Requires an authenticated session. Replaces the SvelteKit /api/v1/storage/[...] BFF (TIDY-5478, TIDY-7383).", "operationId": "storageProxy", "parameters": [ { "description": "{bucket}/{object_path}", "in": "path", "name": "full_path", "required": true, "schema": { "description": "{bucket}/{object_path}", "title": "Full Path", "type": "string" } } ], "responses": { "200": { "content": { "application/octet-stream": {} }, "description": "Streamed object bytes" }, "403": { "description": "Bucket not in allow-list" }, "404": { "description": "File not found" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Authenticated Supabase Storage proxy", "tags": [ "storage" ] } }, "/api/v1/streaming_lookup": { "get": { "description": "Looks a title up on TMDB (`/search/movie` + `/search/tv`) and returns the top matches with year, overview, and where they stream / rent / buy in the requested region (ISO 3166-1 alpha-2; default is the account's country). Missing or rejected (401/403) TMDB credentials return 200 with `configured=false` and no results — never a 500 or 502 (weather contract); a revoked/rotated key IS an unconfigured provider from the caller's perspective. Other TMDB failures are real 502s. TIDY-17689.", "operationId": "getStreamingLookup", "parameters": [ { "in": "query", "name": "query", "required": true, "schema": { "maxLength": 200, "minLength": 1, "title": "Query", "type": "string" } }, { "in": "query", "name": "country", "required": false, "schema": { "anyOf": [ { "maxLength": 2, "minLength": 2, "type": "string" }, { "type": "null" } ], "title": "Country" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StreamingLookupResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Search movies + TV on TMDB and return per-region watch providers", "tags": [ "streaming-lookup" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Consumed by the assistant's tidy_streaming_lookup catalog tool (TIDY-17689); MCP clients get the same data through the assistant surface, so a second MCP wrapper adds nothing." } }, "/api/v1/sync-credentials": { "post": { "description": "Exchanges the bearer of a Tidy surface — a first-party session, which a sign-in by the Tidy Android or desktop app also mints (TIDY-20053) — for a short-lived PowerSync credential. Every other credential — every OAuth client grant (the apps' included), the CLI, PATs, service accounts — is refused: they use the REST API and MCP, not sync.", "operationId": "mintSyncCredential", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SyncCredential" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Mint the PowerSync credential for a Tidy app", "tags": [ "sync" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "A PowerSync credential for Tidy's own apps; no tool or script may hold one." } }, "/api/v1/sync-refusals": { "get": { "description": "The caller's own refusals, newest first (kept 30 days).", "operationId": "listSyncRefusals", "parameters": [ { "description": "Only this upload envelope's refusals", "in": "query", "name": "envelope_id", "required": false, "schema": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "description": "Only this upload envelope's refusals", "title": "Envelope Id" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "maximum": 100, "minimum": 1, "title": "Limit", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SyncRefusalListResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List your refused sync changes", "tags": [ "sync" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/sync-refusals/{refusal_id}": { "get": { "description": "Return the refusal by the id the refusing device shows.\n\nOwner-scoped: another member's refusal answers 404, exactly like one that\ndoes not exist, so ids cannot be probed.", "operationId": "getSyncRefusal", "parameters": [ { "in": "path", "name": "refusal_id", "required": true, "schema": { "format": "uuid", "title": "Refusal Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SyncRefusalResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Look up one of your refused sync changes", "tags": [ "sync" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/sync/batch": { "post": { "description": "Process local-first CRUD operations in one API request.\n\nTIDY-11627 (F1-S3): returns a per-op `results` array. No op is ever silently\ndropped to a 200 — a per-op failure carries its real status so the client can\nclassify it. Idempotency: each op is claimed under its key (origin, else\nenvelope_id + op_index) before it is dispatched, so a retry acknowledges\nan applied op and never re-applies one whose outcome is unknown.", "operationId": "syncBatch", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SyncBatchRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SyncBatchResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Batch PowerSync CRUD upload", "tags": [ "sync" ] } }, "/api/v1/system-skills": { "get": { "operationId": "listSystemSkills", "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/SystemSkillSummary" }, "title": "Response Listsystemskills", "type": "array" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "The skills Tidy publishes for agents", "tags": [ "skills" ], "x-local-capability": "cloud" } }, "/api/v1/system-skills/{slug}": { "get": { "operationId": "getSystemSkill", "parameters": [ { "description": "The skill's slug, e.g. tidy-mcp.", "in": "path", "name": "slug", "required": true, "schema": { "description": "The skill's slug, e.g. tidy-mcp.", "pattern": "^[a-z0-9][a-z0-9-]{0,63}$", "title": "Slug", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SystemSkillResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "One skill Tidy publishes, at its published version, every file whole", "tags": [ "skills" ], "x-local-capability": "cloud" } }, "/api/v1/system-skills/{slug}/archive": { "get": { "operationId": "downloadSystemSkillArchive", "parameters": [ { "description": "The skill's slug, e.g. tidy-mcp.", "in": "path", "name": "slug", "required": true, "schema": { "description": "The skill's slug, e.g. tidy-mcp.", "pattern": "^[a-z0-9][a-z0-9-]{0,63}$", "title": "Slug", "type": "string" } } ], "responses": { "200": { "content": { "application/gzip": {} }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "A ticketed skill's archive, once, with its download token", "tags": [ "skills" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "The agent's shell fetches the archive here; through a tool call its files would pass through the model." } }, "/api/v1/system-skills/{slug}/download-tickets": { "post": { "operationId": "createSystemSkillDownloadTicket", "parameters": [ { "description": "The skill's slug, e.g. tidy-mcp.", "in": "path", "name": "slug", "required": true, "schema": { "description": "The skill's slug, e.g. tidy-mcp.", "pattern": "^[a-z0-9][a-z0-9-]{0,63}$", "title": "Slug", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SystemSkillDownloadTicketResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get a one-time address to install a skill Tidy publishes from your shell", "tags": [ "skills" ], "x-local-capability": "cloud" } }, "/api/v1/tag-assignments": { "delete": { "description": "Remove a page-level note/journal/activity/photo tag assignment by\n primitive + slug. Precise block-level assignments are not touched. The\n migration-293 trigger recomputes the primitive's materialized tags column\n (notes/journals/activities/photos).", "operationId": "deleteTagAssignmentByTuple", "parameters": [ { "in": "query", "name": "primitive_type", "required": true, "schema": { "pattern": "^(note|journal|activity|photo|calendar_event|contact|email|file|organization|record)$", "title": "Primitive Type", "type": "string" } }, { "in": "query", "name": "primitive_id", "required": true, "schema": { "format": "uuid", "title": "Primitive Id", "type": "string" } }, { "in": "query", "name": "tag_slug", "required": true, "schema": { "maxLength": 64, "minLength": 1, "pattern": "^[a-z0-9][a-z0-9-]*(/[a-z0-9][a-z0-9-]*)*$", "title": "Tag Slug", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Delete a page-level tag assignment by tuple", "tags": [ "tags" ] }, "post": { "description": "Add one page-level tag to any taggable primitive (note, journal,\n activity, photo, calendar event, contact, file, organization, record).\n This writes only to tag_assignments; migration 293's trigger owns every\n materialized `tags` column.", "operationId": "createTagAssignment", "parameters": [ { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TagAssignmentCreateRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TagAssignmentCreateResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Create a page-level tag assignment", "tags": [ "tags" ] } }, "/api/v1/tag-assignments/{assignment_id}": { "delete": { "description": "Remove a single tag_assignments row. The migration 293 trigger then\n recomputes the affected primitive's `tags text[]` column with\n IS DISTINCT FROM guards.\n\n Returns:\n 204 No Content on success.\n 400 Bad Request when ID is not a valid UUID.\n 404 Not Found when ID doesn't exist or belongs to another tenant.", "operationId": "deleteTagAssignment", "parameters": [ { "in": "path", "name": "assignment_id", "required": true, "schema": { "title": "Assignment Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Delete a tag assignment", "tags": [ "tags" ] } }, "/api/v1/tags": { "post": { "operationId": "createTag", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TagCreate" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Createtag", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Create Tag", "tags": [ "tags", "tags" ] } }, "/api/v1/tags/": { "get": { "description": "Return the caller's tenant's tags (canonical definitions) with usage counts.\n\nThe tag VOCABULARY is tenant-shared; ``usage_count`` is the caller's count\nof distinct items carrying the tag (TIDY-10582 member scope, TIDY-18050\none definition shared with the web Tag Explorer) — see\n:meth:`TagAssignmentsRepository.member_tag_usage_cte`. A legacy spelling\nof a tag (TIDY-18050 alias) is not listed; its items count toward the\ncanonical tag.", "operationId": "listTags", "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/TagListItem" }, "title": "Response Listtags", "type": "array" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List Tags", "tags": [ "tags", "tags" ] } }, "/api/v1/tags/settings": { "get": { "operationId": "getTagSettings", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TagSettingsResponse" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Read whether AI may create new tags", "tags": [ "tags", "tags" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Tenant Tags settings surface, not an agent primitive." }, "patch": { "operationId": "patchTagSettings", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TagSettingsPatch" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TagSettingsResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Set whether AI may create new tags", "tags": [ "tags", "tags" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Tenant Tags settings surface, not an agent primitive." } }, "/api/v1/tags/{slug}/assignments": { "get": { "description": "Returns the timeline of inline tag mentions for a given slug. Each row\n includes the source primitive's resolved title + the block-level excerpt\n where the mention was placed.\n\n Multi-tenant: scoped to the caller's tenant. RLS provides defense-in-depth.\n\n Path parameters:\n slug: Tag slug (URL-encoded). Lowercase, dash-separated.\n\n Query parameters:\n limit: Max results per page (1-200, default 50).\n cursor: Opaque keyset cursor encoding (updated_at, id).\n primitive_type: Filter by source primitive type\n ('note', 'journal', 'email', 'contact', 'calendar_event',\n 'activity', 'project').\n search: Case-insensitive substring match against either\n primitive_title or source_block_excerpt.\n\n The endpoint never returns 404 for an unknown slug — orphan slugs return\n `{assignments: [], total: 0}`.", "operationId": "getTagAssignments", "parameters": [ { "in": "path", "name": "slug", "required": true, "schema": { "title": "Slug", "type": "string" } }, { "description": "Max results", "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "description": "Max results", "maximum": 200, "minimum": 1, "title": "Limit", "type": "integer" } }, { "description": "Pagination cursor", "in": "query", "name": "cursor", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pagination cursor", "title": "Cursor" } }, { "description": "Filter by primitive type", "in": "query", "name": "primitive_type", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by primitive type", "title": "Primitive Type" } }, { "description": "Case-insensitive substring match (title or excerpt)", "in": "query", "name": "search", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Case-insensitive substring match (title or excerpt)", "title": "Search" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TagAssignmentListResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List tag assignments for a slug", "tags": [ "tags" ] } }, "/api/v1/tags/{source_id}/merge/{target_id}": { "post": { "operationId": "mergeTags", "parameters": [ { "in": "path", "name": "source_id", "required": true, "schema": { "title": "Source Id", "type": "string" } }, { "in": "path", "name": "target_id", "required": true, "schema": { "title": "Target Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Mergetags", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Merge Tags", "tags": [ "tags", "tags" ] } }, "/api/v1/tags/{tag_id}": { "delete": { "operationId": "deleteTag", "parameters": [ { "in": "path", "name": "tag_id", "required": true, "schema": { "title": "Tag Id", "type": "string" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Delete Tag", "tags": [ "tags", "tags" ] }, "patch": { "operationId": "updateTag2", "parameters": [ { "in": "path", "name": "tag_id", "required": true, "schema": { "title": "Tag Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TagUpdate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Updatetag2", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Update Tag", "tags": [ "tags", "tags" ] }, "put": { "operationId": "updateTag", "parameters": [ { "in": "path", "name": "tag_id", "required": true, "schema": { "title": "Tag Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TagUpdate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Updatetag", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Update Tag", "tags": [ "tags", "tags" ] } }, "/api/v1/tags/{tag_id}/rename": { "put": { "operationId": "renameTag", "parameters": [ { "in": "path", "name": "tag_id", "required": true, "schema": { "title": "Tag Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TagRename" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Renametag", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Rename Tag", "tags": [ "tags", "tags" ] } }, "/api/v1/tasks": { "get": { "operationId": "listTasks", "parameters": [ { "in": "query", "name": "status", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Status" } }, { "in": "query", "name": "category", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Category" } }, { "in": "query", "name": "priority", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Priority" } }, { "in": "query", "name": "project_id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Project Id" } }, { "in": "query", "name": "owner", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Owner" } }, { "in": "query", "name": "is_recurring", "required": false, "schema": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is Recurring" } }, { "in": "query", "name": "snoozed", "required": false, "schema": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Snoozed" } }, { "in": "query", "name": "approval_status", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Approval Status" } }, { "in": "query", "name": "has_due_datetime", "required": false, "schema": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Has Due Datetime" } }, { "in": "query", "name": "due_date_lte", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Due Date Lte" } }, { "in": "query", "name": "search", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Search" } }, { "description": "Sort order. One of: score, due_date, updated_at, created_at, start, title, due_date_asc, due_date_desc, created_desc, created_asc, priority_desc. priority_desc follows the facet's own priority options, first option first. Omitted: newest created first.", "in": "query", "name": "sort_by", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Sort order. One of: score, due_date, updated_at, created_at, start, title, due_date_asc, due_date_desc, created_desc, created_asc, priority_desc. priority_desc follows the facet's own priority options, first option first. Omitted: newest created first.", "title": "Sort By" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 100, "maximum": 1000, "minimum": 1, "title": "Limit", "type": "integer" } }, { "in": "query", "name": "offset", "required": false, "schema": { "default": 0, "minimum": 0, "title": "Offset", "type": "integer" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Listtasks", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List tasks (compat: delegates to activities with task facet filter)", "tags": [ "tasks-compat" ] }, "post": { "operationId": "createTask", "parameters": [ { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskCreateCompat" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActivityResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Create task (compat: delegates to activities)", "tags": [ "tasks-compat" ] } }, "/api/v1/tasks/ai-schedule": { "post": { "description": "Generate an AI-proposed schedule for the tenant's open tasks.\n\nReturns a proposal set (not applied to tasks) that the client can then\nsubmit via POST /tasks/ai-schedule/apply to accept all or a subset.\n\nBehavior: scope 'day' schedules tasks for the given start_date (or today\nin the given timezone). scope 'week' schedules across a 7-day window.\nTasks are ordered by activity.score desc, then due_datetime asc.", "operationId": "aiScheduleTasks", "parameters": [ { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActivityAiScheduleRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActivityAiScheduleResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Generate AI-proposed schedule for tasks", "tags": [ "tasks" ] } }, "/api/v1/tasks/ai-schedule/apply": { "post": { "description": "Apply AI-proposed schedule blocks to the originating tasks.\n\nWrites start/end timestamps to each referenced activity. Idempotent:\nre-applying the same proposal_set_id updates timestamps if the proposal\nstill exists, skips already-applied proposals.", "operationId": "applyAiSchedule", "parameters": [ { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActivityAiScheduleApplyRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActivityAiScheduleApplyResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Apply accepted AI schedule blocks", "tags": [ "tasks" ] } }, "/api/v1/tasks/batch": { "post": { "description": "Create or update up to 50 tasks in one call, keyed by ``source_ref``.\n\nRow identity is ``provenance->>'source_ref'``: a miss creates, a hit with\ndifferent content updates, a hit whose comparable projection matches\nreports ``unchanged`` and writes nothing. ``parent_source_ref`` resolves\nwithin the call regardless of row order; a parent cycle rejects every row\ninvolved before any write.", "operationId": "batchCreateTasks", "parameters": [ { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskBatchCreateRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskBatchCreateResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Batch create/update tasks (bounded, idempotent by source_ref)", "tags": [ "tasks-compat" ], "x-local-capability": "cloud" } }, "/api/v1/tasks/from-source": { "post": { "description": "Create a new task linked to a source record.\n\nThe task is created with:\n- linked_references provenance recording the origin\n- facets = ['task']\n- the task facet's own default status (TIDY-19443: this route hardcoded\n 'todo', which a workspace whose task statuses are its own — the projects\n template's backlog/ready_build/… — refuses with a 422, so \"create a task\n from this email\" failed there)", "operationId": "createTaskFromSource", "parameters": [ { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskFromSourceRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActivityResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Create a task from a source (email, note, etc.)", "tags": [ "tasks" ] } }, "/api/v1/tasks/inbox/bulk-approve": { "post": { "operationId": "tasksInboxBulkApprove", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TasksInboxBulkRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TasksInboxBulkResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Bulk Approve", "tags": [ "tasks-inbox" ] } }, "/api/v1/tasks/inbox/bulk-reject": { "post": { "operationId": "tasksInboxBulkReject", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TasksInboxBulkRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TasksInboxBulkResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Bulk Reject", "tags": [ "tasks-inbox" ] } }, "/api/v1/tasks/pending": { "get": { "operationId": "listPendingTasks", "parameters": [ { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Listpendingtasks", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List pending tasks (compat)", "tags": [ "tasks-compat" ] } }, "/api/v1/tasks/recalculate-scores": { "post": { "operationId": "recalculateScores2", "parameters": [ { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActivityScoreRecalculateRequest" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActivityScoreRecalculateResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Recalculate task scores (compat)", "tags": [ "tasks-compat" ] } }, "/api/v1/tasks/{task_id}": { "delete": { "operationId": "deleteTask", "parameters": [ { "description": "Typed ID with prefix 'A'", "in": "path", "name": "task_id", "required": true, "schema": { "description": "Typed ID with prefix 'A'", "title": "Task Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Delete task (compat)", "tags": [ "tasks-compat" ] }, "get": { "operationId": "getTask", "parameters": [ { "description": "Typed ID with prefix 'A'", "in": "path", "name": "task_id", "required": true, "schema": { "description": "Typed ID with prefix 'A'", "title": "Task Id", "type": "string" } }, { "description": "Include resolved comments (TIDY-14992 D18). The default compact read carries unresolved discussion only.", "in": "query", "name": "include_resolved", "required": false, "schema": { "default": false, "description": "Include resolved comments (TIDY-14992 D18). The default compact read carries unresolved discussion only.", "title": "Include Resolved", "type": "boolean" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActivityResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get task by ID (compat)", "tags": [ "tasks-compat" ] }, "patch": { "operationId": "updateTaskPatch", "parameters": [ { "description": "Typed ID with prefix 'A'", "in": "path", "name": "task_id", "required": true, "schema": { "description": "Typed ID with prefix 'A'", "title": "Task Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskUpdateCompat" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActivityResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Update task (compat, partial)", "tags": [ "tasks-compat" ] }, "put": { "operationId": "updateTaskPut", "parameters": [ { "description": "Typed ID with prefix 'A'", "in": "path", "name": "task_id", "required": true, "schema": { "description": "Typed ID with prefix 'A'", "title": "Task Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskUpdateCompat" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActivityResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Update task (compat)", "tags": [ "tasks-compat" ] } }, "/api/v1/tasks/{task_id}/approve": { "post": { "operationId": "approveTask3", "parameters": [ { "description": "Typed ID with prefix 'A'", "in": "path", "name": "task_id", "required": true, "schema": { "description": "Typed ID with prefix 'A'", "title": "Task Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActivityResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Approve pending task (compat)", "tags": [ "tasks-compat" ] } }, "/api/v1/tasks/{task_id}/attachments/upload": { "post": { "description": "Register attachment metadata after the client has uploaded bytes.\n\n**Flow (presigned-URL pattern)**:\n\n1. Client requests a presigned upload URL from /api/v1/files/upload-url\n (or equivalent), receives `{upload_url, storage_path}`.\n2. Client PUTs file bytes directly to `upload_url` (object storage).\n3. Client calls THIS endpoint with `storage_path` + file metadata.\n\nBytes are NEVER proxied through api-service — this endpoint only writes\nthe attachment row in `activity_attachments`.", "operationId": "registerTaskAttachment", "parameters": [ { "description": "Typed ID with prefix 'A'", "in": "path", "name": "task_id", "required": true, "schema": { "description": "Typed ID with prefix 'A'", "title": "Task Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskAttachmentUploadRegisterRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActivityAttachmentResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Register an uploaded attachment's metadata", "tags": [ "tasks" ] } }, "/api/v1/tasks/{task_id}/dependencies": { "get": { "description": "Return tasks this task depends on and tasks blocked by this task.\n\nDependencies are stored as linked_references with link_type='depends_on'.\nReturns both directions for UI display.", "operationId": "listTaskDependencies", "parameters": [ { "description": "Typed ID with prefix 'A'", "in": "path", "name": "task_id", "required": true, "schema": { "description": "Typed ID with prefix 'A'", "title": "Task Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskDependenciesResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List dependencies for a task", "tags": [ "tasks" ] }, "post": { "description": "Record that `task_id` depends on `body.depends_on_task_id`.\n\nIdempotent: if the dependency already exists, returns it rather than\ncreating a duplicate (via ON CONFLICT on the unique index).", "operationId": "createTaskDependency", "parameters": [ { "description": "Typed ID with prefix 'A'", "in": "path", "name": "task_id", "required": true, "schema": { "description": "Typed ID with prefix 'A'", "title": "Task Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskDependencyCreate" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskDependencyResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Add a dependency relationship to a task", "tags": [ "tasks" ] } }, "/api/v1/tasks/{task_id}/dependencies/{dep_id}": { "delete": { "description": "Remove a dependency (hard delete of the linked_references row).", "operationId": "deleteTaskDependency", "parameters": [ { "in": "path", "name": "dep_id", "required": true, "schema": { "title": "Dep Id", "type": "string" } }, { "description": "Typed ID with prefix 'A'", "in": "path", "name": "task_id", "required": true, "schema": { "description": "Typed ID with prefix 'A'", "title": "Task Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Remove a task dependency", "tags": [ "tasks" ] } }, "/api/v1/tasks/{task_id}/reject": { "post": { "operationId": "rejectTask3", "parameters": [ { "description": "Typed ID with prefix 'A'", "in": "path", "name": "task_id", "required": true, "schema": { "description": "Typed ID with prefix 'A'", "title": "Task Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Reject pending task (compat)", "tags": [ "tasks-compat" ] } }, "/api/v1/tasks/{task_id}/reminders": { "get": { "description": "List all reminders linked to a task, ordered by reminder_date asc.", "operationId": "listTaskReminders", "parameters": [ { "description": "Typed ID with prefix 'A'", "in": "path", "name": "task_id", "required": true, "schema": { "description": "Typed ID with prefix 'A'", "title": "Task Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskRemindersListResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List reminders for a task", "tags": [ "tasks" ] }, "post": { "description": "Create a reminder linked to the task, stored in `reminders` table\nwith source_type='task' + source_id=task_id, plus a scheduled_events\nentry so the dispatcher delivers at reminder_date.", "operationId": "createTaskReminder", "parameters": [ { "description": "Typed ID with prefix 'A'", "in": "path", "name": "task_id", "required": true, "schema": { "description": "Typed ID with prefix 'A'", "title": "Task Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskReminderCreate" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskReminderResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Create a reminder for a task", "tags": [ "tasks" ] } }, "/api/v1/tasks/{task_id}/reminders/{reminder_id}": { "delete": { "description": "Cancel and delete a task reminder.", "operationId": "deleteTaskReminder", "parameters": [ { "in": "path", "name": "reminder_id", "required": true, "schema": { "title": "Reminder Id", "type": "string" } }, { "description": "Typed ID with prefix 'A'", "in": "path", "name": "task_id", "required": true, "schema": { "description": "Typed ID with prefix 'A'", "title": "Task Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Delete a task reminder", "tags": [ "tasks" ] } }, "/api/v1/tasks/{task_id}/schedule": { "delete": { "description": "Clear start/end timestamps (set both to NULL).", "operationId": "clearTaskSchedule", "parameters": [ { "description": "Typed ID with prefix 'A'", "in": "path", "name": "task_id", "required": true, "schema": { "description": "Typed ID with prefix 'A'", "title": "Task Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActivityResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Clear a task's schedule", "tags": [ "tasks" ] }, "post": { "description": "Set start/end timestamps for a task.\n\nIdempotent: writing the same times returns the activity without a DB\nwrite (ActivityService.update_activity uses IS DISTINCT FROM guards).", "operationId": "scheduleTask", "parameters": [ { "description": "Typed ID with prefix 'A'", "in": "path", "name": "task_id", "required": true, "schema": { "description": "Typed ID with prefix 'A'", "title": "Task Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskScheduleRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActivityResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Schedule a task (set start/end times)", "tags": [ "tasks" ] } }, "/api/v1/tasks/{task_id}/snooze": { "delete": { "description": "Clear the snoozed_until timestamp and cancel the pending unsnooze event.", "operationId": "unsnoozeTask", "parameters": [ { "description": "Typed ID with prefix 'A'", "in": "path", "name": "task_id", "required": true, "schema": { "description": "Typed ID with prefix 'A'", "title": "Task Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActivityResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Un-snooze a task", "tags": [ "tasks" ] }, "post": { "description": "Snooze a task until a specific timestamp or for a duration.\n\nExactly one of `snoozed_until` or `duration_minutes` must be provided.\nA scheduled_event is created to un-snooze the task automatically.", "operationId": "snoozeTask", "parameters": [ { "description": "Typed ID with prefix 'A'", "in": "path", "name": "task_id", "required": true, "schema": { "description": "Typed ID with prefix 'A'", "title": "Task Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskSnoozeRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActivityResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Snooze a task", "tags": [ "tasks" ] } }, "/api/v1/telemetry/interactions": { "post": { "description": "Ingest a batch of interaction events and roll them up transactionally.\n\nReturns 202 (accepted); a replayed ``batch_id`` returns ``duplicate=true``\nwith ``accepted=0`` and writes nothing. ``read_time`` events without a\n``duration_bucket`` carry no engagement signal and are still stored raw but\ncontribute nothing to the rollup.", "operationId": "ingestInteractionBatch", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InteractionBatchIn" } } }, "required": true }, "responses": { "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InteractionBatchResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Ingest Interactions", "tags": [ "telemetry", "telemetry" ], "x-mcp-skip": true } }, "/api/v1/template-installs": { "get": { "operationId": "listTemplateInstalls", "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/InstallListItem" }, "title": "Response Listtemplateinstalls", "type": "array" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List Installs", "tags": [ "template-installs", "template-installs" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "TIDY-14039 apply/install; marketplace MCP tooling is S8/S9" } }, "/api/v1/template-installs/{install_id}": { "get": { "operationId": "getTemplateInstall", "parameters": [ { "in": "path", "name": "install_id", "required": true, "schema": { "format": "uuid", "title": "Install Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InstallResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Install", "tags": [ "template-installs", "template-installs" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "TIDY-14039 apply/install; marketplace MCP tooling is S8/S9" } }, "/api/v1/template-installs/{install_id}/adopt": { "post": { "description": "Instantiate a unit's items into one project — additive and idempotent.", "operationId": "adoptTemplateInstallUnit", "parameters": [ { "in": "path", "name": "install_id", "required": true, "schema": { "format": "uuid", "title": "Install Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdoptUnitRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdoptUnitResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Adopt Unit Endpoint", "tags": [ "template-installs", "template-installs" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "TIDY-14039 apply/install; marketplace MCP tooling is S8/S9" } }, "/api/v1/template-installs/{install_id}/adoptable-units": { "get": { "description": "The units this project can adopt, each with its adoption state + preview.\n\nPure read (TIDY-17037, tier 2): the preview is the conflict probe of the\nreal apply pipeline, so what it lists is what an adopt would do.", "operationId": "listTemplateInstallAdoptableUnits", "parameters": [ { "in": "path", "name": "install_id", "required": true, "schema": { "format": "uuid", "title": "Install Id", "type": "string" } }, { "in": "query", "name": "project_id", "required": true, "schema": { "format": "uuid", "title": "Project Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdoptableUnitsResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Adoptable Units Endpoint", "tags": [ "template-installs", "template-installs" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "TIDY-14039 apply/install; marketplace MCP tooling is S8/S9" } }, "/api/v1/template-installs/{install_id}/migrate": { "post": { "description": "Execute exactly the previewed plan (hash-confirmed) and journal it.", "operationId": "executeTemplateInstallMigration", "parameters": [ { "in": "path", "name": "install_id", "required": true, "schema": { "format": "uuid", "title": "Install Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MigrationExecuteRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MigrationPlanResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Migrate Endpoint", "tags": [ "template-installs", "template-installs" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "TIDY-14039 apply/install; marketplace MCP tooling is S8/S9" } }, "/api/v1/template-installs/{install_id}/migration-plan": { "post": { "description": "The dry-run plan for a migration recipe. Writes NOTHING (TIDY-17037 tier 3).", "operationId": "previewTemplateInstallMigration", "parameters": [ { "in": "path", "name": "install_id", "required": true, "schema": { "format": "uuid", "title": "Install Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MigrationPlanRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MigrationPlanResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Migration Plan Endpoint", "tags": [ "template-installs", "template-installs" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "TIDY-14039 apply/install; marketplace MCP tooling is S8/S9" } }, "/api/v1/template-installs/{install_id}/preview-uninstall": { "post": { "description": "Return the delete/keep/archive ledger WITHOUT mutating anything.", "operationId": "previewUninstallTemplateInstall", "parameters": [ { "in": "path", "name": "install_id", "required": true, "schema": { "format": "uuid", "title": "Install Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UninstallLedgerResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Preview Uninstall Endpoint", "tags": [ "template-installs", "template-installs" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "TIDY-14039 apply/install; marketplace MCP tooling is S8/S9" } }, "/api/v1/template-installs/{install_id}/uninstall": { "post": { "description": "Execute the three-rule uninstall over the manifest.", "operationId": "uninstallTemplateInstall", "parameters": [ { "in": "path", "name": "install_id", "required": true, "schema": { "format": "uuid", "title": "Install Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/api_service__models__template_install__UninstallRequest" }, { "type": "null" } ], "title": "Body" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UninstallResultResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Uninstall Endpoint", "tags": [ "template-installs", "template-installs" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "TIDY-14039 apply/install; marketplace MCP tooling is S8/S9" } }, "/api/v1/templates": { "get": { "operationId": "listTemplates", "parameters": [ { "description": "Filter to templates USABLE BY this facet: its own, those of every facet it inherits from, and those of its descendants", "in": "query", "name": "primitive", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter to templates USABLE BY this facet: its own, those of every facet it inherits from, and those of its descendants", "title": "Primitive" } }, { "description": "Filter by facet slug (exact match)", "in": "query", "name": "facet", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by facet slug (exact match)", "title": "Facet" } }, { "description": "`me` to limit to caller-owned templates", "in": "query", "name": "owner", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "`me` to limit to caller-owned templates", "title": "Owner" } }, { "description": "`private` | `tenant` | `system`", "in": "query", "name": "visibility", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "`private` | `tenant` | `system`", "title": "Visibility" } }, { "description": "`document` | `form` | `report`", "in": "query", "name": "template_kind", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "`document` | `form` | `report`", "title": "Template Kind" } }, { "in": "query", "name": "is_system", "required": false, "schema": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is System" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/TemplateSummary" }, "title": "Response Listtemplates", "type": "array" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "List templates with filters", "tags": [ "templates" ] }, "post": { "operationId": "createTemplate", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateCreateRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateDetail" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Create a new template", "tags": [ "templates" ] } }, "/api/v1/templates/generate": { "post": { "description": "Generate template content via LLM, optionally persisting to `templates`.\n\nWhen `persist=true`:\n * `name` is required (rejected as 422 otherwise)\n * Generated content + layout are saved via `TemplateWriter.create`\n * Response includes `template_id`\n\nWhen `persist=false` (default), behaves like the previous TIDY-5653\ncontract — generated content is returned for the client to persist via\n`POST /api/v1/templates`.", "operationId": "generateTemplate", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateGenerateRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateGenerateResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Generate a template via AI from a natural language prompt", "tags": [ "template-generation" ] } }, "/api/v1/templates/registry/manifest": { "get": { "operationId": "getAgentTemplateManifest", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentTemplateManifest" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Compact agent-template sync manifest (tenant-resolved)", "tags": [ "templates-registry" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/templates/registry/{slug}": { "delete": { "description": "Tenant-scoped removal marker: the manifest keeps serving the entry with\n``status='deprecated'`` so synced stores mark it locally instead of ever\nsilently deleting a file. Global seeds are never mutated — deprecating a\nglobal-only slug mints a tenant head carrying the marker (COW).", "operationId": "deprecateAgentTemplate", "parameters": [ { "in": "path", "name": "slug", "required": true, "schema": { "title": "Slug", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentTemplateManifestEntry" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Deprecate an agent template for this tenant (never deletes history)", "tags": [ "templates-registry" ], "x-local-capability": "cloud", "x-mcp-skip": true }, "get": { "operationId": "getAgentTemplate", "parameters": [ { "in": "path", "name": "slug", "required": true, "schema": { "title": "Slug", "type": "string" } }, { "in": "query", "name": "version", "required": false, "schema": { "anyOf": [ { "minimum": 1, "type": "integer" }, { "type": "null" } ], "title": "Version" } }, { "description": "Force 'tenant' or 'global' tier", "in": "query", "name": "scope", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Force 'tenant' or 'global' tier", "title": "Scope" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentTemplateContent" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get an agent template body (head, or ?version=N preview)", "tags": [ "templates-registry" ], "x-local-capability": "cloud", "x-mcp-skip": true }, "put": { "operationId": "pushAgentTemplate", "parameters": [ { "in": "path", "name": "slug", "required": true, "schema": { "title": "Slug", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentTemplatePushRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentTemplatePushResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Create/revise an agent template (appends a new version)", "tags": [ "templates-registry" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/templates/registry/{slug}/rollback": { "post": { "operationId": "rollbackAgentTemplate", "parameters": [ { "in": "path", "name": "slug", "required": true, "schema": { "title": "Slug", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentTemplateRollbackRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentTemplatePushResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Re-approve a prior version as the new head (new version row)", "tags": [ "templates-registry" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/templates/registry/{slug}/versions": { "get": { "operationId": "listAgentTemplateVersions", "parameters": [ { "in": "path", "name": "slug", "required": true, "schema": { "title": "Slug", "type": "string" } }, { "in": "query", "name": "scope", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Scope" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentTemplateVersionsResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Attributable version history (who/when/what hash)", "tags": [ "templates-registry" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/templates/{template_id}": { "delete": { "operationId": "deleteTemplate", "parameters": [ { "in": "path", "name": "template_id", "required": true, "schema": { "format": "uuid", "title": "Template Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FormDeleteResponse" } } }, "description": "Successful Response" }, "409": { "description": "The template is bound to a surface and has no source to hand it to (`form_bound`); reassign those surfaces first." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Soft-delete a template; its surface bindings return to the template it was forked from", "tags": [ "templates" ] }, "get": { "operationId": "getTemplate", "parameters": [ { "in": "path", "name": "template_id", "required": true, "schema": { "format": "uuid", "title": "Template Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateDetail" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Get a template (full body + version list)", "tags": [ "templates" ] }, "patch": { "operationId": "updateTemplate", "parameters": [ { "in": "path", "name": "template_id", "required": true, "schema": { "format": "uuid", "title": "Template Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateUpdateRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateDetail" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Update template metadata (name / visibility / layout)", "tags": [ "templates" ] } }, "/api/v1/templates/{template_id}/fork": { "post": { "operationId": "forkTemplate", "parameters": [ { "in": "path", "name": "template_id", "required": true, "schema": { "format": "uuid", "title": "Template Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateForkRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateDetail" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Fork a template into the caller's private scope", "tags": [ "templates" ] } }, "/api/v1/templates/{template_id}/instantiate": { "post": { "description": "Run the server-side instantiation factory.\n\nThe endpoint gates on ``templates:read`` (the caller must be allowed to\nsee the template). The downstream primitive write is authorized by\ntable-level RLS plus the factory's tenant-scoped INSERT — there is no\nsecondary capability check here because creating a primitive from a\ntemplate the caller can already see is the same action as creating\nthat primitive directly.", "operationId": "instantiateTemplate", "parameters": [ { "in": "path", "name": "template_id", "required": true, "schema": { "format": "uuid", "title": "Template Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateInstantiateRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateInstantiateResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Instantiate a template into a new primitive instance", "tags": [ "templates" ] } }, "/api/v1/templates/{template_id}/instantiate-embed": { "post": { "description": "Materialize a single embed under an already-instantiated parent.\n\nTwo shapes (exactly one per call):\n\n* Legacy retry (TIDY-8978): ``parent_primitive_id`` + ``embed_spec`` —\n the AutoCreateBanner's per-failure Retry button; stateless against the\n template body, dispatches to ``create_child_facet``.\n* Form lazy reveal (TIDY-14395, S7 contract): ``parent_record_id`` +\n ``embed_node_id`` (+ optional ``title``) — idempotent per\n ``(parent, node)``: retry-safe, returns the existing child if already\n born; child + ``_form_embeds`` ledger + ``parent_of`` edge land\n atomically, read from the run's PINNED snapshot.\n\n`template_id` is in the URL for audit / scoping.", "operationId": "instantiateTemplateEmbed", "parameters": [ { "in": "path", "name": "template_id", "required": true, "schema": { "format": "uuid", "title": "Template Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateInstantiateEmbedRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateInstantiateEmbedResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Materialize a single missing child facet under a parent (auto-create retry)", "tags": [ "templates" ] } }, "/api/v1/templates/{template_id}/rewrite": { "post": { "description": "Run the LLM rewrite-with-template flow.\n\nGates on ``templates:read`` (the caller must already be allowed to see\nthe template). The LLM call is server-side via LiteLLM so secrets and\nrate-limits stay with the proxy. Failures (timeout, 5xx from LLM,\nparse error) all raise — there is no silent fallback per R26.", "operationId": "rewriteWithTemplate", "parameters": [ { "in": "path", "name": "template_id", "required": true, "schema": { "format": "uuid", "title": "Template Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateRewriteRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateRewriteResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Restructure user content into a template's section structure", "tags": [ "templates" ] } }, "/api/v1/templates/{template_id}/updates": { "post": { "operationId": "writeTemplateUpdate", "parameters": [ { "in": "path", "name": "template_id", "required": true, "schema": { "format": "uuid", "title": "Template Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateUpdateBlobRequest" } } }, "required": true }, "responses": { "204": { "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Write a yjs_state snapshot for a template", "tags": [ "templates" ] } }, "/api/v1/templates/{template_id}/versions": { "get": { "operationId": "listTemplateVersions", "parameters": [ { "in": "path", "name": "template_id", "required": true, "schema": { "format": "uuid", "title": "Template Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/TemplateVersionSummary" }, "title": "Response Listtemplateversions", "type": "array" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "List named save points for a template", "tags": [ "templates" ] }, "post": { "operationId": "createTemplateVersion", "parameters": [ { "in": "path", "name": "template_id", "required": true, "schema": { "format": "uuid", "title": "Template Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateVersionCreateRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateVersionSummary" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Create a named save point", "tags": [ "templates" ] } }, "/api/v1/templates/{template_id}/versions/{version_id}": { "get": { "description": "Return a version's immutable snapshot content (TIDY-14394 P4).\n\nThe generic form viewer renders the snapshot a record run is pinned to\n(`_form_template_version_id`). Visibility mirrors the versions list:\nparent template must be visible AND the version row must pass the same\nsystem/tenant/private predicate.", "operationId": "getTemplateVersion", "parameters": [ { "in": "path", "name": "template_id", "required": true, "schema": { "format": "uuid", "title": "Template Id", "type": "string" } }, { "in": "path", "name": "version_id", "required": true, "schema": { "format": "uuid", "title": "Version Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateVersionDetail" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Fetch one template version snapshot with its content", "tags": [ "templates" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Form-viewer pinned-snapshot content read (TIDY-14394); no MCP template tooling yet." } }, "/api/v1/templates/{template_id}/versions/{version_id}/restore": { "post": { "operationId": "restoreTemplateVersion", "parameters": [ { "in": "path", "name": "template_id", "required": true, "schema": { "format": "uuid", "title": "Template Id", "type": "string" } }, { "in": "path", "name": "version_id", "required": true, "schema": { "format": "uuid", "title": "Version Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateDetail" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Restore a template body from a saved version", "tags": [ "templates" ] } }, "/api/v1/tenant-default-employee": { "get": { "operationId": "getTenantDefaultEmployee", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantDefaultEmployeeResponse" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Tenant Default Employee", "tags": [ "user-preferences" ], "x-local-capability": "local", "x-mcp-skip": true, "x-mcp-skip-reason": "Workspace routing administration" }, "put": { "operationId": "setTenantDefaultEmployee", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DefaultEmployeeRef" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantDefaultEmployeeResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Set Tenant Default Employee", "tags": [ "user-preferences" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Workspace routing administration" } }, "/api/v1/tenant/feature-settings": { "get": { "operationId": "getTenantFeatureSettings", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantFeatureSettingsResponse" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Read the tenant's feature settings", "tags": [ "tenant-feature-settings" ], "x-local-capability": "local", "x-mcp-skip": true }, "put": { "operationId": "updateTenantFeatureSettings", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateTenantFeatureSettingsRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantFeatureSettingsResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Update the tenant's feature settings (tenant Owner/Admin only)", "tags": [ "tenant-feature-settings" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/tenant/feature-settings/evaluated": { "get": { "operationId": "getEvaluatedFeatureSwitches", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EvaluatedFeatureSwitchesResponse" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "THE evaluation seam's answer for every registered switch, for the caller's tenant", "tags": [ "tenant-feature-settings" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/tenant/spend-cap": { "get": { "operationId": "getTenantSpendCap", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SpendCapResponse" } } }, "description": "Successful Response" } }, "summary": "Get Spend Cap", "tags": [ "tenant-spend-cap", "tenant-spend-cap" ] }, "post": { "operationId": "setTenantSpendCap", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SpendCapCreate" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SpendCapResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Set Spend Cap", "tags": [ "tenant-spend-cap", "tenant-spend-cap" ] } }, "/api/v1/tenant/spend-cap/override": { "post": { "description": "Owner-only override — clears the 402 gate for the current cycle.", "operationId": "overrideTenantSpendCap", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SpendCapResponse" } } }, "description": "Successful Response" } }, "summary": "Override Spend Cap", "tags": [ "tenant-spend-cap", "tenant-spend-cap" ] } }, "/api/v1/tenant/ve-work-policy": { "get": { "operationId": "getTenantVeWorkPolicy", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantVeWorkPolicyResponse" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "The workspace's default work policy for virtual employees", "tags": [ "agents", "Agents" ], "x-local-capability": "cloud", "x-mcp-skip": true }, "put": { "operationId": "setTenantVeWorkPolicy", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantVeWorkPolicyRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantVeWorkPolicyResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Set the workspace's default work policy (tenant Owner/Admin only)", "tags": [ "agents", "Agents" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/tenants": { "get": { "description": "List all active or suspended tenants for authenticated user.\n\n Query Parameters:\n status: Filter by status ('active' or 'suspended'), default: 'active'\n limit: Max results (1-1000), default: 100\n offset: Pagination offset, default: 0\n\n Returns:\n {\n \"tenants\": [...],\n \"count\": 2\n }\n\n RLS: Only returns tenants where user is associated.\n Cached: Response cached for 5 minutes.\n\n Related: FR-013, FR-023, KCC-1156", "operationId": "listTenants2", "parameters": [ { "in": "query", "name": "status", "required": false, "schema": { "default": "active", "title": "Status", "type": "string" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 100, "maximum": 1000, "minimum": 1, "title": "Limit", "type": "integer" } }, { "in": "query", "name": "offset", "required": false, "schema": { "default": 0, "minimum": 0, "title": "Offset", "type": "integer" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Listtenants2", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List tenants for authenticated user", "tags": [ "tenants", "Tenants" ] }, "post": { "description": "Create a new tenant (family organization).\n\n Used by:\n 1. **Admin Manual Creation**: POST with admin role\n 2. **Auto-Provisioning**: Called from Supabase Auth webhook on signup\n\n Request:\n {\n \"display_name\": \"The Smith Family\",\n \"account_type\": \"household\"\n }\n\n Response (201 Created):\n {\n \"tenant_id\": \"a1b2c3d4-e5f6-4789-abcd-ef1234567890\",\n \"display_name\": \"The Smith Family\",\n \"status\": \"active\",\n \"role\": \"owner\",\n \"member_count\": 1,\n \"account_type\": \"household\",\n \"created_at\": \"2025-11-08T14:30:22.123Z\",\n \"updated_at\": \"2025-11-08T14:30:22.123Z\"\n }\n\n Validation Rules:\n - display_name: 1-255 characters, non-empty\n - Creator (account_id from JWT) becomes Owner role\n - Tenant status defaults to 'active'\n\n Error Responses:\n - 400 Bad Request: Invalid display_name (empty, too long, invalid characters)\n - 401 Unauthorized: Missing or invalid JWT token\n - 500 Internal Server Error: Database operation failed\n\n Related: FR-004, FR-010, KCC-1150, KCC-1152", "operationId": "createTenant", "parameters": [ { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantCreate" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Create new tenant", "tags": [ "tenants" ] } }, "/api/v1/tenants/associations": { "get": { "description": "List all tenants the user is associated with, including their role in each.\n\n Returns tenant membership information with:\n - tenant_id, tenant_name\n - role (owner, member, viewer)\n - status (active, suspended)\n - is_active (whether this is currently active tenant)\n - last_active_at timestamp\n\n Related: 011-auth-user-onboarding T080", "operationId": "listTenantAssociations", "parameters": [ { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantAssociationsResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List user's tenant associations", "tags": [ "tenants" ] } }, "/api/v1/tenants/mailbox": { "get": { "description": "Get the tenant's KCC mailbox information.\n\n Returns the email address if one has been claimed, or empty if not.\n\n Related: 011-auth-user-onboarding", "operationId": "getTenantMailbox", "parameters": [ { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantMailboxResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get tenant mailbox info", "tags": [ "onboarding" ] } }, "/api/v1/tenants/provision": { "post": { "description": "Provision a new tenant for user after OAuth authentication.\n\n This endpoint is called by the frontend after successful OAuth callback\n to create the tenant, assign ownership, generate mailbox email, and\n provision Supabase Storage folders.\n\n Request:\n {\n \"display_name\": \"The Smith Family\" # Optional, defaults to user's name\n }\n\n Response (201 Created):\n {\n \"tenant_id\": \"550e8400-e29b-41d4-a716-446655440000\",\n \"display_name\": \"The Smith Family\",\n \"mailbox_email\": \"7c9e6679-7425-40de-944b-e07fc1f90ae7@mail.tidy.engineering\",\n \"role\": \"Owner\",\n \"created_at\": \"2025-11-15T10:30:00Z\"\n }\n\n Operations Performed:\n 1. Generate UUID v4 for tenant_id\n 2. Insert into tenants table\n 3. Insert into person_account_memberships (role: Owner)\n 4. Generate UUID for mailbox email address\n 5. Insert into mailbox_tokens table\n 6. Create storage folders: {tenant_id}/raw_emails/, attachments/, profile_pictures/\n\n Error Responses:\n - 400 Bad Request: Invalid display_name\n - 401 Unauthorized: Missing or invalid Supabase session bearer\n - 403 Forbidden: Invite gate refusal — {code: invite_required |\n code_invalid | code_deactivated | code_expired} (TIDY-12617)\n - 409 Conflict: Tenant already exists for this account, or\n {code: code_already_redeemed} for a spent invite code\n - 500 Internal Server Error: Database or storage operation failed\n\n Auth: Bootstrap surface — accepts the Supabase session bearer\n directly (one of two such surfaces; the other is\n /api/v1/auth/session/exchange). New users with no tenant cannot yet\n have a Tidy JWT, so the legacy Supabase token is the only credential\n they can present. Every other /api/v1/* endpoint requires a Tidy ES256\n bearer obtained via /auth/session/exchange after provisioning succeeds.\n\n Related: oauth-authentication-spec.md Feature 2, TIDY-7633", "operationId": "provisionTenant", "parameters": [ { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantProvisionRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantProvisionResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Provision tenant on OAuth sign-up", "tags": [ "provisioning" ] } }, "/api/v1/tenants/switch": { "post": { "description": "Switch the user's active tenant context.\n\n Updates:\n - person_account_memberships.is_primary to mark new tenant as active\n - person_account_memberships.last_active_at for tracking\n\n User must be associated with the target tenant.\n\n Related: 011-auth-user-onboarding T081, T082", "operationId": "switchTenant", "parameters": [ { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantSwitchRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantSwitchResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Switch active tenant", "tags": [ "tenants" ] } }, "/api/v1/tenants/{tenant_id}": { "delete": { "description": "Soft delete tenant (set status='deleted', owner-only).\n\n Permissions (T058):\n Only Owners can delete (canDeleteTenant=true).\n Members and Viewers receive 403 Forbidden.\n\n Role Permissions:\n - Owner: canDeleteTenant=true\n - Member: canDeleteTenant=false\n - Viewer: canDeleteTenant=false\n\n Soft Deletion:\n Sets status='deleted' (not removed from DB).\n Preserved for 90-day retention audit trail.\n\n Related: FR-007, KCC-1162, T058", "operationId": "deleteTenant", "parameters": [ { "in": "path", "name": "tenant_id", "required": true, "schema": { "title": "Tenant Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "204": { "description": "Successful Response" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "The workspace does not exist, or the caller is not an ACTIVE member of it (TIDY-20190)." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Soft delete tenant", "tags": [ "tenants" ] }, "get": { "description": "Retrieve details for a specific tenant.\n\n Returns tenant information including member count.\n User's role is included if user is associated with the tenant.\n\n Response:\n {\n \"tenant_id\": \"a1b2c3d4-e5f6-4789-abcd-ef1234567890\",\n \"display_name\": \"The Smith Family\",\n \"status\": \"active\",\n \"role\": \"owner\",\n \"member_count\": 3,\n \"created_at\": \"2025-11-08T14:30:22.123Z\",\n \"updated_at\": \"2025-11-08T15:45:00.456Z\"\n }\n\n Error Responses:\n - 401 Unauthorized: Missing or invalid JWT token\n - 404 Not Found: Tenant does not exist, or the caller is not an active member of it\n - 500 Internal Server Error: Database operation failed\n\n Related: FR-005, KCC-1152", "operationId": "getTenant", "parameters": [ { "in": "path", "name": "tenant_id", "required": true, "schema": { "title": "Tenant Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantResponse" } } }, "description": "Successful Response" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "The workspace does not exist, or the caller is not an ACTIVE member of it — a non-member's answer is indistinguishable from a missing workspace (TIDY-20190)." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get tenant details", "tags": [ "tenants" ] }, "patch": { "description": "Update tenant display_name or status (owner-only).\n\n Request:\n {\n \"display_name\": \"Smith-Jones Family\",\n \"status\": \"active|suspended|deleted\"\n }\n\n Permissions (T058):\n Only Owners can update (canUpdateTenant=true).\n Members and Viewers receive 403 Forbidden.\n\n Role Permissions:\n - Owner: canUpdateTenant=true\n - Member: canUpdateTenant=false\n - Viewer: canUpdateTenant=false\n\n Related: FR-006, KCC-1160, T058", "operationId": "updateTenant", "parameters": [ { "in": "path", "name": "tenant_id", "required": true, "schema": { "title": "Tenant Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantUpdate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantResponse" } } }, "description": "Successful Response" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "The workspace does not exist, or the caller is not an ACTIVE member of it (TIDY-20190)." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Update tenant", "tags": [ "tenants" ] } }, "/api/v1/tenants/{tenant_id}/agents": { "get": { "operationId": "listTenantAgents", "parameters": [ { "description": "Tenant public id or UUID", "in": "path", "name": "tenant_id", "required": true, "schema": { "description": "Tenant public id or UUID", "title": "Tenant Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentStatusListResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List virtual employee agent status", "tags": [ "agents", "Agents" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Workspace admin provisioning/status API for browser UI and local connector setup." }, "post": { "operationId": "provisionTenantAgent", "parameters": [ { "description": "Tenant public id or UUID", "in": "path", "name": "tenant_id", "required": true, "schema": { "description": "Tenant public id or UUID", "title": "Tenant Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentProvisionRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentProvisionResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Provision a virtual employee agent", "tags": [ "agents", "Agents" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Workspace admin provisioning/status API for browser UI and local connector setup." } }, "/api/v1/tenants/{tenant_id}/agents/autonomy": { "get": { "description": "The operator status board's data — TIDY-16413 (A9).\n\nOne row per VE: its derived autonomy state, wake schedule, current item,\nlast wake decision, and trailing-24h wakes/tokens/cost. The state is a\nread-time projection (never a stored second authority), and the same\nresponse feeds the web board and the Android roster chips so the two\nsurfaces cannot drift in vocabulary.", "operationId": "listTenantAgentAutonomy", "parameters": [ { "description": "Tenant public id or UUID", "in": "path", "name": "tenant_id", "required": true, "schema": { "description": "Tenant public id or UUID", "title": "Tenant Id", "type": "string" } }, { "in": "query", "name": "window_hours", "required": false, "schema": { "default": 24, "maximum": 168, "minimum": 1, "title": "Window Hours", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentAutonomyListResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Virtual employee autonomy telemetry (operator status board)", "tags": [ "agents", "Agents" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Workspace admin provisioning/status API for browser UI and local connector setup." } }, "/api/v1/tenants/{tenant_id}/agents/liveness": { "get": { "description": "Surfaces each virtual employee's heartbeat staleness + pending un-acted\nmentions (D5). A mention delivered to a stale/offline runtime is NOT lost —\nit persists in the inbox and is caught up when the runtime returns.", "operationId": "listTenantAgentLiveness", "parameters": [ { "description": "Tenant public id or UUID", "in": "path", "name": "tenant_id", "required": true, "schema": { "description": "Tenant public id or UUID", "title": "Tenant Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentRuntimeLivenessListResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Virtual employee runtime liveness (heartbeat staleness)", "tags": [ "agents", "Agents" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Workspace admin provisioning/status API for browser UI and local connector setup." } }, "/api/v1/tenants/{tenant_id}/agents/{account_id}": { "delete": { "operationId": "removeTenantAgent", "parameters": [ { "description": "Tenant public id or UUID", "in": "path", "name": "tenant_id", "required": true, "schema": { "description": "Tenant public id or UUID", "title": "Tenant Id", "type": "string" } }, { "description": "Virtual employee account UUID", "in": "path", "name": "account_id", "required": true, "schema": { "description": "Virtual employee account UUID", "title": "Account Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentLifecycleResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Remove a virtual employee connector", "tags": [ "agents", "Agents" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Workspace admin provisioning/status API for browser UI and local connector setup." } }, "/api/v1/tenants/{tenant_id}/agents/{account_id}/approval-grants": { "get": { "operationId": "listAgentApprovalGrants", "parameters": [ { "description": "Tenant public id or UUID", "in": "path", "name": "tenant_id", "required": true, "schema": { "description": "Tenant public id or UUID", "title": "Tenant Id", "type": "string" } }, { "description": "Virtual employee account UUID", "in": "path", "name": "account_id", "required": true, "schema": { "description": "Virtual employee account UUID", "title": "Account Id", "type": "string" } }, { "description": "Include conversation-scoped grants alongside standing ones", "in": "query", "name": "include_session", "required": false, "schema": { "default": true, "description": "Include conversation-scoped grants alongside standing ones", "title": "Include Session", "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalGrantListResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List a virtual employee's live approval grants", "tags": [ "agents", "Agents" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Virtual-employee authorization surface for the settings UI and the local connector — never an assistant-callable tool." } }, "/api/v1/tenants/{tenant_id}/agents/{account_id}/approval-grants/{grant_id}": { "delete": { "operationId": "revokeAgentApprovalGrant", "parameters": [ { "in": "path", "name": "tenant_id", "required": true, "schema": { "title": "Tenant Id", "type": "string" } }, { "in": "path", "name": "account_id", "required": true, "schema": { "title": "Account Id", "type": "string" } }, { "in": "path", "name": "grant_id", "required": true, "schema": { "title": "Grant Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalGrantRevokeResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Revoke an approval grant", "tags": [ "agents", "Agents" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Virtual-employee authorization surface for the settings UI and the local connector — never an assistant-callable tool." } }, "/api/v1/tenants/{tenant_id}/agents/{account_id}/approval-settings": { "get": { "operationId": "getAgentApprovalSettings", "parameters": [ { "in": "path", "name": "tenant_id", "required": true, "schema": { "title": "Tenant Id", "type": "string" } }, { "in": "path", "name": "account_id", "required": true, "schema": { "title": "Account Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalSettingsResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get a virtual employee's approval settings", "tags": [ "agents", "Agents" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Virtual-employee authorization surface for the settings UI and the local connector — never an assistant-callable tool." }, "patch": { "operationId": "updateAgentApprovalSettings", "parameters": [ { "in": "path", "name": "tenant_id", "required": true, "schema": { "title": "Tenant Id", "type": "string" } }, { "in": "path", "name": "account_id", "required": true, "schema": { "title": "Account Id", "type": "string" } }, { "in": "header", "name": "X-Tidy-Acting-Principal", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tidy-Acting-Principal" } }, { "in": "header", "name": "X-Internal-Service", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service" } }, { "in": "header", "name": "X-Internal-Service-Key", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service-Key" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalSettingsRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalSettingsResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Change an employee's approval and authority settings", "tags": [ "agents", "Agents" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Virtual-employee authorization surface for the settings UI and the local connector — never an assistant-callable tool." } }, "/api/v1/tenants/{tenant_id}/agents/{account_id}/command-policy/rules": { "post": { "operationId": "addAgentCommandPolicyRule", "parameters": [ { "in": "path", "name": "tenant_id", "required": true, "schema": { "title": "Tenant Id", "type": "string" } }, { "description": "Virtual employee account UUID", "in": "path", "name": "account_id", "required": true, "schema": { "description": "Virtual employee account UUID", "title": "Account Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommandPolicyRuleRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommandPolicyRule" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Add a per-employee command-policy rule", "tags": [ "agents", "Agents" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Virtual-employee authorization surface for the settings UI and the local connector — never an assistant-callable tool." } }, "/api/v1/tenants/{tenant_id}/agents/{account_id}/consumer-lease": { "get": { "operationId": "getTenantAgentConsumerLease", "parameters": [ { "in": "path", "name": "tenant_id", "required": true, "schema": { "title": "Tenant Id", "type": "string" } }, { "in": "path", "name": "account_id", "required": true, "schema": { "title": "Account Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConsumerLeaseStatusResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Tenant Agent Consumer Lease", "tags": [ "agents", "Agents" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Workspace admin provisioning/status API for browser UI and local connector setup." } }, "/api/v1/tenants/{tenant_id}/agents/{account_id}/credential-recovery": { "post": { "operationId": "issueTenantAgentCredentialRecovery", "parameters": [ { "in": "path", "name": "tenant_id", "required": true, "schema": { "title": "Tenant Id", "type": "string" } }, { "in": "path", "name": "account_id", "required": true, "schema": { "title": "Account Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CredentialRecoveryRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CredentialRecoveryTokenResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Issue Tenant Agent Credential Recovery", "tags": [ "agents", "Agents" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Workspace admin provisioning/status API for browser UI and local connector setup." } }, "/api/v1/tenants/{tenant_id}/agents/{account_id}/elevation": { "post": { "description": "Record the owner's intent; the host converges on it via its heartbeat.\n\nThis endpoint deliberately does NOT reach the machine. It writes intent, and\nthe connector — which is outbound-only — collects it on its next heartbeat\nand reconfigures itself. So a 200 here means \"recorded\", never \"applied\",\nand the response says which by carrying the applied state separately.", "operationId": "setTenantAgentElevation", "parameters": [ { "description": "Tenant public id or UUID", "in": "path", "name": "tenant_id", "required": true, "schema": { "description": "Tenant public id or UUID", "title": "Tenant Id", "type": "string" } }, { "description": "Virtual employee account UUID", "in": "path", "name": "account_id", "required": true, "schema": { "description": "Virtual employee account UUID", "title": "Account Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentElevationRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentElevationResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Set whether a virtual employee may elevate on its host", "tags": [ "agents", "Agents" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Workspace admin provisioning/status API for browser UI and local connector setup." } }, "/api/v1/tenants/{tenant_id}/agents/{account_id}/force-takeover": { "post": { "operationId": "forceTakeoverTenantAgentConnector", "parameters": [ { "in": "path", "name": "tenant_id", "required": true, "schema": { "title": "Tenant Id", "type": "string" } }, { "in": "path", "name": "account_id", "required": true, "schema": { "title": "Account Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForceTakeoverRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForceTakeoverResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Force Takeover Tenant Agent Connector", "tags": [ "agents", "Agents" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Workspace admin provisioning/status API for browser UI and local connector setup." } }, "/api/v1/tenants/{tenant_id}/agents/{account_id}/git-identity": { "put": { "description": "Store the overrides; the host collects the RESOLVED identity on its next\nheartbeat (within a minute) and applies it to subsequent commits.\n\nWhole-value semantics — a null field clears that override back to the\ndefault (the VE's own name / ``<slug>@ve.<app_hostname>``), which is also\nwhat every employee provisioned before this endpoint existed already uses.", "operationId": "setTenantAgentGitIdentity", "parameters": [ { "description": "Tenant public id or UUID", "in": "path", "name": "tenant_id", "required": true, "schema": { "description": "Tenant public id or UUID", "title": "Tenant Id", "type": "string" } }, { "description": "Virtual employee account UUID", "in": "path", "name": "account_id", "required": true, "schema": { "description": "Virtual employee account UUID", "title": "Account Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentGitIdentityRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentGitIdentityResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Set a virtual employee's commit author identity", "tags": [ "agents", "Agents" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Workspace admin provisioning/status API for browser UI and local connector setup." } }, "/api/v1/tenants/{tenant_id}/agents/{account_id}/github-access": { "put": { "deprecated": true, "description": "Refused, in words that name the gesture that replaced it (TIDY-20066 F1).\n\nThe employee's source-control sign-in follows the plugins it is given: a\nGive of a GitHub or GitLab plugin from the plugin's Access section signs\ngit in on its workshop, and Take back signs it out\n(``ve_scm_access.sync_from_lends``). This per-employee consent was a second\nauthority beside the lend, so it no longer decides anything and nothing\nmay write it. The operation stays in the contract, answering 410, for a\nclient built before the change — a desktop build that has not taken this\nweb release yet; remove it once none can call it.", "operationId": "setTenantAgentGitHubAccess", "parameters": [ { "description": "Tenant public id or UUID", "in": "path", "name": "tenant_id", "required": true, "schema": { "description": "Tenant public id or UUID", "title": "Tenant Id", "type": "string" } }, { "description": "Virtual employee account UUID", "in": "path", "name": "account_id", "required": true, "schema": { "description": "Virtual employee account UUID", "title": "Account Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentGitHubAccessRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentGitHubAccessResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Retired: give the employee a source-control plugin instead", "tags": [ "agents", "Agents" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Workspace admin provisioning/status API for browser UI and local connector setup." } }, "/api/v1/tenants/{tenant_id}/agents/{account_id}/heartbeat": { "get": { "description": "TIDY-16406 (A2): per-VE heartbeat settings + the tenant kill switch.", "operationId": "getTenantAgentHeartbeatSettings", "parameters": [ { "description": "Tenant public id or UUID", "in": "path", "name": "tenant_id", "required": true, "schema": { "description": "Tenant public id or UUID", "title": "Tenant Id", "type": "string" } }, { "description": "Virtual employee account UUID", "in": "path", "name": "account_id", "required": true, "schema": { "description": "Virtual employee account UUID", "title": "Account Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentHeartbeatSettingsResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Read a virtual employee's work-heartbeat settings", "tags": [ "agents", "Agents" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Workspace admin provisioning/status API for browser UI and local connector setup." }, "post": { "description": "TIDY-16406 (A2): write the owner's heartbeat settings.\n\nThe evaluator (assistant-service's ve-autonomy Temporal lane) reads these\ncolumns on every tick, and its reconciler converges workflows within its\ninterval — so a 200 means \"recorded\", with the evaluator honoring it on the\nnext evaluation. The tenant kill switch stays authoritative: with\n``ve_autonomy_heartbeat_enabled`` off, an enabled employee still gets zero\nwakes (fail-closed).", "operationId": "setTenantAgentHeartbeatSettings", "parameters": [ { "description": "Tenant public id or UUID", "in": "path", "name": "tenant_id", "required": true, "schema": { "description": "Tenant public id or UUID", "title": "Tenant Id", "type": "string" } }, { "description": "Virtual employee account UUID", "in": "path", "name": "account_id", "required": true, "schema": { "description": "Virtual employee account UUID", "title": "Account Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentHeartbeatSettingsRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentHeartbeatSettingsResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Set a virtual employee's work-heartbeat settings", "tags": [ "agents", "Agents" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Workspace admin provisioning/status API for browser UI and local connector setup." } }, "/api/v1/tenants/{tenant_id}/agents/{account_id}/heartbeat/rearm": { "post": { "description": "TIDY-16414 (A10): the owner says \"keep going\" after a cap tripped.\n\nSeparate from the settings POST on purpose. Editing a cap is a\nconfiguration change; clearing the latch is an acknowledgement — the one\nexplicit human act the design requires, and folding it into a settings save\nwould let a routine edit silently resume spending.\n\nIdempotent: re-arming a VE that is not tripped returns the current state,\nso a double-click cannot un-degrade a VE the error classifier paused.", "operationId": "rearmTenantAgentAutonomy", "parameters": [ { "description": "Tenant public id or UUID", "in": "path", "name": "tenant_id", "required": true, "schema": { "description": "Tenant public id or UUID", "title": "Tenant Id", "type": "string" } }, { "description": "Virtual employee account UUID", "in": "path", "name": "account_id", "required": true, "schema": { "description": "Virtual employee account UUID", "title": "Account Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentHeartbeatSettingsResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Clear a virtual employee's autonomy cap trip", "tags": [ "agents", "Agents" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Workspace admin provisioning/status API for browser UI and local connector setup." } }, "/api/v1/tenants/{tenant_id}/agents/{account_id}/home-room-log": { "get": { "description": "The home room's back-channel timeline, newest first — TIDY-16782 (D3).\n\nThe home room is the system back channel: wakes, work orders, directives,\ncompletion reports, and the connector's system notices (upgrade notes, the\nhome-room turn refusal). No human is a member and the room is plaintext by\ndesign, so this admin-read projection is the ONLY inspection surface the\nhome-base Log tab has for it.", "operationId": "listTenantAgentHomeRoomLog", "parameters": [ { "description": "Tenant public id or UUID", "in": "path", "name": "tenant_id", "required": true, "schema": { "description": "Tenant public id or UUID", "title": "Tenant Id", "type": "string" } }, { "description": "Virtual employee account UUID", "in": "path", "name": "account_id", "required": true, "schema": { "description": "Virtual employee account UUID", "title": "Account Id", "type": "string" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "maximum": 100, "minimum": 1, "title": "Limit", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentHomeRoomLogResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Virtual employee home-room back-channel log", "tags": [ "agents", "Agents" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Workspace admin provisioning/status API for browser UI and local connector setup." } }, "/api/v1/tenants/{tenant_id}/agents/{account_id}/host-rebind": { "post": { "operationId": "rebindTenantAgentConnectorHost", "parameters": [ { "in": "path", "name": "tenant_id", "required": true, "schema": { "title": "Tenant Id", "type": "string" } }, { "in": "path", "name": "account_id", "required": true, "schema": { "title": "Account Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HostRebindRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HostRebindResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Rebind Tenant Agent Connector Host", "tags": [ "agents", "Agents" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Workspace admin provisioning/status API for browser UI and local connector setup." } }, "/api/v1/tenants/{tenant_id}/agents/{account_id}/reconnect": { "post": { "operationId": "reconnectTenantAgent", "parameters": [ { "description": "Tenant public id or UUID", "in": "path", "name": "tenant_id", "required": true, "schema": { "description": "Tenant public id or UUID", "title": "Tenant Id", "type": "string" } }, { "description": "Virtual employee account UUID", "in": "path", "name": "account_id", "required": true, "schema": { "description": "Virtual employee account UUID", "title": "Account Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/AgentReconnectRequest" }, { "type": "null" } ], "title": "Body" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentProvisionResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Reconnect a virtual employee connector", "tags": [ "agents", "Agents" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Workspace admin provisioning/status API for browser UI and local connector setup." } }, "/api/v1/tenants/{tenant_id}/agents/{account_id}/rehome-workshop-installation": { "post": { "description": "Owner-confirmed takeover of a foreign-principal portable installation\ninto its workshop's resident daemon (TIDY-18675). Fences the old consumer\nand re-points the installation so the next ordinary deploy claims it.", "operationId": "rehomeTenantAgentWorkshopInstallation", "parameters": [ { "in": "path", "name": "tenant_id", "required": true, "schema": { "title": "Tenant Id", "type": "string" } }, { "in": "path", "name": "account_id", "required": true, "schema": { "title": "Account Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RehomeInstallationRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RehomeInstallationResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Rehome Tenant Agent Workshop Installation", "tags": [ "agents", "Agents" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Workspace admin provisioning/status API for browser UI and local connector setup." } }, "/api/v1/tenants/{tenant_id}/agents/{account_id}/revoke": { "post": { "operationId": "revokeTenantAgent", "parameters": [ { "description": "Tenant public id or UUID", "in": "path", "name": "tenant_id", "required": true, "schema": { "description": "Tenant public id or UUID", "title": "Tenant Id", "type": "string" } }, { "description": "Virtual employee account UUID", "in": "path", "name": "account_id", "required": true, "schema": { "description": "Virtual employee account UUID", "title": "Account Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/AgentLifecycleRequest" }, { "type": "null" } ], "title": "Body" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentLifecycleResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Revoke a virtual employee connector", "tags": [ "agents", "Agents" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Workspace admin provisioning/status API for browser UI and local connector setup." } }, "/api/v1/tenants/{tenant_id}/agents/{account_id}/scm-access": { "get": { "deprecated": true, "description": "What Tidy decided about this employee's git sign-in, and what the\nmachine confirmed (TIDY-19101 / Astra F5).\n\nTIDY-20066 F1 — the decision follows the source-control plugins the\nemployee is given, and the plugin's Access card says where it stands on\nthe box (``plugin_grants_view.sign_in``); this read stays for a client\nbuilt before that. ``github_access`` answers whether it is given one.", "operationId": "getTenantAgentScmAccess", "parameters": [ { "description": "Tenant public id or UUID", "in": "path", "name": "tenant_id", "required": true, "schema": { "description": "Tenant public id or UUID", "title": "Tenant Id", "type": "string" } }, { "description": "Virtual employee account UUID", "in": "path", "name": "account_id", "required": true, "schema": { "description": "Virtual employee account UUID", "title": "Account Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentScmAccessResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Read a virtual employee's source-control sign-in state", "tags": [ "agents", "Agents" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Workspace admin provisioning/status API for browser UI and local connector setup." } }, "/api/v1/tenants/{tenant_id}/agents/{account_id}/settings": { "get": { "operationId": "getTenantAgentSettings", "parameters": [ { "description": "Tenant public id or UUID", "in": "path", "name": "tenant_id", "required": true, "schema": { "description": "Tenant public id or UUID", "title": "Tenant Id", "type": "string" } }, { "description": "Virtual employee account UUID", "in": "path", "name": "account_id", "required": true, "schema": { "description": "Virtual employee account UUID", "title": "Account Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmployeeAgentSettingsPayload-Output" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get virtual employee settings", "tags": [ "agents", "Agents" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Workspace admin provisioning/status API for browser UI and local connector setup." }, "patch": { "operationId": "updateTenantAgentSettings", "parameters": [ { "description": "Tenant public id or UUID", "in": "path", "name": "tenant_id", "required": true, "schema": { "description": "Tenant public id or UUID", "title": "Tenant Id", "type": "string" } }, { "description": "Virtual employee account UUID", "in": "path", "name": "account_id", "required": true, "schema": { "description": "Virtual employee account UUID", "title": "Account Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmployeeAgentSettingsPayload-Input" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmployeeAgentSettingsPayload-Output" } } }, "description": "Successful Response" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Nothing was saved. Clients key on `error_code`, never on `code` (which is `conflict`); `detail` is always the sentence to show. error_code=skill_selection_changed: `skills` or `harness_skills` was sent with a `skill_selection_basis` that no longer matches the stored selection; the current basis is the top-level `skill_selection_basis`. No error_code: a list sent with no basis (an older client) would change the selection. error_code=skill_plugin_access_required: the save newly makes a skill effective whose required plugin access is unmet; `plan` is top-level." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Update virtual employee settings", "tags": [ "agents", "Agents" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Workspace admin provisioning/status API for browser UI and local connector setup." } }, "/api/v1/tenants/{tenant_id}/agents/{account_id}/setup": { "patch": { "description": "TIDY-18736 (D4) — fix the setup answers of an employee that exists.\n\nAn edit, not a re-enrollment: unlike `reconnect` it revokes no runtime\ncredential, resets no status and drops no liveness. Bounded to an employee\nno box has adopted yet; past that the harness moves only where the machine\ncan commit it, and the 409 names that route.", "operationId": "correctTenantAgentSetup", "parameters": [ { "description": "Tenant public id or UUID", "in": "path", "name": "tenant_id", "required": true, "schema": { "description": "Tenant public id or UUID", "title": "Tenant Id", "type": "string" } }, { "description": "Virtual employee account UUID", "in": "path", "name": "account_id", "required": true, "schema": { "description": "Virtual employee account UUID", "title": "Account Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentSetupCorrectionRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentSetupCorrectionResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Correct a not-yet-adopted employee's harness and sign-in", "tags": [ "agents", "Agents" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Workspace admin provisioning/status API for browser UI and local connector setup." } }, "/api/v1/tenants/{tenant_id}/agents/{account_id}/skill-credential-status": { "get": { "description": "Which declared credential slots this employee actually has filled.\n\nTIDY-17071 (S3 / R5). Slot NAMES only — no value, no credential id. The\nanswer is resolved against the EMPLOYEE's own resolution (its owner's\nkeychain ⊕ its active lends), never against whoever is reading, so this\nendpoint and the connector's refusal can never disagree.", "operationId": "getTenantAgentSkillCredentialStatus", "parameters": [ { "description": "Tenant public id or UUID", "in": "path", "name": "tenant_id", "required": true, "schema": { "description": "Tenant public id or UUID", "title": "Tenant Id", "type": "string" } }, { "description": "The virtual employee's account id", "in": "path", "name": "account_id", "required": true, "schema": { "description": "The virtual employee's account id", "title": "Account Id", "type": "string" } }, { "in": "query", "name": "runtime", "required": false, "schema": { "anyOf": [ { "maxLength": 64, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Runtime" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentSkillCredentialStatusResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Per-skill credential slot satisfaction for one virtual employee", "tags": [ "agents", "Agents" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Workspace admin provisioning/status API for browser UI and local connector setup." } }, "/api/v1/tenants/{tenant_id}/agents/{account_id}/skill-inventory": { "get": { "description": "Every skill the employee carries, by every route, with its published\nversion and what the workshop it runs on now holds (TIDY-19569 F5).\n\nRead live through the same resolver and per-reader rule as the synced\nSkills view, so it answers \"did that just take effect?\" without waiting\nfor the projection. Managing employees does not widen what is shown: a\nskill, collection or project the caller may not see stays withheld.", "operationId": "getTenantAgentSkillInventory", "parameters": [ { "description": "Tenant public id or UUID", "in": "path", "name": "tenant_id", "required": true, "schema": { "description": "Tenant public id or UUID", "title": "Tenant Id", "type": "string" } }, { "description": "The virtual employee's account id", "in": "path", "name": "account_id", "required": true, "schema": { "description": "The virtual employee's account id", "title": "Account Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmployeeSkillInventoryResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "One virtual employee's effective skills, as the caller may see them", "tags": [ "agents", "Agents" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Workspace admin provisioning/status API for browser UI and local connector setup." } }, "/api/v1/tenants/{tenant_id}/agents/{account_id}/suspend": { "post": { "operationId": "suspendTenantAgent", "parameters": [ { "description": "Tenant public id or UUID", "in": "path", "name": "tenant_id", "required": true, "schema": { "description": "Tenant public id or UUID", "title": "Tenant Id", "type": "string" } }, { "description": "Virtual employee account UUID", "in": "path", "name": "account_id", "required": true, "schema": { "description": "Virtual employee account UUID", "title": "Account Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/AgentLifecycleRequest" }, { "type": "null" } ], "title": "Body" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentLifecycleResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Disconnect a virtual employee connector", "tags": [ "agents", "Agents" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Workspace admin provisioning/status API for browser UI and local connector setup." } }, "/api/v1/tenants/{tenant_id}/agents/{account_id}/unsuppress": { "post": { "description": "The board drill-in's un-suppress button — TIDY-16413 (A9).\n\nThe loop detector's suppression is the one gate in this evaluator that\nLATCHES, because the loop is the VE's own behaviour and nothing the VE does\ncan be the evidence that it ended. So a human clears it, and this is the\ntenant-authed door onto the assistant-service route that owns the state and\nthe Temporal signal.", "operationId": "unsuppressTenantAgentConversation", "parameters": [ { "description": "Tenant public id or UUID", "in": "path", "name": "tenant_id", "required": true, "schema": { "description": "Tenant public id or UUID", "title": "Tenant Id", "type": "string" } }, { "description": "Virtual employee account UUID", "in": "path", "name": "account_id", "required": true, "schema": { "description": "Virtual employee account UUID", "title": "Account Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentUnsuppressRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentUnsuppressResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Clear a loop suppression on one of a virtual employee's items", "tags": [ "agents", "Agents" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Workspace admin provisioning/status API for browser UI and local connector setup." } }, "/api/v1/tenants/{tenant_id}/agents/{account_id}/update-policy": { "patch": { "description": "TIDY-16106 (S10). ``update_now`` records the operator's consent so a\n``notify`` installation may act on its pending directive at the next\nheartbeat. Nothing is started here — the connector still refuses to begin\nwhile a turn is running (D36).", "operationId": "setTenantAgentUpdatePolicy", "parameters": [ { "description": "Tenant public id or UUID", "in": "path", "name": "tenant_id", "required": true, "schema": { "description": "Tenant public id or UUID", "title": "Tenant Id", "type": "string" } }, { "description": "Virtual employee account id", "in": "path", "name": "account_id", "required": true, "schema": { "description": "Virtual employee account id", "title": "Account Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentUpdatePolicyRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentUpdatePolicyResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Set a virtual employee's connector update policy / consent to an update", "tags": [ "agents", "Agents" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Workspace admin provisioning/status API for browser UI and local connector setup." } }, "/api/v1/tenants/{tenant_id}/agents/{account_id}/wake-decisions": { "get": { "description": "The append-only wake-decision audit, newest first — TIDY-16413 (A9).\n\nONE contract, three renderers: the board's decision drill-in, A11's Log tab,\nand Android's. The rows are server-only by design (the table is high-volume\nand stays out of PowerSync, the `agent_liveness` precedent), so this\nendpoint is how every surface reads them.\n\nPagination is keyset, not OFFSET — the evaluator writes rows while an\noperator scrolls, and an OFFSET page would repeat or skip a decision every\ntime a wake landed.", "operationId": "listTenantAgentWakeDecisions", "parameters": [ { "description": "Tenant public id or UUID", "in": "path", "name": "tenant_id", "required": true, "schema": { "description": "Tenant public id or UUID", "title": "Tenant Id", "type": "string" } }, { "description": "Virtual employee account UUID", "in": "path", "name": "account_id", "required": true, "schema": { "description": "Virtual employee account UUID", "title": "Account Id", "type": "string" } }, { "description": "Restrict to one conversation's decisions", "in": "query", "name": "conversation_id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Restrict to one conversation's decisions", "title": "Conversation Id" } }, { "description": "Keyset cursor from a prior page", "in": "query", "name": "cursor", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Keyset cursor from a prior page", "title": "Cursor" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "maximum": 200, "minimum": 1, "title": "Limit", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentWakeDecisionsResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Virtual employee wake-decision audit (keyset paginated)", "tags": [ "agents", "Agents" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Workspace admin provisioning/status API for browser UI and local connector setup." } }, "/api/v1/tenants/{tenant_id}/agents/{account_id}/work-policy": { "get": { "operationId": "getTenantAgentWorkPolicy", "parameters": [ { "description": "Tenant public id or UUID", "in": "path", "name": "tenant_id", "required": true, "schema": { "description": "Tenant public id or UUID", "title": "Tenant Id", "type": "string" } }, { "description": "Virtual employee account UUID", "in": "path", "name": "account_id", "required": true, "schema": { "description": "Virtual employee account UUID", "title": "Account Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmployeeWorkPolicyResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "A virtual employee's work policy", "tags": [ "agents", "Agents" ], "x-local-capability": "cloud", "x-mcp-skip": true }, "put": { "operationId": "setTenantAgentWorkPolicy", "parameters": [ { "description": "Tenant public id or UUID", "in": "path", "name": "tenant_id", "required": true, "schema": { "description": "Tenant public id or UUID", "title": "Tenant Id", "type": "string" } }, { "description": "Virtual employee account UUID", "in": "path", "name": "account_id", "required": true, "schema": { "description": "Virtual employee account UUID", "title": "Account Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmployeeWorkPolicyRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmployeeWorkPolicyResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Set which states a virtual employee works, how it orders them, and whether its conversations get their own working copy", "tags": [ "agents", "Agents" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/tenants/{tenant_id}/assistant/settings": { "get": { "operationId": "getAssistantSettings", "parameters": [ { "description": "Tenant public id or UUID", "in": "path", "name": "tenant_id", "required": true, "schema": { "description": "Tenant public id or UUID", "title": "Tenant Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssistantSettingsResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "The built-in Tidy Assistant's autonomy, work policy and rules authority", "tags": [ "agents", "Agents" ], "x-local-capability": "cloud", "x-mcp-skip": true }, "patch": { "operationId": "updateAssistantSettings", "parameters": [ { "description": "Tenant public id or UUID", "in": "path", "name": "tenant_id", "required": true, "schema": { "description": "Tenant public id or UUID", "title": "Tenant Id", "type": "string" } }, { "in": "header", "name": "X-Tidy-Acting-Principal", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tidy-Acting-Principal" } }, { "in": "header", "name": "X-Internal-Service", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service" } }, { "in": "header", "name": "X-Internal-Service-Key", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service-Key" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssistantSettingsUpdate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssistantSettingsResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Change how the built-in Tidy Assistant works on its own (Owner/Admin)", "tags": [ "agents", "Agents" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/tenants/{tenant_id}/command-policy": { "get": { "operationId": "getTenantCommandPolicy", "parameters": [ { "in": "path", "name": "tenant_id", "required": true, "schema": { "title": "Tenant Id", "type": "string" } }, { "description": "Include this employee's layer in the composition", "in": "query", "name": "agent_account_id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Include this employee's layer in the composition", "title": "Agent Account Id" } }, { "description": "Include this conversation's layer in the composition", "in": "query", "name": "conversation_id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Include this conversation's layer in the composition", "title": "Conversation Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommandPolicyResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Read the composed command policy", "tags": [ "agents", "Agents" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Virtual-employee authorization surface for the settings UI and the local connector — never an assistant-callable tool." } }, "/api/v1/tenants/{tenant_id}/command-policy/rules": { "post": { "operationId": "addTenantCommandPolicyRule", "parameters": [ { "in": "path", "name": "tenant_id", "required": true, "schema": { "title": "Tenant Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommandPolicyRuleRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommandPolicyRule" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Add an org-floor command-policy rule", "tags": [ "agents", "Agents" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Virtual-employee authorization surface for the settings UI and the local connector — never an assistant-callable tool." } }, "/api/v1/tenants/{tenant_id}/command-policy/rules/{row_id}": { "delete": { "operationId": "deleteTenantCommandPolicyRule", "parameters": [ { "in": "path", "name": "tenant_id", "required": true, "schema": { "title": "Tenant Id", "type": "string" } }, { "description": "The rule row id (builtin floor rules have none)", "in": "path", "name": "row_id", "required": true, "schema": { "description": "The rule row id (builtin floor rules have none)", "title": "Row Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommandPolicyRuleDeleteResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Remove a tenant-authored command-policy rule", "tags": [ "agents", "Agents" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Virtual-employee authorization surface for the settings UI and the local connector — never an assistant-callable tool." } }, "/api/v1/tenants/{tenant_id}/employees/{account_id}/escalation-policy": { "get": { "operationId": "getEmployeeEscalationPolicy", "parameters": [ { "in": "path", "name": "tenant_id", "required": true, "schema": { "title": "Tenant Id", "type": "string" } }, { "in": "path", "name": "account_id", "required": true, "schema": { "title": "Account Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EscalationPolicyResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Read one employee's escalation policy", "tags": [ "agents", "Agents" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Virtual-employee authorization surface for the settings UI and the local connector — never an assistant-callable tool." }, "put": { "description": "Set the ceiling, the SMS switch, and the two ladder windows.\n\nRaising the ceiling to `now` is what lets this employee wake somebody; the\nSMS switch is the SECOND gate on the only rung that costs money. Both are\nrequired for a text, deliberately — cost-bearing channels are gated twice.", "operationId": "setEmployeeEscalationPolicy", "parameters": [ { "in": "path", "name": "tenant_id", "required": true, "schema": { "title": "Tenant Id", "type": "string" } }, { "in": "path", "name": "account_id", "required": true, "schema": { "title": "Account Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EscalationPolicyRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EscalationPolicyResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Set one employee's escalation policy", "tags": [ "agents", "Agents" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Virtual-employee authorization surface for the settings UI and the local connector — never an assistant-callable tool." } }, "/api/v1/tenants/{tenant_id}/invitations": { "get": { "description": "List pending tenant invitations. Requester must be an Owner or Member.", "operationId": "listTenantInvitations", "parameters": [ { "description": "Tenant ID (UUID v4 or public tenant id)", "in": "path", "name": "tenant_id", "required": true, "schema": { "description": "Tenant ID (UUID v4 or public tenant id)", "title": "Tenant Id", "type": "string" } }, { "description": "Invitation status to list. Only pending is supported.", "in": "query", "name": "status", "required": false, "schema": { "const": "pending", "default": "pending", "description": "Invitation status to list. Only pending is supported.", "title": "Status", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/TenantInvitationResponse" }, "title": "Response Listtenantinvitations", "type": "array" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List tenant invitations", "tags": [ "invitations", "Invitations" ] } }, "/api/v1/tenants/{tenant_id}/invitations/{invitation_id}": { "delete": { "description": "Revoke a pending tenant invitation. Requester must be an Owner.", "operationId": "revokeTenantInvitationById", "parameters": [ { "description": "Tenant ID (UUID v4 or public tenant id)", "in": "path", "name": "tenant_id", "required": true, "schema": { "description": "Tenant ID (UUID v4 or public tenant id)", "title": "Tenant Id", "type": "string" } }, { "description": "Invitation ID to revoke", "in": "path", "name": "invitation_id", "required": true, "schema": { "description": "Invitation ID to revoke", "format": "uuid", "title": "Invitation Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Revoketenantinvitationbyid", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Revoke tenant invitation", "tags": [ "invitations", "Invitations" ] } }, "/api/v1/tenants/{tenant_id}/members": { "get": { "description": "List all members of a tenant with their email addresses and roles. Requester must be associated with tenant.", "operationId": "listMembers", "parameters": [ { "description": "Tenant ID (UUID v4)", "in": "path", "name": "tenant_id", "required": true, "schema": { "description": "Tenant ID (UUID v4)", "title": "Tenant Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/MemberResponse" }, "title": "Response Listmembers", "type": "array" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List tenant members", "tags": [ "members", "Members" ] }, "post": { "description": "Send invitation to user's email for joining a tenant. Inviter must be an Owner, Admin or Member.", "operationId": "inviteMember2", "parameters": [ { "description": "Tenant ID (UUID v4)", "in": "path", "name": "tenant_id", "required": true, "schema": { "description": "Tenant ID (UUID v4)", "title": "Tenant Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemberInvite" } } } }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvitationResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Invite member to tenant", "tags": [ "members", "Members" ] } }, "/api/v1/tenants/{tenant_id}/members/invitations/{invitation_id}": { "delete": { "description": "Revoke a pending tenant member invitation. Requester must be an Owner or Admin.", "operationId": "revokeTenantInvitation", "parameters": [ { "description": "Tenant ID (UUID v4)", "in": "path", "name": "tenant_id", "required": true, "schema": { "description": "Tenant ID (UUID v4)", "title": "Tenant Id", "type": "string" } }, { "description": "Invitation ID to revoke", "in": "path", "name": "invitation_id", "required": true, "schema": { "description": "Invitation ID to revoke", "format": "uuid", "title": "Invitation Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Revoketenantinvitation", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Revoke tenant invitation", "tags": [ "members", "Members" ] } }, "/api/v1/tenants/{tenant_id}/members/{account_id}": { "delete": { "description": "Remove a member from a tenant. Requester must be an Owner, or an Admin removing a Member or Viewer. Cannot remove last Owner.", "operationId": "removeMember2", "parameters": [ { "description": "Tenant ID (UUID v4)", "in": "path", "name": "tenant_id", "required": true, "schema": { "description": "Tenant ID (UUID v4)", "title": "Tenant Id", "type": "string" } }, { "description": "Account ID of member to remove (UUID)", "in": "path", "name": "account_id", "required": true, "schema": { "description": "Account ID of member to remove (UUID)", "title": "Account Id", "type": "string" } }, { "description": "Account ID to transfer data ownership to before removal", "in": "query", "name": "transfer_to", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Account ID to transfer data ownership to before removal", "title": "Transfer To" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Remove member from tenant", "tags": [ "members", "Members" ] } }, "/api/v1/tenants/{tenant_id}/members/{account_id}/role": { "patch": { "description": "Update a member's role within a tenant. An Owner may set any role; an Admin may move Members and Viewers between Member and Viewer. Only an Owner grants, changes or revokes Owner and Admin, and the last Owner cannot be demoted.", "operationId": "updateMemberRole", "parameters": [ { "description": "Tenant ID (UUID v4)", "in": "path", "name": "tenant_id", "required": true, "schema": { "description": "Tenant ID (UUID v4)", "title": "Tenant Id", "type": "string" } }, { "description": "Account ID of member to update (UUID)", "in": "path", "name": "account_id", "required": true, "schema": { "description": "Account ID of member to update (UUID)", "title": "Account Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoleUpdateRequest" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoleUpdateResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Update member role", "tags": [ "members", "Members" ] } }, "/api/v1/tenants/{tenant_id}/members/{account_id}/team-approvals": { "get": { "operationId": "getTeamApprovalSettings", "parameters": [ { "in": "path", "name": "tenant_id", "required": true, "schema": { "title": "Tenant Id", "type": "string" } }, { "description": "The manager: a person's or an employee's account", "in": "path", "name": "account_id", "required": true, "schema": { "description": "The manager: a person's or an employee's account", "title": "Account Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TeamApprovalSettingsResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "What a manager decides for its direct reports", "tags": [ "agents", "Agents" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Virtual-employee authorization surface for the settings UI and the local connector — never an assistant-callable tool." }, "put": { "operationId": "setTeamApprovalSettings", "parameters": [ { "in": "path", "name": "tenant_id", "required": true, "schema": { "title": "Tenant Id", "type": "string" } }, { "description": "The manager: a person's or an employee's account", "in": "path", "name": "account_id", "required": true, "schema": { "description": "The manager: a person's or an employee's account", "title": "Account Id", "type": "string" } }, { "in": "header", "name": "X-Tidy-Acting-Principal", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tidy-Acting-Principal" } }, { "in": "header", "name": "X-Internal-Service", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service" } }, { "in": "header", "name": "X-Internal-Service-Key", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service-Key" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TeamApprovalSettingsRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TeamApprovalSettingsResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Set what a manager decides for its direct reports", "tags": [ "agents", "Agents" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Virtual-employee authorization surface for the settings UI and the local connector — never an assistant-callable tool." } }, "/api/v1/time-logs": { "get": { "description": "List time logs the caller owns or that are shared/tenant/global-visible.", "operationId": "listTimeLogs", "parameters": [ { "description": "Max rows to return", "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "description": "Max rows to return", "maximum": 500, "minimum": 1, "title": "Limit", "type": "integer" } }, { "description": "Pagination offset", "in": "query", "name": "offset", "required": false, "schema": { "default": 0, "description": "Pagination offset", "minimum": 0, "title": "Offset", "type": "integer" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/TimeLogResponse" }, "title": "Response Listtimelogs", "type": "array" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List visible time logs", "tags": [ "time-logs", "time-logs" ] }, "post": { "description": "Create a time-log row owned by the authenticated user.", "operationId": "createTimeLog", "parameters": [ { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TimeLogCreateRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TimeLogResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Create a time log", "tags": [ "time-logs", "time-logs" ] } }, "/api/v1/time-logs/active": { "get": { "description": "Return the caller's currently-active time log (stopped_at IS NULL).\n\nPer-USER (D9 / R7): scoped to owner_id = the caller, so two members'\nactive timers never collide.", "operationId": "getActiveTimeLog", "parameters": [ { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActiveTimeLogResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get the caller's active time log", "tags": [ "time-logs", "time-logs" ] } }, "/api/v1/time-logs/{time_log_id}": { "delete": { "description": "Soft-delete a time log. Only the caller's own rows (D9).", "operationId": "deleteTimeLog", "parameters": [ { "description": "Typed ID with prefix 'L'", "in": "path", "name": "time_log_id", "required": true, "schema": { "description": "Typed ID with prefix 'L'", "title": "Time Log Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Soft-delete a time log", "tags": [ "time-logs", "time-logs" ] }, "get": { "description": "Get one time log. Must be owner or the row must be shared/tenant-visible.", "operationId": "getTimeLog", "parameters": [ { "description": "Typed ID with prefix 'L'", "in": "path", "name": "time_log_id", "required": true, "schema": { "description": "Typed ID with prefix 'L'", "title": "Time Log Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TimeLogResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get a time log by id", "tags": [ "time-logs", "time-logs" ] }, "patch": { "description": "Patch a time log. Only the caller's own rows are mutable (D9).", "operationId": "updateTimeLog", "parameters": [ { "description": "Typed ID with prefix 'L'", "in": "path", "name": "time_log_id", "required": true, "schema": { "description": "Typed ID with prefix 'L'", "title": "Time Log Id", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TimeLogUpdateRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TimeLogResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Update a time log (stop / edit / reassign)", "tags": [ "time-logs", "time-logs" ] } }, "/api/v1/timeline/condense": { "post": { "description": "Condense timeline card text after the view settles on a coarse range.", "operationId": "condenseTimeline", "parameters": [ { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TimelineCondenseRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TimelineCondenseResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Condense Timeline", "tags": [ "timeline" ] } }, "/api/v1/timer/active": { "get": { "description": "Get the CALLER'S active timer (per-user — D9), if any.", "operationId": "getActiveTimer", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActiveTimerResponse" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get active timer", "tags": [ "activities", "Timer" ] } }, "/api/v1/timer/start": { "post": { "description": "Start a timer for a task, event, note, or project.\n\nStops the CALLER'S active timer first (per-user — D9), then opens a new\ntime_logs row. Another member's active timer is untouched.", "operationId": "startTimer", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StartTimerRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TimerSessionResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Start a timer", "tags": [ "activities", "Timer" ] } }, "/api/v1/timer/stop": { "post": { "description": "Stop the caller's active timer (per-user) and return final elapsed.", "operationId": "stopTimer", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TimerSessionResponse" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Stop active timer", "tags": [ "activities", "Timer" ] } }, "/api/v1/tracker/state": { "get": { "description": "Return tracker schema + persisted values for a date.", "operationId": "getTrackerStateEndpoint", "parameters": [ { "description": "Journal date (YYYY-MM-DD).", "in": "query", "name": "date", "required": true, "schema": { "description": "Journal date (YYYY-MM-DD).", "format": "date", "title": "Date", "type": "string" } }, { "description": "Tracker facet slug. Defaults to journal.", "in": "query", "name": "facet_slug", "required": false, "schema": { "default": "journal", "description": "Tracker facet slug. Defaults to journal.", "title": "Facet Slug", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrackerStateResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get server-backed tracker state for a journal date", "tags": [ "tracker" ] }, "put": { "description": "Persist a tracker field value to the journal day's properties.", "operationId": "saveTrackerStateEndpoint", "parameters": [ { "description": "Journal date (YYYY-MM-DD).", "in": "query", "name": "date", "required": true, "schema": { "description": "Journal date (YYYY-MM-DD).", "format": "date", "title": "Date", "type": "string" } }, { "in": "header", "name": "X-Trace-ID", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Trace-Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrackerUpdateRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrackerStateResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Save a server-backed tracker value for a journal date", "tags": [ "tracker" ] } }, "/api/v1/upload/attachment": { "post": { "description": "Uploads a file to Supabase Storage for use in card attachments.\n\n Supports images (JPEG, PNG, GIF, WebP, HEIC), documents (PDF, Word, Excel),\n and audio files (MP3, M4A, WAV). Max file size: 10MB.\n\n For image files, a thumbnail is automatically generated and stored.", "operationId": "uploadAttachment", "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/Body_uploadAttachment" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadedAttachment" } } }, "description": "Successful Response" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_service__routers__upload__ErrorResponse" } } }, "description": "Invalid request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_service__routers__upload__ErrorResponse" } } }, "description": "Unauthorized" }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_service__routers__upload__ErrorResponse" } } }, "description": "File too large" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_service__routers__upload__ErrorResponse" } } }, "description": "Unsupported media type" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Upload a file attachment", "tags": [ "upload" ] } }, "/api/v1/url-preview": { "get": { "description": "Returns OpenGraph / oEmbed / URL-pattern metadata for a URL. Used by the web app to render link cards without cross-origin browser fetches. Tenant-scoped for auth + basic rate-limiting.", "operationId": "getUrlPreview", "parameters": [ { "description": "URL to preview. Must be http or https.", "in": "query", "name": "url", "required": true, "schema": { "description": "URL to preview. Must be http or https.", "title": "Url", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UrlPreview" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Fetch structured link preview metadata for a URL", "tags": [ "url-preview", "url-preview" ] } }, "/api/v1/usage-verdicts": { "get": { "description": "The caller's own live verdicts, newest instruction first.\n\nMember-scoped through the canonical access predicate — another member of the\nsame tenant never sees these rows.", "operationId": "listUsageVerdicts", "parameters": [ { "in": "query", "name": "verdict", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Verdict" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 200, "maximum": 1000, "minimum": 1, "title": "Limit", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageVerdictList" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List Usage Verdicts", "tags": [ "usage-verdicts", "usage-verdicts" ], "x-local-capability": "local", "x-mcp-skip": true, "x-mcp-skip-reason": "Member-private ranking instructions; not an agent tool." }, "post": { "description": "Record the caller's standing verdict on one target.\n\nAccepted REGARDLESS of ``usage_learning_enabled`` — the control governs\nstatistical evidence, never an instruction. Idempotent on the verdict's\nnatural key: re-issuing the same verdict writes nothing and returns\n``changed=false``.", "operationId": "postUsageVerdict", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageVerdictRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageVerdictResult" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Post Usage Verdict", "tags": [ "usage-verdicts", "usage-verdicts" ], "x-local-capability": "outbox", "x-mcp-skip": true, "x-mcp-skip-reason": "A verdict is the MEMBER's standing instruction about their own ranking; an agent issuing one on their behalf is not a capability we want." } }, "/api/v1/usage-verdicts/clear": { "post": { "description": "Retire the caller's standing verdict on one target.\n\nThe row is retained and marked cleared, so re-issuing later revives it in\nplace rather than minting a duplicate.", "operationId": "clearUsageVerdict", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageVerdictClearRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageVerdictResult" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Clear Usage Verdict", "tags": [ "usage-verdicts", "usage-verdicts" ], "x-local-capability": "outbox", "x-mcp-skip": true, "x-mcp-skip-reason": "Counterpart of postUsageVerdict; member-only surface." } }, "/api/v1/usage/account-stats": { "get": { "description": "Returns the caller's storage metrics (materialized `tenant_storage_metrics` when present, else live table counts) plus AI-draft counts. Replaces the PostgREST `tenant_storage_metrics`/count reads (TIDY-12312).", "operationId": "getUsageAccountStats", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Getusageaccountstats", "type": "object" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Storage + AI-draft counts for the settings/usage page", "tags": [ "usage" ], "x-mcp-skip": true } }, "/api/v1/usage/ai-provider-split": { "get": { "description": "Returns the caller's tenant AI usage split between cloud and desktop-served (offloaded) work over a rolling window, plus a per-UTC-day series (S9.6 / TIDY-13085). Provider is derived from the `desktop/<tenant>` model prefix in `llm_usage_logs` — no parallel metering store. `total == cloud + desktop`.", "operationId": "getUsageAiProviderSplit", "parameters": [ { "in": "query", "name": "days", "required": false, "schema": { "default": 30, "title": "Days", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiProviderSplitResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Cloud-vs-desktop AI usage split for the settings/usage page", "tags": [ "usage" ], "x-mcp-skip": true } }, "/api/v1/usage/feedback-summary": { "get": { "description": "Returns the feedback summary aggregate the settings→usage page renders. Runs the existing `get_feedback_summary` SQL function; replaces the PostgREST `.rpc()` call (TIDY-12312).", "operationId": "getUsageFeedbackSummary", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Getusagefeedbacksummary", "type": "object" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Feedback summary for the settings/usage page", "tags": [ "usage" ], "x-mcp-skip": true } }, "/api/v1/user-preferences": { "get": { "description": "Read the current user's preferences (TIDY-7557 / TIDY-7566 / TIDY-8975).", "operationId": "getUserPreferences", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserPreferencesResponse" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get User Preferences", "tags": [ "user-preferences" ] }, "patch": { "description": "Partial update of the current user's preferences.\n\nTemplate-id fields are validated against the binding registry before\nany write (atomic semantics — one bad binding rejects the whole PATCH).\n\nTheme fields (TIDY-9098) route through :class:`ThemePreferenceWriter`,\nwhich is the single canonical write path for those columns. The mode\noverride is validated up-front so a bad value raises 422 before any\nDB work happens.", "operationId": "patchUserPreferences", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserPreferencesPatch" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserPreferencesResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Patch User Preferences", "tags": [ "user-preferences" ] } }, "/api/v1/user-preferences/history": { "get": { "operationId": "getUserPreferencesHistory", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Getuserpreferenceshistory", "type": "object" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get User Preferences Edit History", "tags": [ "user-preferences" ] } }, "/api/v1/user-preferences/history/{change_set_id}/restore": { "post": { "operationId": "restoreUserPreferencesHistoryChangeSet", "parameters": [ { "in": "path", "name": "change_set_id", "required": true, "schema": { "title": "Change Set Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserPreferencesResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Restore User Preferences History Change Set", "tags": [ "user-preferences" ] } }, "/api/v1/users/me/away-state": { "get": { "description": "Resolve OOO + manual chat status into one away-state envelope.\n\nOOO is canonical. If OOO is active → `source='ooo'`, `until=end_at`. If\nOOO is inactive but manual_status is 'away' or 'dnd' → `source='manual'`.\nOtherwise `source='none'`.", "operationId": "getAwayState", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AwayStateResponse" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Resolve the current user's away state", "tags": [ "away-state", "away-state" ] } }, "/api/v1/ve-goals": { "get": { "description": "List objectives in human-set order. Flag off ⇒ empty list, never an error.", "operationId": "listVeGoals", "parameters": [ { "in": "query", "name": "agent_account_id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Agent Account Id" } }, { "in": "query", "name": "include_resolved", "required": false, "schema": { "default": false, "title": "Include Resolved", "type": "boolean" } }, { "description": "Only the objectives assigned to the employee making this call (422 for a person). Overrides agent_account_id.", "in": "query", "name": "mine", "required": false, "schema": { "default": false, "description": "Only the objectives assigned to the employee making this call (422 for a person). Overrides agent_account_id.", "title": "Mine", "type": "boolean" } }, { "description": "Add each objective's `context`: the work linked to it (typed id, kind, title, state) and its latest comments, with exact counts.", "in": "query", "name": "include_context", "required": false, "schema": { "default": false, "description": "Add each objective's `context`: the work linked to it (typed id, kind, title, state) and its latest comments, with exact counts.", "title": "Include Context", "type": "boolean" } }, { "in": "header", "name": "X-Tidy-Acting-Principal", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tidy-Acting-Principal" } }, { "in": "header", "name": "X-Internal-Service", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service" } }, { "in": "header", "name": "X-Internal-Service-Key", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service-Key" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GoalList" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List Goals", "tags": [ "activities" ], "x-local-capability": "cloud" }, "post": { "description": "Create one objective, optionally assigned to an employee.", "operationId": "createVeGoal", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GoalCreate" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GoalResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Create Goal", "tags": [ "activities" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/ve-goals/reorder": { "post": { "description": "Human-set ordering: the given objective ids take positions 1..N.", "operationId": "reorderVeGoals", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GoalReorder" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GoalList" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Reorder Goals", "tags": [ "activities" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/ve-goals/{goal_id}": { "delete": { "operationId": "deleteVeGoal", "parameters": [ { "description": "Typed ID with prefix 'A'", "in": "path", "name": "goal_id", "required": true, "schema": { "description": "Typed ID with prefix 'A'", "title": "Goal Id", "type": "string" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Delete Goal", "tags": [ "activities" ], "x-local-capability": "cloud", "x-mcp-skip": true }, "patch": { "description": "Edit, pause, achieve, drop or reassign an objective.", "operationId": "updateVeGoal", "parameters": [ { "description": "Typed ID with prefix 'A'", "in": "path", "name": "goal_id", "required": true, "schema": { "description": "Typed ID with prefix 'A'", "title": "Goal Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GoalUpdate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GoalResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Update Goal", "tags": [ "activities" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/ve-proposals": { "get": { "description": "List proposals (open by default), sweeping 14-day expiry lazily.", "operationId": "get_proposals_api_v1_ve_proposals_get", "parameters": [ { "in": "query", "name": "agent_account_id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Agent Account Id" } }, { "in": "query", "name": "include_resolved", "required": false, "schema": { "default": false, "title": "Include Resolved", "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProposalList" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Proposals", "tags": [ "activities" ], "x-local-capability": "cloud" }, "post": { "description": "Create one vetted `proposed` item (a reflection session or the employee's own live turn).", "operationId": "create_proposal_api_v1_ve_proposals_post", "parameters": [ { "in": "header", "name": "X-Tidy-Acting-Principal", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tidy-Acting-Principal" } }, { "in": "header", "name": "X-Internal-Service", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service" } }, { "in": "header", "name": "X-Internal-Service-Key", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service-Key" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProposalCreate" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProposalCreated" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Create Proposal", "tags": [ "activities" ], "x-local-capability": "cloud" } }, "/api/v1/ve-proposals/review-meeting": { "post": { "description": "Book the 30-minute proposal-review meeting (reflection sessions only).", "operationId": "book_review_meeting_api_v1_ve_proposals_review_meeting_post", "parameters": [ { "in": "header", "name": "X-Tidy-Acting-Principal", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tidy-Acting-Principal" } }, { "in": "header", "name": "X-Internal-Service", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service" } }, { "in": "header", "name": "X-Internal-Service-Key", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service-Key" } } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReviewMeetingBooked" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Book Review Meeting", "tags": [ "activities" ], "x-local-capability": "cloud" } }, "/api/v1/ve-proposals/{item_id}/approve": { "post": { "description": "Approve: a task becomes ordinary backlog; a job becomes scheduled; a\nhire defines its employees, owned by the approver — on Tidy compute, or\n(TIDY-19882) on the existing workshop its review named, then deployed.", "operationId": "approve_api_v1_ve_proposals__item_id__approve_post", "parameters": [ { "description": "Typed ID with prefix 'A'", "in": "path", "name": "item_id", "required": true, "schema": { "description": "Typed ID with prefix 'A'", "title": "Item Id", "type": "string" } }, { "in": "header", "name": "X-Tidy-Acting-Principal", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tidy-Acting-Principal" } }, { "in": "header", "name": "X-Internal-Service", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service" } }, { "in": "header", "name": "X-Internal-Service-Key", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service-Key" } } ], "requestBody": { "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/ProposalApprove" }, { "type": "null" } ], "title": "Body" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProposalDisposition" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Approve", "tags": [ "activities" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/ve-proposals/{item_id}/reject": { "post": { "description": "Reject with an optional reason — retained, and fed to the next brief.", "operationId": "reject_api_v1_ve_proposals__item_id__reject_post", "parameters": [ { "description": "Typed ID with prefix 'A'", "in": "path", "name": "item_id", "required": true, "schema": { "description": "Typed ID with prefix 'A'", "title": "Item Id", "type": "string" } }, { "in": "header", "name": "X-Tidy-Acting-Principal", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Tidy-Acting-Principal" } }, { "in": "header", "name": "X-Internal-Service", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service" } }, { "in": "header", "name": "X-Internal-Service-Key", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service-Key" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_service__routers__ve_proposals__RejectBody" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProposalDisposition" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Reject", "tags": [ "activities" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/ve/assign-virtual-employee": { "post": { "description": "The ``assign_virtual_employee`` intake action (TIDY-14151 / S7 / DD8).\n\nMaps the bundle into a task at the workspace's ready status (``todo``, or\nits own open state nearest the work; TIDY-19611 — ``dev_status`` in the\nresponse echoes the retired word it maps from), assigned to the employee,\nand sends the employee an ordinary message in the caller's DM with it\n(TIDY-19869): ``message`` as the instruction, the task link and the\nbundle's fields. The board is ground truth: the item ALWAYS exists first; a\nfailed hand-off leaves it recoverable there and is returned in\n``dispatch_error`` — never silently dropped. Callable directly by a\nworkflow script, or run declaratively by a plugin event.", "operationId": "assignVirtualEmployee", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssignVirtualEmployeeRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssignVirtualEmployeeResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Create a task from a bundle, assign it to a virtual employee and message it", "tags": [ "ve-intake", "ve-intake" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Intake action for workflow scripts and plugin events; the employee gets an ordinary message." } }, "/api/v1/views/sources/{facet_slug}/rows": { "get": { "operationId": "queryViewSourceRows", "parameters": [ { "in": "path", "name": "facet_slug", "required": true, "schema": { "title": "Facet Slug", "type": "string" } }, { "description": "The view's FilterGroup ({logic, conditions}) as JSON.", "in": "query", "name": "filters", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The view's FilterGroup ({logic, conditions}) as JSON.", "title": "Filters" } }, { "description": "The view's sort as a JSON array of {\"field\", \"direction\"}.", "in": "query", "name": "sort", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The view's sort as a JSON array of {\"field\", \"direction\"}.", "title": "Sort" } }, { "description": "Free text over the title and text fields.", "in": "query", "name": "search", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Free text over the title and text fields.", "title": "Search" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "maximum": 200, "minimum": 1, "title": "Limit", "type": "integer" } }, { "in": "query", "name": "offset", "required": false, "schema": { "default": 0, "minimum": 0, "title": "Offset", "type": "integer" } }, { "description": "The previous page's next_cursor: continue after its last row, under the same sort.", "in": "query", "name": "after", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The previous page's next_cursor: continue after its last row, under the same sort.", "title": "After" } }, { "description": "Also count the matching rows (capped).", "in": "query", "name": "with_total", "required": false, "schema": { "default": false, "description": "Also count the matching rows (capped).", "title": "With Total", "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ViewSourceRowsResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Query View Source Rows", "tags": [ "views" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Row pages for the web database view's server-read sources." } }, "/api/v1/visualizations/export": { "post": { "description": "Export a chart or dashboard as a PNG or SVG image.\n\nThe render executes the app's own chart definitions and theme, and every\nsource resolves under the REQUESTING account's member-visible predicate and\nfilter-variable bindings — so two members exporting the same shared\ndashboard get their own numbers. Exports are point-in-time snapshots and\ncarry no live binding; re-export to refresh.", "operationId": "exportVisualizationImage", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VisualizationExportRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "`save: true` — the stored file, attachable through the usual machinery.", "properties": { "as_of": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "As Of" }, "file_id": { "title": "File Id", "type": "string" }, "height": { "title": "Height", "type": "integer" }, "mime_type": { "title": "Mime Type", "type": "string" }, "name": { "title": "Name", "type": "string" }, "size_bytes": { "title": "Size Bytes", "type": "integer" }, "width": { "title": "Width", "type": "integer" } }, "required": [ "file_id", "name", "mime_type", "size_bytes", "width", "height" ], "title": "VisualizationExportSavedResponse", "type": "object" } }, "image/png": { "schema": { "format": "binary", "type": "string" } }, "image/svg+xml": { "schema": { "type": "string" } } }, "description": "The rendered image, or — with `save: true` — the stored file ref." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Export Visualization Image", "tags": [ "visualizations", "visualizations" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/visualizations/render/{record_id}": { "get": { "description": "Render a chart or dashboard as a themed PNG for image-only clients.\n\nThis is the Android visual posture's seam (R21): a plain authenticated\nimage URL, so the client needs no chart code at all. Responses are cached\nbriefly on (definition, data horizon, viewer, theme, size) and carry\n`X-Render-As-Of` so a client can show honest staleness.", "operationId": "renderVisualizationImage", "parameters": [ { "description": "Typed ID with prefix 'R'", "in": "path", "name": "record_id", "required": true, "schema": { "description": "Typed ID with prefix 'R'", "title": "Record Id", "type": "string" } }, { "in": "query", "name": "theme", "required": false, "schema": { "default": "light", "enum": [ "light", "dark", "eink" ], "title": "Theme", "type": "string" } }, { "in": "query", "name": "w", "required": false, "schema": { "anyOf": [ { "maximum": 4096, "minimum": 64, "type": "integer" }, { "type": "null" } ], "title": "W" } }, { "in": "query", "name": "h", "required": false, "schema": { "anyOf": [ { "maximum": 4096, "minimum": 64, "type": "integer" }, { "type": "null" } ], "title": "H" } }, { "description": "Leave a dashboard's embed panes (a note, a record, …) out of the picture — for a client that shows them live beside it.", "in": "query", "name": "omit_embeds", "required": false, "schema": { "default": false, "description": "Leave a dashboard's embed panes (a note, a record, …) out of the picture — for a client that shows them live beside it.", "title": "Omit Embeds", "type": "boolean" } }, { "description": "`stage` draws exactly `w`×`h`. `content` lays a dashboard out at width `w` the way the app does — its panels stack on a narrow screen — and returns it at its own height. A chart fills the stage either way.", "in": "query", "name": "fit", "required": false, "schema": { "default": "stage", "description": "`stage` draws exactly `w`×`h`. `content` lays a dashboard out at width `w` the way the app does — its panels stack on a narrow screen — and returns it at its own height. A chart fills the stage either way.", "enum": [ "stage", "content" ], "title": "Fit", "type": "string" } }, { "description": "Device pixel ratio. `w` and `h` are then CSS pixels, and the image comes back `scale` times larger, sharp on a high-density screen.", "in": "query", "name": "scale", "required": false, "schema": { "anyOf": [ { "maximum": 4, "minimum": 1, "type": "number" }, { "type": "null" } ], "description": "Device pixel ratio. `w` and `h` are then CSS pixels, and the image comes back `scale` times larger, sharp on a high-density screen.", "title": "Scale" } } ], "responses": { "200": { "content": { "application/json": { "schema": {} }, "image/png": { "schema": { "format": "binary", "type": "string" } } }, "description": "The rendered image." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Render Visualization Image", "tags": [ "visualizations", "visualizations" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/visualizations/validate": { "post": { "description": "Validate a visualization definition: spec schema, referenced-source\nexistence, and field-name sanity against the source's catalog where\nresolvable. Returns the complete structured issues list, plus — for a\nvalid chart — whether the requested FORM suits the data (TIDY-17060).", "operationId": "validateVisualization", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VisualizationValidateRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VisualizationValidateResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Validate Visualization", "tags": [ "visualizations", "visualizations" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/voice-identity/consent": { "delete": { "operationId": "revokeVoiceIdentityConsent", "parameters": [ { "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Idempotency-Key" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoiceIdentityRevocationRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoiceIdentityRevocationResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Revoke", "tags": [ "voice-identity" ], "x-local-capability": "cloud", "x-mcp-skip": true }, "get": { "operationId": "getVoiceIdentityConsent", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoiceIdentityConsentResponse" } } }, "description": "Successful Response" } }, "summary": "Read Consent", "tags": [ "voice-identity" ], "x-local-capability": "cloud", "x-mcp-skip": true }, "post": { "operationId": "setVoiceIdentityConsent", "parameters": [ { "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Idempotency-Key" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoiceIdentityConsentRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoiceIdentityConsentResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Set Consent", "tags": [ "voice-identity" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/voice-identity/correction": { "post": { "operationId": "correctVoiceIdentitySpeaker", "parameters": [ { "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Idempotency-Key" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoiceIdentityCorrectionRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoiceIdentityCorrectionResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Correction", "tags": [ "voice-identity" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/voice-identity/enroll": { "post": { "operationId": "startVoiceIdentityEnrollment", "parameters": [ { "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Idempotency-Key" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoiceIdentityEnrollRequest" } } }, "required": true }, "responses": { "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoiceIdentityEnrollmentResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Enroll", "tags": [ "voice-identity" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/voice-identity/enrollment": { "get": { "operationId": "getVoiceIdentityEnrollment", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoiceIdentityEnrollmentResponse" } } }, "description": "Successful Response" } }, "summary": "Enrollment Status", "tags": [ "voice-identity" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/voice-identity/enrollment-tracks": { "get": { "operationId": "listVoiceIdentityEnrollmentTracks", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoiceIdentityEnrollmentTracksResponse" } } }, "description": "Successful Response" } }, "summary": "Enrollment Tracks", "tags": [ "voice-identity" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/voice/end": { "post": { "description": "End an active voice session and calculate duration.", "operationId": "endVoiceSession", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoiceEndRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoiceEndResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "End Voice Session", "tags": [ "voice" ] } }, "/api/v1/voice/preferences": { "get": { "description": "Get current voice preference, read-aloud defaults and available voices.", "operationId": "getVoicePreferences", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoicePreferenceResponse" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Voice Preferences", "tags": [ "voice" ] }, "put": { "description": "Update any of voice_id, voice_speed, playback_speed, playback_quality.", "operationId": "updateVoicePreferences", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoicePreferenceUpdateRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoicePreferenceResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Update Voice Preferences", "tags": [ "voice" ] } }, "/api/v1/voice/stt": { "post": { "operationId": "voiceServerStt", "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/Body_voiceServerStt" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoiceSttResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Transcribe audio via the server whisperx engine (alternative path).", "tags": [ "voice" ], "x-mcp-skip": true, "x-mcp-skip-reason": "Chat voice-message transcription alternative path; invoked by the S2 client router, not an agent tool." } }, "/api/v1/voice/token": { "post": { "description": "Generate a LiveKit JWT for voice session.", "operationId": "createVoiceToken", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoiceTokenRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoiceTokenResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Create Voice Token", "tags": [ "voice" ] } }, "/api/v1/voice/tts": { "post": { "operationId": "voiceServerTts", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoiceTtsRequest" } } }, "required": true }, "responses": { "200": { "content": { "audio/*": {} }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Synthesize speech via the server voice-gateway (alternative path).", "tags": [ "voice" ], "x-mcp-skip": true, "x-mcp-skip-reason": "Chat playback alternative path; invoked by the S1 client router, not an agent tool." } }, "/api/v1/voice/usage": { "get": { "description": "Get current month's voice usage statistics.", "operationId": "getVoiceUsage", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoiceUsageResponse" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Voice Usage", "tags": [ "voice" ] } }, "/api/v1/voices/catalogue": { "get": { "description": "The voices a speaker may pick, per engine (TIDY-20000).", "operationId": "listVoiceCatalogue", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoiceCatalogueResponse" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List each voice engine's own voices and the speeds a voice may have", "tags": [ "account-voice", "account-voice" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/voices/employees/{employee_account_id}": { "patch": { "description": "The voice the employee's calls and read-aloud replies use from now on.\n\nThe employee's owner or a workspace admin only (403 otherwise). A call\nalready running keeps the voice it started with.", "operationId": "setEmployeeVoice", "parameters": [ { "in": "path", "name": "employee_account_id", "required": true, "schema": { "format": "uuid", "title": "Employee Account Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmployeeVoiceUpdate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmployeeVoiceResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Set an employee's voice: its engine, one of that engine's voices, its speed", "tags": [ "account-voice", "account-voice" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/voices/members": { "get": { "description": "Return unified voice descriptors for the given Matrix ids.\n\nOnly members of the caller's tenant are resolvable; unknown / cross-tenant\nids are omitted (not an error). Unifies human ``accounts.voice_*``,\nAI-assistant + virtual-employee ``employee_agent_settings.default_voice_id``,\nand the ``@tidy`` default. Each carries its speaker's engine and speed\n(TIDY-20000), so a reply is read aloud the way its sender sounds.", "operationId": "listMemberVoiceDescriptors", "parameters": [ { "description": "Comma-separated Matrix ids, e.g. @a:host,@b:host", "in": "query", "name": "matrix_ids", "required": true, "schema": { "description": "Comma-separated Matrix ids, e.g. @a:host,@b:host", "maxLength": 4000, "title": "Matrix Ids", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoiceMembersResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Resolve voice descriptors for a set of tenant-visible members", "tags": [ "account-voice", "account-voice" ], "x-mcp-skip": true } }, "/api/v1/weather": { "get": { "description": "Returns current conditions and a short forecast for the account's home location (free NWS API). If the account has no home location set, returns 200 with `home_location_set=false` and a message guiding the user to set it in their profile — never a 500. TIDY-11326.", "operationId": "getWeather", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WeatherResponse" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Current weather + forecast for the account's home location", "tags": [ "weather" ] } }, "/api/v1/weather/hourly/refresh": { "post": { "description": "Brings the caller's synced hourly weather (observations for past hours, the NWS hourly forecast ahead) up to the current hour for their home location. NWS is asked at most once per hour per location. 503 when NWS keeps failing; the synced rows stay as they were. TIDY-19411 F4.", "operationId": "refreshHourlyWeather", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HourlyWeatherRefreshResponse" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Refresh the hourly weather the Feed sky replays", "tags": [ "weather" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/web-search": { "post": { "description": "Search the open web (Tavily), metered to the caller's credits.\n\n402 ``pool_exhausted`` / ``checkpoint_required`` when the credit gate\nrefuses; 429 when the provider rate-limits; 502 on a provider failure.", "operationId": "webSearch", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebSearchRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebSearchResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Run Web Search", "tags": [ "web-research" ], "x-local-capability": "cloud" } }, "/api/v1/webhooks/github": { "post": { "description": "Verify, record, and enqueue one GitHub App delivery.\n\nNo auth dependency by design: the App-level HMAC IS the boundary.", "operationId": "githubAppWebhook", "parameters": [ { "in": "header", "name": "X-GitHub-Event", "required": false, "schema": { "default": "", "title": "X-Github-Event", "type": "string" } }, { "in": "header", "name": "X-GitHub-Delivery", "required": false, "schema": { "default": "", "title": "X-Github-Delivery", "type": "string" } }, { "in": "header", "name": "X-Hub-Signature-256", "required": false, "schema": { "default": "", "title": "X-Hub-Signature-256", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "GitHub App webhook receiver", "tags": [ "integrations", "integrations" ], "x-mcp-skip": true } }, "/api/v1/webhooks/gitlab": { "post": { "description": "Verify, record, and enqueue one GitLab delivery (S9, R16).\n\nNo auth dependency by design: the per-connection webhook secret IS the\nboundary, and it is ALSO the tenant attribution — GitLab has no App-level\ninstallation to route by, so the receiver matches the delivery against\nevery active connection's vault secret and records which one verified.\n\nVerification prefers the newer HMAC scheme when the headers are present\n(`webhook-signature: v1,<hex>` over `{id}.{timestamp}.{body}`, replay-\nwindowed) and falls back to constant-time comparison of the legacy plain\n`X-Gitlab-Token` header. A signature failure is **401**, so the instance\nmarks the delivery failed and retries — visibility beats politeness.", "operationId": "gitlabWebhook", "parameters": [ { "in": "header", "name": "X-Gitlab-Event", "required": false, "schema": { "default": "", "title": "X-Gitlab-Event", "type": "string" } }, { "in": "header", "name": "X-Gitlab-Event-UUID", "required": false, "schema": { "default": "", "title": "X-Gitlab-Event-Uuid", "type": "string" } }, { "in": "header", "name": "X-Gitlab-Token", "required": false, "schema": { "default": "", "title": "X-Gitlab-Token", "type": "string" } }, { "in": "header", "name": "Webhook-Id", "required": false, "schema": { "default": "", "title": "Webhook-Id", "type": "string" } }, { "in": "header", "name": "Webhook-Timestamp", "required": false, "schema": { "default": "", "title": "Webhook-Timestamp", "type": "string" } }, { "in": "header", "name": "Webhook-Signature", "required": false, "schema": { "default": "", "title": "Webhook-Signature", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "GitLab webhook receiver", "tags": [ "integrations", "integrations" ], "x-mcp-skip": true } }, "/api/v1/webhooks/todoist": { "post": { "operationId": "receiveTodoistAppEvent", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PluginAppEventReceipt" } } }, "description": "Successful Response" } }, "summary": "Todoist's events for every account signed in with Tidy's Todoist app, signed with its client secret", "tags": [ "plugins" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "The public door an outside sender delivers to; never called on a member's behalf." } }, "/api/v1/widget-presets": { "get": { "operationId": "listWidgetPresets", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WidgetPresetList" } } }, "description": "Successful Response" } }, "summary": "List the member's reusable widget presets", "tags": [ "forms" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Widget-preset authoring (TIDY-16219 / D4): part of the form DESIGN surface; agents operate on records, not on their layout." }, "post": { "operationId": "createWidgetPreset", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WidgetPresetCreateRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WidgetPresetDetail" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Save a widget or a selected sub-tree as a reusable built-in", "tags": [ "forms" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Widget-preset authoring (TIDY-16219 / D4): part of the form DESIGN surface; agents operate on records, not on their layout." } }, "/api/v1/widget-presets/{preset_id}": { "delete": { "operationId": "deleteWidgetPreset", "parameters": [ { "in": "path", "name": "preset_id", "required": true, "schema": { "format": "uuid", "title": "Preset Id", "type": "string" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Soft-delete a widget preset", "tags": [ "forms" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Widget-preset authoring (TIDY-16219 / D4): part of the form DESIGN surface; agents operate on records, not on their layout." }, "get": { "operationId": "getWidgetPreset", "parameters": [ { "in": "path", "name": "preset_id", "required": true, "schema": { "format": "uuid", "title": "Preset Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WidgetPresetDetail" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Get one widget preset", "tags": [ "forms" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Widget-preset authoring (TIDY-16219 / D4): part of the form DESIGN surface; agents operate on records, not on their layout." }, "patch": { "operationId": "updateWidgetPreset", "parameters": [ { "in": "path", "name": "preset_id", "required": true, "schema": { "format": "uuid", "title": "Preset Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WidgetPresetUpdateRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WidgetPresetDetail" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Edit a preset — every linked instance of it updates", "tags": [ "forms" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Widget-preset authoring (TIDY-16219 / D4): part of the form DESIGN surface; agents operate on records, not on their layout." } }, "/api/v1/workflows": { "get": { "description": "List workflow scripts visible to the current user.\n\nRegular users see their own workflows plus shared/global workflows.\nAdmins/Owners see all tenant workflows.", "operationId": "listWorkflows", "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/WorkflowResponse" }, "title": "Response Listworkflows", "type": "array" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List Workflows", "tags": [ "workflows", "workflows" ] }, "post": { "description": "Create a new workflow script with an initial version record.", "operationId": "createWorkflow", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowCreate" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Create Workflow", "tags": [ "workflows", "workflows" ] } }, "/api/v1/workflows/bindable": { "get": { "description": "List workflows bindable to a facet action, with their declared inputs.\n\nConsumed by the facet-action authoring picker (TIDY-11015 / S1, used later\nby S3/S8) so an author can pick a ``workflow:<id>`` handler and see which\ninputs to map. Reuses the existing ``workflow_scripts`` store and the same\nowner/admin visibility as ``listWorkflows`` — no new table. Inputs come from\n``trigger_config.inputs`` via ``parse_workflow_inputs``.", "operationId": "listBindableWorkflows", "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/BindableWorkflow" }, "title": "Response Listbindableworkflows", "type": "array" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List Bindable Workflows", "tags": [ "workflows", "workflows" ], "x-mcp-skip": true } }, "/api/v1/workflows/ephemeral-runs": { "post": { "description": "Create a hidden audit-anchor workflow row and dispatch it once.", "operationId": "createEphemeralRun", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EphemeralRunRequest" } } }, "required": true }, "responses": { "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EphemeralRunAccepted" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Create Ephemeral Run", "tags": [ "workflows", "workflows" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/workflows/ephemeral-runs/{run_id}": { "get": { "description": "Poll an ephemeral run; only its executor or a tenant admin may read it.", "operationId": "getEphemeralRun", "parameters": [ { "in": "path", "name": "run_id", "required": true, "schema": { "title": "Run Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExecutionResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Ephemeral Run", "tags": [ "workflows", "workflows" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/workflows/executions": { "get": { "description": "List workflow executions across all workflows (TIDY-15279 / R4).\n\nThe audit surface for ephemeral runs: ``?trigger_source=ephemeral`` returns\nevery one-off sandbox run the caller may see, with the declared ceilings\n(timeout_sec / allowed_hosts) from the run's workflow row. Non-admins see\ntheir own runs; tenant admins see all tenant runs (matching the\n``getEphemeralRun`` admin read). Script content stays behind\n``getWorkflowCode`` and its creator-only ephemeral gate.", "operationId": "listWorkflowExecutions", "parameters": [ { "in": "query", "name": "trigger_source", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Trigger Source" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "title": "Limit", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/ExecutionResponse" }, "title": "Response Listworkflowexecutions", "type": "array" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List Workflow Executions", "tags": [ "workflows", "workflows" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/workflows/{script_id}": { "delete": { "description": "Delete a workflow script and cascade to versions/logs.", "operationId": "deleteWorkflow", "parameters": [ { "in": "path", "name": "script_id", "required": true, "schema": { "title": "Script Id", "type": "string" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Delete Workflow", "tags": [ "workflows", "workflows" ] }, "get": { "description": "Fetch a single workflow script visible to the current user.\n\nMirrors ``listWorkflows`` visibility: owner + shared/global rows;\nadmins/owners see all tenant workflows. A row outside the caller's\nvisibility (other tenant, another member's private workflow, or a\nnonexistent id) returns 404 — never 403 — matching the PATCH/DELETE\nconvention so existence is not leaked. ``code`` is deliberately NOT\nfetched or returned here; it stays on ``GET /{script_id}/code`` behind\nits owner-or-admin gate (TIDY-11907).", "operationId": "getWorkflow", "parameters": [ { "in": "path", "name": "script_id", "required": true, "schema": { "title": "Script Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Workflow", "tags": [ "workflows", "workflows" ] }, "patch": { "description": "Update a workflow script. Creates a new version record if code changes.", "operationId": "updateWorkflow", "parameters": [ { "in": "path", "name": "script_id", "required": true, "schema": { "title": "Script Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowUpdate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Update Workflow", "tags": [ "workflows", "workflows" ] } }, "/api/v1/workflows/{script_id}/code": { "get": { "description": "Fetch the code of a workflow script. Owner or admin only.", "operationId": "getWorkflowCode", "parameters": [ { "in": "path", "name": "script_id", "required": true, "schema": { "title": "Script Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowCodeResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Workflow Code", "tags": [ "workflows", "workflows" ] } }, "/api/v1/workflows/{script_id}/execute": { "post": { "description": "Manually trigger a workflow execution. Returns 202 (queued for Temporal).\n\nAn optional ``TriggerEnvelope`` body (TIDY-10489 / D7) is persisted onto the\nexecution log and forwarded into the Temporal run so the script understands\nits own call-in. Manual UI triggers omit the body.\n\nChat-origin attribution (TIDY-10263): a chat invoke carries\n``origin_surface='chat'`` + ``origin_room_id`` on the envelope and the W3C\n``traceparent`` header; both are propagated so one trace spans composer →\ninvoke → engine run and the run row is attributed to chat.", "operationId": "executeWorkflow", "parameters": [ { "in": "path", "name": "script_id", "required": true, "schema": { "title": "Script Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/TriggerEnvelope" }, { "type": "null" } ], "title": "Envelope" } } } }, "responses": { "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExecuteAccepted" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Execute Workflow", "tags": [ "workflows", "workflows" ] } }, "/api/v1/workflows/{script_id}/execute-async": { "post": { "description": "Dispatch a background workflow run with a durable assistant continuation.\n\nWrites an ``assistant_continuations`` row (status ``pending``) keyed on the\nworkflow run, then dispatches through the canonical\n``_dispatch_workflow_execution`` path. On completion the execution finalizer\nemits ``workflow.execution_completed``; the event-dispatcher resumes the\nassistant in ``conversation_id`` under this principal (TIDY-11351 / D3).\n\nReturns 202 ``{workflow_run_id, continuation_id}``.", "operationId": "executeWorkflowAsync", "parameters": [ { "in": "path", "name": "script_id", "required": true, "schema": { "title": "Script Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExecuteAsyncRequest" } } }, "required": true }, "responses": { "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExecuteAsyncAccepted" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Execute Workflow Async", "tags": [ "workflows", "workflows" ] } }, "/api/v1/workflows/{script_id}/executions": { "get": { "description": "List execution history for a workflow script. Owner or admin only.", "operationId": "listExecutions", "parameters": [ { "in": "path", "name": "script_id", "required": true, "schema": { "title": "Script Id", "type": "string" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 20, "title": "Limit", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/ExecutionResponse" }, "title": "Response Listexecutions", "type": "array" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List Executions", "tags": [ "workflows", "workflows" ] } }, "/api/v1/workflows/{script_id}/restore/{version}": { "post": { "description": "Restore a previous version by creating a new version with the restored code.", "operationId": "restoreVersion", "parameters": [ { "in": "path", "name": "script_id", "required": true, "schema": { "title": "Script Id", "type": "string" } }, { "in": "path", "name": "version", "required": true, "schema": { "title": "Version", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Restore Version", "tags": [ "workflows", "workflows" ] } }, "/api/v1/workflows/{script_id}/toggle": { "post": { "description": "Enable or disable a workflow script.", "operationId": "toggleWorkflow", "parameters": [ { "in": "path", "name": "script_id", "required": true, "schema": { "title": "Script Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToggleResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Toggle Workflow", "tags": [ "workflows", "workflows" ] } }, "/api/v1/workflows/{script_id}/versions": { "get": { "description": "List version history for a workflow script. Owner or admin only.", "operationId": "listVersions", "parameters": [ { "in": "path", "name": "script_id", "required": true, "schema": { "title": "Script Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/VersionResponse" }, "title": "Response Listversions", "type": "array" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List Versions", "tags": [ "workflows", "workflows" ] } }, "/api/v1/workflows/{script_id}/watch-first-run": { "post": { "description": "Arm a first-run report for a saved+enabled workflow (TIDY-11602 / D3).\n\nWrites a ``workflow_first_run`` ``assistant_continuations`` row keyed on the\nworkflow (NOT a run id — armed before any run exists). The first REAL\ntriggered run's ``workflow.execution_completed`` event claims it (in the\nevent-dispatcher) and the assistant reports the run in ``conversation_id``.\nAuthoring-test and manual runs never claim it (S1's ``trigger_source`` gate).\n\nIdempotent: re-arming an already-pending watch returns the existing\ncontinuation (the partial unique index on (tenant_id, workflow_script_id)\nenforces one pending watch per workflow). assistant-internal surface\n(``x-mcp-skip``) — not a user-facing MCP tool.", "operationId": "watchWorkflowFirstRun", "parameters": [ { "in": "path", "name": "script_id", "required": true, "schema": { "title": "Script Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WatchFirstRunRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WatchFirstRunResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Watch Workflow First Run", "tags": [ "workflows", "workflows" ], "x-mcp-skip": true } }, "/api/v1/workforce-attention/dismissals": { "post": { "description": "Hide one Attention item from the caller's queue (TIDY-19411).\n\nResolves nothing: the item stays open for everyone else it is waiting on.\nOnly a member the item is waiting on may dismiss it; anything else is a\n404, the same as an item that does not exist.", "operationId": "dismissWorkforceAttentionItem", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttentionDismissRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttentionDismissResult" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Dismiss Item", "tags": [ "workforce" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/workforce-attention/{item_id}/retry-projection": { "post": { "operationId": "retryWorkforceProjection", "parameters": [ { "in": "path", "name": "item_id", "required": true, "schema": { "format": "uuid", "title": "Item Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectionRetryResult" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Retry Projection", "tags": [ "workforce" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/workforce-attention/{item_id}/snooze": { "post": { "description": "Snooze one open allowance item until the provider-named reset (TIDY-18906).\n\nThe snooze is the resolved+marker design: the row RESOLVES with\n`snoozed_until` stamped on its `action_params`, and the refresh function\nre-raises nothing until the stamp passes. Any member the item is visible to\nmay snooze it — the audience check IS the authority here, the same audience\nthe row was emitted to.", "operationId": "snoozeWorkforceAttentionItem", "parameters": [ { "in": "path", "name": "item_id", "required": true, "schema": { "format": "uuid", "title": "Item Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AllowanceSnoozeRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AllowanceSnoozeResult" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Snooze Item", "tags": [ "workforce" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/workforce/events": { "get": { "operationId": "listWorkforceEvents", "parameters": [ { "in": "query", "name": "principal_key", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Principal Key" } }, { "in": "query", "name": "workshop_id", "required": false, "schema": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Workshop Id" } }, { "description": "Opaque continuation token from a previous response's next_cursor. Pass it back verbatim; it is not a timestamp and must not be constructed by the caller.", "in": "query", "name": "cursor", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Opaque continuation token from a previous response's next_cursor. Pass it back verbatim; it is not a timestamp and must not be constructed by the caller.", "title": "Cursor" } }, { "description": "Explicit keyset boundary, for a caller filtering history by an instant it already holds rather than continuing a page. Requires before_id, and is mutually exclusive with cursor.", "in": "query", "name": "before", "required": false, "schema": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "Explicit keyset boundary, for a caller filtering history by an instant it already holds rather than continuing a page. Requires before_id, and is mutually exclusive with cursor.", "title": "Before" } }, { "in": "query", "name": "before_id", "required": false, "schema": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Before Id" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "maximum": 200, "minimum": 1, "title": "Limit", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LedgerPage" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List Workforce Events", "tags": [ "workforce" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/workforce/spend": { "get": { "operationId": "getWorkforceSpendWindow", "parameters": [ { "in": "query", "name": "scope", "required": true, "schema": { "enum": [ "employee", "workshop" ], "title": "Scope", "type": "string" } }, { "in": "query", "name": "scope_key", "required": true, "schema": { "title": "Scope Key", "type": "string" } }, { "in": "query", "name": "window", "required": false, "schema": { "default": "today", "enum": [ "today", "7d", "30d" ], "title": "Window", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SpendWindow" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Workforce Spend", "tags": [ "workforce" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/workshop-apps/sessions/{session_id}/direct": { "post": { "description": "Re-run the pass's gates, then grant the workshop a direct path to this\ndevice for it: the same-network lane when both are on one network, a\nWebRTC link otherwise. The workshop admits the view only on a lease Tidy\nrenews every two seconds while the pass stands.", "operationId": "openWorkshopAppDirect", "parameters": [ { "in": "path", "name": "session_id", "required": true, "schema": { "pattern": "^[0-9a-fA-F-]{36}$", "title": "Session Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkshopAppDirectBody" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkshopAppDirectResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Ask for a direct path to an app view you have open", "tags": [ "workshops" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "A direct path carries an open view's app traffic between the viewer's desktop and the workshop; an agent tool has no view to carry." } }, "/api/v1/workshop-apps/sessions/{session_id}/direct/manifest": { "post": { "description": "Every stream on a direct path carries a signed session naming this\nview and certificate; each lasts minutes. The gates re-run first.", "operationId": "renewWorkshopAppDirectSession", "parameters": [ { "in": "path", "name": "session_id", "required": true, "schema": { "pattern": "^[0-9a-fA-F-]{36}$", "title": "Session Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkshopAppDirectManifestBody" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkshopAppDirectSession" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "A fresh signed session for a direct app view's streams", "tags": [ "workshops" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "A direct path carries an open view's app traffic between the viewer's desktop and the workshop; an agent tool has no view to carry." } }, "/api/v1/workshop-apps/{app_id}/sessions": { "post": { "description": "Mint a viewing pass bound to the caller's own Tidy sign-in.\n\nA token, an integration or an employee cannot open one: the pass lives\nonly as long as the signed-in session that asked for it, and only the\nperson whose approval added the app may ask.", "operationId": "openWorkshopAppSession", "parameters": [ { "in": "path", "name": "app_id", "required": true, "schema": { "pattern": "^[0-9a-fA-F-]{36}$", "title": "App Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkshopAppSessionResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Open a short-lived viewing pass to an app you added to Tidy", "tags": [ "workshops" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "A viewing pass is spent by the viewer's browser for the app's own host; an agent tool has no browser to spend it in." } }, "/api/v1/workshop-apps/{app_id}/viewer-keys": { "get": { "description": "A JWKS, public by design: the app has no Tidy sign-in to fetch it with,\nand a public key grants nothing. An id no workshop registered is a 404.", "operationId": "getWorkshopAppViewerKeys", "parameters": [ { "in": "path", "name": "app_id", "required": true, "schema": { "pattern": "^[0-9a-fA-F-]{36}$", "title": "App Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkshopAppViewerKeysResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "The public keys an app verifies the X-Tidy-Viewer header against", "tags": [ "workshops" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Read by the app itself on its workshop, which holds no Tidy credential; the keys are public." } }, "/api/v1/workshop-apps/{app_id}/workshop-browser": { "post": { "description": "Open (or join) the live session of the app's browser on its workshop.\n\nOnly for an app its owner set to open on the workshop: its cookies, local\ndata and service worker stay there, and that browser reaches the app's own\nport and nothing else on the machine or its network.", "operationId": "openWorkshopAppOnWorkshop", "parameters": [ { "in": "path", "name": "app_id", "required": true, "schema": { "pattern": "^[0-9a-fA-F-]{36}$", "title": "App Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkshopAppBrowserResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Open an app you added to Tidy in its workshop's own browser, live", "tags": [ "workshops" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "The app is shown to its approver live in Tidy; an agent tool has no screen to show it on, and employees never drive an app's browser." } }, "/api/v1/workshop-provider-connections": { "get": { "operationId": "listWorkshopProviderConnections", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectionList" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List Connections", "tags": [ "workshops", "workshop-providers" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Privileged provider settings and confirmed cloud lifecycle; provider secrets never enter generative tools." }, "post": { "operationId": "createWorkshopProviderConnection", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectionCreate" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectionResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Create Connection", "tags": [ "workshops", "workshop-providers" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Privileged provider settings and confirmed cloud lifecycle; provider secrets never enter generative tools." } }, "/api/v1/workshop-provider-connections/{connection_id}": { "get": { "operationId": "getWorkshopProviderConnection", "parameters": [ { "in": "path", "name": "connection_id", "required": true, "schema": { "format": "uuid", "title": "Connection Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectionResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Connection", "tags": [ "workshops", "workshop-providers" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Privileged provider settings and confirmed cloud lifecycle; provider secrets never enter generative tools." } }, "/api/v1/workshop-provider-connections/{connection_id}/catalog-refresh": { "post": { "operationId": "refreshWorkshopProviderCatalog", "parameters": [ { "in": "path", "name": "connection_id", "required": true, "schema": { "format": "uuid", "title": "Connection Id", "type": "string" } } ], "responses": { "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperationResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Refresh Catalog", "tags": [ "workshops", "workshop-providers" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Privileged provider settings and confirmed cloud lifecycle; provider secrets never enter generative tools." } }, "/api/v1/workshop-provider-connections/{connection_id}/revoke": { "post": { "operationId": "revokeWorkshopProviderConnection", "parameters": [ { "in": "path", "name": "connection_id", "required": true, "schema": { "format": "uuid", "title": "Connection Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectionResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Revoke Connection", "tags": [ "workshops", "workshop-providers" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Privileged provider settings and confirmed cloud lifecycle; provider secrets never enter generative tools." } }, "/api/v1/workshop-provider-connections/{connection_id}/rotate": { "post": { "operationId": "rotateWorkshopProviderConnection", "parameters": [ { "in": "path", "name": "connection_id", "required": true, "schema": { "format": "uuid", "title": "Connection Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectionCreate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectionResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Rotate Connection", "tags": [ "workshops", "workshop-providers" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Privileged provider settings and confirmed cloud lifecycle; provider secrets never enter generative tools." } }, "/api/v1/workshop-provider-operations/{operation_id}": { "get": { "operationId": "getWorkshopProviderOperation", "parameters": [ { "in": "path", "name": "operation_id", "required": true, "schema": { "format": "uuid", "title": "Operation Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperationResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Operation", "tags": [ "workshops", "workshop-providers" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Privileged provider settings and confirmed cloud lifecycle; provider secrets never enter generative tools." } }, "/api/v1/workshop-provider-operations/{operation_id}/reconcile": { "post": { "operationId": "reconcileWorkshopProviderOperation", "parameters": [ { "in": "path", "name": "operation_id", "required": true, "schema": { "format": "uuid", "title": "Operation Id", "type": "string" } } ], "responses": { "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperationResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Reconcile Operation", "tags": [ "workshops", "workshop-providers" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Privileged provider settings and confirmed cloud lifecycle; provider secrets never enter generative tools." } }, "/api/v1/workshop-providers/catalog": { "get": { "description": "Which providers this deployment can actually provision on.\n\nThe REGISTRY is the answer, so a provider that ships makes itself visible by\nregistering its adapter and nothing else. TIDY-18238 shipped a literal\n`(\"digitalocean\", \"hetzner\")` here, which read as registry-driven and was in\nfact a permanent blacklist: `ADAPTERS` has carried a real `lightsail`\nadapter since TIDY-18134, and no amount of finishing it could ever have made\nthe card offer it. Whether a provider is offered is a property of what is\nregistered, never of a tuple in a route.", "operationId": "getWorkshopProviderCatalog", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkshopProviderCatalog" } } }, "description": "Successful Response" } }, "summary": "Provider Catalog", "tags": [ "workshops", "workshop-providers" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Privileged provider settings and confirmed cloud lifecycle; provider secrets never enter generative tools." } }, "/api/v1/workshop-tunnels": { "get": { "description": "A workshop's own credential lists its tunnels both ways; an employee,\nthose of the workshop it runs on; a member, the ones they asked for or\nwhose either workshop they approve.", "operationId": "listWorkshopTunnels", "parameters": [ { "description": "Only this workshop's (id, or `self` for the one you run on).", "in": "query", "name": "workshop", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Only this workshop's (id, or `self` for the one you run on).", "title": "Workshop" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkshopTunnelListResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "The tunnels you may see: asked for, open, and closed this week", "tags": [ "workshops" ], "x-local-capability": "cloud" } }, "/api/v1/workshop-tunnels/{tunnel_id}/close": { "post": { "description": "Either workshop's owner, whoever asked for it, and either workshop\nitself may close it: every connection through it ends within seconds.", "operationId": "closeWorkshopTunnel", "parameters": [ { "in": "path", "name": "tunnel_id", "required": true, "schema": { "pattern": "^[0-9a-fA-F-]{36}$", "title": "Tunnel Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkshopTunnelResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Close a tunnel, or withdraw one still waiting for approval", "tags": [ "workshops" ], "x-local-capability": "cloud" } }, "/api/v1/workshops": { "get": { "description": "The workshops the caller can see (the Workshops view's visibility),\nwith each one's roster, status and last heartbeat.", "operationId": "listWorkshops", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkshopListResponse" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List Workshops", "tags": [ "workshops", "workshops" ], "x-local-capability": "cloud" }, "post": { "description": "Create a workshop: the control-plane row + its facet-bearing record in\none transaction. It starts `unenrolled`; the setup command enrolls it.", "operationId": "createWorkshop", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkshopCreateRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkshopResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Create Workshop", "tags": [ "workshops", "workshops" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/workshops/gateway/claim": { "post": { "description": "Redeemed BY the machine, from inside the setup command.\n\nToken-bearing and unauthenticated — the same contract as the employee\nconnector claim (`POST /agents/claim`): the box has no Tidy session, the\ntoken is the authority, and it is single use.", "operationId": "claimWorkshopGateway", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkshopGatewayClaimRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkshopEnrollResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Claim Gateway", "tags": [ "workshops", "workshops" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/workshops/gateway/daemon-install": { "get": { "description": "What `install-workshop.sh` / `.ps1` and the desktop app fetch before\nthey fetch anything else (TIDY-18237): the promoted Go bootstrap and\nruntime archive for this host, each pinned by digest and size.\nUnauthenticated on purpose — the script runs on a box with no Tidy\nsession, the artifacts are public, and the pins are the integrity\nguarantee, not a secret. `host_os`/`host_arch` (TIDY-18239) default to\nthe pre-S5 Linux x86_64 contract; an unpublished tuple is a typed 400.", "operationId": "workshopDaemonInstall", "parameters": [ { "in": "query", "name": "host_os", "required": false, "schema": { "default": "linux", "maxLength": 16, "title": "Host Os", "type": "string" } }, { "in": "query", "name": "host_arch", "required": false, "schema": { "default": "x86_64", "maxLength": 16, "title": "Host Arch", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkshopDaemonInstallResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Daemon Install", "tags": [ "workshops", "workshops" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/workshops/gateway/enrollment-attempts": { "post": { "description": "An installer that could not reach the claim tells Tidy why\n(TIDY-18239): the execution policy refused the script, Defender\nquarantined the bootstrap, the OS is unsupported. Token-bearing like the\nclaim — and the token is NOT consumed, so the same command works again\nonce the box is fixed.", "operationId": "reportWorkshopEnrollmentAttempt", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkshopEnrollmentAttemptRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkshopEnrollmentAttemptResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Report Enrollment Attempt", "tags": [ "workshops", "workshops" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/workshops/gateway/enrollment-binding": { "post": { "description": "Which workshop, in which workspace, a setup command was minted for\n(TIDY-19557). The Linux installer asks before it spends the token, when\nthe install the command names is still on the box from before the owner\nrevoked the workshop and established it again. Token-bearing like the\nclaim, the token in the body; resolved, never consumed.", "operationId": "workshopEnrollmentBinding", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkshopEnrollmentBindingRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkshopEnrollmentBindingResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Enrollment Binding", "tags": [ "workshops", "workshops" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Called only by the Linux workshop installer, with the setup command's token." } }, "/api/v1/workshops/mounts": { "get": { "description": "My Files → workshops: the member-visible workshops and each one's\nmounted volumes, read from the persisted report — the box's last\n``fs.mounts.list`` reading, mirrored onto the facet record. Declared\nBEFORE ``/{workshop_id}`` so ``mounts`` is never parsed as a workshop id.\nA browse is a separate, explicit call (``browseWorkshopMount``) — nothing\nhere touches the box.", "operationId": "listWorkshopMounts", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkshopMountsListResponse" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List Workshop Mounts", "tags": [ "workshops", "workshops" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/workshops/push-policy-floor": { "get": { "description": "The tenant-wide minimum push policy (D17). Every workshop's effective\npolicy is at least this strict.", "operationId": "getWorkshopPushPolicyFloor", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkshopPushPolicyFloorResponse" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Push Policy Floor", "tags": [ "workshops", "workshops" ], "x-local-capability": "cloud", "x-mcp-skip": true }, "put": { "description": "Raise or lower the floor. An owner may be stricter than it on their\nown workshop, never looser — enforced on every enqueue, not in the UI.", "operationId": "setWorkshopPushPolicyFloor", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkshopPushPolicyFloorRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkshopPushPolicyFloorResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Set Push Policy Floor", "tags": [ "workshops", "workshops" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/workshops/{source_workshop_id}/sends": { "post": { "description": "Send files and folders from this workshop to a folder on another\n(TIDY-19414 F11 S3, My Files' Send to workshop).\n\nEach end is a Project Root or one of the volumes the workshop reports, so\nan SD card on a laptop-workshop is a source as it is. Gated like a single\ntransfer — the owner or a workspace Owner/Admin on BOTH boxes — and every\nfile's vouch re-runs that gate just before the file starts. The files move\nbeside the source's job slot, up to three at once, and the Send's\n``workshop_transfer`` record shows them move.\n\nOn a source that asks before anything runs, a Send waits for ONE approval\nof exactly what it names (TIDY-19414): the source's owner sending is that\napproval, its proof asked for here, at the press (TIDY-19770); anyone\nelse's Send is ``awaiting_approval`` until the owner answers its card.", "operationId": "sendToWorkshop", "parameters": [ { "description": "Workshop id (UUID)", "in": "path", "name": "source_workshop_id", "required": true, "schema": { "description": "Workshop id (UUID)", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", "title": "Source Workshop Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkshopSendRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkshopSendResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Send To Workshop", "tags": [ "workshops", "workshops" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/workshops/{source_workshop_id}/transfers": { "post": { "description": "Authorize one workshop→workshop transfer: the backend's whole\ninvolvement in it, and then it gets out of the way.\n\nThe backend resolves the destination (a Project Root in the target's\nregistry, the file-write's write-right check), authorizes the write (the\nattach gate on BOTH boxes), and mints the Transfer Authorization — the\nvouch signed with the target's pinned key binding source, target, root +\npath, the declared size, the deadline, and the target daemon's per-boot\nseal key. It queues the source's ``file.transfer`` job (the vouch rides\nonly its signed payload) and writes the audit row, in one transaction.\nThe bytes ride the non-persisting relay; no file byte crosses this route.\n\nThe gate is the attach gate (the box's owner or a workspace Owner/\nAdmin), not the read gate: a member who can see the record may browse\nit, but authorizing a file to leave a machine is a write, on both ends.", "operationId": "authorizeWorkshopTransfer", "parameters": [ { "description": "Workshop id (UUID)", "in": "path", "name": "source_workshop_id", "required": true, "schema": { "description": "Workshop id (UUID)", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", "title": "Source Workshop Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkshopTransferAuthorizeRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkshopTransferAuthorizeResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Authorize Workshop Transfer", "tags": [ "workshops", "workshops" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/workshops/{workshop_id}": { "delete": { "description": "Tombstone a workshop. Refused (409) while employees are attached —\nemployees always survive a workshop; detach them first (R2).", "operationId": "deleteWorkshop", "parameters": [ { "description": "Workshop id (UUID)", "in": "path", "name": "workshop_id", "required": true, "schema": { "description": "Workshop id (UUID)", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", "title": "Workshop Id", "type": "string" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Delete Workshop", "tags": [ "workshops", "workshops" ], "x-local-capability": "cloud", "x-mcp-skip": true }, "get": { "operationId": "getWorkshop", "parameters": [ { "description": "Workshop id (UUID)", "in": "path", "name": "workshop_id", "required": true, "schema": { "description": "Workshop id (UUID)", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", "title": "Workshop Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkshopResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Workshop", "tags": [ "workshops", "workshops" ], "x-local-capability": "cloud", "x-mcp-skip": true }, "patch": { "operationId": "updateWorkshop", "parameters": [ { "description": "Workshop id (UUID)", "in": "path", "name": "workshop_id", "required": true, "schema": { "description": "Workshop id (UUID)", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", "title": "Workshop Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkshopUpdateRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkshopResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Update Workshop", "tags": [ "workshops", "workshops" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/workshops/{workshop_id}/acp-registry": { "get": { "description": "TIDY-19931 (F7) — the Agent Client Protocol registry as this workshop can\nuse it: only agents with a build its platform runs, each with whether Tidy\ncan install it here or why not, and what the workshop already runs.\n\nThe server reads the registry itself (cached, bounded); no client and no\nbox ever does. Adding one is `PUT /agents/{id}/harnesses/{runtime}` with\n`install_if_missing`, which signs the registry's own source for this\nplatform into the workshop's `harness.ensure`.", "operationId": "searchWorkshopAcpRegistry", "parameters": [ { "description": "Workshop id (UUID)", "in": "path", "name": "workshop_id", "required": true, "schema": { "description": "Workshop id (UUID)", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", "title": "Workshop Id", "type": "string" } }, { "description": "Matched in id, name and description.", "in": "query", "name": "q", "required": false, "schema": { "anyOf": [ { "maxLength": 100, "type": "string" }, { "type": "null" } ], "description": "Matched in id, name and description.", "title": "Q" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkshopAcpRegistryResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Search Workshop Acp Registry", "tags": [ "workshops", "workshops", "workshops" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/workshops/{workshop_id}/agent-usage": { "get": { "description": "A machine's usage IS its employees' usage — there is no second place it accrues.\n\nThe pool binds THIS viewer per row (F1): a member who cannot see an\nemployee receives no contribution from that employee's accounts.", "operationId": "getWorkshopAgentUsageLimits", "parameters": [ { "in": "path", "name": "workshop_id", "required": true, "schema": { "format": "uuid", "title": "Workshop Id", "type": "string" } }, { "description": "The viewer's IANA timezone; the slice is cut in it.", "in": "query", "name": "tz", "required": true, "schema": { "description": "The viewer's IANA timezone; the slice is cut in it.", "title": "Tz", "type": "string" } }, { "in": "query", "name": "slice", "required": false, "schema": { "default": "today", "title": "Slice", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageLimitsResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Workshop Usage Limits", "tags": [ "agents" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Harness configuration is a first-party settings surface." } }, "/api/v1/workshops/{workshop_id}/agent-usage/insights": { "get": { "description": "A machine's insights pool every employee on it — each contribution still\nfiltered by THIS viewer's visibility before it is summed.", "operationId": "getWorkshopUsageInsights", "parameters": [ { "in": "path", "name": "workshop_id", "required": true, "schema": { "format": "uuid", "title": "Workshop Id", "type": "string" } }, { "description": "The viewer's IANA timezone; the slice is cut in it.", "in": "query", "name": "tz", "required": true, "schema": { "description": "The viewer's IANA timezone; the slice is cut in it.", "title": "Tz", "type": "string" } }, { "in": "query", "name": "slice", "required": false, "schema": { "default": "today", "title": "Slice", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageInsightsResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Workshop Usage Insights", "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Usage insights are a first-party settings surface." } }, "/api/v1/workshops/{workshop_id}/allow-docker": { "patch": { "description": "TIDY-19557: turn Docker on or off for this workshop (default off). When\non, turns reach Docker only through the connector's filtering proxy, which\nrefuses privileged containers and host namespaces — the raw socket is never\nexposed. When off, every turn's Docker call is refused with a coded message.", "operationId": "setWorkshopAllowDocker", "parameters": [ { "description": "Workshop id (UUID)", "in": "path", "name": "workshop_id", "required": true, "schema": { "description": "Workshop id (UUID)", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", "title": "Workshop Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkshopAllowDockerRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkshopResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Set Allow Docker", "tags": [ "workshops", "workshops" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/workshops/{workshop_id}/apps": { "post": { "description": "Register (or rename) an app on a loopback port of this workshop.\n\nIt stays unreachable until the workshop's owner adds it to Tidy from the\nAttention ask this raises. Only the workshop itself registers: an employee\nfrom a turn on it, or a person at the machine with its credential.", "operationId": "registerWorkshopApp", "parameters": [ { "description": "The workshop's id, or `self` for the one you run on.", "in": "path", "name": "workshop_id", "required": true, "schema": { "description": "The workshop's id, or `self` for the one you run on.", "title": "Workshop Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkshopAppRegister" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkshopAppResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Ask the workshop's owner to add a web app it serves on a local port to Tidy", "tags": [ "workshops" ], "x-local-capability": "cloud" } }, "/api/v1/workshops/{workshop_id}/attach-employee": { "post": { "description": "Assign an employee to this workshop (the roster edge + the\ninstallation row when the workshop is enrolled). 409 naming where the\nemployee already runs — another workshop, or Tidy compute — because\nre-homing a live employee is the move flow, not a side effect of attach.\n\nOn a daemon-run workshop (TIDY-18237) the assignment is also the deploy:\nthe signed `employee.adopt` job is queued and named in `push_job_id`, and\nthe answer is 202 because the box has not finished yet.", "operationId": "attachWorkshopEmployee", "parameters": [ { "description": "Workshop id (UUID)", "in": "path", "name": "workshop_id", "required": true, "schema": { "description": "Workshop id (UUID)", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", "title": "Workshop Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkshopAttachRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkshopResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Attach Employee", "tags": [ "workshops", "workshops" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/workshops/{workshop_id}/browser-controller/action-authorize": { "post": { "operationId": "authorizeBrowserControllerAction", "parameters": [ { "in": "path", "name": "workshop_id", "required": true, "schema": { "format": "uuid", "title": "Workshop Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ControllerSignedRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ControllerActionDecision" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Authorize Browser Controller Action", "tags": [ "browser-controller" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Protected controller installation and independent-key protocol; not agent authority." } }, "/api/v1/workshops/{workshop_id}/browser-controller/claim": { "post": { "operationId": "claimBrowserController", "parameters": [ { "in": "path", "name": "workshop_id", "required": true, "schema": { "format": "uuid", "title": "Workshop Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProtectedControllerClaimRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ControllerStatusResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Claim Browser Controller", "tags": [ "browser-controller" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Protected controller installation and independent-key protocol; not agent authority." } }, "/api/v1/workshops/{workshop_id}/browser-controller/enroll": { "post": { "operationId": "enrollBrowserController", "parameters": [ { "in": "path", "name": "workshop_id", "required": true, "schema": { "format": "uuid", "title": "Workshop Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ControllerEnrollmentRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ControllerEnrollmentResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Enroll Browser Controller", "tags": [ "browser-controller" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Protected controller installation and independent-key protocol; not agent authority." } }, "/api/v1/workshops/{workshop_id}/browser-controller/file-read": { "post": { "operationId": "readBrowserSelectedFile", "parameters": [ { "in": "path", "name": "workshop_id", "required": true, "schema": { "format": "uuid", "title": "Workshop Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrowserFileReadRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/octet-stream": { "schema": { "format": "binary", "type": "string" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Read Selected File", "tags": [ "browser-controller" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Browser control transport and configured actions; harness tools are a separate contract." } }, "/api/v1/workshops/{workshop_id}/browser-controller/file-save": { "post": { "operationId": "saveBrowserDownload", "parameters": [ { "in": "path", "name": "workshop_id", "required": true, "schema": { "format": "uuid", "title": "Workshop Id", "type": "string" } }, { "in": "header", "name": "X-Tidy-Controller-Proof", "required": true, "schema": { "format": "password", "maxLength": 16384, "title": "X-Tidy-Controller-Proof", "type": "string", "writeOnly": true } }, { "in": "header", "name": "X-Tidy-Browser-Authorization", "required": true, "schema": { "format": "password", "maxLength": 8192, "title": "X-Tidy-Browser-Authorization", "type": "string", "writeOnly": true } } ], "requestBody": { "content": { "application/octet-stream": { "schema": { "format": "binary", "type": "string" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrowserFileSavedResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Save Download", "tags": [ "browser-controller" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Browser control transport and configured actions; harness tools are a separate contract." } }, "/api/v1/workshops/{workshop_id}/browser-controller/mode-applied": { "post": { "operationId": "applyBrowserControllerMode", "parameters": [ { "in": "path", "name": "workshop_id", "required": true, "schema": { "format": "uuid", "title": "Workshop Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ControllerSignedRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ControllerModeAppliedResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Apply Browser Controller Mode", "tags": [ "browser-controller" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Protected controller installation and independent-key protocol; not agent authority." } }, "/api/v1/workshops/{workshop_id}/browser-controller/readiness": { "post": { "operationId": "reportBrowserControllerReadiness", "parameters": [ { "in": "path", "name": "workshop_id", "required": true, "schema": { "format": "uuid", "title": "Workshop Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ControllerSignedRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ControllerStatusResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Report Browser Controller Readiness", "tags": [ "browser-controller" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Protected controller installation and independent-key protocol; not agent authority." } }, "/api/v1/workshops/{workshop_id}/browser-controller/transport-paused": { "post": { "operationId": "pauseBrowserControllerTransport", "parameters": [ { "in": "path", "name": "workshop_id", "required": true, "schema": { "format": "uuid", "title": "Workshop Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ControllerSignedRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ControllerModeAppliedResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Pause Browser Controller Transport", "tags": [ "browser-controller" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Protected controller installation and independent-key protocol; not agent authority." } }, "/api/v1/workshops/{workshop_id}/daemon-update": { "post": { "description": "Update now (TIDY-19118): move this box onto the runtime Tidy has\npromoted, approved by the caller. The box still swaps only once every\nemployee is idle, and rolls back if the new runtime does not stay up.", "operationId": "requestWorkshopDaemonUpdate", "parameters": [ { "description": "Workshop id (UUID)", "in": "path", "name": "workshop_id", "required": true, "schema": { "description": "Workshop id (UUID)", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", "title": "Workshop Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkshopResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Request Daemon Update", "tags": [ "workshops", "workshops" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/workshops/{workshop_id}/detach-employee": { "post": { "description": "Remove an employee from this workshop. The employee — definition,\nbacklog, memory, conversations — persists and can redeploy elsewhere.", "operationId": "detachWorkshopEmployee", "parameters": [ { "description": "Workshop id (UUID)", "in": "path", "name": "workshop_id", "required": true, "schema": { "description": "Workshop id (UUID)", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", "title": "Workshop Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkshopDetachRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkshopResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Detach Employee", "tags": [ "workshops", "workshops" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/workshops/{workshop_id}/employees/{agent_account_id}/deploy": { "post": { "description": "Deploy an assigned employee through the workshop daemon (TIDY-18237):\na signed `employee.adopt` job carrying a server-minted claim token, behind\na policy-gated `harness.ensure` when the box lacks the harness, and a\n`health.check` after it. 409 `deploy_in_progress` while one is open;\n`harness_unsupported_on_workshop` names the constraint before anything\nis queued.", "operationId": "deployWorkshopEmployee", "parameters": [ { "description": "Workshop id (UUID)", "in": "path", "name": "workshop_id", "required": true, "schema": { "description": "Workshop id (UUID)", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", "title": "Workshop Id", "type": "string" } }, { "description": "Employee agent account id (UUID)", "in": "path", "name": "agent_account_id", "required": true, "schema": { "description": "Employee agent account id (UUID)", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", "title": "Agent Account Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkshopDeployRequest" } } }, "required": true }, "responses": { "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkshopPushJobEnqueueResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Deploy Employee", "tags": [ "workshops", "workshops" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/workshops/{workshop_id}/employees/{agent_account_id}/deploy-status": { "get": { "description": "The six-step deploy ledger for one employee on one workshop, with the\npush job carrying it. Every step is present; a step nothing has touched\nreads `pending`.", "operationId": "getWorkshopEmployeeDeployStatus", "parameters": [ { "description": "Workshop id (UUID)", "in": "path", "name": "workshop_id", "required": true, "schema": { "description": "Workshop id (UUID)", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", "title": "Workshop Id", "type": "string" } }, { "description": "Employee agent account id (UUID)", "in": "path", "name": "agent_account_id", "required": true, "schema": { "description": "Employee agent account id (UUID)", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", "title": "Agent Account Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkshopDeployStatus" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Deploy Status", "tags": [ "workshops", "workshops", "workshops" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/workshops/{workshop_id}/employees/{agent_account_id}/deploy-steps/{step}/retry": { "post": { "description": "Retry one failed deploy step (TIDY-20019 F8): re-run that step and what\ndepends on it, never the whole deploy unless the step is the deploy (the\nharness, the adopt). A Retry that would restart an employee running there\nrefuses 409 `deploy_retry_restarts_employee` with its turns in progress\nuntil `restart` says it may; a skills step waiting only on a key refuses\n`deploy_step_needs_key` — lending the key installs it.\n\nTIDY-20019 F11: a redeploying Retry refused for access it needs is retried\nwith the access reviewed for it (the deploy's own fields), through this\nsame Retry, so its restart gate still asks first.", "operationId": "retryWorkshopDeployStep", "parameters": [ { "description": "Workshop id (UUID)", "in": "path", "name": "workshop_id", "required": true, "schema": { "description": "Workshop id (UUID)", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", "title": "Workshop Id", "type": "string" } }, { "description": "Employee agent account id (UUID)", "in": "path", "name": "agent_account_id", "required": true, "schema": { "description": "Employee agent account id (UUID)", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", "title": "Agent Account Id", "type": "string" } }, { "in": "path", "name": "step", "required": true, "schema": { "enum": [ "harness", "credentials", "mcp", "skills", "roots", "health_check" ], "title": "Step", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/WorkshopDeployStepRetryRequest" }, { "type": "null" } ], "title": "Body" } } } }, "responses": { "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkshopDeployStepRetry" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Retry Deploy Step", "tags": [ "workshops", "workshops", "workshops" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/workshops/{workshop_id}/employees/{agent_account_id}/setup-command": { "post": { "description": "Deploy an assigned employee onto its workshop's machine.\n\nThe define journey creates a portable employee with no machine at all, so\nthis is where the two halves meet: the OS/architecture come from the\nworkshop, the identity and harness from the employee, and the owner names\nthe one fact neither row holds — the project directory on that box.", "operationId": "mintWorkshopEmployeeSetupCommand", "parameters": [ { "description": "Workshop id (UUID)", "in": "path", "name": "workshop_id", "required": true, "schema": { "description": "Workshop id (UUID)", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", "title": "Workshop Id", "type": "string" } }, { "description": "Employee agent account id (UUID)", "in": "path", "name": "agent_account_id", "required": true, "schema": { "description": "Employee agent account id (UUID)", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", "title": "Agent Account Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkshopEmployeeSetupCommandRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkshopEmployeeSetupCommandResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Mint Employee Setup Command", "tags": [ "workshops", "workshops" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/workshops/{workshop_id}/enroll": { "post": { "description": "Enroll the WORKSHOP-scoped gateway (F1): mints/binds\n`host_instance_id` on the workshop row and starts its liveness — an\nenrolled workshop with zero employees is honestly `online`. Called by the\nworkshop setup command (the guided establish journey is S2; this is its\ncontract).", "operationId": "enrollWorkshopGateway", "parameters": [ { "description": "Workshop id (UUID)", "in": "path", "name": "workshop_id", "required": true, "schema": { "description": "Workshop id (UUID)", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", "title": "Workshop Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkshopEnrollRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkshopEnrollResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Enroll Workshop", "tags": [ "workshops", "workshops" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/workshops/{workshop_id}/gateway-adopt": { "post": { "description": "`install-workshop.sh --heal` on a box enrolled by the retired timer\npath (TIDY-18237): mints the daemon's PAT and signing key for the SAME\nidentity so the migration has no heartbeat gap and no re-enrollment.\nAuthenticated by the continuity token, like the heartbeat — a wrong host\nid or token is the same 409.", "operationId": "adoptWorkshopDaemon", "parameters": [ { "description": "Workshop id (UUID)", "in": "path", "name": "workshop_id", "required": true, "schema": { "description": "Workshop id (UUID)", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", "title": "Workshop Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkshopDaemonAdoptRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkshopEnrollResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Adopt Daemon", "tags": [ "workshops", "workshops" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/workshops/{workshop_id}/gateway-heartbeat": { "post": { "description": "The workshop gateway's own liveness beat. Continuity violations keep\ntheir refuse-to-boot semantics (409); a stale-flipped workshop re-arms to\n`online` here.\n\nAuthenticated by the continuity token, not by a session (TIDY-17341): the\nbeat comes from the workshop machine, which holds the token the enrollment\nhanded it and no Tidy session at all. The tenant is resolved FROM the\nworkshop row, so a caller cannot beat across tenants; a wrong host id or\ntoken is the same 409 it always was.", "operationId": "workshopGatewayHeartbeat", "parameters": [ { "description": "Workshop id (UUID)", "in": "path", "name": "workshop_id", "required": true, "schema": { "description": "Workshop id (UUID)", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", "title": "Workshop Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkshopHeartbeatRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkshopHeartbeatResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Gateway Heartbeat", "tags": [ "workshops", "workshops" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/workshops/{workshop_id}/gateway-lifecycle": { "post": { "description": "The installer's last step (TIDY-18037): what it measured about the\ndaemon's supervisor once the daemon was up — enabled at boot, stayed up —\nand, in return, the outcome of the pinned note that records this machine\nin the enrolling member's workspace. An updater that left the daemon not\nrunning reports here too, with `update_error` (TIDY-19497). Authenticated\nby the continuity token, like the heartbeat; a wrong host id or token is\nthe same 409.", "operationId": "reportWorkshopGatewayLifecycle", "parameters": [ { "description": "Workshop id (UUID)", "in": "path", "name": "workshop_id", "required": true, "schema": { "description": "Workshop id (UUID)", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", "title": "Workshop Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkshopGatewayLifecycleRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkshopGatewayLifecycleResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Gateway Lifecycle", "tags": [ "workshops", "workshops" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/workshops/{workshop_id}/harness-catalog": { "get": { "description": "TIDY-19931 (F7) — every harness this workshop can be given: the built-ins\nTidy drives on its own adapters and the Agent Client Protocol registry's\nagents with a build for its platform, as one list. Each says whether Tidy\ncan install it here (or why not) and what the workshop runs.\n\nThe Runtime tab's harness picker reads this, and the workshop's registered\nInstall / Remove harness actions offer their choices from the same list.\nThe registry is read by the server (cached, bounded); when it cannot be\nreached the built-ins are still listed and `registry_unavailable` says so.", "operationId": "listWorkshopHarnessCatalog", "parameters": [ { "description": "Workshop id (UUID)", "in": "path", "name": "workshop_id", "required": true, "schema": { "description": "Workshop id (UUID)", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", "title": "Workshop Id", "type": "string" } }, { "description": "Matched in id, name and description.", "in": "query", "name": "q", "required": false, "schema": { "anyOf": [ { "maxLength": 100, "type": "string" }, { "type": "null" } ], "description": "Matched in id, name and description.", "title": "Q" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkshopHarnessCatalogResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List Workshop Harness Catalog", "tags": [ "workshops", "workshops", "workshops" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/workshops/{workshop_id}/harnesses/{runtime}/holders": { "get": { "description": "Who still uses this harness on this box — employees and live\nconversations — plus whether a `harness.remove` reservation is open.\n\nNo primitives-read scope: the workshop daemon re-validates holders at\nexecution with its AGENT_CONTROL_WRITE PAT, and the owner reads the same\npayload from the session. `_fetch_workshop` keeps the row tenant-scoped.", "operationId": "listWorkshopHarnessHolders", "parameters": [ { "description": "Workshop id (UUID)", "in": "path", "name": "workshop_id", "required": true, "schema": { "description": "Workshop id (UUID)", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", "title": "Workshop Id", "type": "string" } }, { "in": "path", "name": "runtime", "required": true, "schema": { "title": "Runtime", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkshopHarnessHoldersResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List Harness Holders", "tags": [ "workshops", "workshops", "workshops" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/workshops/{workshop_id}/mounts/{mount_id}/browse": { "post": { "description": "Browse one directory on a reported mount: pushes an ``fs.browse`` job\nto the enrolled daemon and relays the listing it answers with. Read-only\non the box — the daemon lists a directory and sends the names back; the\nbytes never travel. ``mount_id`` is the stable id the list endpoint shows\n(URL-safe; the mount point may hold ``/``). A workshop that is not\nreachable by the time the bounded wait expires answers ``queued`` with its\njob id — the last beat's mount list still stands. On a workshop that asks\nbefore anything runs, its approver's own browse is the approval of that\nread (TIDY-19414); anyone else's waits in Attention.", "operationId": "browseWorkshopMount", "parameters": [ { "description": "Workshop id (UUID)", "in": "path", "name": "workshop_id", "required": true, "schema": { "description": "Workshop id (UUID)", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", "title": "Workshop Id", "type": "string" } }, { "description": "Mount id (12-hex sha256 digest of kind + mount point, not a UUID)", "in": "path", "name": "mount_id", "required": true, "schema": { "description": "Mount id (12-hex sha256 digest of kind + mount point, not a UUID)", "pattern": "^[0-9a-f]{12}$", "title": "Mount Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkshopMountBrowseRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkshopMountBrowseResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Browse Workshop Mount", "tags": [ "workshops", "workshops" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/workshops/{workshop_id}/mounts/{mount_id}/mkdir": { "post": { "description": "Create a folder on a reported mount: signs one ``fs.mkdir`` frame to\nthe enrolled daemon over the read relay and relays its answer. The box\nre-checks the boundary on its own filesystem — a symlink inside the mount\nis refused, and a name the sensitive list withholds is never created.\nThe write gate is the attach gate: the box's owner or a workspace\nOwner/Admin, not merely anyone who can see the record.", "operationId": "mkdirWorkshopMount", "parameters": [ { "description": "Workshop id (UUID)", "in": "path", "name": "workshop_id", "required": true, "schema": { "description": "Workshop id (UUID)", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", "title": "Workshop Id", "type": "string" } }, { "description": "Mount id (12-hex sha256 digest of kind + mount point, not a UUID)", "in": "path", "name": "mount_id", "required": true, "schema": { "description": "Mount id (12-hex sha256 digest of kind + mount point, not a UUID)", "pattern": "^[0-9a-f]{12}$", "title": "Mount Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkshopMountMkdirRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkshopMountMkdirResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Mkdir Workshop Mount", "tags": [ "workshops", "workshops" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/workshops/{workshop_id}/mounts/{mount_id}/shares": { "get": { "description": "The live grants on a mount, newest first — what, to whom, at which\nrole. A read: anyone who can see the workshop sees who its folder is\nshared with. Revoked grants are gone.", "operationId": "listWorkshopMountShares", "parameters": [ { "description": "Workshop id (UUID)", "in": "path", "name": "workshop_id", "required": true, "schema": { "description": "Workshop id (UUID)", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", "title": "Workshop Id", "type": "string" } }, { "description": "Mount id (12-hex sha256 digest of kind + mount point, not a UUID)", "in": "path", "name": "mount_id", "required": true, "schema": { "description": "Mount id (12-hex sha256 digest of kind + mount point, not a UUID)", "pattern": "^[0-9a-f]{12}$", "title": "Mount Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkshopMountSharesListResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List Workshop Mount Shares", "tags": [ "workshops", "workshops" ], "x-local-capability": "cloud", "x-mcp-skip": true }, "post": { "description": "Share a folder on a reported mount to one or more VEs at a role.\n\nThe control plane records the grant (this mount, this prefix, to this VE,\nat this role), validates each grantee is on the workshop's roster, and\naudits the grant. The box — not this route — is the authority on its own\nfilesystem: it honors the grant only for the prefix it names and refuses a\nwrite under a ``read`` grant. The gate is the attach gate: a grant\nauthorizes a sandboxed process to reach a machine's disk, so it is the\nowner's (or a workspace Owner/Admin's) call, never anyone who can merely\nsee the record.", "operationId": "createWorkshopMountShare", "parameters": [ { "description": "Workshop id (UUID)", "in": "path", "name": "workshop_id", "required": true, "schema": { "description": "Workshop id (UUID)", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", "title": "Workshop Id", "type": "string" } }, { "description": "Mount id (12-hex sha256 digest of kind + mount point, not a UUID)", "in": "path", "name": "mount_id", "required": true, "schema": { "description": "Mount id (12-hex sha256 digest of kind + mount point, not a UUID)", "pattern": "^[0-9a-f]{12}$", "title": "Mount Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkshopMountShareCreateRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkshopMountShareCreateResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Create Workshop Mount Share", "tags": [ "workshops", "workshops" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/workshops/{workshop_id}/mounts/{mount_id}/shares/{share_id}": { "delete": { "description": "Revoke one grant: the box stops honoring it, and the revocation is\naudited. Never destructive — the folder on disk is left alone. Attach-\ngated, like the grant itself.", "operationId": "revokeWorkshopMountShare", "parameters": [ { "description": "Workshop id (UUID)", "in": "path", "name": "workshop_id", "required": true, "schema": { "description": "Workshop id (UUID)", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", "title": "Workshop Id", "type": "string" } }, { "description": "Mount id (12-hex sha256 digest of kind + mount point, not a UUID)", "in": "path", "name": "mount_id", "required": true, "schema": { "description": "Mount id (12-hex sha256 digest of kind + mount point, not a UUID)", "pattern": "^[0-9a-f]{12}$", "title": "Mount Id", "type": "string" } }, { "description": "Mount share id (UUID minted by the grant response's answer)", "in": "path", "name": "share_id", "required": true, "schema": { "description": "Mount share id (UUID minted by the grant response's answer)", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", "title": "Share Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkshopMountShareRevokeResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Revoke Workshop Mount Share", "tags": [ "workshops", "workshops" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/workshops/{workshop_id}/mounts/{mount_id}/uploads": { "post": { "description": "Begin a save session onto a reported mount: the box opens an\nunguessable temp file in the file's directory and answers the session's\ntoken. The uploader then posts the file's slices one at a time\n(``uploadWorkshopMountChunk``) and closes with ``commitWorkshopMountUpload``\n— the box renames the temp onto the final path atomically and reports the\nhash it read back. The bytes cross the relay one slice at a time and\nnever park in backend storage.", "operationId": "beginWorkshopMountUpload", "parameters": [ { "description": "Workshop id (UUID)", "in": "path", "name": "workshop_id", "required": true, "schema": { "description": "Workshop id (UUID)", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", "title": "Workshop Id", "type": "string" } }, { "description": "Mount id (12-hex sha256 digest of kind + mount point, not a UUID)", "in": "path", "name": "mount_id", "required": true, "schema": { "description": "Mount id (12-hex sha256 digest of kind + mount point, not a UUID)", "pattern": "^[0-9a-f]{12}$", "title": "Mount Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkshopMountUploadBeginRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkshopMountUploadBeginResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Begin Workshop Mount Upload", "tags": [ "workshops", "workshops" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/workshops/{workshop_id}/mounts/{mount_id}/uploads/{upload_id}/chunks": { "post": { "description": "Relay one slice of a save session to the box: the slice is sealed to\nthe box's per-boot key, its digest signed into the frame, and the box\nappends it at the offset the schedule names. A retried slice lands on the\nsame bytes — the write is idempotent, so a lost answer costs a rewrite of\nidentical content, never a corrupted file.", "operationId": "uploadWorkshopMountChunk", "parameters": [ { "description": "Workshop id (UUID)", "in": "path", "name": "workshop_id", "required": true, "schema": { "description": "Workshop id (UUID)", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", "title": "Workshop Id", "type": "string" } }, { "description": "Mount id (12-hex sha256 digest of kind + mount point, not a UUID)", "in": "path", "name": "mount_id", "required": true, "schema": { "description": "Mount id (12-hex sha256 digest of kind + mount point, not a UUID)", "pattern": "^[0-9a-f]{12}$", "title": "Mount Id", "type": "string" } }, { "description": "Upload session id (UUID minted by the begin response's answer)", "in": "path", "name": "upload_id", "required": true, "schema": { "description": "Upload session id (UUID minted by the begin response's answer)", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", "title": "Upload Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkshopMountUploadChunkRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkshopMountUploadChunkResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Upload Workshop Mount Chunk", "tags": [ "workshops", "workshops" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/workshops/{workshop_id}/mounts/{mount_id}/uploads/{upload_id}/commit": { "post": { "description": "Commit a save session: the box checks the temp file against the\ndeclared size, reports the sha256 it read back, and renames it onto the\nfinal path. A commit whose answer was lost is idempotent — the box says\nthe file is already there from the final file itself, not from memory.", "operationId": "commitWorkshopMountUpload", "parameters": [ { "description": "Workshop id (UUID)", "in": "path", "name": "workshop_id", "required": true, "schema": { "description": "Workshop id (UUID)", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", "title": "Workshop Id", "type": "string" } }, { "description": "Mount id (12-hex sha256 digest of kind + mount point, not a UUID)", "in": "path", "name": "mount_id", "required": true, "schema": { "description": "Mount id (12-hex sha256 digest of kind + mount point, not a UUID)", "pattern": "^[0-9a-f]{12}$", "title": "Mount Id", "type": "string" } }, { "description": "Upload session id (UUID minted by the begin response's answer)", "in": "path", "name": "upload_id", "required": true, "schema": { "description": "Upload session id (UUID minted by the begin response's answer)", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", "title": "Upload Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkshopMountUploadCommitRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkshopMountUploadCommitResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Commit Workshop Mount Upload", "tags": [ "workshops", "workshops" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/workshops/{workshop_id}/move-employee": { "post": { "description": "Move an employee HERE from wherever it runs today.\n\n409 `employee_not_settled` (carrying the conversations) unless `force`.\nForcing leaves the old machine's working tree in place, flagged — a dirty\ntree is never deleted. The employee's conversations, backlog, objectives\nand memory are untouched: only the machine changes.", "operationId": "moveWorkshopEmployee", "parameters": [ { "description": "Workshop id (UUID)", "in": "path", "name": "workshop_id", "required": true, "schema": { "description": "Workshop id (UUID)", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", "title": "Workshop Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkshopMoveRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkshopMoveResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Move Employee", "tags": [ "workshops", "workshops" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/workshops/{workshop_id}/moves": { "get": { "description": "Every move in or out of this workshop, newest first — including the\nones that failed, with the step they failed on.", "operationId": "listWorkshopMoves", "parameters": [ { "description": "Workshop id (UUID)", "in": "path", "name": "workshop_id", "required": true, "schema": { "description": "Workshop id (UUID)", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", "title": "Workshop Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkshopMoveListResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List Moves", "tags": [ "workshops", "workshops" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/workshops/{workshop_id}/plugin-access-plan": { "post": { "description": "The plugin access an attach, move or deploy of this employee onto this\nworkshop needs from you — or, with no employee yet (Define), what the\nskills you picked will need once it runs on ``harness`` here. Read-only:\nnothing is created to answer it. Requirements, readiness and ids only;\nnames are the client's own local-first rows.", "operationId": "planWorkshopDeployPluginAccess", "parameters": [ { "description": "Workshop id (UUID)", "in": "path", "name": "workshop_id", "required": true, "schema": { "description": "Workshop id (UUID)", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", "title": "Workshop Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeployPluginAccessPlanRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeployPluginAccessPlan" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Plan Deploy Plugin Access", "tags": [ "workshops", "workshops" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "A person's own Access review before a deploy (TIDY-19802)." } }, "/api/v1/workshops/{workshop_id}/provider-actions": { "post": { "operationId": "actOnWorkshopProvider", "parameters": [ { "in": "path", "name": "workshop_id", "required": true, "schema": { "format": "uuid", "title": "Workshop Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderActionRequest" } } }, "required": true }, "responses": { "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperationResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Provider Action", "tags": [ "workshops", "workshop-providers" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Privileged provider settings and confirmed cloud lifecycle; provider secrets never enter generative tools." } }, "/api/v1/workshops/{workshop_id}/provision": { "post": { "operationId": "provisionWorkshop", "parameters": [ { "in": "path", "name": "workshop_id", "required": true, "schema": { "format": "uuid", "title": "Workshop Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProvisionRequest" } } }, "required": true }, "responses": { "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperationResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Provision", "tags": [ "workshops", "workshop-providers" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Privileged provider settings and confirmed cloud lifecycle; provider secrets never enter generative tools." } }, "/api/v1/workshops/{workshop_id}/pty/tickets": { "post": { "description": "Mint a single-use PTY attach ticket for a workshop machine.\n\nThe shell runs as the workshop's own service account (TIDY-19592), not\ninside any employee. Refuses — never silently downgrades — when the caller\nis not on the attach allowlist (the workshop's owner, or a workspace\nOwner/Admin), when the workshop has no live daemon credential, or when\nthis workshop has minted too many sessions in the last minute. The ticket\nis worthless without the caller's own bearer: the relay checks both.", "operationId": "mintWorkshopPtyTicket", "parameters": [ { "in": "path", "name": "workshop_id", "required": true, "schema": { "title": "Workshop Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MintPtyTicketResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Mint Pty Ticket", "tags": [ "workshops" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/workshops/{workshop_id}/push-jobs": { "get": { "description": "The push history, newest first: every job with its digest, policy\noutcome and approver.", "operationId": "listWorkshopPushJobs", "parameters": [ { "description": "Workshop id (UUID)", "in": "path", "name": "workshop_id", "required": true, "schema": { "description": "Workshop id (UUID)", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", "title": "Workshop Id", "type": "string" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "title": "Limit", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkshopPushJobListResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List Push Jobs", "tags": [ "workshops", "workshops", "workshops" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/workshops/{workshop_id}/push-jobs/{job_id}": { "get": { "operationId": "getWorkshopPushJob", "parameters": [ { "description": "Workshop id (UUID)", "in": "path", "name": "workshop_id", "required": true, "schema": { "description": "Workshop id (UUID)", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", "title": "Workshop Id", "type": "string" } }, { "description": "Push job id (UUID)", "in": "path", "name": "job_id", "required": true, "schema": { "description": "Push job id (UUID)", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", "title": "Job Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkshopPushJob" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Push Job", "tags": [ "workshops", "workshops", "workshops" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/workshops/{workshop_id}/push-jobs/{job_id}/approve": { "post": { "description": "Let a policy-held job run. The approver is recorded on the row.", "operationId": "approveWorkshopPushJob", "parameters": [ { "description": "Workshop id (UUID)", "in": "path", "name": "workshop_id", "required": true, "schema": { "description": "Workshop id (UUID)", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", "title": "Workshop Id", "type": "string" } }, { "description": "Push job id (UUID)", "in": "path", "name": "job_id", "required": true, "schema": { "description": "Push job id (UUID)", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", "title": "Job Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkshopPushJob" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Approve Push Job", "tags": [ "workshops", "workshops", "workshops" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/workshops/{workshop_id}/push-jobs/{job_id}/approve-request": { "post": { "description": "Approve exactly the request that was reviewed (TIDY-19802 U2). Refused\nwith nothing written: 409 `push_request_changed` when the request changed\nsince its review (review it again), 409 `push_request_not_reviewable` when\nTidy cannot fully describe what it would release, 503\n`push_request_review_unavailable` when it could not re-read it in time.", "operationId": "approveWorkshopPushRequest", "parameters": [ { "description": "Workshop id (UUID)", "in": "path", "name": "workshop_id", "required": true, "schema": { "description": "Workshop id (UUID)", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", "title": "Workshop Id", "type": "string" } }, { "description": "Push job id (UUID)", "in": "path", "name": "job_id", "required": true, "schema": { "description": "Push job id (UUID)", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", "title": "Job Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkshopPushRequestApprove" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkshopPushJob" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Approve Push Request", "tags": [ "workshops", "workshops", "workshops" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/workshops/{workshop_id}/push-jobs/{job_id}/cancel": { "post": { "description": "Cancel a job that has not ended — a queued one never runs, an\nin-flight one is told to stop over its channel.", "operationId": "cancelWorkshopPushJob", "parameters": [ { "description": "Workshop id (UUID)", "in": "path", "name": "workshop_id", "required": true, "schema": { "description": "Workshop id (UUID)", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", "title": "Workshop Id", "type": "string" } }, { "description": "Push job id (UUID)", "in": "path", "name": "job_id", "required": true, "schema": { "description": "Push job id (UUID)", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", "title": "Job Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkshopPushJob" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Cancel Push Job", "tags": [ "workshops", "workshops", "workshops" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/workshops/{workshop_id}/push-jobs/{job_id}/deny": { "post": { "description": "Refuse a policy-held job; whatever depended on it is cancelled too.", "operationId": "denyWorkshopPushJob", "parameters": [ { "description": "Workshop id (UUID)", "in": "path", "name": "workshop_id", "required": true, "schema": { "description": "Workshop id (UUID)", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", "title": "Workshop Id", "type": "string" } }, { "description": "Push job id (UUID)", "in": "path", "name": "job_id", "required": true, "schema": { "description": "Push job id (UUID)", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", "title": "Job Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkshopPushJob" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Deny Push Job", "tags": [ "workshops", "workshops", "workshops" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/workshops/{workshop_id}/push-jobs/{job_id}/request": { "get": { "description": "Everything approving this held job would release, a page at a time\n(TIDY-19802 U2): the whole dependency-connected request, its totals and\none digest every page carries. Approve it with `approve-request` and that\ndigest. Reads only; the approver is checked again on the snapshot read.", "operationId": "reviewWorkshopPushRequest", "parameters": [ { "description": "Workshop id (UUID)", "in": "path", "name": "workshop_id", "required": true, "schema": { "description": "Workshop id (UUID)", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", "title": "Workshop Id", "type": "string" } }, { "description": "Push job id (UUID)", "in": "path", "name": "job_id", "required": true, "schema": { "description": "Push job id (UUID)", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", "title": "Job Id", "type": "string" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cursor" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "maximum": 200, "minimum": 1, "title": "Limit", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkshopPushRequestReview" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Review Push Request", "tags": [ "workshops", "workshops", "workshops" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/workshops/{workshop_id}/push-jobs/{job_id}/retry": { "post": { "description": "Run a failed, refused or cancelled job again as a fresh signed copy.\nA deploy-chain job re-runs the deploy instead, so the box gets a claim\ntoken that is still valid, and a post-revocation cleanup job is re-armed as\nitself — the capability that admits the box names that one job id.\n\nTIDY-18249: the body moved to ``workshop_push_verbs.owner_retry_job`` —\nthe ONE owner-retry implementation, shared with the facet-action spine\nthe Android offline outbox drains through.", "operationId": "retryWorkshopPushJob", "parameters": [ { "description": "Workshop id (UUID)", "in": "path", "name": "workshop_id", "required": true, "schema": { "description": "Workshop id (UUID)", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", "title": "Workshop Id", "type": "string" } }, { "description": "Push job id (UUID)", "in": "path", "name": "job_id", "required": true, "schema": { "description": "Push job id (UUID)", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", "title": "Job Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkshopPushJob" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Retry Push Job", "tags": [ "workshops", "workshops", "workshops" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/workshops/{workshop_id}/push-policy": { "patch": { "description": "What the box may do without asking (D17): `automatic`, `ask_installs`\n(the default — harness installs, the browser controller and uninstall\nwait for Approve), or `ask_all`. The tenant floor still applies on top.", "operationId": "setWorkshopPushPolicy", "parameters": [ { "description": "Workshop id (UUID)", "in": "path", "name": "workshop_id", "required": true, "schema": { "description": "Workshop id (UUID)", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", "title": "Workshop Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkshopPushPolicyRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkshopResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Set Push Policy", "tags": [ "workshops", "workshops" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/workshops/{workshop_id}/redeploy-roster": { "post": { "description": "D16 — the \"workshop died, stand up a new box, the team resumes\"\njourney. The same move fanned over the roster; a partial failure isolates\nto the employee that could not move.", "operationId": "redeployWorkshopRoster", "parameters": [ { "description": "Workshop id (UUID)", "in": "path", "name": "workshop_id", "required": true, "schema": { "description": "Workshop id (UUID)", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", "title": "Workshop Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkshopRedeployRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkshopRedeployResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Redeploy Roster", "tags": [ "workshops", "workshops" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/workshops/{workshop_id}/redeploy-roster/plugin-access-plan": { "post": { "description": "Every employee a roster redeploy would move, with what it needs from you\non the target — the one review before confirming (D2).", "operationId": "planWorkshopRedeployPluginAccess", "parameters": [ { "description": "Workshop id (UUID)", "in": "path", "name": "workshop_id", "required": true, "schema": { "description": "Workshop id (UUID)", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", "title": "Workshop Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkshopRedeployRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RosterPluginAccessPlan" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Plan Redeploy Plugin Access", "tags": [ "workshops", "workshops" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "A person's own Access review before a deploy (TIDY-19802)." } }, "/api/v1/workshops/{workshop_id}/revoke": { "post": { "description": "Revoke the box (D17): every employee device, materialized key, browser\ncontroller, workshop token and continuity token dies now; the daemon\nself-disables on its next beat. Irreversible for this identity — a\nre-establish mints a new one.", "operationId": "revokeWorkshop", "parameters": [ { "description": "Workshop id (UUID)", "in": "path", "name": "workshop_id", "required": true, "schema": { "description": "Workshop id (UUID)", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", "title": "Workshop Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkshopRevokeRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkshopRevokeResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Revoke Workshop", "tags": [ "workshops", "workshops" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/workshops/{workshop_id}/setup-command": { "post": { "description": "The last step of the establish-workshop journey: the one-time command\nthe owner runs ON that machine. Single use and TTL-bounded; re-minting\nsupersedes the previous command.", "operationId": "mintWorkshopSetupCommand", "parameters": [ { "description": "Workshop id (UUID)", "in": "path", "name": "workshop_id", "required": true, "schema": { "description": "Workshop id (UUID)", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", "title": "Workshop Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkshopSetupCommandRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkshopSetupCommandResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Mint Setup Command", "tags": [ "workshops", "workshops" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/workshops/{workshop_id}/sleep-state": { "post": { "description": "The Tidy desktop app on the workshop machine reports the OS suspend or\nresume it observed (TIDY-18239). `asleep` is what turns the next missed\nheartbeat into \"offline while asleep\" instead of an alarm; `awake`\nclears it. Never touches `gateway_status` — only the daemon's own beat\nbrings the gateway back.", "operationId": "setWorkshopSleepState", "parameters": [ { "description": "Workshop id (UUID)", "in": "path", "name": "workshop_id", "required": true, "schema": { "description": "Workshop id (UUID)", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", "title": "Workshop Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkshopSleepStateRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkshopSleepStateResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Set Sleep State", "tags": [ "workshops", "workshops" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/workshops/{workshop_id}/tunnels": { "post": { "description": "Ask for a tunnel: programs on this workshop reach `port` on the other\nworkshop's 127.0.0.1. Nothing listens or connects until the other\nworkshop's owner approves it from the Attention card this raises.", "operationId": "requestWorkshopTunnel", "parameters": [ { "description": "The workshop the tunnel starts from, or `self` for the one you run on.", "in": "path", "name": "workshop_id", "required": true, "schema": { "description": "The workshop the tunnel starts from, or `self` for the one you run on.", "title": "Workshop Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkshopTunnelRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkshopTunnelResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Ask another workshop's owner for a tunnel from this workshop to a port there", "tags": [ "workshops" ], "x-local-capability": "cloud" } }, "/api/v1/workshops/{workshop_id}/update-policy": { "patch": { "description": "How this box takes a new Tidy runtime (TIDY-19118): `automatic` (the\ndefault — the daemon updates itself when every employee is idle) or `ask`\n(the update waits in Attention for Approve).", "operationId": "setWorkshopUpdatePolicy", "parameters": [ { "description": "Workshop id (UUID)", "in": "path", "name": "workshop_id", "required": true, "schema": { "description": "Workshop id (UUID)", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", "title": "Workshop Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkshopUpdatePolicyRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkshopResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Set Update Policy", "tags": [ "workshops", "workshops" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v1/workspace-templates": { "get": { "description": "List published workspace templates (authenticated). Filters by family/chip.", "operationId": "listWorkspaceTemplates", "parameters": [ { "description": "Filter by family (business|personal)", "in": "query", "name": "family", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by family (business|personal)", "title": "Family" } }, { "description": "Filter to templates carrying this chip", "in": "query", "name": "chip", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter to templates carrying this chip", "title": "Chip" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/WorkspaceTemplateListItem" }, "title": "Response Listworkspacetemplates", "type": "array" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List Workspace Templates", "tags": [ "workspace-templates", "workspace-templates" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "TIDY-14038 catalog/authoring; marketplace MCP tooling is S8/S9" }, "post": { "description": "Create or update a draft workspace template (admin/service-role only).", "operationId": "upsertWorkspaceTemplate", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceTemplateUpsertRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceTemplateResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Upsert Workspace Template", "tags": [ "workspace-templates", "workspace-templates" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "TIDY-14038 catalog/authoring; marketplace MCP tooling is S8/S9" } }, "/api/v1/workspace-templates/{slug}": { "get": { "description": "Published workspace template detail with the generated 'what you get' summary.", "operationId": "getWorkspaceTemplate", "parameters": [ { "in": "path", "name": "slug", "required": true, "schema": { "title": "Slug", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceTemplateResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Workspace Template", "tags": [ "workspace-templates", "workspace-templates" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "TIDY-14038 catalog/authoring; marketplace MCP tooling is S8/S9" } }, "/api/v1/workspace-templates/{slug}/apply": { "post": { "description": "Apply a published template into the caller's tenant, recording the manifest.", "operationId": "applyWorkspaceTemplate", "parameters": [ { "in": "path", "name": "slug", "required": true, "schema": { "title": "Slug", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/api_service__models__template_install__ApplyRequest" }, { "type": "null" } ], "title": "Body" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InstallResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Apply Endpoint", "tags": [ "template-installs", "template-installs" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "TIDY-14039 apply/install; marketplace MCP tooling is S8/S9" } }, "/api/v1/workspace-templates/{slug}/preview-apply": { "post": { "description": "Return the apply plan (create/skip per item) without writing anything.", "operationId": "previewApplyWorkspaceTemplate", "parameters": [ { "in": "path", "name": "slug", "required": true, "schema": { "title": "Slug", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PreviewApplyResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Preview Apply Endpoint", "tags": [ "template-installs", "template-installs" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "TIDY-14039 apply/install; marketplace MCP tooling is S8/S9" } }, "/api/v1/workspace-templates/{slug}/publish": { "post": { "description": "Validate + publish the draft, bumping version and snapshotting (admin only).", "operationId": "publishWorkspaceTemplate", "parameters": [ { "in": "path", "name": "slug", "required": true, "schema": { "title": "Slug", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceTemplateResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Publish Workspace Template", "tags": [ "workspace-templates", "workspace-templates" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "TIDY-14038 catalog/authoring; marketplace MCP tooling is S8/S9" } }, "/api/v1/workspace-templates/{slug}/validate": { "post": { "description": "Validate the stored draft definition without publishing (admin only).", "operationId": "validateWorkspaceTemplate", "parameters": [ { "in": "path", "name": "slug", "required": true, "schema": { "title": "Slug", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceTemplateValidateResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Validate Workspace Template", "tags": [ "workspace-templates", "workspace-templates" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "TIDY-14038 catalog/authoring; marketplace MCP tooling is S8/S9" } }, "/api/v1/workspace/accounts": { "get": { "description": "Return person info and all tenant memberships for the caller.", "operationId": "listWorkspaceAccounts", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceAccountsResponse" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List Workspace Accounts", "tags": [ "workspace", "workspace" ] } }, "/api/v1/workspace/capability-requests": { "get": { "operationId": "listCapabilityRequests", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListCapabilityRequestsResponse" } } }, "description": "Successful Response" } }, "summary": "List Capability Requests", "tags": [ "workspace", "workspace" ] } }, "/api/v1/workspace/capability-requests/{request_id}/decide": { "post": { "operationId": "decideCapabilityRequest", "parameters": [ { "in": "path", "name": "request_id", "required": true, "schema": { "title": "Request Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DecideRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DecideCapabilityRequestResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Decide Capability Request", "tags": [ "workspace", "workspace" ] } }, "/api/v1/workspace/connected-agents": { "get": { "description": "Agents the current user claimed via device-grant first-consent.\n\nFilters by ``first_bound_account_id`` (set by the approve handler at\nfirst-consent time). Excludes soft-deleted and rejected clients.", "operationId": "listConnectedAgents", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListConnectedAgentsResponse" } } }, "description": "Successful Response" } }, "summary": "List Connected Agents", "tags": [ "oauth_apps", "oauth_apps" ] } }, "/api/v1/workspace/connected-agents/{client_pk_id}/revoke": { "post": { "description": "Revoke a connected agent — scoped to the caller's account.\n\nOnly the user who claimed the client (``first_bound_account_id``) may\nrevoke it via this endpoint. Other users on the same client_id (rare\ntoday, possible after F-future multi-user agent installs) are\nunaffected. Token revocation propagates within the D20 60s SLO via\nRedis (see ``FamilyRevoker``).", "operationId": "revokeConnectedAgent", "parameters": [ { "in": "path", "name": "client_pk_id", "required": true, "schema": { "title": "Client Pk Id", "type": "string" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Revoke Connected Agent", "tags": [ "oauth_apps", "oauth_apps" ] } }, "/api/v1/workspace/connected-apps": { "get": { "operationId": "listConnectedApps", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListConnectedAppsResponse" } } }, "description": "Successful Response" } }, "summary": "List Connected Apps", "tags": [ "oauth_apps", "oauth_apps" ] } }, "/api/v1/workspace/connected-apps/{client_pk_id}": { "delete": { "description": "User revokes all of THEIR OWN grants for an OAuth app.\n\nImplemented as: for every non-revoked refresh-token family the user holds\nagainst this client, cascade-revoke the family. No tenant-wide side\neffects (that's /revoke-workspace-wide, admin-only).", "operationId": "revokeConnectedApp", "parameters": [ { "in": "path", "name": "client_pk_id", "required": true, "schema": { "title": "Client Pk Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevokeConnectedAppResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Revoke Connected App", "tags": [ "oauth_apps", "oauth_apps" ] } }, "/api/v1/workspace/current": { "get": { "description": "Return the person's currently active workspace context.", "operationId": "getCurrentWorkspace", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceCurrentResponse" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Current Workspace", "tags": [ "workspace", "workspace" ] } }, "/api/v1/workspace/me/capabilities/{capability}/request": { "post": { "operationId": "requestOwnCapability", "parameters": [ { "in": "path", "name": "capability", "required": true, "schema": { "title": "Capability", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestCapabilityResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Request Own Capability", "tags": [ "workspace", "workspace" ] } }, "/api/v1/workspace/member-items/{item_table}/{item_id}": { "get": { "description": "One member's item, read-only, for a workspace Owner or Admin.", "operationId": "getWorkspaceMemberItem", "parameters": [ { "in": "path", "name": "item_table", "required": true, "schema": { "title": "Item Table", "type": "string" } }, { "in": "path", "name": "item_id", "required": true, "schema": { "title": "Item Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemberItemResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Member Item", "tags": [ "workspace" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Owner/Admin oversight read for the web member-item tab." } }, "/api/v1/workspace/members": { "get": { "operationId": "listWorkspaceMembers", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListMembersResponse" } } }, "description": "Successful Response" } }, "summary": "List Members", "tags": [ "workspace", "workspace" ] } }, "/api/v1/workspace/members/{user_id}": { "get": { "operationId": "getWorkspaceMember", "parameters": [ { "in": "path", "name": "user_id", "required": true, "schema": { "title": "User Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemberDetailResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Get Member", "tags": [ "workspace", "workspace" ] } }, "/api/v1/workspace/members/{user_id}/capabilities/{capability}": { "delete": { "operationId": "revokeMemberCapability", "parameters": [ { "in": "path", "name": "user_id", "required": true, "schema": { "title": "User Id", "type": "string" } }, { "in": "path", "name": "capability", "required": true, "schema": { "title": "Capability", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityMutationResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Revoke Member Capability", "tags": [ "workspace", "workspace" ] }, "post": { "operationId": "grantMemberCapability", "parameters": [ { "in": "path", "name": "user_id", "required": true, "schema": { "title": "User Id", "type": "string" } }, { "in": "path", "name": "capability", "required": true, "schema": { "title": "Capability", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityMutationResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Grant Member Capability", "tags": [ "workspace", "workspace" ] } }, "/api/v1/workspace/members/{user_id}/role": { "put": { "operationId": "updateWorkspaceMemberRole", "parameters": [ { "in": "path", "name": "user_id", "required": true, "schema": { "title": "User Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoleUpdate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateMemberRoleResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Update Member Role", "tags": [ "workspace", "workspace" ] } }, "/api/v1/workspace/oauth-apps": { "get": { "operationId": "listOAuthApps", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListOAuthAppsResponse" } } }, "description": "Successful Response" } }, "summary": "List Oauth Apps", "tags": [ "oauth_apps", "oauth_apps" ] }, "post": { "operationId": "registerOAuthApp", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegisterOAuthAppRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegisterOAuthAppResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Register Oauth App", "tags": [ "oauth_apps", "oauth_apps" ] } }, "/api/v1/workspace/oauth-apps/{client_pk_id}": { "delete": { "operationId": "deleteOAuthApp", "parameters": [ { "in": "path", "name": "client_pk_id", "required": true, "schema": { "title": "Client Pk Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthAppMutationResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Delete Oauth App", "tags": [ "oauth_apps", "oauth_apps" ] }, "put": { "operationId": "updateOAuthApp", "parameters": [ { "in": "path", "name": "client_pk_id", "required": true, "schema": { "title": "Client Pk Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateOAuthAppRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthAppMutationResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Update Oauth App", "tags": [ "oauth_apps", "oauth_apps" ] } }, "/api/v1/workspace/oauth-apps/{client_pk_id}/revoke-workspace-wide": { "post": { "operationId": "revokeOAuthAppWorkspaceWide", "parameters": [ { "in": "path", "name": "client_pk_id", "required": true, "schema": { "title": "Client Pk Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevokeWorkspaceWideResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Revoke Oauth App Workspace Wide", "tags": [ "oauth_apps", "oauth_apps" ] } }, "/api/v1/workspace/oauth-apps/{client_pk_id}/scopes": { "put": { "operationId": "updateOAuthAppScopes", "parameters": [ { "in": "path", "name": "client_pk_id", "required": true, "schema": { "title": "Client Pk Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateScopesRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateOAuthAppScopesResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Update Oauth App Scopes", "tags": [ "oauth_apps", "oauth_apps" ] } }, "/api/v1/workspace/pats": { "get": { "operationId": "listWorkspacePats", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListTenantPATsResponse" } } }, "description": "Successful Response" } }, "summary": "List Tenant Pats", "tags": [ "pats", "pats" ] } }, "/api/v1/workspace/service-accounts": { "get": { "operationId": "listServiceAccounts", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListServiceAccountsResponse" } } }, "description": "Successful Response" } }, "summary": "List Service Accounts", "tags": [ "service_accounts", "service_accounts" ] }, "post": { "operationId": "createServiceAccount", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSARequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateServiceAccountResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Create Service Account", "tags": [ "service_accounts", "service_accounts" ] } }, "/api/v1/workspace/service-accounts/{sa_id}": { "delete": { "operationId": "revokeServiceAccount", "parameters": [ { "in": "path", "name": "sa_id", "required": true, "schema": { "title": "Sa Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceAccountMutationResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Revoke Service Account", "tags": [ "service_accounts", "service_accounts" ] }, "put": { "operationId": "updateServiceAccount", "parameters": [ { "in": "path", "name": "sa_id", "required": true, "schema": { "title": "Sa Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSARequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceAccountMutationResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Update Service Account", "tags": [ "service_accounts", "service_accounts" ] } }, "/api/v1/workspace/settings": { "get": { "operationId": "getWorkspaceSettings", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceSettingsResponse" } } }, "description": "Successful Response" } }, "summary": "Get Workspace Settings", "tags": [ "workspace", "workspace" ] } }, "/api/v1/workspace/settings/require-capability-approval": { "put": { "operationId": "updateRequireCapabilityApproval", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequireCapabilityApprovalUpdate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateRequireCapabilityApprovalResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Update Require Capability Approval", "tags": [ "workspace", "workspace" ] } }, "/api/v1/workspace/switch/{tenant_id}": { "post": { "description": "Switch active workspace to a different tenant.", "operationId": "switchWorkspace", "parameters": [ { "in": "path", "name": "tenant_id", "required": true, "schema": { "title": "Tenant Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceSwitchResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Switch Workspace", "tags": [ "workspace", "workspace" ] } }, "/api/v1/workstations": { "post": { "description": "Create or upsert a workstation (idempotent on `id`).\n\nThe caller is stamped as `owner_id` — a client-supplied owner is never\ntrusted — and the conflict UPDATE branch never writes `owner_id`, so an\nupsert over an existing row cannot transfer it.\n\nThat branch carries the SAME member-visible predicate PUT / PATCH /\nDELETE / reorder carry (TIDY-19131). It used to restate `tenant_id`\nalone, which made this the one door in a four-door write surface that a\nco-member could walk through: member B POSTing member A's id rewrote the\nrow — name, icon, position, and `visibility`, so B could flip A's\nPRIVATE workstation to `shared` — and got a 201 back naming A as owner.\n\nA conflict branch whose WHERE fails writes nothing and returns nothing,\nwhich is now two different refusals, so the no-op asks which one it was:\n\n* the id belongs to ANOTHER tenant → 409, unchanged (saved_views'\n TIDY-7564 guard, the only thing standing between a POST and a\n cross-tenant overwrite on a service connection that bypasses RLS);\n* the id belongs to THIS tenant but the caller may not write it →\n 404 \"Workstation not found\", the sibling verbs' exact answer. Fail\n closed and non-enumerating: a 403 would confirm the row exists, and\n the 409 would additionally lie about where it lives.", "operationId": "createWorkstation", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWorkstationRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Createworkstation", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Create a workstation", "tags": [ "workstations" ], "x-local-capability": "outbox", "x-mcp-skip": true, "x-mcp-skip-reason": "PowerSync upload surface — clients write locally and the sync batch routes here; reads are local-first." } }, "/api/v1/workstations/reorder": { "post": { "description": "Assign positions 1..N in list order. Ids that are not member-visible\nare skipped (reported in `skipped`), never silently renumbered.", "operationId": "reorderWorkstations", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReorderWorkstationsRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Reorderworkstations", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Reorder workstations", "tags": [ "workstations" ], "x-local-capability": "outbox", "x-mcp-skip": true, "x-mcp-skip-reason": "PowerSync upload surface — clients write locally and the sync batch routes here; reads are local-first." } }, "/api/v1/workstations/{workstation_id}": { "delete": { "description": "Soft delete (PowerSync tombstone contract — the sync rules filter\n`deleted_at IS NOT NULL` so every client reconciles the removal).", "operationId": "deleteWorkstation", "parameters": [ { "in": "path", "name": "workstation_id", "required": true, "schema": { "title": "Workstation Id", "type": "string" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Delete a workstation", "tags": [ "workstations" ], "x-local-capability": "outbox", "x-mcp-skip": true, "x-mcp-skip-reason": "PowerSync upload surface — clients write locally and the sync batch routes here; reads are local-first." }, "put": { "description": "Partial update. Bound to PUT and PATCH (PowerSync uploads PATCH).\n\nThe WHERE carries the canonical member-visible predicate — a member may\nedit a workstation only if it is visible to them (own or shared).", "operationId": "updateWorkstation", "parameters": [ { "in": "path", "name": "workstation_id", "required": true, "schema": { "title": "Workstation Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateWorkstationRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Updateworkstation", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Update a workstation", "tags": [ "workstations" ], "x-local-capability": "outbox", "x-mcp-skip": true, "x-mcp-skip-reason": "PowerSync upload surface — clients write locally and the sync batch routes here; reads are local-first." } }, "/api/v1/{primitive_type}/{entity_id}/demote": { "post": { "description": "Demote an entity to a lower visibility tier (non-destructive, D4).", "operationId": "demoteEntity", "parameters": [ { "in": "path", "name": "primitive_type", "required": true, "schema": { "title": "Primitive Type", "type": "string" } }, { "in": "path", "name": "entity_id", "required": true, "schema": { "title": "Entity Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DemoteRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DemoteResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Demote Entity", "tags": [ "entity-promotion", "entity-promotion" ] } }, "/api/v1/{primitive_type}/{entity_id}/insights": { "get": { "description": "Return the caller's Insight Facet overlay for one entity (capped, RLS-filtered).", "operationId": "getEntityInsightOverlay", "parameters": [ { "in": "path", "name": "primitive_type", "required": true, "schema": { "title": "Primitive Type", "type": "string" } }, { "in": "path", "name": "entity_id", "required": true, "schema": { "title": "Entity Id", "type": "string" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 40, "maximum": 40, "minimum": 1, "title": "Limit", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InsightOverlayResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Entity Insight Overlay", "tags": [ "insights", "insights" ] } }, "/api/v1/{primitive_type}/{entity_id}/promote": { "post": { "description": "Promote an entity to a higher visibility tier, merging a strong match if present.", "operationId": "promoteEntity", "parameters": [ { "in": "path", "name": "primitive_type", "required": true, "schema": { "title": "Primitive Type", "type": "string" } }, { "in": "path", "name": "entity_id", "required": true, "schema": { "title": "Entity Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api_service__models__entity_promotion__PromoteRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PromoteResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Promote Entity", "tags": [ "entity-promotion", "entity-promotion" ] } }, "/api/v1/{primitive_type}/{entity_id}/strong-match-candidates": { "get": { "description": "Preview strong-match merge candidates at the requested tier.", "operationId": "getEntityStrongMatchCandidates", "parameters": [ { "in": "path", "name": "primitive_type", "required": true, "schema": { "title": "Primitive Type", "type": "string" } }, { "in": "path", "name": "entity_id", "required": true, "schema": { "title": "Entity Id", "type": "string" } }, { "description": "Target tier to search: 'shared' or 'global'", "in": "query", "name": "at_visibility", "required": true, "schema": { "description": "Target tier to search: 'shared' or 'global'", "title": "At Visibility", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StrongMatchResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Strong Match Candidates", "tags": [ "entity-promotion", "entity-promotion" ] } }, "/api/v2/automations/activity": { "get": { "operationId": "getAutomationsActivity", "parameters": [ { "description": "Filter by workflow, subagent, or artifact; 'ephemeral' selects one-off sandbox workflow runs.", "in": "query", "name": "type", "required": false, "schema": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "description": "Filter by workflow, subagent, or artifact; 'ephemeral' selects one-off sandbox workflow runs.", "title": "Type" } }, { "description": "Filter by success, failed, partial, running, or queued.", "in": "query", "name": "status", "required": false, "schema": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "description": "Filter by success, failed, partial, running, or queued.", "title": "Status" } }, { "description": "Filter by origin surface: chat, web, sms, mcp, scheduled, manual.", "in": "query", "name": "origin", "required": false, "schema": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "description": "Filter by origin surface: chat, web, sms, mcp, scheduled, manual.", "title": "Origin" } }, { "description": "Lookback window in days. Defaults to 30; max 90.", "in": "query", "name": "window_days", "required": false, "schema": { "default": 30, "description": "Lookback window in days. Defaults to 30; max 90.", "maximum": 90, "minimum": 1, "title": "Window Days", "type": "integer" } }, { "description": "Page size. Max 100.", "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "description": "Page size. Max 100.", "maximum": 100, "minimum": 1, "title": "Limit", "type": "integer" } }, { "description": "Opaque pagination cursor.", "in": "query", "name": "cursor", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Opaque pagination cursor.", "title": "Cursor" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutomationActivityResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List Automation Activity", "tags": [ "automations" ], "x-mcp-skip": true, "x-mcp-skip-reason": "User-facing activity feed read model for web UI." } }, "/api/v2/automations/activity/subagent/{run_id}": { "get": { "operationId": "getSubagentActivityDetail", "parameters": [ { "in": "path", "name": "run_id", "required": true, "schema": { "title": "Run Id", "type": "string" } }, { "description": "Include the (compacted) full transcript. Defaults false.", "in": "query", "name": "include_transcript", "required": false, "schema": { "default": false, "description": "Include the (compacted) full transcript. Defaults false.", "title": "Include Transcript", "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubagentActivityDetail" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Subagent Activity Detail Route", "tags": [ "automations" ], "x-mcp-skip": true, "x-mcp-skip-reason": "User-facing activity drill-down read model for web UI." } }, "/api/v2/automations/audit": { "get": { "description": "Unified, keyset-paginated tenant audit timeline. Self-audits the read.", "operationId": "getTenantAudit", "parameters": [ { "in": "query", "name": "window_days", "required": false, "schema": { "default": 30, "maximum": 90, "minimum": 1, "title": "Window Days", "type": "integer" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "maximum": 100, "minimum": 1, "title": "Limit", "type": "integer" } }, { "description": "Opaque keyset cursor.", "in": "query", "name": "cursor", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Opaque keyset cursor.", "title": "Cursor" } }, { "description": "actor_account_id filter.", "in": "query", "name": "actor", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "actor_account_id filter.", "title": "Actor" } }, { "description": "Vocabulary event-type filter (unknown → 400).", "in": "query", "name": "event_type", "required": false, "schema": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "description": "Vocabulary event-type filter (unknown → 400).", "title": "Event Type" } }, { "description": "Source filter: audit | agent_run | subagent | workflow.", "in": "query", "name": "source", "required": false, "schema": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "description": "Source filter: audit | agent_run | subagent | workflow.", "title": "Source" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantAuditResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List Tenant Audit", "tags": [ "automations" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Tenant-admin governance surface for the web Audit tab." } }, "/api/v2/automations/audit/export": { "post": { "description": "Create a durable tenant-unified export job (202). Self-audits the export.", "operationId": "startTenantAuditExport", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantExportRequest" } } }, "required": true }, "responses": { "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantExportJobResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Start Tenant Export", "tags": [ "automations" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Tenant-admin governance export for the web Audit tab." } }, "/api/v2/automations/audit/export/{job_id}/download": { "get": { "operationId": "downloadTenantAuditExport", "parameters": [ { "in": "path", "name": "job_id", "required": true, "schema": { "format": "uuid", "title": "Job Id", "type": "string" } } ], "responses": { "307": { "description": "Redirect to the signed storage URL (valid 7 days)." }, "404": { "description": "Job not found." }, "409": { "description": "Job not yet complete." }, "410": { "description": "Download URL has expired." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Tenant Export Download", "tags": [ "automations" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Tenant-admin governance export for the web Audit tab." } }, "/api/v2/automations/audit/export/{job_id}/status": { "get": { "operationId": "getTenantAuditExportStatus", "parameters": [ { "in": "path", "name": "job_id", "required": true, "schema": { "format": "uuid", "title": "Job Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantExportStatusResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Tenant Export Status", "tags": [ "automations" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Tenant-admin governance export for the web Audit tab." } }, "/api/v2/automations/audit/run/{source}/{run_id}": { "get": { "description": "Drill into one run. Metadata is tenant-wide; content is member-visible\nonly (the caller must own the run), so another member's private run content\nnever leaks through the surface.", "operationId": "getTenantAuditRunDetail", "parameters": [ { "in": "path", "name": "source", "required": true, "schema": { "title": "Source", "type": "string" } }, { "in": "path", "name": "run_id", "required": true, "schema": { "title": "Run Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantAuditRunDetail" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Tenant Audit Run", "tags": [ "automations" ], "x-local-capability": "cloud", "x-mcp-skip": true, "x-mcp-skip-reason": "Tenant-admin governance surface for the web Audit tab." } }, "/api/v2/automations/credentials": { "get": { "operationId": "listAutomationCredentials", "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/AutomationCredentialResponse" }, "title": "Response Listautomationcredentials", "type": "array" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List Credentials", "tags": [ "automations" ], "x-mcp-skip": true }, "post": { "operationId": "createAutomationCredential", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutomationCredentialCreate" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutomationCredentialResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Create Credential", "tags": [ "automations" ], "x-mcp-skip": true } }, "/api/v2/automations/credentials/{credential_id}": { "delete": { "operationId": "deleteAutomationCredential", "parameters": [ { "in": "path", "name": "credential_id", "required": true, "schema": { "title": "Credential Id", "type": "string" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Delete Credential", "tags": [ "automations" ], "x-mcp-skip": true }, "get": { "operationId": "getAutomationCredential", "parameters": [ { "in": "path", "name": "credential_id", "required": true, "schema": { "title": "Credential Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutomationCredentialResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Credential", "tags": [ "automations" ], "x-mcp-skip": true }, "patch": { "operationId": "updateAutomationCredential", "parameters": [ { "in": "path", "name": "credential_id", "required": true, "schema": { "title": "Credential Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutomationCredentialUpdate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutomationCredentialResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Update Credential", "tags": [ "automations" ], "x-mcp-skip": true } }, "/api/v2/automations/mcp-servers": { "get": { "operationId": "listMcpServerConnections", "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/McpServerConnectionResponse" }, "title": "Response Listmcpserverconnections", "type": "array" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List Connections", "tags": [ "automations", "automations" ], "x-mcp-skip": true }, "post": { "operationId": "createMcpServerConnection", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpServerConnectionCreate" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpServerConnectionResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Create Connection", "tags": [ "automations", "automations" ], "x-mcp-skip": true } }, "/api/v2/automations/mcp-servers/catalog": { "get": { "description": "List the enabled curated catalog connectors, ordered for display.\n\nPlatform-global reference data (no tenant/owner columns) — a disabled row is\nnever returned; an empty catalog returns ``[]``, not an error.", "operationId": "listMcpCatalog", "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/McpCatalogConnectorResponse" }, "title": "Response Listmcpcatalog", "type": "array" } } }, "description": "Successful Response" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List Catalog", "tags": [ "automations", "automations" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v2/automations/mcp-servers/catalog/{slug}/enable": { "post": { "description": "One-toggle enable: materialize a private connection from a catalog entry.\n\nReuses the existing ``ensure_connection_for_install`` (idempotent; never\noverwrites an already-authorized connection) + ``classify_authorization``.\nNo bespoke insert, no parallel store. Token connectors link a vault\ncredential from ``secret_value``; OAuth connectors return an authorize URL.", "operationId": "enableMcpCatalogConnector", "parameters": [ { "in": "path", "name": "slug", "required": true, "schema": { "title": "Slug", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnableFromCatalogRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnableFromCatalogResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Enable Catalog Connector", "tags": [ "automations", "automations" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v2/automations/mcp-servers/ensure-for-install": { "post": { "description": "Ensure a template's named MCP servers exist for the installing user and\nreport which still need authorization.\n\nIdempotent: re-applying ensures the SAME connections (no duplicates) and\nnever overwrites an already-authorized connection. The request schema is\nsecret-free (``extra='forbid'``) so a template can never ship credentials\nthrough this path — Pydantic rejects any secret-bearing field with a 422.\nNo secret is ever created or logged here; the user authorizes their own\nconnections out-of-band (OAuth flow / credential entry).", "operationId": "ensureMcpServersForInstall", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnsureForInstallRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnsureForInstallResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Ensure For Install", "tags": [ "automations", "automations" ], "x-mcp-skip": true } }, "/api/v2/automations/mcp-servers/oauth/callback": { "post": { "operationId": "completeMcpOAuth", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpOAuthCallbackRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpServerStatusResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Oauth Callback", "tags": [ "automations", "automations" ], "x-mcp-skip": true } }, "/api/v2/automations/mcp-servers/{connection_id}": { "delete": { "operationId": "deleteMcpServerConnection", "parameters": [ { "in": "path", "name": "connection_id", "required": true, "schema": { "title": "Connection Id", "type": "string" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Delete Connection", "tags": [ "automations", "automations" ], "x-mcp-skip": true }, "get": { "operationId": "getMcpServerConnection", "parameters": [ { "in": "path", "name": "connection_id", "required": true, "schema": { "title": "Connection Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpServerConnectionResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Connection", "tags": [ "automations", "automations" ], "x-mcp-skip": true }, "patch": { "operationId": "updateMcpServerConnection", "parameters": [ { "in": "path", "name": "connection_id", "required": true, "schema": { "title": "Connection Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpServerConnectionUpdate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpServerConnectionResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Update Connection", "tags": [ "automations", "automations" ], "x-mcp-skip": true } }, "/api/v2/automations/mcp-servers/{connection_id}/assistants": { "get": { "operationId": "listMcpAssistantLinks", "parameters": [ { "in": "path", "name": "connection_id", "required": true, "schema": { "title": "Connection Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/McpAssistantLinkResponse" }, "title": "Response Listmcpassistantlinks", "type": "array" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List Assistant Links", "tags": [ "automations", "automations" ], "x-mcp-skip": true }, "post": { "description": "Link a connection to exactly one actor — an AI Assistant or a virtual\nemployee (TIDY-14147 / S5). Idempotent upsert on the matching partial-unique.", "operationId": "linkMcpServerToAssistant", "parameters": [ { "in": "path", "name": "connection_id", "required": true, "schema": { "title": "Connection Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpAssistantLinkCreate" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpAssistantLinkResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Link Assistant", "tags": [ "automations", "automations" ], "x-mcp-skip": true } }, "/api/v2/automations/mcp-servers/{connection_id}/assistants/{actor_id}": { "delete": { "description": "Unlink an actor from a connection. ``actor_id`` matches either the\nai_employee_id or the agent_member_id leg (TIDY-14147 / S5).", "operationId": "unlinkMcpServerFromAssistant", "parameters": [ { "in": "path", "name": "connection_id", "required": true, "schema": { "title": "Connection Id", "type": "string" } }, { "in": "path", "name": "actor_id", "required": true, "schema": { "title": "Actor Id", "type": "string" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Unlink Assistant", "tags": [ "automations", "automations" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v2/automations/mcp-servers/{connection_id}/check": { "post": { "description": "Actively probe the target MCP server and persist the resulting status.\n\nPerforms a real `initialize` handshake against the endpoint using the\nconnection's resolved auth (vault secret or auto-refreshed OAuth token),\nthen records working / needs_reauth + detail on the identity row. No\nfallback: connectivity or auth failures are recorded as\nstatus='needs_reauth', never hidden.", "operationId": "checkMcpServerConnection", "parameters": [ { "in": "path", "name": "connection_id", "required": true, "schema": { "title": "Connection Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpServerStatusResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Check Connection", "tags": [ "automations", "automations" ], "x-mcp-skip": true } }, "/api/v2/automations/mcp-servers/{connection_id}/oauth/authorize": { "post": { "operationId": "initiateMcpOAuth", "parameters": [ { "in": "path", "name": "connection_id", "required": true, "schema": { "title": "Connection Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpOAuthAuthorizeResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Initiate Oauth", "tags": [ "automations", "automations" ], "x-mcp-skip": true } }, "/api/v2/automations/mcp-servers/{connection_id}/status": { "get": { "operationId": "getMcpServerConnectionStatus", "parameters": [ { "in": "path", "name": "connection_id", "required": true, "schema": { "title": "Connection Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpServerStatusResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get Connection Status", "tags": [ "automations", "automations" ], "x-mcp-skip": true } }, "/api/v2/automations/mcp-servers/{connection_id}/tools": { "get": { "description": "List a connection's live tools joined with persisted policy.\n\nOwner/admin/shared may view. A ``tools/list`` failure returns\n``status='needs_reauth'`` + detail and the persisted policy rows only — never a\nfabricated tool list, never tool arguments or the auth header.", "operationId": "listMcpConnectionTools", "parameters": [ { "in": "path", "name": "connection_id", "required": true, "schema": { "title": "Connection Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpToolListResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List Connection Tools", "tags": [ "automations", "automations" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/api/v2/automations/mcp-servers/{connection_id}/tools/{tool_name}/policy": { "put": { "description": "Upsert a per-tool exposure + execution policy. Owner/admin gated.\n\n``write_capable`` is computed once at row creation (name-verb heuristic, no\nlive metadata) and preserved on update — the user's ``execution_policy`` is\nthe durable override.", "operationId": "setMcpConnectionToolPolicy", "parameters": [ { "in": "path", "name": "connection_id", "required": true, "schema": { "title": "Connection Id", "type": "string" } }, { "in": "path", "name": "tool_name", "required": true, "schema": { "title": "Tool Name", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpToolPolicyUpdate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpToolPolicyResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Set Connection Tool Policy", "tags": [ "automations", "automations" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/install-agent/setup.json": { "get": { "operationId": "getAgentRuntimeSetup", "responses": { "200": { "description": "Successful Response" } }, "summary": "Get Agent Runtime Setup", "tags": [ "agent-runtime" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/install-agent/{path}": { "get": { "operationId": "getAgentRuntimeBootstrap", "parameters": [ { "in": "path", "name": "path", "required": true, "schema": { "title": "Path", "type": "string" } }, { "in": "header", "name": "authorization", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Authorization" } }, { "in": "header", "name": "Range", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Range" } } ], "responses": { "200": { "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Get Agent Runtime Bootstrap", "tags": [ "agent-runtime" ], "x-local-capability": "cloud", "x-mcp-skip": true } }, "/internal/v1/chat/messages/{room_id}/{event_id}": { "delete": { "description": "Orchestrated retention delete for chat retention (F11).\n\nOrder: tell memory-service first (so a row stays in Postgres if MRS fails,\naudit can recover). Then delete the Postgres row only when MRS confirms.", "operationId": "internalDeleteChatMessage", "parameters": [ { "in": "path", "name": "room_id", "required": true, "schema": { "title": "Room Id", "type": "string" } }, { "in": "path", "name": "event_id", "required": true, "schema": { "title": "Event Id", "type": "string" } }, { "in": "header", "name": "X-Tenant-ID", "required": true, "schema": { "title": "X-Tenant-Id", "type": "string" } }, { "in": "header", "name": "x-internal-service", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service" } }, { "in": "header", "name": "x-internal-service-key", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service-Key" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteChatMessageResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Retention-delete a chat message from chat_message_index + MRS", "tags": [ "internal", "chat", "internal", "chat" ] } }, "/internal/v1/memory/chat-retrieve": { "post": { "description": "Raw retrieval used by F12 (chat Q&A) and F8 S6 (summarizer).\n\nHybrid: Postgres BM25 + memory-service semantic, fused via RRF. No UI\ngroupings, no `<mark>` snippets — F12 builds those.", "operationId": "internalChatRetrieve", "parameters": [ { "in": "header", "name": "x-internal-service", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service" } }, { "in": "header", "name": "x-internal-service-key", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Service-Key" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatRetrieveRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatRetrieveResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Internal retrieve over chat_message_index — for F12 Q&A flow", "tags": [ "internal", "chat", "internal", "chat" ] } }, "/metrics": { "get": { "description": "Endpoint that serves Prometheus metrics.", "operationId": "metrics_metrics_get", "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response" } }, "summary": "Metrics" } }, "/oauth/callback/{provider}": { "get": { "description": "RFC 9700 exact-match redirect URI for every OAuth provider.\n\nDispatches to the per-provider handler. Unknown provider returns a\n404 problem+json envelope (F0 / TIDY-7134).", "operationId": "oauth_callback", "parameters": [ { "in": "path", "name": "provider", "required": true, "schema": { "title": "Provider", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Oauth Callback", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Oauth Callback", "tags": [ "oauth", "oauth" ] } }, "/oauth/device_authorization": { "post": { "description": "RFC 8628 §3.1 device authorization request.\n\nForm-encoded body matches the spec. `resource` is mandatory (D15).\n`code_challenge`/`code_challenge_method=S256` are optional but if\nsupplied, the corresponding verifier becomes mandatory at /token.", "operationId": "deviceAuthorization", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeviceAuthorizationResponse" } } }, "description": "Successful Response" } }, "summary": "Device Authorization", "tags": [ "oauth" ] } }, "/oauth/register": { "post": { "description": "RFC 7591 Dynamic Client Registration endpoint.\n\nPublic endpoint — no Authorization header required. See module docstring\n+ TIDY-7542 for safety model (scope limit + rate limit + consent gate).", "operationId": "dynamicClientRegistration", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DCRRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DCRResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Dynamic Client Registration", "tags": [ "oauth" ] } }, "/oauth/token": { "post": { "description": "RFC 6749 / OAuth 2.1 token endpoint.\n\nSupports grant types: authorization_code, refresh_token,\nclient_credentials, and (F9) urn:ietf:params:oauth:grant-type:device_code.", "operationId": "oauthToken", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenResponse" } } }, "description": "Successful Response" } }, "summary": "Token Endpoint", "tags": [ "oauth" ] } }, "/subscriptions/{username}/{device_id}.txt": { "get": { "operationId": "getGpodderSubscriptionsText", "parameters": [ { "in": "path", "name": "username", "required": true, "schema": { "title": "Username", "type": "string" } }, { "in": "path", "name": "device_id", "required": true, "schema": { "title": "Device Id", "type": "string" } } ], "responses": { "200": { "content": { "text/plain": { "schema": { "type": "string" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] }, { "HTTPBasic": [] } ], "summary": "Get Gpodder Subscriptions Text", "tags": [ "gpodder" ] }, "post": { "operationId": "postGpodderSubscriptionsText", "parameters": [ { "in": "path", "name": "username", "required": true, "schema": { "title": "Username", "type": "string" } }, { "in": "path", "name": "device_id", "required": true, "schema": { "title": "Device Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GpodderSubscriptionChangesRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GpodderUpdatedUrlsResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] }, { "HTTPBasic": [] } ], "summary": "Post Gpodder Subscriptions Text", "tags": [ "gpodder" ] }, "put": { "operationId": "putGpodderSubscriptionsText", "parameters": [ { "in": "path", "name": "username", "required": true, "schema": { "title": "Username", "type": "string" } }, { "in": "path", "name": "device_id", "required": true, "schema": { "title": "Device Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Putgpoddersubscriptionstext", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] }, { "HTTPBasic": [] } ], "summary": "Put Gpodder Subscriptions Text", "tags": [ "gpodder" ] } } }, "servers": [ { "url": "https://tidy.engineering" } ], "x-tidy-scope-bundles": { "admin_agent": [ "email:read", "calendar:read", "contacts:read", "notes:read", "tasks:read", "projects:read", "files:read", "facets:read", "tags:read", "search:read", "primitives:read", "audit:read", "openapi:read", "podcast:read", "comments:read", "evidence:read", "agent_sessions:read", "agent_ledger:read", "email:send", "email:patch", "notes:write", "notes:patch", "calendar:write", "tasks:write", "contacts:write", "chat:send", "assistant:invoke", "memory:search", "memory:recall", "memory:observe", "memory:enrich", "primitives:write", "projects:write", "tokens:manage", "comments:write", "links:write", "mobile_devices:write", "podcast:write", "podcast:generate", "workflow:execute", "email:triage", "files:write", "facets:extract", "sms:send", "facets:manage", "templates:manage", "views:manage", "activities:archive", "evidence:write", "agent_sessions:write", "agent_ledger:write", "admin:members", "admin:workspace", "webhooks:manage", "agent_control:write", "data:export", "data:import" ], "basic_access": [ "email:read", "calendar:read", "contacts:read", "notes:read", "tasks:read", "projects:read", "files:read", "facets:read", "tags:read", "search:read", "primitives:read", "audit:read", "openapi:read", "podcast:read", "comments:read", "evidence:read", "agent_sessions:read", "agent_ledger:read" ], "full_agent": [ "email:read", "calendar:read", "contacts:read", "notes:read", "tasks:read", "projects:read", "files:read", "facets:read", "tags:read", "search:read", "primitives:read", "audit:read", "openapi:read", "podcast:read", "comments:read", "evidence:read", "agent_sessions:read", "agent_ledger:read", "email:send", "email:patch", "notes:write", "notes:patch", "calendar:write", "tasks:write", "contacts:write", "chat:send", "assistant:invoke", "memory:search", "memory:recall", "memory:observe", "memory:enrich", "primitives:write", "projects:write", "tokens:manage", "comments:write", "links:write", "mobile_devices:write", "podcast:write", "podcast:generate", "workflow:execute", "email:triage", "files:write", "facets:extract", "sms:send", "facets:manage", "templates:manage", "views:manage", "activities:archive", "evidence:write", "agent_sessions:write", "agent_ledger:write" ], "standard_agent": [ "email:read", "calendar:read", "contacts:read", "notes:read", "tasks:read", "projects:read", "files:read", "facets:read", "tags:read", "search:read", "primitives:read", "audit:read", "openapi:read", "podcast:read", "comments:read", "evidence:read", "agent_sessions:read", "agent_ledger:read", "email:send", "email:patch", "notes:write", "notes:patch", "calendar:write", "tasks:write", "contacts:write", "chat:send", "assistant:invoke", "memory:search", "memory:recall", "memory:observe", "memory:enrich", "primitives:write", "projects:write", "tokens:manage", "comments:write", "links:write", "mobile_devices:write", "podcast:write", "podcast:generate" ] } }