{"openapi":"3.0.0","info":{"version":"1.0.0","title":"EffectiveAI Public API","description":"Public API reference for the EffectiveAI platform. Authenticate with Bearer token: Authorization: Bearer sk-eai-...","contact":{"name":"EffectiveAI Team","email":"arijit@effectiveailabs.com"}},"servers":[{"url":"https://effectiveai.app","description":"Production server"}],"security":[{"bearerAuth":[]}],"paths":{"/api/v1/admin/oidc/.well-known/openid-configuration":{"get":{"tags":["OAuth"],"summary":"OIDC discovery document for dev sandbox WIF","description":"Public OIDC discovery document used by Google STS to validate subject tokens.","responses":{"200":{"description":"OIDC discovery document","content":{"application/json":{"schema":{"type":"object","properties":{"issuer":{"type":"string"},"jwks_uri":{"type":"string"},"response_types_supported":{"type":"array","items":{"type":"string"}},"subject_types_supported":{"type":"array","items":{"type":"string"}},"id_token_signing_alg_values_supported":{"type":"array","items":{"type":"string"}}},"required":["issuer","jwks_uri","response_types_supported","subject_types_supported","id_token_signing_alg_values_supported"]}}}}}}},"/api/v1/admin/oidc/jwks.json":{"get":{"tags":["OAuth"],"summary":"JWKS for dev sandbox WIF","description":"Public signing keys used by Google STS to validate subject tokens.","responses":{"200":{"description":"JWKS document","content":{"application/json":{"schema":{"type":"object","properties":{"keys":{"type":"array","items":{"type":"object","additionalProperties":{"nullable":true}}}},"required":["keys"]}}}}}}},"/api/v1/tenants/{name}":{"get":{"summary":"Get tenant by name","description":"Lookup Descope tenant by tenant name (unauthenticated)","tags":["Tenants"],"parameters":[{"schema":{"type":"string","description":"The tenant name to lookup"},"required":true,"description":"The tenant name to lookup","name":"name","in":"path"}],"responses":{"200":{"description":"Tenant info","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TenantResponse"}}}},"404":{"description":"Tenant not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/share/{slug}":{"get":{"summary":"Get public share HTML by slug","description":"Returns stored static HTML for a share slug","tags":["Shares"],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"slug","in":"path"}],"responses":{"200":{"description":"HTML content","content":{"text/html; charset=utf-8":{"schema":{"type":"string"}}}},"404":{"description":"Share not found"},"500":{"description":"Server error"}}}},"/api/v1/share/artifacts/{id}":{"get":{"summary":"Get a publicly shared artifact","description":"Returns artifact metadata and a signed download URL for a publicly shared artifact. No authentication required.","tags":["Shares"],"parameters":[{"schema":{"type":"string","format":"uuid","description":"Artifact ID"},"required":true,"description":"Artifact ID","name":"id","in":"path"}],"responses":{"200":{"description":"Artifact metadata and download URL","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicArtifactResponse"}}}},"404":{"description":"Artifact not found or not public"},"500":{"description":"Server error"}}}},"/api/v1/demo-booking":{"post":{"summary":"Book a demo meeting","description":"Submit a request to book a demo meeting with the sales team","tags":["Demo Booking"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DemoBookingRequest"}}}},"responses":{"200":{"description":"Demo booking request submitted successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DemoBookingResponse"}}}},"400":{"description":"Bad request - invalid input data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/oauth/{provider}/connect":{"post":{"tags":["OAuth"],"summary":"Initiate OAuth connection","description":"Returns the authorization URL to redirect the user to. Sets state + PKCE cookies as a side effect.","parameters":[{"schema":{"type":"string","minLength":1,"maxLength":100},"required":true,"name":"provider","in":"path"}],"responses":{"200":{"description":"Connect URL generated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuthConnectResponse"}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown provider","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Provider not configured for this org","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/oauth/{provider}/status":{"get":{"tags":["OAuth"],"summary":"Get OAuth integration status","description":"Reports whether the current user is connected to the provider, whether the provider is configured at the org level, and whether reconnection is required (e.g. after admin scope changes).","parameters":[{"schema":{"type":"string","minLength":1,"maxLength":100},"required":true,"name":"provider","in":"path"}],"responses":{"200":{"description":"Integration status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuthStatusResponse"}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown provider","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/oauth/{provider}/disconnect":{"delete":{"tags":["OAuth"],"summary":"Disconnect OAuth integration","description":"Deactivate the current user's active integration for the provider.","parameters":[{"schema":{"type":"string","minLength":1,"maxLength":100},"required":true,"name":"provider","in":"path"}],"responses":{"200":{"description":"Integration disconnected","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuthDisconnectResponse"}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown provider or no active integration","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/webhooks/gmail-pubsub":{"post":{"summary":"Consume a Gmail Pub/Sub push notification","description":"Receives a Google Pub/Sub push envelope for Gmail watch notifications, decodes the base64 payload, and signals the singleton Gmail monitor workflow.","tags":["Webhooks"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GmailPubSubPushEnvelope"}}}},"responses":{"200":{"description":"Notification accepted, rejected as malformed, or skipped while disabled"},"401":{"description":"Missing or invalid OIDC token"},"403":{"description":"Unauthorized service account"},"500":{"description":"Failed to signal the Gmail monitor workflow"}}}},"/api/v1/admin/oidc/subject-token":{"get":{"tags":["Admin/OIDC"],"summary":"Mint an OIDC subject token for dev sandbox WIF","description":"Authenticated endpoint used by dev-mode sandboxes to obtain a short-lived JWT for Google STS.","parameters":[{"schema":{"type":"string","minLength":1},"required":false,"name":"session_id","in":"query"}],"responses":{"200":{"description":"Subject token response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MintSubjectTokenResponse"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/api/v1/users":{"post":{"summary":"Create a new user","description":"Create a new user in Descope and database (Tenant Admin or Super Admin only)","tags":["Users"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserCreate"}}}},"responses":{"200":{"description":"Existing user added to current tenant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/User"}}}},"201":{"description":"User created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/User"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden - requires Tenant Admin or Super Admin role","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict - user already exists in this tenant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/users/me":{"get":{"summary":"Get current user","description":"Retrieve the profile of the authenticated user","tags":["Users"],"responses":{"200":{"description":"Current user profile","content":{"application/json":{"schema":{"$ref":"#/components/schemas/User"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"summary":"Update current user","description":"Update name or metadata for the authenticated user","tags":["Users"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserUpdate"}}}},"responses":{"200":{"description":"Updated user profile","content":{"application/json":{"schema":{"$ref":"#/components/schemas/User"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/users/me/profile":{"get":{"summary":"Get current user profile","description":"Retrieve the authenticated user identity and agent-facing profile fields.","tags":["Users"],"responses":{"200":{"description":"Current user identity and profile","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserProfileResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"summary":"Update current user profile","description":"Update agent-facing profile fields for the authenticated user. Pass null to clear a field.","tags":["Users"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserProfilePatch"}}}},"responses":{"200":{"description":"Updated user identity and profile","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserProfileResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/users/me/preferences":{"get":{"summary":"Get current user preferences","description":"Retrieve the authenticated user’s notification (and other) preferences. Missing keys are filled with the Zod hardcoded defaults defined in @effectiveai/shared-types.","tags":["Users"],"responses":{"200":{"description":"Resolved user preferences (defaults filled in)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserPreferences"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"summary":"Update current user preferences","description":"Update notification (or other) preferences for the authenticated user. The body is a partial document; provided keys are deep-merged into the user’s existing preferences and the merged result is validated against the full schema.","tags":["Users"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserPreferencesPatch"}}}},"responses":{"200":{"description":"Updated user preferences (resolved)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserPreferences"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/users/stats":{"get":{"summary":"Get user statistics","description":"Retrieve aggregate statistics about users","tags":["Users"],"responses":{"200":{"description":"User statistics","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserStats"}}}}}}},"/api/v1/users/org-members":{"get":{"summary":"List org members","description":"List users within the authenticated user's org. Available to all authenticated users (not just admins). Returns minimal user info for sharing/collaboration features.","tags":["Users"],"parameters":[{"schema":{"type":"string","description":"Search text to filter members by name or email"},"required":false,"description":"Search text to filter members by name or email","name":"query","in":"query"},{"schema":{"type":"string","description":"Max results to return (default 50, max 1000)"},"required":false,"description":"Max results to return (default 50, max 1000)","name":"limit","in":"query"}],"responses":{"200":{"description":"List of org members","content":{"application/json":{"schema":{"type":"object","properties":{"users":{"type":"array","items":{"type":"object","properties":{"id":{"type":"number","description":"User ID (used for sharing)"},"name":{"type":"string","nullable":true,"description":"Display name"},"email":{"type":"string","description":"Email address"}},"required":["id","name","email"]}}},"required":["users"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/api/v1/users/{id}":{"get":{"summary":"Get user by ID","description":"Retrieve a user by their ID","tags":["Users"],"parameters":[{"schema":{"type":"integer","minimum":0,"exclusiveMinimum":true,"description":"User ID"},"required":true,"description":"User ID","name":"id","in":"path"}],"responses":{"200":{"description":"User profile","content":{"application/json":{"schema":{"$ref":"#/components/schemas/User"}}}},"404":{"description":"User not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/emails/send":{"post":{"summary":"Send an email","description":"Send a transactional email using a predefined template. When `to` is omitted it defaults to the authenticated caller's email. Non-admin users may only send to themselves.","tags":["Emails"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"template":{"type":"string","enum":["user-invitation","user-invitation-simple","custom","subscription-notification"]},"to":{"anyOf":[{"type":"string","format":"email"},{"type":"array","items":{"type":"string","format":"email"},"minItems":1}],"description":"Recipient email address(es). When omitted, defaults to the authenticated caller's email."},"subject":{"type":"string"},"data":{"anyOf":[{"type":"object","properties":{"summaryLine":{"type":"string","description":"One-line summary shown at the top of the email"},"scheduleType":{"type":"string","description":"e.g. \"Daily\", \"Weekly\", \"Hourly\""},"timezone":{"type":"string","description":"e.g. \"America/New_York\""},"sessionUrl":{"type":"string","format":"uri","description":"CTA button URL linking to the agent session"},"previewText":{"type":"string","description":"Preview text shown in email clients"},"windowStart":{"type":"string","description":"Scan window start, human-readable"},"windowEnd":{"type":"string","description":"Scan window end, human-readable"},"filterSummary":{"type":"string","description":"Human-readable filter summary"},"filings":{"type":"array","items":{"type":"object","properties":{"trackingNumber":{"type":"string"},"state":{"type":"string"},"toiCode":{"type":"string"}},"required":["trackingNumber"]},"description":"Matched filings"},"matchCount":{"type":"number","description":"Total match count"},"runTime":{"type":"string","description":"Run time for scheduled triggers"},"instruction":{"type":"string","description":"Subscription instruction/prompt"}},"required":["summaryLine","scheduleType","sessionUrl"]},{"type":"object","properties":{"body":{"type":"string","description":"Email body in markdown format"},"heading":{"type":"string","description":"Heading displayed above the body"},"previewText":{"type":"string","description":"Preview text shown in email clients"},"ctaLabel":{"type":"string","description":"Call-to-action button label"},"ctaUrl":{"type":"string","format":"uri","description":"Call-to-action button URL"}},"required":["body"]},{"type":"object","properties":{"userName":{"type":"string"},"customMessage":{"type":"string","description":"Optional markdown content rendered between login steps and the CTA"}}}]},"orgId":{"type":"string","minLength":1,"description":"Target tenant for user-invitation emails. When provided, validates the recipient belongs to this tenant. When omitted, auto-resolves from recipient tenant membership."},"cc":{"anyOf":[{"type":"string","format":"email"},{"type":"array","items":{"type":"string","format":"email"}}]},"bcc":{"anyOf":[{"type":"string","format":"email"},{"type":"array","items":{"type":"string","format":"email"}}]},"scheduledAt":{"type":"string","format":"date-time"},"attachments":{"type":"array","items":{"type":"object","properties":{"filename":{"type":"string","description":"Attachment filename"},"content":{"type":"string","description":"Base64-encoded attachment content. Single-send only. Resend limits attachment payloads to 40 MiB per email after base64 encoding."},"path":{"type":"string","format":"uri","description":"Hosted file URL. Single-send only."},"contentType":{"type":"string","description":"MIME content type"},"contentId":{"type":"string","description":"Inline content ID for cid: references"}},"description":"Resend attachment. Attachments are supported for /send and /preview metadata only; /batch does not support attachments. Resend limits attachment payloads to 40 MiB per email after base64 encoding."},"description":"Attachments for a single email send. Not supported by the batch endpoint. Resend limits attachment payloads to 40 MiB per email after base64 encoding."}},"required":["template"]}}}},"responses":{"200":{"description":"Email sent successfully","content":{"application/json":{"schema":{"type":"object","properties":{"messageId":{"type":"string"}},"required":["messageId"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — not authorized to send to the specified recipients","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too Many Requests — email quota exceeded for recipient","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/emails/preview":{"post":{"summary":"Preview an email","description":"Render an email to HTML/text without sending. Uses the same render pipeline for pixel-perfect preview. When `to` is omitted it defaults to the authenticated caller's email.","tags":["Emails"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"template":{"type":"string","enum":["user-invitation","user-invitation-simple","custom","subscription-notification"]},"to":{"anyOf":[{"type":"string","format":"email"},{"type":"array","items":{"type":"string","format":"email"},"minItems":1}],"description":"Recipient email address(es) for the preview. When omitted, defaults to the authenticated caller's email."},"subject":{"type":"string"},"data":{"anyOf":[{"type":"object","properties":{"summaryLine":{"type":"string","description":"One-line summary shown at the top of the email"},"scheduleType":{"type":"string","description":"e.g. \"Daily\", \"Weekly\", \"Hourly\""},"timezone":{"type":"string","description":"e.g. \"America/New_York\""},"sessionUrl":{"type":"string","format":"uri","description":"CTA button URL linking to the agent session"},"previewText":{"type":"string","description":"Preview text shown in email clients"},"windowStart":{"type":"string","description":"Scan window start, human-readable"},"windowEnd":{"type":"string","description":"Scan window end, human-readable"},"filterSummary":{"type":"string","description":"Human-readable filter summary"},"filings":{"type":"array","items":{"type":"object","properties":{"trackingNumber":{"type":"string"},"state":{"type":"string"},"toiCode":{"type":"string"}},"required":["trackingNumber"]},"description":"Matched filings"},"matchCount":{"type":"number","description":"Total match count"},"runTime":{"type":"string","description":"Run time for scheduled triggers"},"instruction":{"type":"string","description":"Subscription instruction/prompt"}},"required":["summaryLine","scheduleType","sessionUrl"]},{"type":"object","properties":{"body":{"type":"string","description":"Email body in markdown format"},"heading":{"type":"string","description":"Heading displayed above the body"},"previewText":{"type":"string","description":"Preview text shown in email clients"},"ctaLabel":{"type":"string","description":"Call-to-action button label"},"ctaUrl":{"type":"string","format":"uri","description":"Call-to-action button URL"}},"required":["body"]},{"type":"object","properties":{"userName":{"type":"string"},"customMessage":{"type":"string","description":"Optional markdown content rendered between login steps and the CTA"}}}]},"orgId":{"type":"string","minLength":1,"description":"Target tenant for user-invitation previews. When provided, validates the recipient belongs to this tenant."},"attachments":{"type":"array","items":{"type":"object","properties":{"filename":{"type":"string","description":"Attachment filename"},"contentType":{"type":"string","description":"MIME content type"},"contentId":{"type":"string","description":"Inline content ID for cid: references"}}},"description":"Attachment metadata for preview display only. Preview does not send or store attachment bytes."}},"required":["template"]}}}},"responses":{"200":{"description":"Rendered email preview","content":{"application/json":{"schema":{"type":"object","properties":{"to":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]},"from":{"type":"string"},"subject":{"type":"string"},"html":{"type":"string"},"text":{"type":"string"},"attachments":{"type":"array","items":{"type":"object","properties":{"filename":{"type":"string","description":"Attachment filename"},"contentType":{"type":"string","description":"MIME content type"},"contentId":{"type":"string","description":"Inline content ID for cid: references"}}}}},"required":["to","from","subject","html","text"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — not authorized to preview for the specified recipients","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/emails/batch":{"post":{"summary":"Send batch emails","description":"Send up to 100 templated emails in a single API call. Each email specifies a template and recipient data. When `to` is omitted on an item it defaults to the authenticated caller's email. Non-admin users may only send to themselves. Resend batch sending does not support attachments or scheduledAt; use /send for attached or scheduled emails.","tags":["Emails"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"emails":{"type":"array","items":{"type":"object","properties":{"template":{"type":"string","enum":["user-invitation","user-invitation-simple","custom","subscription-notification"]},"to":{"anyOf":[{"type":"string","format":"email"},{"type":"array","items":{"type":"string","format":"email"},"minItems":1}],"description":"Recipient email address(es). When omitted, defaults to the authenticated caller's email."},"subject":{"type":"string"},"data":{"anyOf":[{"type":"object","properties":{"summaryLine":{"type":"string","description":"One-line summary shown at the top of the email"},"scheduleType":{"type":"string","description":"e.g. \"Daily\", \"Weekly\", \"Hourly\""},"timezone":{"type":"string","description":"e.g. \"America/New_York\""},"sessionUrl":{"type":"string","format":"uri","description":"CTA button URL linking to the agent session"},"previewText":{"type":"string","description":"Preview text shown in email clients"},"windowStart":{"type":"string","description":"Scan window start, human-readable"},"windowEnd":{"type":"string","description":"Scan window end, human-readable"},"filterSummary":{"type":"string","description":"Human-readable filter summary"},"filings":{"type":"array","items":{"type":"object","properties":{"trackingNumber":{"type":"string"},"state":{"type":"string"},"toiCode":{"type":"string"}},"required":["trackingNumber"]},"description":"Matched filings"},"matchCount":{"type":"number","description":"Total match count"},"runTime":{"type":"string","description":"Run time for scheduled triggers"},"instruction":{"type":"string","description":"Subscription instruction/prompt"}},"required":["summaryLine","scheduleType","sessionUrl"]},{"type":"object","properties":{"body":{"type":"string","description":"Email body in markdown format"},"heading":{"type":"string","description":"Heading displayed above the body"},"previewText":{"type":"string","description":"Preview text shown in email clients"},"ctaLabel":{"type":"string","description":"Call-to-action button label"},"ctaUrl":{"type":"string","format":"uri","description":"Call-to-action button URL"}},"required":["body"]},{"type":"object","properties":{"userName":{"type":"string"},"customMessage":{"type":"string","description":"Optional markdown content rendered between login steps and the CTA"}}}]},"orgId":{"type":"string","minLength":1,"description":"Target tenant for this invitation email"},"scheduledAt":{"type":"string","format":"date-time","description":"Unsupported for batch sending. Use /send for scheduled emails."},"attachments":{"type":"array","items":{"type":"object","properties":{"filename":{"type":"string","description":"Attachment filename"},"content":{"type":"string","description":"Base64-encoded attachment content. Single-send only. Resend limits attachment payloads to 40 MiB per email after base64 encoding."},"path":{"type":"string","format":"uri","description":"Hosted file URL. Single-send only."},"contentType":{"type":"string","description":"MIME content type"},"contentId":{"type":"string","description":"Inline content ID for cid: references"}},"description":"Resend attachment. Attachments are supported for /send and /preview metadata only; /batch does not support attachments. Resend limits attachment payloads to 40 MiB per email after base64 encoding."},"description":"Unsupported for batch sending. Use /send for attached emails."},"cc":{"anyOf":[{"type":"string","format":"email"},{"type":"array","items":{"type":"string","format":"email"}}]},"bcc":{"anyOf":[{"type":"string","format":"email"},{"type":"array","items":{"type":"string","format":"email"}}]}},"required":["template"]},"minItems":1,"maxItems":100}},"required":["emails"]}}}},"responses":{"200":{"description":"Batch sent","content":{"application/json":{"schema":{"type":"object","properties":{"ids":{"type":"array","items":{"type":"string"}},"blocked":{"type":"array","items":{"type":"object","properties":{"email":{"type":"string"},"reason":{"type":"string"}},"required":["email","reason"]}}},"required":["ids"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — not authorized to send to the specified recipients","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded — 24-hour email quota reached for one or more recipients","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/extractions":{"post":{"summary":"Create a new extraction","description":"Creates a new extraction in queued status for the given source document.","tags":["Extractions"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"sourceDocumentId":{"type":"string","format":"uuid"},"type":{"type":"string"},"config":{"type":"object","additionalProperties":{"nullable":true}}},"required":["sourceDocumentId","type"]}}}},"responses":{"201":{"description":"Extraction created","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"sourceDocumentId":{"type":"string","format":"uuid"},"type":{"type":"string"},"status":{"type":"string","enum":["queued","running","done","published","error","rejected","cancelled"]},"sessionId":{"type":"string","nullable":true},"outputArtifactId":{"type":"string","nullable":true,"format":"uuid"},"errorDetail":{"type":"string","nullable":true},"config":{"type":"object","additionalProperties":{"nullable":true}},"progress":{"type":"object","additionalProperties":{"nullable":true}},"originatingOrgId":{"type":"string","nullable":true},"createdBy":{"type":"string"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","sourceDocumentId","type","status","sessionId","outputArtifactId","errorDetail","config","progress","originatingOrgId","createdBy","createdAt","updatedAt"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"summary":"List extractions with filters","description":"Lists extractions with optional filters. Status accepts comma-separated values for OR filtering.","tags":["Extractions"],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":false,"name":"sourceDocumentId","in":"query"},{"schema":{"type":"string","description":"Filter by agent session ID"},"required":false,"description":"Filter by agent session ID","name":"sessionId","in":"query"},{"schema":{"type":"string"},"required":false,"name":"type","in":"query"},{"schema":{"type":"string","description":"Comma-separated status values for OR filtering"},"required":false,"description":"Comma-separated status values for OR filtering","name":"status","in":"query"},{"schema":{"type":"string","enum":["createdAt","updatedAt"],"description":"Field to sort by (default: createdAt)"},"required":false,"description":"Field to sort by (default: createdAt)","name":"orderBy","in":"query"},{"schema":{"type":"string","enum":["asc","desc"],"description":"Sort direction (default: desc)"},"required":false,"description":"Sort direction (default: desc)","name":"orderDirection","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100},"required":false,"name":"limit","in":"query"},{"schema":{"type":"integer","nullable":true,"minimum":0},"required":false,"name":"offset","in":"query"}],"responses":{"200":{"description":"Paginated list of extractions","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"sourceDocumentId":{"type":"string","format":"uuid"},"type":{"type":"string"},"status":{"type":"string","enum":["queued","running","done","published","error","rejected","cancelled"]},"sessionId":{"type":"string","nullable":true},"outputArtifactId":{"type":"string","nullable":true,"format":"uuid"},"errorDetail":{"type":"string","nullable":true},"config":{"type":"object","additionalProperties":{"nullable":true}},"progress":{"type":"object","additionalProperties":{"nullable":true}},"originatingOrgId":{"type":"string","nullable":true},"createdBy":{"type":"string"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","sourceDocumentId","type","status","sessionId","outputArtifactId","errorDetail","config","progress","originatingOrgId","createdBy","createdAt","updatedAt"]}},"total":{"type":"integer"}},"required":["items","total"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/extractions/library":{"get":{"summary":"List active extraction library entries","description":"Returns active entries from the shared extraction library. These are curated extractions available to all tenants. Supports filtering by source_document_id, serff_tracking_number, and type.","tags":["Extractions"],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":false,"name":"source_document_id","in":"query"},{"schema":{"type":"string"},"required":false,"name":"serff_tracking_number","in":"query"},{"schema":{"type":"string"},"required":false,"name":"type","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100},"required":false,"name":"limit","in":"query"},{"schema":{"type":"integer","nullable":true,"minimum":0},"required":false,"name":"offset","in":"query"}],"responses":{"200":{"description":"Paginated list of active library entries","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"sourceDocumentId":{"type":"string","format":"uuid"},"extractionId":{"type":"string","format":"uuid"},"artifactId":{"type":"string","format":"uuid"},"type":{"type":"string"},"scope":{"type":"string"},"suspended":{"type":"boolean"},"status":{"type":"string","enum":["pending","active","superseded","rejected"]},"serffTrackingNumber":{"type":"string"},"docName":{"type":"string","nullable":true},"reviewedBy":{"type":"string","nullable":true},"reviewedAt":{"type":"string","nullable":true},"createdAt":{"type":"string"}},"required":["id","sourceDocumentId","extractionId","artifactId","type","scope","suspended","status","serffTrackingNumber","docName","reviewedBy","reviewedAt","createdAt"]}},"total":{"type":"integer"}},"required":["items","total"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/extractions/library/resolve":{"get":{"summary":"Resolve a single extraction library entry","description":"Returns the active, non-suspended extraction library entry for a source document and type.","tags":["Extractions"],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"source_document_id","in":"query"},{"schema":{"type":"string"},"required":true,"name":"type","in":"query"}],"responses":{"200":{"description":"Resolved extraction library entry","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"sourceDocumentId":{"type":"string","format":"uuid"},"extractionId":{"type":"string","format":"uuid"},"artifactId":{"type":"string","format":"uuid"},"type":{"type":"string"},"scope":{"type":"string"},"suspended":{"type":"boolean"},"status":{"type":"string","enum":["pending","active","superseded","rejected"]},"serffTrackingNumber":{"type":"string"},"docName":{"type":"string","nullable":true},"reviewedBy":{"type":"string","nullable":true},"reviewedAt":{"type":"string","nullable":true},"createdAt":{"type":"string"}},"required":["id","sourceDocumentId","extractionId","artifactId","type","scope","suspended","status","serffTrackingNumber","docName","reviewedBy","reviewedAt","createdAt"]}}}},"404":{"description":"Library entry not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/extractions/{id}":{"get":{"summary":"Get extraction by ID","description":"Returns a single extraction.","tags":["Extractions"],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Extraction","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"sourceDocumentId":{"type":"string","format":"uuid"},"type":{"type":"string"},"status":{"type":"string","enum":["queued","running","done","published","error","rejected","cancelled"]},"sessionId":{"type":"string","nullable":true},"outputArtifactId":{"type":"string","nullable":true,"format":"uuid"},"errorDetail":{"type":"string","nullable":true},"config":{"type":"object","additionalProperties":{"nullable":true}},"progress":{"type":"object","additionalProperties":{"nullable":true}},"originatingOrgId":{"type":"string","nullable":true},"createdBy":{"type":"string"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","sourceDocumentId","type","status","sessionId","outputArtifactId","errorDetail","config","progress","originatingOrgId","createdBy","createdAt","updatedAt"]}}}},"404":{"description":"Extraction not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"summary":"Update extraction fields","description":"Updates specified fields on an extraction. Status changes are validated against the transition table.","tags":["Extractions"],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["queued","running","done","published","error","rejected","cancelled"]},"sessionId":{"type":"string"},"outputArtifactId":{"type":"string","format":"uuid"},"errorDetail":{"type":"string"},"progress":{"type":"object","additionalProperties":{"nullable":true}}}}}}},"responses":{"200":{"description":"Updated extraction","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"sourceDocumentId":{"type":"string","format":"uuid"},"type":{"type":"string"},"status":{"type":"string","enum":["queued","running","done","published","error","rejected","cancelled"]},"sessionId":{"type":"string","nullable":true},"outputArtifactId":{"type":"string","nullable":true,"format":"uuid"},"errorDetail":{"type":"string","nullable":true},"config":{"type":"object","additionalProperties":{"nullable":true}},"progress":{"type":"object","additionalProperties":{"nullable":true}},"originatingOrgId":{"type":"string","nullable":true},"createdBy":{"type":"string"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","sourceDocumentId","type","status","sessionId","outputArtifactId","errorDetail","config","progress","originatingOrgId","createdBy","createdAt","updatedAt"]}}}},"400":{"description":"Invalid status transition","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Extraction not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/extractions/source-documents":{"post":{"summary":"Upsert a source document","description":"Creates or updates a source document record. Deduped by artifact_id within the org.","tags":["Extractions"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"artifactId":{"type":"string","format":"uuid"},"serffTrackingNumber":{"type":"string"},"name":{"type":"string"},"totalPages":{"type":"integer"}},"required":["artifactId","serffTrackingNumber","name"]}}}},"responses":{"200":{"description":"Source document (existing or newly created)","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"artifactId":{"type":"string","format":"uuid"},"serffTrackingNumber":{"type":"string"},"name":{"type":"string"},"totalPages":{"type":"integer","nullable":true},"createdBy":{"type":"string"},"createdAt":{"type":"string"}},"required":["id","artifactId","serffTrackingNumber","name","totalPages","createdBy","createdAt"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/cosmos/sql":{"post":{"summary":"Execute Cosmos SQL query","description":"Execute a PostgreSQL query against tenant-authorized Cosmos reporting schemas such as insurance, NAIC, and regulatory.","tags":["Cosmos"],"requestBody":{"description":"Cosmos SQL query request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CosmosSqlQueryRequest"}}}},"responses":{"200":{"description":"Cosmos SQL query results","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CosmosSqlQueryResponse"}}}},"400":{"description":"Bad request - invalid SQL query request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden - SQL query is not permitted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"408":{"description":"Request timeout - SQL query exceeded the execution limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Payload too large - SQL query returned too many rows","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/cosmos/insurance-space-dsn":{"post":{"summary":"Resolve tenant insurance_space DSN","description":"Returns the bundle-scoped Postgres DSN for the authenticated tenant. Resolution is lazy — sandbox boot no longer injects this as an env var. The toolkit calls this route on first insurance access; the response is served from the in-process TTL cache after the first miss. Empty DSN (\"\") is a degraded but valid response matching the existing MissingDSNError contract; callers raise only on actual access. No request body — tenant context and dataset entitlements are resolved server-side from the authenticated request. The generated Python SDK posts with Content-Type: application/json and Content-Length: 0 (empty body); declaring no request body in the OpenAPI spec keeps the zod-openapi JSON validator out of the path so the empty body is accepted instead of rejected as malformed JSON.","tags":["Cosmos"],"responses":{"200":{"description":"Tenant insurance_space DSN (empty string when degraded).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CosmosInsuranceSpaceDsnResponse"}}}},"500":{"description":"Server error — non-transient mint failure (missing dataset role, GRANT, etc.).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/api-keys":{"get":{"summary":"List API keys","description":"List all API keys for the authenticated user","tags":["API Keys"],"responses":{"200":{"description":"List of API keys","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKeyList"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"summary":"Create API key","description":"Create a new API key for the authenticated user","tags":["API Keys"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateApiKey"}}}},"responses":{"201":{"description":"API key created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateApiKeyResponse"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/api-keys/{id}":{"get":{"summary":"Get API key","description":"Get an API key by ID","tags":["API Keys"],"parameters":[{"schema":{"type":"string","format":"uuid","description":"API key ID"},"required":true,"description":"API key ID","name":"id","in":"path"}],"responses":{"200":{"description":"API key details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKey"}}}},"404":{"description":"API key not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"summary":"Update API key","description":"Update an API key (rename or enable/disable)","tags":["API Keys"],"parameters":[{"schema":{"type":"string","format":"uuid","description":"API key ID"},"required":true,"description":"API key ID","name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateApiKey"}}}},"responses":{"200":{"description":"API key updated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKey"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"API key not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"summary":"Delete API key","description":"Delete an API key","tags":["API Keys"],"parameters":[{"schema":{"type":"string","format":"uuid","description":"API key ID"},"required":true,"description":"API key ID","name":"id","in":"path"}],"responses":{"204":{"description":"API key deleted successfully"},"404":{"description":"API key not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/agent-sync/sync":{"post":{"summary":"Sync Claude Code transcript","description":"Append raw, already-redacted JSONL transcript lines to a native Effective session. Idempotent: the session id is deterministic per (org, file) and messages are skipped by id.","tags":["Agent Sync"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentSyncRequest"}}}},"responses":{"200":{"description":"Transcript synced","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentSyncResponse"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/agents":{"get":{"summary":"List available agents","description":"Returns agents from the active sandbox agent catalog.","tags":["Agents"],"responses":{"200":{"description":"List of available agents","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListAgentsResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentsErrorResponse"}}}}}}},"/api/v1/agent-function-runs":{"post":{"summary":"Create agent function run","description":"Run a resolved typed agent task without requiring api-server to know workflow code.","tags":["Agent Function Runs"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateAgentFunctionRunRequest"}}}},"responses":{"200":{"description":"Agent function run completed or timed out","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentFunctionRunResponse"}}}},"202":{"description":"Agent function run queued","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentFunctionRunResponse"}}}},"400":{"description":"Invalid request"},"404":{"description":"Preset reference, project, or project phase not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentFunctionRunResponse"}}}},"429":{"description":"Spending limit exceeded - cost control enforce mode active","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentFunctionRunResponse"}}}},"500":{"description":"Failed to create agent function run"}}}},"/api/v1/agent-function-runs/{runId}":{"get":{"summary":"Get agent function run","description":"Read the current status and output for a resolved typed agent task run.","tags":["Agent Function Runs"],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"runId","in":"path"}],"responses":{"200":{"description":"Agent function run status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentFunctionRunResponse"}}}},"404":{"description":"Agent function run not found"}}}},"/api/v1/agent-tasks":{"post":{"summary":"Create agent task","description":"Create a new agent task for agent-to-agent delegation","tags":["Agent Tasks"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateAgentTask"}}}},"responses":{"201":{"description":"Task created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentTask"}}}},"400":{"description":"Invalid request"}}},"get":{"summary":"List agent tasks","description":"Get a paginated list of agent tasks with optional filters","tags":["Agent Tasks"],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":200,"default":50,"description":"Max items to return"},"required":false,"description":"Max items to return","name":"limit","in":"query"},{"schema":{"type":"integer","nullable":true,"minimum":0,"default":0,"description":"Pagination offset"},"required":false,"description":"Pagination offset","name":"offset","in":"query"},{"schema":{"type":"string","description":"Filter by creator session"},"required":false,"description":"Filter by creator session","name":"creator_session_id","in":"query"},{"schema":{"type":"string","description":"Filter by assigned session (via agent_task_assignments)"},"required":false,"description":"Filter by assigned session (via agent_task_assignments)","name":"assignee_session_id","in":"query"},{"schema":{"type":"string","format":"uuid","description":"Filter by project ID"},"required":false,"description":"Filter by project ID","name":"project_id","in":"query"},{"schema":{"type":"string","description":"Comma-separated valid project UUIDs for bulk project task lookup"},"required":false,"description":"Comma-separated valid project UUIDs for bulk project task lookup","name":"project_ids","in":"query"},{"schema":{"type":"string","format":"uuid","description":"Filter by project phase ID"},"required":false,"description":"Filter by project phase ID","name":"project_phase_id","in":"query"},{"schema":{"type":"string","description":"Filter by project phase key"},"required":false,"description":"Filter by project phase key","name":"project_phase_key","in":"query"},{"schema":{"type":"string","enum":["open","blocked","completed","closed"],"description":"Filter by task status"},"required":false,"description":"Filter by task status","name":"status","in":"query"},{"schema":{"type":"string","description":"Filter to tasks containing this label (e.g. ai-overview)"},"required":false,"description":"Filter to tasks containing this label (e.g. ai-overview)","name":"label","in":"query"},{"schema":{"type":"string","format":"date-time","description":"Only tasks created after this timestamp"},"required":false,"description":"Only tasks created after this timestamp","name":"created_after","in":"query"},{"schema":{"type":"string","format":"date-time","description":"Only tasks created before this timestamp"},"required":false,"description":"Only tasks created before this timestamp","name":"created_before","in":"query"},{"schema":{"type":"string","enum":["created_at"],"default":"created_at","description":"Sort field"},"required":false,"description":"Sort field","name":"order_by","in":"query"},{"schema":{"type":"string","enum":["asc","desc"],"default":"desc","description":"Sort direction"},"required":false,"description":"Sort direction","name":"order","in":"query"},{"schema":{"type":"string","description":"Comma-separated relations to include: submissions, comments"},"required":false,"description":"Comma-separated relations to include: submissions, comments","name":"include","in":"query"}],"responses":{"200":{"description":"Paginated list of tasks","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentTaskListResponse"}}}}}}},"/api/v1/agent-tasks/inbox":{"get":{"summary":"List assigned tasks for current user","description":"Get tasks assigned directly to the authenticated user or through one of their user groups. Use has_submission=false to find pending work.","tags":["Agent Tasks"],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":200,"default":50,"description":"Max items to return"},"required":false,"description":"Max items to return","name":"limit","in":"query"},{"schema":{"type":"integer","nullable":true,"minimum":0,"default":0,"description":"Pagination offset"},"required":false,"description":"Pagination offset","name":"offset","in":"query"},{"schema":{"type":"string","enum":["open","blocked","completed","closed"],"description":"Filter by task status"},"required":false,"description":"Filter by task status","name":"status","in":"query"},{"schema":{"type":"string","enum":["true","false"],"description":"Filter by whether the authenticated user has submitted. false = pending work."},"required":false,"description":"Filter by whether the authenticated user has submitted. false = pending work.","name":"has_submission","in":"query"},{"schema":{"type":"string","format":"uuid","description":"Filter by project ID"},"required":false,"description":"Filter by project ID","name":"project_id","in":"query"},{"schema":{"type":"string","description":"Comma-separated valid project UUIDs for bulk project task lookup"},"required":false,"description":"Comma-separated valid project UUIDs for bulk project task lookup","name":"project_ids","in":"query"},{"schema":{"type":"string","format":"uuid","description":"Filter by project phase ID"},"required":false,"description":"Filter by project phase ID","name":"project_phase_id","in":"query"},{"schema":{"type":"string","description":"Filter by project phase key"},"required":false,"description":"Filter by project phase key","name":"project_phase_key","in":"query"},{"schema":{"type":"string","enum":["asc","desc"],"default":"desc","description":"Sort direction by assignment creation time"},"required":false,"description":"Sort direction by assignment creation time","name":"order","in":"query"}],"responses":{"200":{"description":"Paginated list of assigned tasks","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentTaskListResponse"}}}}}}},"/api/v1/agent-tasks/assignments":{"get":{"summary":"List assignments for a session","description":"Get assignments for a specific agent session. Use has_submission=false to find pending work.","tags":["Agent Tasks"],"parameters":[{"schema":{"type":"string","description":"Filter by assigned session ID (required)"},"required":true,"description":"Filter by assigned session ID (required)","name":"session_id","in":"query"},{"schema":{"type":"string","enum":["true","false"],"description":"Filter by whether the assignee has submitted. false = pending work."},"required":false,"description":"Filter by whether the assignee has submitted. false = pending work.","name":"has_submission","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":200,"default":50,"description":"Max items to return"},"required":false,"description":"Max items to return","name":"limit","in":"query"},{"schema":{"type":"integer","nullable":true,"minimum":0,"default":0,"description":"Pagination offset"},"required":false,"description":"Pagination offset","name":"offset","in":"query"},{"schema":{"type":"string","enum":["asc","desc"],"default":"asc","description":"Sort order by createdAt. Defaults to asc (oldest first)."},"required":false,"description":"Sort order by createdAt. Defaults to asc (oldest first).","name":"order","in":"query"}],"responses":{"200":{"description":"Paginated list of assignments","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentTaskAssignmentListResponse"}}}}}}},"/api/v1/agent-tasks/assignments/by-task-ids":{"get":{"summary":"List assignments for multiple tasks","description":"Get assignments for multiple task IDs in a single request","tags":["Agent Tasks"],"parameters":[{"schema":{"type":"string","description":"Comma-separated task IDs (max 200)"},"required":true,"description":"Comma-separated task IDs (max 200)","name":"task_ids","in":"query"},{"schema":{"type":"string","enum":["asc","desc"],"default":"asc","description":"Sort order by createdAt. Defaults to asc (oldest first)."},"required":false,"description":"Sort order by createdAt. Defaults to asc (oldest first).","name":"order","in":"query"}],"responses":{"200":{"description":"Assignments for the provided task IDs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentTaskAssignmentsByTaskIdsResponse"}}}}}}},"/api/v1/agent-tasks/submissions/{submissionId}":{"get":{"summary":"Get a submission by ID","description":"Retrieve a specific task submission by its ID","tags":["Agent Tasks"],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"submissionId","in":"path"}],"responses":{"200":{"description":"Submission details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentTaskSubmission"}}}},"404":{"description":"Submission not found"}}}},"/api/v1/agent-tasks/submissions/{submissionId}/comments":{"post":{"summary":"Add comment to a submission","description":"Add feedback to a specific submission","tags":["Agent Tasks"],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"submissionId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateAgentTaskComment"}}}},"responses":{"201":{"description":"Comment created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentTaskComment"}}}},"404":{"description":"Submission not found"}}},"get":{"summary":"List comments for a submission","description":"Get a paginated list of comments for a specific submission","tags":["Agent Tasks"],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"submissionId","in":"path"},{"schema":{"type":"integer","minimum":1,"maximum":200,"default":50},"required":false,"name":"limit","in":"query"},{"schema":{"type":"integer","nullable":true,"minimum":0,"default":0},"required":false,"name":"offset","in":"query"}],"responses":{"200":{"description":"Paginated list of comments","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentTaskCommentListResponse"}}}}}}},"/api/v1/agent-tasks/{id}/comments":{"post":{"summary":"Add comment to a task","description":"Add feedback to a task, optionally without linking it to a submission","tags":["Agent Tasks"],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateAgentTaskComment"}}}},"responses":{"201":{"description":"Comment created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentTaskComment"}}}},"404":{"description":"Task not found"}}},"get":{"summary":"List comments for a task","description":"Get a paginated list of comments for a task","tags":["Agent Tasks"],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"},{"schema":{"type":"integer","minimum":1,"maximum":200,"default":50},"required":false,"name":"limit","in":"query"},{"schema":{"type":"integer","nullable":true,"minimum":0,"default":0},"required":false,"name":"offset","in":"query"}],"responses":{"200":{"description":"Paginated list of comments","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentTaskCommentListResponse"}}}},"404":{"description":"Task not found"}}}},"/api/v1/agent-tasks/{id}":{"get":{"summary":"Get agent task","description":"Get a specific agent task by ID","tags":["Agent Tasks"],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Task details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentTask"}}}},"404":{"description":"Task not found"}}},"patch":{"summary":"Update agent task","description":"Update mutable fields for an agent task","tags":["Agent Tasks"],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateAgentTask"}}}},"responses":{"200":{"description":"Task updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentTask"}}}},"404":{"description":"Task not found"}}},"delete":{"summary":"Delete agent task","description":"Delete an agent task and all its submissions and comments (cascade)","tags":["Agent Tasks"],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"204":{"description":"Task deleted"},"404":{"description":"Task not found"}}}},"/api/v1/agent-tasks/{id}/links":{"post":{"summary":"Link two tasks","description":"Create a task-to-task link. Supported types: blocks, relates_to, duplicates, parent. Idempotent — creating the same link again returns the existing link.","tags":["Agent Tasks"],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateAgentTaskLink"}}}},"responses":{"200":{"description":"Existing link","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentTaskLink"}}}},"201":{"description":"Link created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentTaskLink"}}}},"400":{"description":"Invalid link"},"404":{"description":"Source or target task not found"}}},"get":{"summary":"List links for a task","description":"Get task-to-task links connected to a task.","tags":["Agent Tasks"],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","enum":["outgoing","incoming","all"],"default":"all","description":"Filter links by direction relative to the selected task"},"required":false,"description":"Filter links by direction relative to the selected task","name":"direction","in":"query"},{"schema":{"type":"string","enum":["blocks","relates_to","duplicates","parent"],"description":"Filter by link type"},"required":false,"description":"Filter by link type","name":"type","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":200,"default":50,"description":"Max items to return"},"required":false,"description":"Max items to return","name":"limit","in":"query"},{"schema":{"type":"integer","nullable":true,"minimum":0,"default":0,"description":"Pagination offset"},"required":false,"description":"Pagination offset","name":"offset","in":"query"}],"responses":{"200":{"description":"Paginated list of links","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentTaskLinkListResponse"}}}},"404":{"description":"Task not found"}}}},"/api/v1/agent-tasks/{id}/links/{linkId}":{"delete":{"summary":"Remove a task link","description":"Delete a task-to-task link connected to this task.","tags":["Agent Tasks"],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"linkId","in":"path"}],"responses":{"204":{"description":"Link deleted"},"404":{"description":"Link not found"}}}},"/api/v1/agent-tasks/{id}/assignments":{"post":{"summary":"Assign a session to a task","description":"Create an assignment linking an agent session to a task. Idempotent — re-assigning the same session returns the existing assignment.","tags":["Agent Tasks"],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateAgentTaskAssignment"}}}},"responses":{"201":{"description":"Assignment created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentTaskAssignment"}}}},"404":{"description":"Task not found"}}},"get":{"summary":"List assignments for a task","description":"Get a paginated list of session assignments for an agent task","tags":["Agent Tasks"],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"},{"schema":{"type":"integer","minimum":1,"maximum":200,"default":50},"required":false,"name":"limit","in":"query"},{"schema":{"type":"integer","nullable":true,"minimum":0,"default":0},"required":false,"name":"offset","in":"query"}],"responses":{"200":{"description":"Paginated list of assignments","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentTaskAssignmentListResponse"}}}}}}},"/api/v1/agent-tasks/{id}/assignments/{assignmentId}":{"delete":{"summary":"Remove a session assignment from a task","description":"Delete an assignment, un-assigning the agent session from the task","tags":["Agent Tasks"],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"assignmentId","in":"path"}],"responses":{"204":{"description":"Assignment deleted"},"404":{"description":"Assignment not found"}}}},"/api/v1/agent-tasks/{id}/submissions":{"post":{"summary":"Submit result for a task","description":"Add a new submission (result) to an agent task","tags":["Agent Tasks"],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateAgentTaskSubmission"}}}},"responses":{"201":{"description":"Submission created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentTaskSubmission"}}}},"400":{"description":"Submission does not match task answer schema"},"403":{"description":"User is not assigned to this task"},"404":{"description":"Task not found"},"409":{"description":"Task is not open for submissions"}}},"get":{"summary":"List submissions for a task","description":"Get a paginated list of submissions for an agent task","tags":["Agent Tasks"],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"},{"schema":{"type":"integer","minimum":1,"maximum":200,"default":50},"required":false,"name":"limit","in":"query"},{"schema":{"type":"integer","nullable":true,"minimum":0,"default":0},"required":false,"name":"offset","in":"query"},{"schema":{"type":"string","enum":["asc","desc"],"default":"asc","description":"Sort direction by submitted_at"},"required":false,"description":"Sort direction by submitted_at","name":"order","in":"query"}],"responses":{"200":{"description":"Paginated list of submissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentTaskSubmissionListResponse"}}}}}}},"/api/v1/resource-annotations/summaries":{"post":{"summary":"Badge counts for a batch of resources","description":"Index-only counts for list-view indicators (open/total threads, bookmark state). POST because the ref batch exceeds query-string practicality; read-only semantics. Response array is index-aligned with the request refs.","tags":["Resource Annotations"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SummarizeResourcesRequest"}}}},"responses":{"200":{"description":"Summaries, index-aligned with request refs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SummarizeResourcesResponse"}}}}}}},"/api/v1/resource-annotations/threads":{"post":{"summary":"Create a thread on a resource","description":"Validates the resource (must exist and be visible) and any anchor, then creates the thread with its first comment.","tags":["Resource Annotations"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateThreadRequest"}}}},"responses":{"201":{"description":"Thread created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateThreadResponse"}}}},"400":{"description":"Bad anchor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"summary":"List threads for a resource","description":"Read-cheap: returns thread rows ordered by recent activity. Anchor drift display is computed client-side against the resource.","tags":["Resource Annotations"],"parameters":[{"schema":{"type":"string","minLength":1,"description":"base64url-encoded JSON ResourceRef identifying the annotated resource"},"required":true,"description":"base64url-encoded JSON ResourceRef identifying the annotated resource","name":"resource","in":"query"},{"schema":{"type":"string","enum":["open","resolved"]},"required":false,"name":"status","in":"query"},{"schema":{"type":"string","description":"Opaque cursor from nextCursor"},"required":false,"description":"Opaque cursor from nextCursor","name":"cursor","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Threads page","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResourceThreadPage"}}}},"400":{"description":"Malformed resource or cursor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/resource-annotations/threads/{threadId}":{"get":{"summary":"Get a thread","description":"Fetch a single thread by id.","tags":["Resource Annotations"],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"threadId","in":"path"}],"responses":{"200":{"description":"Thread","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResourceThread"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"summary":"Delete a thread","description":"Creator-only soft delete.","tags":["Resource Annotations"],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"threadId","in":"path"}],"responses":{"204":{"description":"Deleted"},"403":{"description":"Not creator","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/resource-annotations/threads/{threadId}/resolve":{"post":{"summary":"Resolve a thread","description":"Idempotent; appends a status_change event when the status actually changes.","tags":["Resource Annotations"],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"threadId","in":"path"}],"responses":{"200":{"description":"Updated thread","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResourceThread"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/resource-annotations/threads/{threadId}/reopen":{"post":{"summary":"Reopen a thread","description":"Idempotent; appends a status_change event when the status actually changes.","tags":["Resource Annotations"],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"threadId","in":"path"}],"responses":{"200":{"description":"Updated thread","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResourceThread"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/resource-annotations/threads/{threadId}/comments":{"get":{"summary":"List comments in a thread","description":"Oldest-first timeline including system events; deleted comments appear as tombstones.","tags":["Resource Annotations"],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"threadId","in":"path"},{"schema":{"type":"string","description":"Opaque cursor from nextCursor"},"required":false,"description":"Opaque cursor from nextCursor","name":"cursor","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":200},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Comments page","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResourceThreadCommentPage"}}}},"400":{"description":"Malformed cursor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Thread not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"summary":"Add a comment to a thread","description":"Top-level message or a one-level reply to an existing top-level comment.","tags":["Resource Annotations"],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"threadId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddCommentRequest"}}}},"responses":{"201":{"description":"Comment created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResourceThreadComment"}}}},"400":{"description":"Invalid parent","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/resource-annotations/comments/{commentId}":{"patch":{"summary":"Edit a comment","description":"Author-only; message comments only. Sets the edited marker.","tags":["Resource Annotations"],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"commentId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EditCommentRequest"}}}},"responses":{"200":{"description":"Updated comment","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResourceThreadComment"}}}},"400":{"description":"Not editable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Not author","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"summary":"Delete a comment","description":"Author-only soft delete; the comment becomes a tombstone in the timeline.","tags":["Resource Annotations"],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"commentId","in":"path"}],"responses":{"204":{"description":"Deleted"},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Not author","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/resource-annotations/bookmarks":{"put":{"summary":"Save a bookmark","description":"Idempotent for the authenticated user; re-saving updates the note.","tags":["Resource Annotations"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SaveBookmarkRequest"}}}},"responses":{"200":{"description":"Bookmark saved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResourceBookmark"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"summary":"Remove a bookmark","description":"Always succeeds for the authenticated user, even if the resource is gone.","tags":["Resource Annotations"],"parameters":[{"schema":{"type":"string","minLength":1,"description":"base64url-encoded JSON ResourceRef of the bookmarked resource"},"required":true,"description":"base64url-encoded JSON ResourceRef of the bookmarked resource","name":"resource","in":"query"}],"responses":{"204":{"description":"Removed (or was not saved)"},"400":{"description":"Malformed resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"summary":"List the authenticated user's bookmarks","description":"Newest first. Hydration of resource names is client-side via resource APIs.","tags":["Resource Annotations"],"parameters":[{"schema":{"type":"string","description":"Opaque cursor from nextCursor"},"required":false,"description":"Opaque cursor from nextCursor","name":"cursor","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":200},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Bookmarks page","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResourceBookmarkPage"}}}},"400":{"description":"Malformed cursor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/ai-overviews":{"get":{"summary":"Get AI overview","description":"Get the persisted AI overview for a target, if one exists","tags":["AI Overviews"],"parameters":[{"schema":{"$ref":"#/components/schemas/AiOverviewTargetKind"},"required":true,"name":"target_kind","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":255},"required":true,"name":"target_id","in":"query"}],"responses":{"200":{"description":"AI overview response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AiOverviewResponse"}}}}}}},"/api/v1/ai-overviews/regenerate":{"post":{"summary":"Regenerate AI overview","description":"Generate and persist an AI overview for a target","tags":["AI Overviews"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegenerateAiOverview"}}}},"responses":{"200":{"description":"Regenerated AI overview response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AiOverviewResponse"}}}},"404":{"description":"AI overview target not found"}}}},"/api/v1/workflow-runs/projects/{projectId}/events":{"get":{"summary":"Subscribe to workflow project events","description":"Subscribe to realtime workflow events for a project. Emits Server-Sent Events with keep_alive heartbeats.","tags":["Workflow Runs"],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"projectId","in":"path"}],"responses":{"200":{"description":"Server-Sent Events stream of workflow realtime events","content":{"text/event-stream":{"schema":{"$ref":"#/components/schemas/WorkflowRealtimeEvent"}}}}}}},"/api/v1/workflow-runs/mission-controls/{missionControlId}/events":{"get":{"summary":"Subscribe to workflow mission control events","description":"Subscribe to realtime workflow events for a mission control. Emits Server-Sent Events with keep_alive heartbeats.","tags":["Workflow Runs"],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"missionControlId","in":"path"}],"responses":{"200":{"description":"Server-Sent Events stream of workflow realtime events","content":{"text/event-stream":{"schema":{"$ref":"#/components/schemas/WorkflowRealtimeEvent"}}}}}}},"/api/v1/workflow-runs":{"post":{"summary":"Start a workflow run","description":"Start an L1 (Vercel Workflow SDK) run. If the workflow catalog declares a required project template and project_id is omitted, the API creates the project and phases first. Persists the project↔run edge and threads projectId into the run input.","tags":["Workflow Runs"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StartWorkflowRun"}}}},"responses":{"201":{"description":"Run started","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkflowRun"}}}},"404":{"description":"Project not found"},"503":{"description":"Workflows service not configured"}}},"get":{"summary":"List workflow runs","tags":["Workflow Runs"],"parameters":[{"schema":{"type":"string","format":"uuid","description":"Filter by project ID"},"required":false,"description":"Filter by project ID","name":"project_id","in":"query"},{"schema":{"type":"string","description":"Comma-separated project IDs for bulk project run lookup"},"required":false,"description":"Comma-separated project IDs for bulk project run lookup","name":"project_ids","in":"query"},{"schema":{"type":"string","enum":["running","waiting","completed","failed","cancelled"]},"required":false,"name":"status","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":200,"default":50},"required":false,"name":"limit","in":"query"},{"schema":{"type":"integer","nullable":true,"minimum":0,"default":0},"required":false,"name":"offset","in":"query"}],"responses":{"200":{"description":"Paginated list of workflow runs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkflowRunListResponse"}}}}}}},"/api/v1/workflow-runs/engine/{engineRunId}":{"get":{"summary":"Get workflow run by engine run id","tags":["Workflow Runs"],"parameters":[{"schema":{"type":"string"},"required":true,"name":"engineRunId","in":"path"}],"responses":{"200":{"description":"Workflow run","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkflowRun"}}}},"404":{"description":"Workflow run not found"}}}},"/api/v1/workflow-runs/engine/{engineRunId}/events":{"get":{"summary":"List workflow engine events","description":"List technical workflow engine events for a run. Event payloads are intended for diagnostics.","tags":["Workflow Runs"],"parameters":[{"schema":{"type":"string"},"required":true,"name":"engineRunId","in":"path"}],"responses":{"200":{"description":"Workflow engine events","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkflowRunEngineEventListResponse"}}}},"404":{"description":"Workflow engine run not found"}}}},"/api/v1/workflow-runs/engine/{engineRunId}/tasks":{"get":{"summary":"List materialized tasks for a workflow run","description":"List the native agent tasks created from workflow waits for an engine run. The SDK hook token is intentionally not returned; submissions should go through /agent-tasks/{taskId}/submissions.","tags":["Workflow Runs"],"parameters":[{"schema":{"type":"string"},"required":true,"name":"engineRunId","in":"path"}],"responses":{"200":{"description":"Materialized workflow tasks","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkflowRunTaskListResponse"}}}}}}},"/api/v1/workflow-runs/engine/{engineRunId}/cancel":{"post":{"summary":"Cancel a workflow run","description":"Cancel the underlying workflow engine run and mark any API-side project workflow run, waiting waits, and open/blocked materialized tasks as terminal.","tags":["Workflow Runs"],"parameters":[{"schema":{"type":"string"},"required":true,"name":"engineRunId","in":"path"}],"responses":{"204":{"description":"Run cancelled"},"404":{"description":"Workflow engine run not found"},"409":{"description":"Workflow engine run is already terminal"},"503":{"description":"Workflows service not configured"}}}},"/api/v1/workflow-runs/engine/{engineRunId}/retry":{"post":{"summary":"Retry a failed workflow run","description":"Re-enqueue the same underlying workflow engine run so durable history is replayed and execution continues from the failed point.","tags":["Workflow Runs"],"parameters":[{"schema":{"type":"string"},"required":true,"name":"engineRunId","in":"path"}],"responses":{"200":{"description":"Workflow run retry requested","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkflowRun"}}}},"404":{"description":"Workflow engine run not found"},"409":{"description":"Workflow engine run is not failed or cannot be retried"},"503":{"description":"Workflows service not configured"}}}},"/api/v1/workflow-runs/{workflowRunId}/tasks":{"post":{"summary":"Materialize a workflow hook as a task","description":"Called by a workflow (server-to-server) right after createHook(): creates the agent_task and the workflow_waits row holding the resume token. Idempotent on the token. The run is identified by our workflow run id (path), which the workflow received via platformContext.workflowRunId.","tags":["Workflow Runs"],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"workflowRunId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegisterWorkflowTask"}}}},"responses":{"201":{"description":"Task + wait created (or existing returned)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegisterWorkflowTaskResponse"}}}},"404":{"description":"Workflow run not found"}}}},"/api/v1/workflow-runs/{workflowRunId}/draft-tasks":{"post":{"summary":"Materialize a workflow hook as a Context Base draft-editing task","description":"Called by a workflow (server-to-server) right after createHook(): creates the agent_function task + the workflow_waits row, AND a Context Base draft bound to the agent session (the agent edits the draft directly — it never opens one itself). The created draftId is baked into the task output. Idempotent on the token and per agent task.","tags":["Workflow Runs"],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"workflowRunId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegisterWorkflowDraftTask"}}}},"responses":{"201":{"description":"Task + wait created (or existing returned)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegisterWorkflowTaskResponse"}}}},"404":{"description":"Workflow run not found"}}}},"/api/v1/workflow-runs/{workflowRunId}/draft-waits":{"post":{"summary":"Materialize a workflow hook as a wait on a Context Base draft lifecycle task","description":"Called by a workflow (server-to-server) after a Context Base draft has been created. Creates a workflow_waits row attached to the draft lifecycle task and resumes the hook when the draft reaches a terminal lifecycle status (published or abandoned).","tags":["Workflow Runs"],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"workflowRunId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegisterWorkflowDraftWait"}}}},"responses":{"201":{"description":"Draft wait created (or existing returned)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegisterWorkflowTaskResponse"}}}},"404":{"description":"Workflow run not found"}}}},"/api/v1/workflow-runs/{workflowRunId}/resolve-secrets":{"post":{"summary":"Resolve secrets for a workflow run","description":"Called by a workflow at runtime. Looks up the workflow_id from the project_workflow_runs table, then resolves declared secrets via workflow_secrets + workflow_secret_bindings.","tags":["Workflow Runs"],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"workflowRunId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"names":{"type":"array","items":{"type":"string"},"description":"Optional filter — resolve only these secret names. If omitted, all declared secrets are resolved."}}}}}},"responses":{"200":{"description":"Resolved secrets keyed by name","content":{"application/json":{"schema":{"type":"object","properties":{"secrets":{"type":"object","additionalProperties":{"type":"string","nullable":true}}},"required":["secrets"]}}}},"403":{"description":"Forbidden — caller is not the run starter or an admin"},"404":{"description":"Workflow run not found"}}}},"/api/v1/workflows/{workflowId}/secrets":{"get":{"tags":["Workflows/Secrets"],"summary":"List a workflow's requirements with hydrated default + caller binding","parameters":[{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Workflow ID (slug, e.g. \"prod-release\")"},"required":true,"description":"Workflow ID (slug, e.g. \"prod-release\")","name":"workflowId","in":"path"}],"responses":{"200":{"description":"Requirements + caller-relative metadata","content":{"application/json":{"schema":{"type":"object","properties":{"requirements":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"orgId":{"type":"string"},"workflowId":{"type":"string"},"secretName":{"type":"string"},"defaultSecretId":{"type":"string","nullable":true,"format":"uuid"},"defaultSecret":{"type":"object","nullable":true,"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"ownerUserId":{"type":"string","nullable":true},"ownerAppId":{"type":"string","nullable":true},"ownerWorkflowId":{"type":"string","nullable":true},"secretValueMasked":{"type":"string","description":"Masked preview, e.g. \"••••abcd\". Never contains the raw value."},"networkInjectionConfigJson":{"$ref":"#/components/schemas/NetworkInjectionConfig"}},"required":["id","name","ownerUserId","ownerAppId","ownerWorkflowId","secretValueMasked","networkInjectionConfigJson"],"description":"Hydrated default secret (brief — no raw value) when the pointer resolves."},"myBinding":{"type":"object","nullable":true,"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"ownerUserId":{"type":"string","nullable":true},"ownerAppId":{"type":"string","nullable":true},"ownerWorkflowId":{"type":"string","nullable":true},"secretValueMasked":{"type":"string","description":"Masked preview, e.g. \"••••abcd\". Never contains the raw value."},"networkInjectionConfigJson":{"$ref":"#/components/schemas/NetworkInjectionConfig"}},"required":["id","name","ownerUserId","ownerAppId","ownerWorkflowId","secretValueMasked","networkInjectionConfigJson"],"description":"The caller's user-owned binding that overrides the default at resolve time, if any."},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","orgId","workflowId","secretName","defaultSecretId","defaultSecret","myBinding","createdAt","updatedAt"]}}},"required":["requirements"]}}}}}},"put":{"tags":["Workflows/Secrets"],"summary":"Declare (or refresh) a required secret for a workflow","parameters":[{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Workflow ID (slug, e.g. \"prod-release\")"},"required":true,"description":"Workflow ID (slug, e.g. \"prod-release\")","name":"workflowId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"secretName":{"type":"string","minLength":1,"maxLength":100,"description":"Secret name (e.g. \"openai-key\")"}},"required":["secretName"]}}}},"responses":{"200":{"description":"Requirement declared","content":{"application/json":{"schema":{"type":"object","properties":{"secret":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"orgId":{"type":"string"},"workflowId":{"type":"string"},"secretName":{"type":"string"},"defaultSecretId":{"type":"string","nullable":true,"format":"uuid"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","orgId","workflowId","secretName","defaultSecretId","createdAt","updatedAt"]}},"required":["secret"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/workflows/{workflowId}/secrets/{name}":{"delete":{"tags":["Workflows/Secrets"],"summary":"Remove a required-secret declaration","parameters":[{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Workflow ID (slug, e.g. \"prod-release\")"},"required":true,"description":"Workflow ID (slug, e.g. \"prod-release\")","name":"workflowId","in":"path"},{"schema":{"type":"string","minLength":1,"maxLength":100,"description":"Declared secret name"},"required":true,"description":"Declared secret name","name":"name","in":"path"}],"responses":{"200":{"description":"Requirement removed","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}},"required":["success"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Requirement not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/workflows/{workflowId}/secrets/{name}/default":{"put":{"tags":["Workflows/Secrets"],"summary":"Set (or clear) the org-level default secret for a requirement","parameters":[{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Workflow ID (slug, e.g. \"prod-release\")"},"required":true,"description":"Workflow ID (slug, e.g. \"prod-release\")","name":"workflowId","in":"path"},{"schema":{"type":"string","minLength":1,"maxLength":100,"description":"Declared secret name"},"required":true,"description":"Declared secret name","name":"name","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"secretId":{"type":"string","nullable":true,"format":"uuid","description":"Secret ID to use as default, or null to clear"}},"required":["secretId"]}}}},"responses":{"200":{"description":"Default updated","content":{"application/json":{"schema":{"type":"object","properties":{"secret":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"orgId":{"type":"string"},"workflowId":{"type":"string"},"secretName":{"type":"string"},"defaultSecretId":{"type":"string","nullable":true,"format":"uuid"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","orgId","workflowId","secretName","defaultSecretId","createdAt","updatedAt"]}},"required":["secret"]}}}},"400":{"description":"Bad request — secret not pickable by caller","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Requirement not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/workflows/{workflowId}/secrets/{name}/binding":{"put":{"tags":["Workflows/Secrets"],"summary":"Bind a secret to this workflow's requirement (caller scope)","parameters":[{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Workflow ID (slug, e.g. \"prod-release\")"},"required":true,"description":"Workflow ID (slug, e.g. \"prod-release\")","name":"workflowId","in":"path"},{"schema":{"type":"string","minLength":1,"maxLength":100,"description":"Declared secret name"},"required":true,"description":"Declared secret name","name":"name","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"secretId":{"type":"string","format":"uuid","description":"Secret ID the caller picks for this slot"}},"required":["secretId"]}}}},"responses":{"200":{"description":"Binding written","content":{"application/json":{"schema":{"type":"object","properties":{"binding":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"orgId":{"type":"string"},"workflowId":{"type":"string"},"secretName":{"type":"string"},"userId":{"type":"string"},"secretId":{"type":"string","format":"uuid"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","orgId","workflowId","secretName","userId","secretId","createdAt","updatedAt"]}},"required":["binding"]}}}},"400":{"description":"Bad request — secret not pickable by caller","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized — user authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Requirement not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"tags":["Workflows/Secrets"],"summary":"Clear the caller's binding for a workflow's required secret","parameters":[{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Workflow ID (slug, e.g. \"prod-release\")"},"required":true,"description":"Workflow ID (slug, e.g. \"prod-release\")","name":"workflowId","in":"path"},{"schema":{"type":"string","minLength":1,"maxLength":100,"description":"Declared secret name"},"required":true,"description":"Declared secret name","name":"name","in":"path"}],"responses":{"200":{"description":"Binding removed","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}},"required":["success"]}}}},"401":{"description":"Unauthorized — user authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Binding not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/workflows/{workflowId}/secrets/pickable-defaults":{"get":{"tags":["Workflows/Secrets"],"summary":"List secrets eligible to be set as this workflow's default for a requirement","parameters":[{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Workflow ID (slug, e.g. \"prod-release\")"},"required":true,"description":"Workflow ID (slug, e.g. \"prod-release\")","name":"workflowId","in":"path"}],"responses":{"200":{"description":"Eligible secrets in brief shape","content":{"application/json":{"schema":{"type":"object","properties":{"secrets":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"ownerUserId":{"type":"string","nullable":true},"ownerAppId":{"type":"string","nullable":true},"ownerWorkflowId":{"type":"string","nullable":true},"secretValueMasked":{"type":"string","description":"Masked preview, e.g. \"••••abcd\". Never contains the raw value."},"networkInjectionConfigJson":{"$ref":"#/components/schemas/NetworkInjectionConfig"}},"required":["id","name","ownerUserId","ownerAppId","ownerWorkflowId","secretValueMasked","networkInjectionConfigJson"]}}},"required":["secrets"]}}}}}}},"/api/v1/apps/{appId}/webhooks":{"post":{"tags":["Apps"],"summary":"Create an incoming webhook for an app","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"appId","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateIncomingWebhookRequest"}}}},"responses":{"201":{"description":"Webhook created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateIncomingWebhookResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"App not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Webhook name already exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"tags":["Apps"],"summary":"List incoming webhooks for an app","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"appId","in":"path"}],"responses":{"200":{"description":"Webhooks listed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListIncomingWebhooksResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"App not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/apps/{appId}/webhooks/{webhookId}":{"delete":{"tags":["Apps"],"summary":"Revoke an incoming app webhook","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"appId","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"webhookId","in":"path"}],"responses":{"200":{"description":"Webhook revoked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RevokeIncomingWebhookResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Webhook not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/chat/sessions/{sessionId}/webhooks":{"post":{"tags":["Chat"],"summary":"Create an incoming webhook for a session","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"sessionId","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateIncomingWebhookRequest"}}}},"responses":{"201":{"description":"Webhook created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateIncomingWebhookResponse"}}}},"404":{"description":"Session not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Webhook name already exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"tags":["Chat"],"summary":"List incoming webhooks for a session","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"sessionId","in":"path"}],"responses":{"200":{"description":"Webhooks listed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListIncomingWebhooksResponse"}}}},"404":{"description":"Session not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/chat/sessions/{sessionId}/webhooks/{webhookId}":{"delete":{"tags":["Chat"],"summary":"Revoke an incoming session webhook","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"sessionId","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"webhookId","in":"path"}],"responses":{"200":{"description":"Webhook revoked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RevokeIncomingWebhookResponse"}}}},"404":{"description":"Webhook not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/hooks/{pathSlug}":{"post":{"tags":["Webhooks"],"summary":"Fire an incoming webhook using Bearer auth","description":"Authenticated webhook endpoint. Uses the caller's API key (Bearer token) for auth instead of a URL-embedded secret. For app-owned webhooks, validates that the caller has app run permission. Deduplicates by Idempotency-Key header.","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"pathSlug","in":"path"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"nullable":true,"description":"Arbitrary JSON payload delivered as an incoming_webhook event."}}}},"responses":{"200":{"description":"Duplicate webhook replay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IncomingWebhookBearerFireResponse"}}}},"202":{"description":"Webhook accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IncomingWebhookBearerFireResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Webhook not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Webhook fire already in flight","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IncomingWebhookBearerFireResponse"}}}},"500":{"description":"Failed to publish webhook event","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IncomingWebhookBearerFireResponse"}}}}}}},"/api/v1/apps":{"post":{"summary":"Register a new app","description":"Creates or updates an app_settings row with catalog metadata and infrastructure config. Called from sandbox `app create` to persist the app in the database. Idempotent — safe to call multiple times for the same app.","tags":["Apps"],"requestBody":{"required":true,"description":"App registration data","content":{"application/json":{"schema":{"type":"object","properties":{"appId":{"type":"string","minLength":1,"description":"App identifier (e.g. app-my-dashboard)"},"title":{"type":"string","minLength":1,"description":"Display title"},"description":{"type":"string","description":"Catalog description"},"iconEmoji":{"type":"string","description":"Single emoji icon (e.g. 📦)"},"iconUrl":{"type":"string","format":"uri","description":"URL to an icon image"},"visibility":{"type":"string","enum":["private","team"],"description":"Catalog visibility — 'team' (default) or 'private'"}},"required":["appId"]}}}},"responses":{"200":{"description":"App registered successfully","content":{"application/json":{"schema":{"type":"object","properties":{"appId":{"type":"string"},"registered":{"type":"boolean"}},"required":["appId","registered"]}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"summary":"List all available apps","description":"List all available apps in the system","tags":["Apps"],"responses":{"200":{"description":"Apps stream retrieved successfully","content":{"application/x-ndjson":{"schema":{"$ref":"#/components/schemas/ListAppsNdjsonResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/apps/{appId}/archive":{"post":{"summary":"Archive an app","description":"Hides the app from all listings. Also archives any projects scoped to this app.","tags":["Apps"],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"appId","in":"path"}],"responses":{"200":{"description":"App archived","content":{"application/json":{"schema":{"type":"object","properties":{"app_id":{"type":"string"},"archived":{"type":"boolean","enum":[true]}},"required":["app_id","archived"]}}}},"403":{"description":"Not the creator","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"App not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/apps/{appId}/unarchive":{"post":{"summary":"Unarchive an app","description":"Restores a previously archived app so it reappears in listings.","tags":["Apps"],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"appId","in":"path"}],"responses":{"200":{"description":"App unarchived","content":{"application/json":{"schema":{"type":"object","properties":{"app_id":{"type":"string"},"archived":{"type":"boolean","enum":[false]}},"required":["app_id","archived"]}}}},"403":{"description":"Permission denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/apps/{appId}/share":{"post":{"summary":"Share an app with the team","description":"Sets visibility to 'team' for this app. Creator or Tenant Admin can share.","tags":["Apps"],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"appId","in":"path"}],"responses":{"200":{"description":"App shared","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppShareResponse"}}}},"403":{"description":"Not the creator","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"App not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/apps/{appId}/unshare":{"post":{"summary":"Unshare an app (make private)","description":"Sets visibility to 'private' for this app. Creator or Tenant Admin can unshare. The app remains visible to its creator but hidden from others.","tags":["Apps"],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"appId","in":"path"}],"responses":{"200":{"description":"App unshared","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppUnshareResponse"}}}},"403":{"description":"Not the creator","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"App not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/apps/{appId}/make-public":{"post":{"summary":"Make an app publicly accessible","description":"Allows unauthenticated access to the app UI via its public hostname. Creator or Tenant Admin can make an app public.","tags":["Apps"],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"appId","in":"path"}],"responses":{"200":{"description":"App is now public","content":{"application/json":{"schema":{"type":"object","properties":{"app_id":{"type":"string"},"public":{"type":"boolean","enum":[true]}},"required":["app_id","public"]}}}},"403":{"description":"Not the creator","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"App not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/apps/{appId}/remove-public-access":{"post":{"summary":"Remove public access from an app","description":"Requires authentication again for the app UI.","tags":["Apps"],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"appId","in":"path"}],"responses":{"200":{"description":"App is now private","content":{"application/json":{"schema":{"type":"object","properties":{"app_id":{"type":"string"},"public":{"type":"boolean","enum":[false]}},"required":["app_id","public"]}}}},"403":{"description":"Not the creator","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"App not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/apps/{appId}/publish/prepare":{"post":{"summary":"Prepare a deployment — check status and get presigned upload URLs","description":"Validates auth, checks for existing uploads in R2. If the SHA is not yet uploaded and a file list is provided, returns presigned PUT URLs for each file. Each URL is scoped to one specific R2 object and expires after 15 minutes. Max 2000 files per call. The sandbox uploads files directly to R2 using these URLs, then calls publish/finalize.","tags":["Apps"],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"appId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"sha":{"type":"string","minLength":1,"description":"Git commit SHA — used as the immutable content key"},"totalSize":{"type":"integer","minimum":0,"exclusiveMinimum":true,"description":"Total size of all files in bytes (optional, validated if provided)"},"files":{"type":"array","items":{"type":"string","minLength":1},"maxItems":2000,"description":"Relative file paths within dist/. When provided and SHA is not yet uploaded, the response includes presigned PUT URLs for each file."}},"required":["sha"]}}}},"responses":{"200":{"description":"Upload status, asset prefix, and optional presigned URLs","content":{"application/json":{"schema":{"type":"object","properties":{"alreadyUploaded":{"type":"boolean"},"assetPrefix":{"type":"string"},"uploadUrls":{"type":"object","additionalProperties":{"type":"string"}}},"required":["alreadyUploaded","assetPrefix"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"App not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/apps/{appId}/publish/finalize":{"post":{"summary":"Finalize a deployment — record in DB after R2 upload","description":"Verifies index.html exists in R2, creates the deployment record, and updates the app_settings pointer for production deployments. Idempotent — calling with the same SHA and channel returns the existing deployment.","tags":["Apps"],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"appId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"sha":{"type":"string","minLength":1,"description":"Must match the SHA from prepare"},"channelKey":{"type":"string","default":"production","description":"\"production\" or \"branch/{name}\""},"title":{"type":"string","description":"Display title for the app"},"description":{"type":"string","description":"Short description of the app"},"visibility":{"type":"string","enum":["private","team"],"description":"Catalog visibility — 'private' or 'team'"}},"required":["sha"]}}}},"responses":{"200":{"description":"Deployment recorded","content":{"application/json":{"schema":{"type":"object","properties":{"deploymentId":{"type":"string"},"sha":{"type":"string"},"channelKey":{"type":"string"},"publishedAt":{"type":"string"}},"required":["deploymentId","sha","channelKey","publishedAt"]}}}},"403":{"description":"Permission denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"App not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Upload not complete","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/apps/{appId}/deployments":{"get":{"summary":"List deployment history for an app","tags":["Apps"],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"appId","in":"path"},{"schema":{"type":"integer","minimum":0,"exclusiveMinimum":true,"default":20},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Deployment history","content":{"application/json":{"schema":{"type":"object","properties":{"deployments":{"type":"array","items":{"type":"object","properties":{"deploymentId":{"type":"string"},"sha":{"type":"string"},"channelKey":{"type":"string"},"publishedBy":{"type":"string","nullable":true},"publishedAt":{"type":"string"}},"required":["deploymentId","sha","channelKey","publishedBy","publishedAt"]}}},"required":["deployments"]}}}},"403":{"description":"Permission denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/apps/{appId}/session-url":{"get":{"summary":"Get session URLs for an app","description":"Returns dev and deployment URLs for an app in the context of a session sandbox. The devUrl points to the Vite dev server via sandbox proxy. The deploymentUrl points to the CDN-served published version (if a deployment exists).","tags":["Apps"],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"appId","in":"path"},{"schema":{"type":"string","minLength":1,"description":"Session ID whose sandbox should serve the app"},"required":true,"description":"Session ID whose sandbox should serve the app","name":"sessionId","in":"query"},{"schema":{"type":"string","description":"Project name (reserved for future use)"},"required":false,"description":"Project name (reserved for future use)","name":"project","in":"query"}],"responses":{"200":{"description":"Session URLs","content":{"application/json":{"schema":{"type":"object","properties":{"devUrl":{"type":"string","description":"URL to the Vite dev server via sandbox proxy"},"deploymentUrl":{"type":"string","nullable":true,"description":"URL to the CDN-served published version (null if no deployment)"},"deployment":{"type":"object","nullable":true,"properties":{"sha":{"type":"string"},"source":{"type":"string","enum":["cdn","vault"]},"publishedAt":{"type":"string"},"publishedBy":{"type":"string","nullable":true}},"required":["sha","source","publishedAt","publishedBy"],"description":"Deployment metadata (null if no deployment)"}},"required":["devUrl","deploymentUrl","deployment"]}}}},"403":{"description":"Permission denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Session or sandbox not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/apps/{appId}/permissions":{"get":{"summary":"List per-app permission grants","description":"Lists users and groups with direct runner/builder grants.","tags":["Apps"],"parameters":[{"schema":{"type":"string"},"required":true,"name":"appId","in":"path"}],"responses":{"200":{"description":"Permission grants","content":{"application/json":{"schema":{"type":"object","properties":{"grants":{"type":"array","items":{"type":"object","properties":{"subjectType":{"type":"string"},"subjectId":{"type":"string"},"relation":{"type":"string"}},"required":["subjectType","subjectId","relation"]}}},"required":["grants"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"summary":"Grant a per-app permission","description":"Grants runner or builder access on this app to a user or group.","tags":["Apps"],"parameters":[{"schema":{"type":"string"},"required":true,"name":"appId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"subjectType":{"type":"string","enum":["user","group","org"]},"subjectId":{"type":"string","minLength":1},"relation":{"type":"string","enum":["runner","builder"]}},"required":["subjectType","relation"]}}}},"responses":{"201":{"description":"Permission granted","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}},"required":["success"]}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"summary":"Revoke a per-app permission","description":"Removes runner or builder access on this app from a user or group.","tags":["Apps"],"parameters":[{"schema":{"type":"string"},"required":true,"name":"appId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"subjectType":{"type":"string","enum":["user","group","org"]},"subjectId":{"type":"string","minLength":1},"relation":{"type":"string","enum":["runner","builder"]}},"required":["subjectType","relation"]}}}},"responses":{"200":{"description":"Permission revoked","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}},"required":["success"]}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/apps/{appId}/static-ip":{"put":{"summary":"Assign a static IP to an app","description":"Associates an app with a static IP from the org pool. Tenant Admin required.","tags":["Apps"],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"appId","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"staticIpId":{"type":"string","format":"uuid","description":"ID of the static IP to assign"}},"required":["staticIpId"]}}}},"responses":{"200":{"description":"App assigned to static IP","content":{"application/json":{"schema":{"type":"object","properties":{"appId":{"type":"string"},"staticIpId":{"type":"string","format":"uuid"},"ipAddress":{"type":"string","nullable":true}},"required":["appId","staticIpId","ipAddress"]}}}},"403":{"description":"Forbidden — Tenant Admin required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Static IP not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Static IP not active","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"status":{"type":"string"}},"required":["error","status"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"summary":"Unassign a static IP from an app","description":"Removes the static IP assignment for an app. Tenant Admin required.","tags":["Apps"],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"appId","in":"path"}],"responses":{"200":{"description":"Static IP unassigned","content":{"application/json":{"schema":{"type":"object","properties":{"appId":{"type":"string"},"staticIpId":{"nullable":true}},"required":["appId","staticIpId"]}}}},"403":{"description":"Forbidden — Tenant Admin required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No static IP assigned to this app","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/apps/{appId}/secrets":{"get":{"tags":["Apps/Secrets"],"summary":"List an app's requirements with hydrated default + caller binding","parameters":[{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"App ID"},"required":true,"description":"App ID","name":"appId","in":"path"}],"responses":{"200":{"description":"Requirements + caller-relative metadata","content":{"application/json":{"schema":{"type":"object","properties":{"canBuild":{"type":"boolean","description":"True when the caller can mutate this app (creator, workspace admin, or builder-grant holder). Drives build-only affordances like declaring requirements and setting defaults."},"canManage":{"type":"boolean","description":"Deprecated alias for `canBuild`. Computed from the same `canBuildApp` check; do not use for new code."},"requirements":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"orgId":{"type":"string"},"appId":{"type":"string"},"secretName":{"type":"string"},"defaultSecretId":{"type":"string","nullable":true,"format":"uuid"},"defaultSecret":{"type":"object","nullable":true,"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"ownerUserId":{"type":"string","nullable":true},"ownerAppId":{"type":"string","nullable":true},"ownerWorkflowId":{"type":"string","nullable":true},"secretValueMasked":{"type":"string","description":"Masked preview, e.g. \"••••abcd\". Never contains the raw value."},"networkInjectionConfigJson":{"$ref":"#/components/schemas/NetworkInjectionConfig"}},"required":["id","name","ownerUserId","ownerAppId","ownerWorkflowId","secretValueMasked","networkInjectionConfigJson"],"description":"Hydrated default secret (brief — no raw value) when the pointer resolves."},"myBinding":{"type":"object","nullable":true,"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"ownerUserId":{"type":"string","nullable":true},"ownerAppId":{"type":"string","nullable":true},"ownerWorkflowId":{"type":"string","nullable":true},"secretValueMasked":{"type":"string","description":"Masked preview, e.g. \"••••abcd\". Never contains the raw value."},"networkInjectionConfigJson":{"$ref":"#/components/schemas/NetworkInjectionConfig"}},"required":["id","name","ownerUserId","ownerAppId","ownerWorkflowId","secretValueMasked","networkInjectionConfigJson"],"description":"The caller's user-owned binding that overrides the default at resolve time, if any."},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","orgId","appId","secretName","defaultSecretId","defaultSecret","myBinding","createdAt","updatedAt"]}}},"required":["canBuild","canManage","requirements"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"App not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"put":{"tags":["Apps/Secrets"],"summary":"Declare (or refresh) a required secret for an app","parameters":[{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"App ID"},"required":true,"description":"App ID","name":"appId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"secretName":{"type":"string","minLength":1,"maxLength":100,"description":"Secret name (e.g. \"openai-key\")"}},"required":["secretName"]}}}},"responses":{"200":{"description":"Requirement declared","content":{"application/json":{"schema":{"type":"object","properties":{"secret":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"orgId":{"type":"string"},"appId":{"type":"string"},"secretName":{"type":"string"},"defaultSecretId":{"type":"string","nullable":true,"format":"uuid"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","orgId","appId","secretName","defaultSecretId","createdAt","updatedAt"]}},"required":["secret"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"App not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/apps/{appId}/secrets/{name}":{"delete":{"tags":["Apps/Secrets"],"summary":"Remove a required-secret declaration","parameters":[{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"App ID"},"required":true,"description":"App ID","name":"appId","in":"path"},{"schema":{"type":"string","minLength":1,"maxLength":100,"description":"Declared secret name"},"required":true,"description":"Declared secret name","name":"name","in":"path"}],"responses":{"200":{"description":"Requirement removed","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}},"required":["success"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Requirement not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/apps/{appId}/secrets/{name}/default":{"put":{"tags":["Apps/Secrets"],"summary":"Set (or clear) the org-level default secret for a requirement","parameters":[{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"App ID"},"required":true,"description":"App ID","name":"appId","in":"path"},{"schema":{"type":"string","minLength":1,"maxLength":100,"description":"Declared secret name"},"required":true,"description":"Declared secret name","name":"name","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"secretId":{"type":"string","nullable":true,"format":"uuid","description":"Secret ID to use as default, or null to clear"}},"required":["secretId"]}}}},"responses":{"200":{"description":"Default updated","content":{"application/json":{"schema":{"type":"object","properties":{"secret":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"orgId":{"type":"string"},"appId":{"type":"string"},"secretName":{"type":"string"},"defaultSecretId":{"type":"string","nullable":true,"format":"uuid"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","orgId","appId","secretName","defaultSecretId","createdAt","updatedAt"]}},"required":["secret"]}}}},"400":{"description":"Bad request — secret not pickable by caller","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Requirement not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/apps/{appId}/secrets/{name}/binding":{"put":{"tags":["Apps/Secrets"],"summary":"Bind a secret to this app's requirement (caller scope)","parameters":[{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"App ID"},"required":true,"description":"App ID","name":"appId","in":"path"},{"schema":{"type":"string","minLength":1,"maxLength":100,"description":"Declared secret name"},"required":true,"description":"Declared secret name","name":"name","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"secretId":{"type":"string","format":"uuid","description":"Secret ID the caller picks for this slot"}},"required":["secretId"]}}}},"responses":{"200":{"description":"Binding written","content":{"application/json":{"schema":{"type":"object","properties":{"binding":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"orgId":{"type":"string"},"appId":{"type":"string"},"secretName":{"type":"string"},"userId":{"type":"string"},"secretId":{"type":"string","format":"uuid"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","orgId","appId","secretName","userId","secretId","createdAt","updatedAt"]}},"required":["binding"]}}}},"400":{"description":"Bad request — secret not pickable by caller","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"App or requirement not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"tags":["Apps/Secrets"],"summary":"Clear the caller's binding for an app's required secret","parameters":[{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"App ID"},"required":true,"description":"App ID","name":"appId","in":"path"},{"schema":{"type":"string","minLength":1,"maxLength":100,"description":"Declared secret name"},"required":true,"description":"Declared secret name","name":"name","in":"path"}],"responses":{"200":{"description":"Binding removed","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}},"required":["success"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Binding not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/apps/{appId}/secrets/pickable-defaults":{"get":{"tags":["Apps/Secrets"],"summary":"List secrets eligible to be set as this app's default for a requirement","parameters":[{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"App ID"},"required":true,"description":"App ID","name":"appId","in":"path"}],"responses":{"200":{"description":"Eligible secrets (org-owned + this-app-owned) in brief shape","content":{"application/json":{"schema":{"type":"object","properties":{"secrets":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"ownerUserId":{"type":"string","nullable":true},"ownerAppId":{"type":"string","nullable":true},"ownerWorkflowId":{"type":"string","nullable":true},"secretValueMasked":{"type":"string","description":"Masked preview, e.g. \"••••abcd\". Never contains the raw value."},"networkInjectionConfigJson":{"$ref":"#/components/schemas/NetworkInjectionConfig"}},"required":["id","name","ownerUserId","ownerAppId","ownerWorkflowId","secretValueMasked","networkInjectionConfigJson"]}}},"required":["secrets"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"App not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/apps/{appId}/secrets/{name}/default/promote":{"post":{"tags":["Apps/Secrets"],"summary":"Promote a legacy user-owned app default to an app-owned secret","parameters":[{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"App ID"},"required":true,"description":"App ID","name":"appId","in":"path"},{"schema":{"type":"string","minLength":1,"maxLength":100,"description":"Declared secret name"},"required":true,"description":"Declared secret name","name":"name","in":"path"}],"responses":{"200":{"description":"Default repointed at a new app-owned secret","content":{"application/json":{"schema":{"type":"object","properties":{"secret":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"orgId":{"type":"string"},"appId":{"type":"string"},"secretName":{"type":"string"},"defaultSecretId":{"type":"string","nullable":true,"format":"uuid"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","orgId","appId","secretName","defaultSecretId","createdAt","updatedAt"]},"newSecretId":{"type":"string","format":"uuid","description":"Id of the newly app-owned secret"}},"required":["secret","newSecretId"]}}}},"400":{"description":"Bad request — default is not user-owned (nothing to promote)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Requirement not found, or no default set","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/apps/{appId}/secrets/resolved":{"get":{"tags":["Apps/Secrets"],"summary":"List declared secrets with resolved values for the caller","parameters":[{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"App ID"},"required":true,"description":"App ID","name":"appId","in":"path"}],"responses":{"200":{"description":"Resolved secrets for runtime use — raw values, gated to runners","content":{"application/json":{"schema":{"type":"object","properties":{"secrets":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"secretValue":{"type":"string","nullable":true}},"required":["name","secretValue"]}}},"required":["secrets"]}}}},"403":{"description":"Forbidden — run access required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"App not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/apps/{appId}/bookmark":{"post":{"summary":"Bookmark an app","description":"Adds a bookmark for the current user on the specified app. Idempotent — calling multiple times for the same app has no additional effect.","tags":["Apps"],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"appId","in":"path"}],"responses":{"200":{"description":"App bookmarked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BookmarkResponse"}}}},"401":{"description":"User authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"App not found or not accessible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"summary":"Unbookmark an app","description":"Removes the bookmark for the current user on the specified app. Idempotent — calling when no bookmark exists has no effect.","tags":["Apps"],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"appId","in":"path"}],"responses":{"200":{"description":"App unbookmarked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnbookmarkResponse"}}}},"401":{"description":"User authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/apps/{appId}/logs":{"get":{"summary":"Get platform API call logs for an app","description":"Query structured platform logs for API calls made by this app. Returns curated log entries, not raw infrastructure records.","tags":["Apps"],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"appId","in":"path"},{"schema":{"type":"number","nullable":true,"description":"Max log entries per page (default 50)"},"required":false,"description":"Max log entries per page (default 50)","name":"limit","in":"query"},{"schema":{"type":"string","description":"Cursor for forward pagination: only return logs after this timestamp"},"required":false,"description":"Cursor for forward pagination: only return logs after this timestamp","name":"afterTimestamp","in":"query"},{"schema":{"type":"string","description":"Cursor for backward pagination: only return logs before this timestamp"},"required":false,"description":"Cursor for backward pagination: only return logs before this timestamp","name":"beforeTimestamp","in":"query"},{"schema":{"type":"string","description":"Filter by log level (e.g. ERROR, WARN, INFO)"},"required":false,"description":"Filter by log level (e.g. ERROR, WARN, INFO)","name":"level","in":"query"},{"schema":{"type":"string","description":"Filter logs containing this text"},"required":false,"description":"Filter logs containing this text","name":"search","in":"query"},{"schema":{"type":"number","nullable":true,"description":"Window start as epoch millis (default: now - 1h)"},"required":false,"description":"Window start as epoch millis (default: now - 1h)","name":"startTime","in":"query"},{"schema":{"type":"number","nullable":true,"description":"Window end as epoch millis (default: now)"},"required":false,"description":"Window end as epoch millis (default: now)","name":"endTime","in":"query"},{"schema":{"type":"string","enum":["asc","desc"],"description":"Sort order for results (default desc — newest first)"},"required":false,"description":"Sort order for results (default desc — newest first)","name":"sortOrder","in":"query"},{"schema":{"type":"string","description":"Log source filter (reserved for future phases)"},"required":false,"description":"Log source filter (reserved for future phases)","name":"source","in":"query"}],"responses":{"200":{"description":"App logs retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppLogsResponse"}}}},"403":{"description":"Permission denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/org-sandbox/url":{"get":{"summary":"Get the org sandbox root gateway URL","description":"Returns the gateway URL for the caller's org sandbox. The gateway proxies the full sandbox CLI server surface ({publicUrl}/health, /toolkits, /cli/*, etc.) with CORS enabled. The webapp authenticates to the gateway using its existing Bearer API-key (or `_sandbox_auth` cookie); the `_auth_token` flow is not used for the root gateway.","tags":["Org Sandbox"],"responses":{"200":{"description":"Gateway URL resolved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrgSandboxUrlResponse"}}}},"502":{"description":"Failed to resolve org sandbox","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/artifacts":{"get":{"summary":"List artifacts","description":"Get a list of all artifacts (both file and submission artifacts)","tags":["Artifacts"],"parameters":[{"schema":{"type":"integer","minimum":0,"exclusiveMinimum":true,"maximum":100,"default":50},"required":false,"name":"limit","in":"query"},{"schema":{"type":"integer","nullable":true,"minimum":0,"default":0},"required":false,"name":"offset","in":"query"},{"schema":{"type":"string","description":"If provided, only return artifacts for this chat session"},"required":false,"description":"If provided, only return artifacts for this chat session","name":"sessionId","in":"query"}],"responses":{"200":{"description":"List of artifacts","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ArtifactListResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/artifacts/ls":{"get":{"summary":"List artifacts (ls command)","description":"List artifacts with filesystem-like navigation, supporting path prefixes and filtering","tags":["Artifacts"],"parameters":[{"schema":{"type":"string","description":"Path prefix to list contents of (e.g., \"/vault/\")"},"required":false,"description":"Path prefix to list contents of (e.g., \"/vault/\")","name":"pathPrefix","in":"query"},{"schema":{"type":"string","description":"Direct parent artifact ID"},"required":false,"description":"Direct parent artifact ID","name":"parentId","in":"query"},{"schema":{"type":"string","enum":["personal","org","global","gitfs"],"description":"Vault to list. When parentId is provided, validates that the parent belongs to this vault"},"required":false,"description":"Vault to list. When parentId is provided, validates that the parent belongs to this vault","name":"vault","in":"query"},{"schema":{"type":"string","enum":["file","submission","table","folder","prompt","report"],"description":"Filter by artifact type"},"required":false,"description":"Filter by artifact type","name":"type","in":"query"},{"schema":{"type":"string","enum":["file","folder"],"description":"Filter by node kind"},"required":false,"description":"Filter by node kind","name":"nodeKind","in":"query"},{"schema":{"type":"string","description":"Pattern to match artifact names"},"required":false,"description":"Pattern to match artifact names","name":"namePattern","in":"query"},{"schema":{"type":"string","description":"Filter by stringFacet1 value"},"required":false,"description":"Filter by stringFacet1 value","name":"stringFacet1","in":"query"},{"schema":{"type":"string","description":"Filter by stringFacet2 value"},"required":false,"description":"Filter by stringFacet2 value","name":"stringFacet2","in":"query"},{"schema":{"type":"integer","minimum":0,"exclusiveMinimum":true,"maximum":100,"default":50},"required":false,"name":"limit","in":"query"},{"schema":{"type":"integer","nullable":true,"minimum":0,"default":0},"required":false,"name":"offset","in":"query"},{"schema":{"type":"string","description":"If true, return all results without pagination"},"required":false,"description":"If true, return all results without pagination","name":"fetch_all","in":"query"},{"schema":{"type":"string","description":"Include user-specific vault contents (default: true)"},"required":false,"description":"Include user-specific vault contents (default: true)","name":"include_local","in":"query"},{"schema":{"type":"string","description":"Include global/library vault contents (default: false)"},"required":false,"description":"Include global/library vault contents (default: false)","name":"include_global","in":"query"}],"responses":{"200":{"description":"List of artifacts at the specified path or root","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ArtifactLsResponse"}}}},"400":{"description":"Bad request - invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/artifacts/flatten":{"get":{"summary":"List flattened files under a folder","description":"Recursively lists file artifacts under a folder, flattened. No pagination, with a hard cap.","tags":["Artifacts"],"parameters":[{"schema":{"type":"string","description":"Folder artifact ID to flatten"},"required":true,"description":"Folder artifact ID to flatten","name":"parentId","in":"query"},{"schema":{"type":"integer","minimum":0,"exclusiveMinimum":true,"maximum":1000,"default":200,"description":"Hard cap on the number of items to return (default 200)"},"required":false,"description":"Hard cap on the number of items to return (default 200)","name":"maxItems","in":"query"},{"schema":{"type":"integer","minimum":0,"exclusiveMinimum":true,"maximum":1000,"description":"DEPRECATED: Use maxItems instead. Hard cap on items (default 200)"},"required":false,"description":"DEPRECATED: Use maxItems instead. Hard cap on items (default 200)","name":"maxFiles","in":"query"},{"schema":{"type":"integer","minimum":0,"exclusiveMinimum":true,"maximum":100,"default":25,"description":"Maximum recursion depth (default 25)"},"required":false,"description":"Maximum recursion depth (default 25)","name":"maxDepth","in":"query"},{"schema":{"type":"string","description":"Include folders in results (default: false, files only)"},"required":false,"description":"Include folders in results (default: false, files only)","name":"includeFolders","in":"query"},{"schema":{"type":"string","description":"Include signed URLs for download optimization (default: false)"},"required":false,"description":"Include signed URLs for download optimization (default: false)","name":"includeSignedUrls","in":"query"},{"schema":{"type":"string","description":"Include extracted-text signed URLs for indexed files (default: false)"},"required":false,"description":"Include extracted-text signed URLs for indexed files (default: false)","name":"includeExtractedTextUrls","in":"query"}],"responses":{"200":{"description":"Flattened list of artifacts","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ArtifactFlattenResponse"}}}},"400":{"description":"Bad request - invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/artifacts/files":{"post":{"summary":"Upload a file","description":"Upload a file to the artifact hierarchy","tags":["Artifacts"],"requestBody":{"description":"File upload data","content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"description":"File name"},"content":{"type":"string","description":"Base64-encoded file content"},"mimeType":{"type":"string","enum":["text/plain","text/markdown","text/csv","application/json","application/xml","text/xml","text/html","text/css","text/javascript","application/javascript","application/typescript","text/x-python","text/x-rsl","application/pdf","application/vnd.openxmlformats-officedocument.spreadsheetml.sheet","application/vnd.ms-excel","application/vnd.ms-excel.sheet.macroEnabled.12","application/vnd.openxmlformats-officedocument.spreadsheetml.sheet.macroEnabled.12","application/vnd.ms-excel.sheet.macroenabled.12","application/vnd.ms-excel.sheet.binary.macroEnabled.12","application/vnd.openxmlformats-officedocument.wordprocessingml.document","application/vnd.openxmlformats-officedocument.presentationml.presentation","application/vnd.ms-outlook","application/zip","application/x-tar","application/gzip","application/octet-stream","image/jpeg","image/png","image/gif","image/webp","image/svg+xml","audio/mpeg","audio/wav","audio/ogg","audio/mp4","audio/webm","video/mp4","video/webm","video/quicktime","video/x-msvideo","video/ogg"],"description":"MIME type of the file"},"parentId":{"type":"string","description":"Parent folder ID (optional - defaults to vault root)"},"vault":{"type":"string","enum":["personal","org","global","gitfs"],"description":"Vault to upload into when parentId is not provided"},"sessionId":{"type":"string","description":"Chat session ID — stores file under /{userId}/vault/sessions/{sessionId}"},"skipIndexing":{"type":"boolean","default":false,"description":"Skip indexing of the file"}},"required":["name","content"]}}}},"responses":{"201":{"description":"File uploaded successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Artifact"}}}},"400":{"description":"Bad request - invalid file data or parent must be a folder","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Parent folder not found (when parentId is specified)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"File name already exists in the specified folder","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/artifacts/{id}/content":{"patch":{"summary":"Update file content","description":"Overwrite the content of an existing file artifact while preserving its ID","tags":["Artifacts"],"parameters":[{"schema":{"type":"string","description":"Artifact ID to update"},"required":true,"description":"Artifact ID to update","name":"id","in":"path"}],"requestBody":{"description":"Updated content and options. For text files, use textContent (raw text). For binary files, use content (base64-encoded).","content":{"application/json":{"schema":{"type":"object","properties":{"content":{"type":"string","minLength":1,"description":"Base64-encoded file content (for binary files)"},"textContent":{"type":"string","description":"Raw text content (for text files like markdown, plain text, etc.)"},"skipIndexing":{"type":"boolean","description":"Skip indexing for this update"}}}}}},"responses":{"200":{"description":"Updated artifact","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Artifact"}}}},"400":{"description":"Bad request - invalid artifact type or content","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden - insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Artifact not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/artifacts/{id}/move":{"patch":{"summary":"Move artifact","description":"Move an artifact (file or folder) to a different parent folder","tags":["Artifacts"],"parameters":[{"schema":{"type":"string","description":"Artifact ID to move"},"required":true,"description":"Artifact ID to move","name":"id","in":"path"}],"requestBody":{"description":"Move operation data","content":{"application/json":{"schema":{"type":"object","properties":{"newParentId":{"type":"string","nullable":true,"description":"New parent folder ID (null for root, undefined to keep current)"},"targetPath":{"type":"string","description":"Target path to resolve to parent ID (e.g., \"/vault/folder1/subfolder\")"}}}}}},"responses":{"200":{"description":"Artifact moved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Artifact"}}}},"400":{"description":"Bad request - invalid move operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Artifact or target parent not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Name conflict or would create cycle","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/artifacts/{id}/rename":{"patch":{"summary":"Rename artifact","description":"Rename an artifact (file or folder) within its current parent folder","tags":["Artifacts"],"parameters":[{"schema":{"type":"string","description":"Artifact ID to rename"},"required":true,"description":"Artifact ID to rename","name":"id","in":"path"}],"requestBody":{"description":"Rename operation data","content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"description":"New artifact name"}},"required":["name"]}}}},"responses":{"200":{"description":"Artifact renamed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Artifact"}}}},"400":{"description":"Bad request - invalid rename operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden - insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Artifact not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Name conflict in the target folder","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/artifacts/{id}/sharing":{"patch":{"summary":"Update artifact sharing","description":"Update the list of users who can access this artifact. Any user with access can modify sharing. For session artifacts, this adds users beyond session-level access. For private artifacts, this grants access to specific users.","tags":["Artifacts"],"parameters":[{"schema":{"type":"string","description":"Artifact ID"},"required":true,"description":"Artifact ID","name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"visibleTo":{"type":"array","items":{"type":"string"},"description":"List of user IDs who should have access to this artifact"}},"required":["visibleTo"]}}}},"responses":{"200":{"description":"Sharing updated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Artifact"}}}},"400":{"description":"Invalid request (e.g., cannot modify sharing for org-wide artifacts)"},"403":{"description":"Forbidden — user does not have access to this artifact"},"404":{"description":"Artifact not found"}}}},"/api/v1/artifacts/{id}/public":{"patch":{"summary":"Toggle public access","description":"Make an artifact publicly accessible via a shareable link, or revoke public access. Returns the updated artifact with the public slug for URL construction.","tags":["Artifacts"],"parameters":[{"schema":{"type":"string","description":"Artifact ID"},"required":true,"description":"Artifact ID","name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"isPublic":{"type":"boolean","description":"Whether to make the artifact publicly accessible"}},"required":["isPublic"]}}}},"responses":{"200":{"description":"Public access updated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SetPublicAccessResponse"}}}},"400":{"description":"Invalid request (e.g., non-file artifact)"},"403":{"description":"Forbidden — user does not have access to this artifact"},"404":{"description":"Artifact not found"}}}},"/api/v1/artifacts/resolve-folder":{"get":{"summary":"Resolve folder path to ID","description":"Resolve a user-facing vault path to the folder artifact ID","tags":["Artifacts"],"parameters":[{"schema":{"type":"string","enum":["personal","org","global","gitfs"],"description":"Vault type (personal, org, or global)"},"required":false,"description":"Vault type (personal, org, or global)","name":"vault","in":"query"},{"schema":{"type":"string","description":"Folder path within the vault (e.g., \"documents/reports\")"},"required":true,"description":"Folder path within the vault (e.g., \"documents/reports\")","name":"path","in":"query"}],"responses":{"200":{"description":"Folder resolved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"Folder artifact ID"},"path":{"type":"string","description":"Full storage path"}},"required":["id","path"]}}}},"404":{"description":"Folder not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/artifacts/bookmarked":{"get":{"summary":"Get bookmarked artifacts","description":"Get all bookmarked artifacts for the current user","tags":["Artifacts"],"responses":{"200":{"description":"Map of bookmarked artifacts","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BookmarkedArtifactsResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/artifacts/{id}":{"get":{"summary":"Get artifact by ID","description":"Retrieve a specific artifact by ID (supports both file and submission artifacts)","tags":["Artifacts"],"parameters":[{"schema":{"type":"string","description":"Artifact ID"},"required":true,"description":"Artifact ID","name":"id","in":"path"},{"schema":{"type":"string","description":"If true, include a presigned URL to the extracted text, if available"},"required":false,"description":"If true, include a presigned URL to the extracted text, if available","name":"include_extracted_text","in":"query"}],"responses":{"200":{"description":"Artifact details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Artifact"}}}},"403":{"description":"Forbidden - insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Artifact not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"summary":"Delete artifact","description":"Delete an artifact (file or folder). Folders are deleted recursively with all contents.","tags":["Artifacts"],"parameters":[{"schema":{"type":"string","description":"Artifact ID to delete"},"required":true,"description":"Artifact ID to delete","name":"id","in":"path"}],"responses":{"200":{"description":"Artifact deleted successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"}},"required":["success","message"]}}}},"403":{"description":"Forbidden - insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Artifact not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/artifacts/folders":{"post":{"summary":"Create folder","description":"Create a new folder in the artifact hierarchy","tags":["Artifacts"],"requestBody":{"description":"Folder creation data","content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"description":"Folder name"},"parentId":{"type":"string","description":"Parent folder ID (optional, defaults to vault root)"},"vault":{"type":"string","enum":["personal","org","global","gitfs"],"description":"Vault scope for the folder (personal: user vault, org: organization vault, global: shared library)"}},"required":["name"]}}}},"responses":{"201":{"description":"Folder created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Artifact"}}}},"400":{"description":"Bad request - invalid folder name or parent ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Parent folder not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Folder name already exists in the specified location","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/artifacts/{id}/reindex":{"post":{"summary":"Reindex artifact","description":"Force reindexing of a file artifact. Schedules an indexing workflow.","tags":["Artifacts"],"parameters":[{"schema":{"type":"string","description":"Artifact ID to reindex"},"required":true,"description":"Artifact ID to reindex","name":"id","in":"path"}],"responses":{"202":{"description":"Reindex scheduled","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"}},"required":["success","message"]}}}},"400":{"description":"Bad request - invalid artifact type or unsupported file","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden - insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Artifact not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/artifacts/{id}/path":{"get":{"summary":"Get artifact path","description":"Get the full path of an artifact from the vault root","tags":["Artifacts"],"parameters":[{"schema":{"type":"string","description":"Artifact ID"},"required":true,"description":"Artifact ID","name":"id","in":"path"}],"responses":{"200":{"description":"Artifact path information","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"path":{"type":"string","description":"Full path from vault root"},"segments":{"type":"array","items":{"type":"string"},"description":"Path segments as array"}},"required":["id","path","segments"]}}}},"403":{"description":"Forbidden - insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Artifact not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/artifacts/save-to-cache":{"post":{"summary":"Save file to global cache","description":"Save a file directly to a global cache folder structure. Supports different cache types with type-specific folder structures.","tags":["Artifacts"],"requestBody":{"description":"Save to cache request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SaveToCacheRequest"}}}},"responses":{"200":{"description":"File saved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SaveToCacheResponse"}}}},"400":{"description":"Bad request - invalid cache name or missing required fields","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/artifacts/{id}/fingerprints":{"get":{"summary":"Get artifact fingerprints","description":"Get fingerprints for an artifact/version, optionally filtered by page numbers or page range","tags":["Artifacts"],"parameters":[{"schema":{"type":"string","description":"Artifact ID"},"required":true,"description":"Artifact ID","name":"id","in":"path"},{"schema":{"type":"integer","minimum":0,"exclusiveMinimum":true,"description":"Fingerprint version number"},"required":true,"description":"Fingerprint version number","name":"version","in":"query"},{"schema":{"type":"string","description":"Comma-separated page numbers (e.g., \"1,5,10\")"},"required":false,"description":"Comma-separated page numbers (e.g., \"1,5,10\")","name":"pageNumbers","in":"query"},{"schema":{"type":"string","description":"Page range (e.g., \"1-10\" for pages 1 to 10, inclusive)"},"required":false,"description":"Page range (e.g., \"1-10\" for pages 1 to 10, inclusive)","name":"pageRange","in":"query"}],"responses":{"200":{"description":"List of fingerprints","content":{"application/json":{"schema":{"type":"object","properties":{"fingerprints":{"type":"array","items":{"type":"object","properties":{"artifactId":{"type":"string"},"pageNumber":{"type":"number"},"version":{"type":"number"},"fingerprintJson":{"type":"object","additionalProperties":{"nullable":true}},"orgId":{"type":"string"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["artifactId","pageNumber","version","fingerprintJson","orgId","createdAt","updatedAt"]}}},"required":["fingerprints"]}}}},"404":{"description":"Artifact not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"put":{"summary":"Upsert artifact fingerprints","description":"Create or update fingerprints for an artifact/version","tags":["Artifacts"],"parameters":[{"schema":{"type":"string","description":"Artifact ID"},"required":true,"description":"Artifact ID","name":"id","in":"path"},{"schema":{"type":"integer","minimum":0,"exclusiveMinimum":true,"description":"Fingerprint version number"},"required":true,"description":"Fingerprint version number","name":"version","in":"query"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"fingerprints":{"type":"array","items":{"type":"object","properties":{"pageNumber":{"type":"integer","minimum":0,"exclusiveMinimum":true},"fingerprintJson":{"type":"object","additionalProperties":{"nullable":true}}},"required":["pageNumber","fingerprintJson"]},"minItems":1,"description":"Array of page fingerprints to upsert"}},"required":["fingerprints"]}}}},"responses":{"200":{"description":"Fingerprints upserted successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"count":{"type":"number"}},"required":["success","count"]}}}},"400":{"description":"Bad request - validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Artifact not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"summary":"Delete artifact fingerprints","description":"Delete fingerprints for an artifact. If version is provided, deletes only that version; otherwise deletes all versions.","tags":["Artifacts"],"parameters":[{"schema":{"type":"string","description":"Artifact ID"},"required":true,"description":"Artifact ID","name":"id","in":"path"},{"schema":{"type":"integer","minimum":0,"exclusiveMinimum":true,"description":"Fingerprint version number (optional - if omitted, deletes all versions)"},"required":false,"description":"Fingerprint version number (optional - if omitted, deletes all versions)","name":"version","in":"query"}],"responses":{"200":{"description":"Fingerprints deleted successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"deletedCount":{"type":"number"}},"required":["success","deletedCount"]}}}},"404":{"description":"Artifact not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/artifacts/prepare-file-tree":{"post":{"summary":"Prepare file tree upload","description":"Create folder structure and generate pre-signed URLs for all files in a file tree","tags":["Artifacts"],"requestBody":{"description":"File tree structure","content":{"application/json":{"schema":{"type":"object","properties":{"nodes":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["file","folder"]},"name":{"type":"string","minLength":1},"path":{"type":"string","minLength":1},"parentPath":{"type":"string"},"size":{"type":"number"},"mimeType":{"type":"string","enum":["text/plain","text/markdown","text/csv","application/json","application/xml","text/xml","text/html","text/css","text/javascript","application/javascript","application/typescript","text/x-python","text/x-rsl","application/pdf","application/vnd.openxmlformats-officedocument.spreadsheetml.sheet","application/vnd.ms-excel","application/vnd.ms-excel.sheet.macroEnabled.12","application/vnd.openxmlformats-officedocument.spreadsheetml.sheet.macroEnabled.12","application/vnd.ms-excel.sheet.macroenabled.12","application/vnd.ms-excel.sheet.binary.macroEnabled.12","application/vnd.openxmlformats-officedocument.wordprocessingml.document","application/vnd.openxmlformats-officedocument.presentationml.presentation","application/vnd.ms-outlook","application/zip","application/x-tar","application/gzip","application/octet-stream","image/jpeg","image/png","image/gif","image/webp","image/svg+xml","audio/mpeg","audio/wav","audio/ogg","audio/mp4","audio/webm","video/mp4","video/webm","video/quicktime","video/x-msvideo","video/ogg"]}},"required":["type","name","path"]}},"parentId":{"type":"string"},"vault":{"type":"string","enum":["personal","org","global","gitfs"],"description":"Vault to upload into (default: personal)"},"isGlobalVault":{"type":"boolean","description":"DEPRECATED: Use vault parameter instead"}},"required":["nodes"]}}}},"responses":{"200":{"description":"File tree prepared successfully","content":{"application/json":{"schema":{"type":"object","properties":{"folderMap":{"type":"object","additionalProperties":{"type":"string"}},"uploadUrls":{"type":"object","additionalProperties":{"type":"object","properties":{"path":{"type":"string"},"uploadUrl":{"type":"string"},"artifactId":{"type":"string"},"headers":{"type":"object","additionalProperties":{"type":"string"}},"expiresAt":{"type":"string"}},"required":["path","uploadUrl","artifactId","expiresAt"]}}},"required":["folderMap","uploadUrls"]}}}},"400":{"description":"Bad request - invalid file tree","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/api/v1/artifacts/confirm-bulk-upload":{"post":{"summary":"Confirm bulk upload","description":"Confirm that multiple direct uploads have completed and create artifact records","tags":["Artifacts"],"requestBody":{"description":"Bulk upload confirmation","content":{"application/json":{"schema":{"type":"object","properties":{"uploads":{"type":"array","items":{"type":"object","properties":{"artifactId":{"type":"string"},"path":{"type":"string"},"fileName":{"type":"string"},"fileSize":{"type":"number"},"mimeType":{"type":"string","enum":["text/plain","text/markdown","text/csv","application/json","application/xml","text/xml","text/html","text/css","text/javascript","application/javascript","application/typescript","text/x-python","text/x-rsl","application/pdf","application/vnd.openxmlformats-officedocument.spreadsheetml.sheet","application/vnd.ms-excel","application/vnd.ms-excel.sheet.macroEnabled.12","application/vnd.openxmlformats-officedocument.spreadsheetml.sheet.macroEnabled.12","application/vnd.ms-excel.sheet.macroenabled.12","application/vnd.ms-excel.sheet.binary.macroEnabled.12","application/vnd.openxmlformats-officedocument.wordprocessingml.document","application/vnd.openxmlformats-officedocument.presentationml.presentation","application/vnd.ms-outlook","application/zip","application/x-tar","application/gzip","application/octet-stream","image/jpeg","image/png","image/gif","image/webp","image/svg+xml","audio/mpeg","audio/wav","audio/ogg","audio/mp4","audio/webm","video/mp4","video/webm","video/quicktime","video/x-msvideo","video/ogg"]}},"required":["artifactId","path","fileName","fileSize"]}},"folderMap":{"type":"object","additionalProperties":{"type":"string"}},"parentId":{"type":"string","description":"Parent folder ID for single file uploads"},"skipIndexing":{"type":"boolean","default":false,"description":"If true, do not schedule indexing"},"vault":{"type":"string","enum":["personal","org","global","gitfs"],"description":"Vault to upload into (default: personal)"},"isGlobalVault":{"type":"boolean","description":"DEPRECATED: Use vault parameter instead"}},"required":["uploads"]}}}},"responses":{"200":{"description":"Bulk upload confirmed","content":{"application/json":{"schema":{"type":"object","properties":{"successful":{"type":"array","items":{"type":"string"}},"failed":{"type":"array","items":{"type":"object","properties":{"artifactId":{"type":"string"},"error":{"type":"string"}},"required":["artifactId","error"]}},"workflows":{"type":"array","items":{"type":"object","properties":{"artifactId":{"type":"string"},"workflowId":{"type":"string"}},"required":["artifactId","workflowId"]}}},"required":["successful","failed"]}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/api/v1/reports":{"post":{"tags":["Reports"],"summary":"Create a new report or assign an existing artifact as a report","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateReportBody"}}}},"responses":{"201":{"description":"Report created or assigned","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Artifact"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReportError"}}}},"404":{"description":"Artifact not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReportError"}}}}}},"get":{"tags":["Reports"],"summary":"List reports for a Mission Control instance","parameters":[{"schema":{"type":"string","minLength":1,"description":"Mission Control instance ID"},"required":true,"description":"Mission Control instance ID","name":"missionControlId","in":"query"},{"schema":{"type":"string","description":"Filter by report category"},"required":false,"description":"Filter by report category","name":"category","in":"query"},{"schema":{"type":"integer","minimum":0,"exclusiveMinimum":true,"maximum":100,"default":50},"required":false,"name":"limit","in":"query"},{"schema":{"type":"integer","nullable":true,"minimum":0,"default":0},"required":false,"name":"offset","in":"query"}],"responses":{"200":{"description":"List of reports","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReportListResponse"}}}}}}},"/api/v1/reports/{id}":{"delete":{"tags":["Reports"],"summary":"Unassign a report (reverts to file, does not delete the artifact)","parameters":[{"schema":{"type":"string","format":"uuid","description":"Report artifact ID"},"required":true,"description":"Report artifact ID","name":"id","in":"path"}],"responses":{"204":{"description":"Report unassigned"},"404":{"description":"Report not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReportError"}}}}}}},"/api/v1/files/{id}/content":{"get":{"summary":"Get file content","description":"Get the raw content of a specific file by ID. Optionally specify versionId to get content of a specific version.","tags":["Files"],"parameters":[{"schema":{"type":"string","description":"File ID"},"required":true,"description":"File ID","name":"id","in":"path"},{"schema":{"type":"string","description":"Version ID to get content of a specific version"},"required":false,"description":"Version ID to get content of a specific version","name":"versionId","in":"query"}],"responses":{"200":{"description":"File content","content":{"text/plain":{"schema":{"type":"string"}},"application/octet-stream":{"schema":{"type":"string"}}}},"404":{"description":"File not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/files/{id}/signed-url":{"get":{"summary":"Generate signed URL","description":"Generate a signed URL for secure file access (supports global vault files via local/global lookup). Optionally specify versionId to get signed URL for a specific version.","tags":["Files"],"parameters":[{"schema":{"type":"string","description":"File ID"},"required":true,"description":"File ID","name":"id","in":"path"},{"schema":{"type":"string","description":"Version ID to get signed URL for a specific version"},"required":false,"description":"Version ID to get signed URL for a specific version","name":"versionId","in":"query"}],"responses":{"200":{"description":"Signed URL generated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SignedUrlResponse"}}}},"404":{"description":"File not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/serff/list":{"post":{"summary":"List SERFF filings","description":"Get a paginated list of SERFF filing records with filtering, sorting, and full-text search","tags":["SERFF"],"requestBody":{"description":"Options for listing SERFF filings","content":{"application/json":{"schema":{"type":"object","properties":{"limit":{"type":"number","minimum":1,"maximum":1200,"default":50},"offset":{"type":"number","nullable":true,"minimum":0,"default":0},"sort_columns":{"type":"array","items":{"type":"object","properties":{"column":{"type":"string","enum":["id","org_id","artifact_id","primary_pdf_artifact_id","filing_summary_artifact_id","state","company_name","naic_group_code","business_type","insurance_product_name","type_of_insurance","sub_type_of_insurance","filing_type","filing_status","state_status","disposition_status","serff_tracking_number","submission_date","disposition_date","state_status_last_change_date","page_count","created_at","updated_at","normalized_outcome","regime_expected","regime_observed","outcome_favorable","filing_type_normalized","filing_type_variant"]},"direction":{"type":"string","enum":["asc","desc"]}},"required":["column","direction"]},"default":[{"column":"submission_date","direction":"desc"}]},"filters":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"fieldId":{"type":"string"},"operator":{"type":"string","enum":["eq"]},"value":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"}]}},"required":["fieldId","operator","value"]},{"type":"object","properties":{"fieldId":{"type":"string"},"operator":{"type":"string","enum":["neq"]},"value":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"}]}},"required":["fieldId","operator","value"]},{"type":"object","properties":{"fieldId":{"type":"string"},"operator":{"type":"string","enum":["gt"]},"startValue":{"anyOf":[{"type":"number"},{"type":"string"}]}},"required":["fieldId","operator","startValue"]},{"type":"object","properties":{"fieldId":{"type":"string"},"operator":{"type":"string","enum":["gte"]},"startValue":{"anyOf":[{"type":"number"},{"type":"string"}]}},"required":["fieldId","operator","startValue"]},{"type":"object","properties":{"fieldId":{"type":"string"},"operator":{"type":"string","enum":["lt"]},"endValue":{"anyOf":[{"type":"number"},{"type":"string"}]}},"required":["fieldId","operator","endValue"]},{"type":"object","properties":{"fieldId":{"type":"string"},"operator":{"type":"string","enum":["lte"]},"endValue":{"anyOf":[{"type":"number"},{"type":"string"}]}},"required":["fieldId","operator","endValue"]},{"type":"object","properties":{"fieldId":{"type":"string"},"operator":{"type":"string","enum":["contains"]},"value":{"type":"string"}},"required":["fieldId","operator","value"]},{"type":"object","properties":{"fieldId":{"type":"string"},"operator":{"type":"string","enum":["between"]},"startValue":{"anyOf":[{"type":"number"},{"type":"string"}]},"endValue":{"anyOf":[{"type":"number"},{"type":"string"}]}},"required":["fieldId","operator","startValue","endValue"]},{"type":"object","properties":{"fieldId":{"type":"string"},"operator":{"type":"string","enum":["in"]},"values":{"type":"array","items":{"type":"string"}}},"required":["fieldId","operator","values"]},{"type":"object","properties":{"fieldId":{"type":"string"},"operator":{"type":"string","enum":["containsAny"]},"values":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}}},"required":["fieldId","operator","values"]},{"type":"object","properties":{"fieldId":{"type":"string"},"operator":{"type":"string","enum":["notContainsAny"]},"values":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}}},"required":["fieldId","operator","values"]},{"type":"object","properties":{"fieldId":{"type":"string"},"operator":{"type":"string","enum":["containsPhrase"]},"value":{"type":"string"}},"required":["fieldId","operator","value"]}]}},"search":{"type":"string"},"cursor_token":{"type":"string"},"search_text_fetch_mode":{"type":"string","enum":["docReader","fromTurbo","none"],"description":"Override the text fetch strategy used when performing full-text search (requires smaller top_k)"},"include_extraction_metadata":{"type":"boolean","default":false,"description":"If true, include extraction_metadata_json in the response records. Default is false to reduce response size."},"data_scope":{"type":"string","enum":["recent","historical","all"],"default":"recent","description":"Controls which shards to query: recent (2018+, default), historical (≤2017), or all"},"fts_version":{"type":"string","enum":["v1","v2"],"description":"Controls which FTS namespace version to query: v2 (word_v3 tokenizer, default) or v1 (word_v4 tokenizer, legacy)"}},"description":"Options for listing SERFF filings via API"}}}},"responses":{"200":{"description":"SERFF filing info records","content":{"application/json":{"schema":{"type":"object","properties":{"records":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"org_id":{"type":"string"},"artifact_id":{"type":"string","nullable":true},"primary_pdf_artifact_id":{"type":"string","nullable":true},"filing_summary_artifact_id":{"type":"string","nullable":true},"is_table_row":{"type":"boolean","nullable":true},"table_name":{"type":"string","nullable":true},"artifact_type":{"type":"string","nullable":true},"is_primary_doc":{"type":"boolean","nullable":true},"is_attachment":{"type":"boolean","nullable":true},"is_rate_rule_attachment":{"type":"boolean","nullable":true},"is_form_attachment":{"type":"boolean","nullable":true},"is_supporting_doc_attachment":{"type":"boolean","nullable":true},"is_correspondence_attachment":{"type":"boolean","nullable":true},"file_extension":{"type":"string","nullable":true},"state":{"type":"string"},"company_name":{"type":"string"},"naic_group_code":{"type":"number","nullable":true},"naic_company_codes":{"type":"array","nullable":true,"items":{"type":"number"}},"business_type":{"type":"string","nullable":true},"insurance_product_name":{"type":"string","nullable":true},"type_of_insurance":{"type":"string","nullable":true},"sub_type_of_insurance":{"type":"string","nullable":true},"filing_type":{"type":"string","nullable":true},"filing_status":{"type":"string","nullable":true},"serff_tracking_number":{"type":"string","minLength":1},"submission_date":{"type":"string","nullable":true},"disposition_date":{"type":"string","nullable":true},"state_status_last_change_date":{"type":"string","nullable":true},"disposition_status":{"type":"string","nullable":true},"state_status":{"type":"string","nullable":true},"page_count":{"type":"number","nullable":true},"tags":{"type":"array","nullable":true,"items":{"type":"string"}},"extraction_metadata_json":{"type":"object","nullable":true,"additionalProperties":{"nullable":true},"description":"Structured metadata extracted from SERFF PDF filing"},"normalized_outcome":{"type":"string","nullable":true},"regime_expected":{"type":"string","nullable":true},"regime_observed":{"type":"string","nullable":true},"outcome_favorable":{"type":"string","nullable":true},"is_closed":{"type":"string","nullable":true},"maybe_withdrawal":{"type":"boolean","nullable":true},"filing_type_normalized":{"type":"string","nullable":true},"filing_type_variant":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","org_id","artifact_id","primary_pdf_artifact_id","filing_summary_artifact_id","state","company_name","business_type","insurance_product_name","type_of_insurance","sub_type_of_insurance","filing_type","filing_status","serff_tracking_number","submission_date","disposition_date","state_status_last_change_date","page_count","created_at","updated_at"],"description":"A SERFF filing record"}},"total":{"type":"number"},"hasMore":{"type":"boolean"},"next_cursor":{"anyOf":[{"type":"number"},{"type":"string"},{"nullable":true}]},"matches":{"type":"array","items":{"type":"object","properties":{"filingId":{"type":"string","description":"SERFF filing ID"},"artifactId":{"type":"string","description":"File artifact ID containing the matches"},"artifactName":{"type":"string","description":"File name"},"artifactType":{"type":"string","description":"File type"},"hitCount":{"type":"number","description":"Total number of matching chunks in this file"},"topScore":{"type":"number","description":"Best passage score for ranking"},"passages":{"type":"array","items":{"type":"object","properties":{"text":{"type":"string","description":"Snippet text"},"score":{"type":"number","description":"Relevance score for this passage"},"location":{"type":"object","properties":{"page":{"type":"number","description":"Primary page number"},"pageStart":{"type":"number","description":"First page of this passage"},"pageEnd":{"type":"number","description":"Last page of this passage"},"charStart":{"type":"number","description":"Character offset in combined text"},"charEnd":{"type":"number","description":"Character offset in combined text"},"chunkIndex":{"type":"number","description":"Index of the chunk"}},"description":"Where this passage is in the document"},"highlights":{"type":"array","items":{"type":"object","properties":{"start":{"type":"number","description":"Character offset where highlight begins"},"end":{"type":"number","description":"Character offset where highlight ends"}},"required":["start","end"]},"description":"Highlighted query term offsets"}},"required":["text","location"]},"description":"Top passages from this file"}},"required":["filingId","artifactId","hitCount","topScore","passages"]},"description":"Grouped passages when search is active"}},"required":["records"],"description":"Response for listing SERFF filings"}}}},"400":{"description":"Bad request - invalid query parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/serff/forms/list":{"post":{"summary":"List SERFF forms","description":"Get a paginated list of SERFF form records backed by the serff_forms table with filtering and search","tags":["SERFF"],"requestBody":{"description":"Options for listing SERFF forms","content":{"application/json":{"schema":{"type":"object","properties":{"limit":{"type":"number","minimum":1,"maximum":200,"default":50},"offset":{"type":"number","nullable":true,"minimum":0,"default":0},"sort_columns":{"type":"array","items":{"type":"object","properties":{"column":{"type":"string","enum":["id","org_id","serff_tracking_number","state","company_name","type_of_insurance","sub_type_of_insurance","form_pdf_artifact_id","form_number","form_name","edition_date","form_type","form_type_normalized","form_action","previous_filing_number","replaced_form_number","replaced_edition_date","created_at"]},"direction":{"type":"string","enum":["asc","desc"]}},"required":["column","direction"]},"default":[{"column":"created_at","direction":"desc"}]},"filters":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"fieldId":{"type":"string"},"operator":{"type":"string","enum":["eq"]},"value":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"}]}},"required":["fieldId","operator","value"]},{"type":"object","properties":{"fieldId":{"type":"string"},"operator":{"type":"string","enum":["neq"]},"value":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"}]}},"required":["fieldId","operator","value"]},{"type":"object","properties":{"fieldId":{"type":"string"},"operator":{"type":"string","enum":["gt"]},"startValue":{"anyOf":[{"type":"number"},{"type":"string"}]}},"required":["fieldId","operator","startValue"]},{"type":"object","properties":{"fieldId":{"type":"string"},"operator":{"type":"string","enum":["gte"]},"startValue":{"anyOf":[{"type":"number"},{"type":"string"}]}},"required":["fieldId","operator","startValue"]},{"type":"object","properties":{"fieldId":{"type":"string"},"operator":{"type":"string","enum":["lt"]},"endValue":{"anyOf":[{"type":"number"},{"type":"string"}]}},"required":["fieldId","operator","endValue"]},{"type":"object","properties":{"fieldId":{"type":"string"},"operator":{"type":"string","enum":["lte"]},"endValue":{"anyOf":[{"type":"number"},{"type":"string"}]}},"required":["fieldId","operator","endValue"]},{"type":"object","properties":{"fieldId":{"type":"string"},"operator":{"type":"string","enum":["contains"]},"value":{"type":"string"}},"required":["fieldId","operator","value"]},{"type":"object","properties":{"fieldId":{"type":"string"},"operator":{"type":"string","enum":["between"]},"startValue":{"anyOf":[{"type":"number"},{"type":"string"}]},"endValue":{"anyOf":[{"type":"number"},{"type":"string"}]}},"required":["fieldId","operator","startValue","endValue"]},{"type":"object","properties":{"fieldId":{"type":"string"},"operator":{"type":"string","enum":["in"]},"values":{"type":"array","items":{"type":"string"}}},"required":["fieldId","operator","values"]},{"type":"object","properties":{"fieldId":{"type":"string"},"operator":{"type":"string","enum":["containsAny"]},"values":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}}},"required":["fieldId","operator","values"]},{"type":"object","properties":{"fieldId":{"type":"string"},"operator":{"type":"string","enum":["notContainsAny"]},"values":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}}},"required":["fieldId","operator","values"]},{"type":"object","properties":{"fieldId":{"type":"string"},"operator":{"type":"string","enum":["containsPhrase"]},"value":{"type":"string"}},"required":["fieldId","operator","value"]}]}},"search":{"type":"string","minLength":1,"description":"Optional search string matched against form number, name, and tracking number"}},"description":"Options for listing SERFF forms via API"}}}},"responses":{"200":{"description":"SERFF form records","content":{"application/json":{"schema":{"type":"object","properties":{"records":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"org_id":{"type":"string"},"serff_tracking_number":{"type":"string"},"state":{"type":"string","nullable":true},"company_name":{"type":"string","nullable":true},"naic_company_codes":{"type":"array","nullable":true,"items":{"type":"number"}},"type_of_insurance":{"type":"string","nullable":true},"sub_type_of_insurance":{"type":"string","nullable":true},"form_pdf_artifact_id":{"type":"string","nullable":true},"form_number":{"type":"string","nullable":true},"form_name":{"type":"string","nullable":true},"edition_date":{"type":"string","nullable":true},"form_type":{"type":"string","nullable":true},"form_type_normalized":{"type":"string","nullable":true},"topic_tags":{"type":"array","nullable":true,"items":{"type":"string"}},"form_action":{"type":"string","nullable":true},"previous_filing_number":{"type":"string","nullable":true},"replaced_form_number":{"type":"string","nullable":true},"replaced_edition_date":{"type":"string","nullable":true},"applicable_states":{"type":"array","nullable":true,"items":{"type":"string"}},"created_at":{"type":"string"}},"required":["id","org_id","serff_tracking_number","state","company_name","type_of_insurance","sub_type_of_insurance","form_pdf_artifact_id","form_number","form_name","edition_date","form_type","form_type_normalized","form_action","previous_filing_number","replaced_form_number","replaced_edition_date","created_at"]}},"total":{"type":"number"},"hasMore":{"type":"boolean"},"next_cursor":{"anyOf":[{"type":"number"},{"type":"string"},{"nullable":true}]}},"required":["records"]}}}},"400":{"description":"Bad request - invalid query parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/serff/objections/list":{"post":{"summary":"List SERFF objections","description":"Get a paginated list of SERFF objection records with filtering and search","tags":["SERFF"],"requestBody":{"description":"Options for listing SERFF objections","content":{"application/json":{"schema":{"type":"object","properties":{"limit":{"type":"number","minimum":1,"maximum":200,"default":50},"offset":{"type":"number","nullable":true,"minimum":0,"default":0},"sort_columns":{"type":"array","items":{"type":"object","properties":{"column":{"type":"string","enum":["id","org_id","serff_tracking_number","reviewer_name","objection_date","response_date","objection_tags","correspondence_type","created_at"]},"direction":{"type":"string","enum":["asc","desc"]}},"required":["column","direction"]},"default":[{"column":"objection_date","direction":"desc"}]},"filters":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"fieldId":{"type":"string"},"operator":{"type":"string","enum":["eq"]},"value":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"}]}},"required":["fieldId","operator","value"]},{"type":"object","properties":{"fieldId":{"type":"string"},"operator":{"type":"string","enum":["neq"]},"value":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"}]}},"required":["fieldId","operator","value"]},{"type":"object","properties":{"fieldId":{"type":"string"},"operator":{"type":"string","enum":["gt"]},"startValue":{"anyOf":[{"type":"number"},{"type":"string"}]}},"required":["fieldId","operator","startValue"]},{"type":"object","properties":{"fieldId":{"type":"string"},"operator":{"type":"string","enum":["gte"]},"startValue":{"anyOf":[{"type":"number"},{"type":"string"}]}},"required":["fieldId","operator","startValue"]},{"type":"object","properties":{"fieldId":{"type":"string"},"operator":{"type":"string","enum":["lt"]},"endValue":{"anyOf":[{"type":"number"},{"type":"string"}]}},"required":["fieldId","operator","endValue"]},{"type":"object","properties":{"fieldId":{"type":"string"},"operator":{"type":"string","enum":["lte"]},"endValue":{"anyOf":[{"type":"number"},{"type":"string"}]}},"required":["fieldId","operator","endValue"]},{"type":"object","properties":{"fieldId":{"type":"string"},"operator":{"type":"string","enum":["contains"]},"value":{"type":"string"}},"required":["fieldId","operator","value"]},{"type":"object","properties":{"fieldId":{"type":"string"},"operator":{"type":"string","enum":["between"]},"startValue":{"anyOf":[{"type":"number"},{"type":"string"}]},"endValue":{"anyOf":[{"type":"number"},{"type":"string"}]}},"required":["fieldId","operator","startValue","endValue"]},{"type":"object","properties":{"fieldId":{"type":"string"},"operator":{"type":"string","enum":["in"]},"values":{"type":"array","items":{"type":"string"}}},"required":["fieldId","operator","values"]},{"type":"object","properties":{"fieldId":{"type":"string"},"operator":{"type":"string","enum":["containsAny"]},"values":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}}},"required":["fieldId","operator","values"]},{"type":"object","properties":{"fieldId":{"type":"string"},"operator":{"type":"string","enum":["notContainsAny"]},"values":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}}},"required":["fieldId","operator","values"]},{"type":"object","properties":{"fieldId":{"type":"string"},"operator":{"type":"string","enum":["containsPhrase"]},"value":{"type":"string"}},"required":["fieldId","operator","value"]}]}},"search":{"type":"string","minLength":1,"description":"Optional search string matched against tracking number, reviewer name, and tags"}},"description":"Options for listing SERFF objections via API"}}}},"responses":{"200":{"description":"SERFF objection records","content":{"application/json":{"schema":{"type":"object","properties":{"records":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"org_id":{"type":"string"},"serff_tracking_number":{"type":"string"},"reviewer_id":{"type":"string","nullable":true},"reviewer_name":{"type":"string","nullable":true},"objection_date":{"type":"string","nullable":true},"response_date":{"type":"string","nullable":true},"objection_tags":{"type":"string","nullable":true},"correspondence_type":{"type":"string","nullable":true},"created_at":{"type":"string"}},"required":["id","org_id","serff_tracking_number","reviewer_id","reviewer_name","objection_date","response_date","objection_tags","correspondence_type","created_at"]}},"total":{"type":"number"},"hasMore":{"type":"boolean"},"next_cursor":{"anyOf":[{"type":"number"},{"type":"string"},{"nullable":true}]}},"required":["records"]}}}},"400":{"description":"Bad request - invalid query parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/serff/objection-catalog/list":{"post":{"summary":"List SERFF objection catalog","description":"Get a paginated list of SERFF objection classification rules with filtering and search","tags":["SERFF"],"requestBody":{"description":"Options for listing SERFF objection catalog","content":{"application/json":{"schema":{"type":"object","properties":{"limit":{"type":"number","minimum":1,"maximum":200,"default":50},"offset":{"type":"number","nullable":true,"minimum":0,"default":0},"sort_columns":{"type":"array","items":{"type":"object","properties":{"column":{"type":"string","enum":["id","org_id","rule_id","rule_description","when_applied","specificity","tag","subtag","state","toi","frequency","created_at","updated_at"]},"direction":{"type":"string","enum":["asc","desc"]}},"required":["column","direction"]},"default":[{"column":"frequency","direction":"desc"}]},"filters":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"fieldId":{"type":"string"},"operator":{"type":"string","enum":["eq"]},"value":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"}]}},"required":["fieldId","operator","value"]},{"type":"object","properties":{"fieldId":{"type":"string"},"operator":{"type":"string","enum":["neq"]},"value":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"}]}},"required":["fieldId","operator","value"]},{"type":"object","properties":{"fieldId":{"type":"string"},"operator":{"type":"string","enum":["gt"]},"startValue":{"anyOf":[{"type":"number"},{"type":"string"}]}},"required":["fieldId","operator","startValue"]},{"type":"object","properties":{"fieldId":{"type":"string"},"operator":{"type":"string","enum":["gte"]},"startValue":{"anyOf":[{"type":"number"},{"type":"string"}]}},"required":["fieldId","operator","startValue"]},{"type":"object","properties":{"fieldId":{"type":"string"},"operator":{"type":"string","enum":["lt"]},"endValue":{"anyOf":[{"type":"number"},{"type":"string"}]}},"required":["fieldId","operator","endValue"]},{"type":"object","properties":{"fieldId":{"type":"string"},"operator":{"type":"string","enum":["lte"]},"endValue":{"anyOf":[{"type":"number"},{"type":"string"}]}},"required":["fieldId","operator","endValue"]},{"type":"object","properties":{"fieldId":{"type":"string"},"operator":{"type":"string","enum":["contains"]},"value":{"type":"string"}},"required":["fieldId","operator","value"]},{"type":"object","properties":{"fieldId":{"type":"string"},"operator":{"type":"string","enum":["between"]},"startValue":{"anyOf":[{"type":"number"},{"type":"string"}]},"endValue":{"anyOf":[{"type":"number"},{"type":"string"}]}},"required":["fieldId","operator","startValue","endValue"]},{"type":"object","properties":{"fieldId":{"type":"string"},"operator":{"type":"string","enum":["in"]},"values":{"type":"array","items":{"type":"string"}}},"required":["fieldId","operator","values"]},{"type":"object","properties":{"fieldId":{"type":"string"},"operator":{"type":"string","enum":["containsAny"]},"values":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}}},"required":["fieldId","operator","values"]},{"type":"object","properties":{"fieldId":{"type":"string"},"operator":{"type":"string","enum":["notContainsAny"]},"values":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}}},"required":["fieldId","operator","values"]},{"type":"object","properties":{"fieldId":{"type":"string"},"operator":{"type":"string","enum":["containsPhrase"]},"value":{"type":"string"}},"required":["fieldId","operator","value"]}]}},"search":{"type":"string","minLength":1,"description":"Optional search string matched against rule_id, rule_description, and when_applied"}},"description":"Options for listing SERFF objection catalog via API"}}}},"responses":{"200":{"description":"SERFF objection catalog records","content":{"application/json":{"schema":{"type":"object","properties":{"records":{"type":"array","items":{"type":"object","properties":{"id":{"type":"number"},"org_id":{"type":"string"},"rule_id":{"type":"string"},"rule_description":{"type":"string"},"when_applied":{"type":"string"},"specificity":{"type":"string"},"tag":{"type":"string"},"subtag":{"type":"string","nullable":true},"state":{"type":"string","nullable":true},"toi":{"type":"string","nullable":true},"statute_refs":{"type":"array","nullable":true,"items":{"type":"string"}},"form_refs":{"type":"array","nullable":true,"items":{"type":"string"}},"objection_codes":{"type":"array","nullable":true,"items":{"type":"string"}},"frequency":{"type":"number"},"sample_tracking_numbers":{"type":"array","nullable":true,"items":{"type":"string"}},"sample_text":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","org_id","rule_id","rule_description","when_applied","specificity","tag","subtag","state","toi","frequency","sample_text","created_at","updated_at"]}},"total":{"type":"number"},"hasMore":{"type":"boolean"},"next_cursor":{"anyOf":[{"type":"number"},{"type":"string"},{"nullable":true}]}},"required":["records"]}}}},"400":{"description":"Bad request - invalid query parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/serff/rate-impact/list":{"post":{"summary":"List SERFF rate impact","description":"Get a paginated list of SERFF rate impact records with filtering and search","tags":["SERFF"],"requestBody":{"description":"Options for listing SERFF rate impact","content":{"application/json":{"schema":{"type":"object","properties":{"limit":{"type":"number","minimum":1,"maximum":200,"default":50},"offset":{"type":"number","nullable":true,"minimum":0,"default":0},"sort_columns":{"type":"array","items":{"type":"object","properties":{"column":{"type":"string","enum":["id","serff_tracking_number","overall_indicated_change","overall_rate_impact","written_premium_change","num_policyholders_affected","written_premium","max_change","min_change","created_at","updated_at"]},"direction":{"type":"string","enum":["asc","desc"]}},"required":["column","direction"]},"default":[{"column":"overall_rate_impact","direction":"desc"}]},"filters":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"fieldId":{"type":"string"},"operator":{"type":"string","enum":["eq"]},"value":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"}]}},"required":["fieldId","operator","value"]},{"type":"object","properties":{"fieldId":{"type":"string"},"operator":{"type":"string","enum":["neq"]},"value":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"}]}},"required":["fieldId","operator","value"]},{"type":"object","properties":{"fieldId":{"type":"string"},"operator":{"type":"string","enum":["gt"]},"startValue":{"anyOf":[{"type":"number"},{"type":"string"}]}},"required":["fieldId","operator","startValue"]},{"type":"object","properties":{"fieldId":{"type":"string"},"operator":{"type":"string","enum":["gte"]},"startValue":{"anyOf":[{"type":"number"},{"type":"string"}]}},"required":["fieldId","operator","startValue"]},{"type":"object","properties":{"fieldId":{"type":"string"},"operator":{"type":"string","enum":["lt"]},"endValue":{"anyOf":[{"type":"number"},{"type":"string"}]}},"required":["fieldId","operator","endValue"]},{"type":"object","properties":{"fieldId":{"type":"string"},"operator":{"type":"string","enum":["lte"]},"endValue":{"anyOf":[{"type":"number"},{"type":"string"}]}},"required":["fieldId","operator","endValue"]},{"type":"object","properties":{"fieldId":{"type":"string"},"operator":{"type":"string","enum":["contains"]},"value":{"type":"string"}},"required":["fieldId","operator","value"]},{"type":"object","properties":{"fieldId":{"type":"string"},"operator":{"type":"string","enum":["between"]},"startValue":{"anyOf":[{"type":"number"},{"type":"string"}]},"endValue":{"anyOf":[{"type":"number"},{"type":"string"}]}},"required":["fieldId","operator","startValue","endValue"]},{"type":"object","properties":{"fieldId":{"type":"string"},"operator":{"type":"string","enum":["in"]},"values":{"type":"array","items":{"type":"string"}}},"required":["fieldId","operator","values"]},{"type":"object","properties":{"fieldId":{"type":"string"},"operator":{"type":"string","enum":["containsAny"]},"values":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}}},"required":["fieldId","operator","values"]},{"type":"object","properties":{"fieldId":{"type":"string"},"operator":{"type":"string","enum":["notContainsAny"]},"values":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}}},"required":["fieldId","operator","values"]},{"type":"object","properties":{"fieldId":{"type":"string"},"operator":{"type":"string","enum":["containsPhrase"]},"value":{"type":"string"}},"required":["fieldId","operator","value"]}]}},"search":{"type":"string","minLength":1,"description":"Optional search string matched against serff_tracking_number"}},"description":"Options for listing SERFF rate impact via API"}}}},"responses":{"200":{"description":"SERFF rate impact records","content":{"application/json":{"schema":{"type":"object","properties":{"records":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"serff_tracking_number":{"type":"string"},"org_id":{"type":"string"},"overall_indicated_change":{"type":"number","nullable":true},"overall_rate_impact":{"type":"number","nullable":true},"written_premium_change":{"type":"number","nullable":true},"num_policyholders_affected":{"type":"number","nullable":true},"written_premium":{"type":"number","nullable":true},"max_change":{"type":"number","nullable":true},"min_change":{"type":"number","nullable":true},"company_info_json":{"nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","serff_tracking_number","org_id","overall_indicated_change","overall_rate_impact","written_premium_change","num_policyholders_affected","written_premium","max_change","min_change","created_at","updated_at"]}},"total":{"type":"number"},"hasMore":{"type":"boolean"},"next_cursor":{"anyOf":[{"type":"number"},{"type":"string"},{"nullable":true}]}},"required":["records"]}}}},"400":{"description":"Bad request - invalid query parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/serff/sql":{"post":{"summary":"Execute SERFF SQL query","description":"Execute a read-only PostgreSQL SELECT query against whitelisted SERFF tables using the restricted SQL table service role.","tags":["SERFF"],"requestBody":{"description":"SQL query to execute against whitelisted SERFF tables","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SerffSqlQueryRequest"}}}},"responses":{"200":{"description":"SERFF SQL query results","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SerffSqlQueryResponse"}}}},"400":{"description":"Bad request - invalid SQL query request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden - SQL query is not permitted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"408":{"description":"Request timeout - SQL query exceeded the execution limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Payload too large - SQL query returned too many rows","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/serff/filter-metadata":{"get":{"summary":"Get filter metadata for SERFF filings","description":"Returns enum values for low cardinality fields that can be used for filtering","tags":["SERFF"],"responses":{"200":{"description":"Filter metadata retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"fields":{"type":"array","items":{"type":"object","properties":{"fieldId":{"type":"string"},"fieldName":{"type":"string"},"dataType":{"type":"string","enum":["enum"]},"values":{"type":"array","items":{"type":"string"}},"valueCounts":{"type":"array","items":{"type":"object","properties":{"value":{"type":"string"},"count":{"type":"number"},"percentage":{"type":"number"}},"required":["value","count","percentage"]}}},"required":["fieldId","fieldName","dataType","values"]}},"generatedAt":{"type":"string","format":"date-time"},"condensed_output":{"type":"string"}},"required":["fields","generatedAt"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/serff/forms/recompute":{"post":{"summary":"Trigger SERFF forms recompute workflow","description":"Repopulate the serff_form_info table by rerunning the periodic_insert_form_info dbt macro (Tenant Admin or Super Admin only).","tags":["SERFF"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"truncate":{"type":"boolean","default":false},"maxRuns":{"type":"integer","minimum":1,"maximum":100,"description":"Maximum iterations to run periodic_insert_form_info (1-100)"}},"default":{"truncate":false},"description":"Options for recomputing SERFF forms"}}}},"responses":{"200":{"description":"SERFF forms recompute workflow triggered successfully","content":{"application/json":{"schema":{"type":"object","properties":{"workflowId":{"type":"string","description":"Temporal workflow ID"},"message":{"type":"string","description":"Success message"},"truncate":{"type":"boolean","description":"Whether the forms table will be truncated first"},"maxRuns":{"type":"integer","minimum":1,"maximum":100,"description":"Applied maximum iteration count"}},"required":["workflowId","message","truncate","maxRuns"]}}}},"403":{"description":"Forbidden"},"500":{"description":"Failed to trigger workflow"}}}},"/api/v1/serff/reviewers-objections/recompute":{"post":{"summary":"Trigger SERFF reviewers and objections recompute workflow","description":"Refresh serff_reviewers and serff_filing_objections tables by rerunning the periodic_insert_objections dbt macro (Tenant Admin or Super Admin only).","tags":["SERFF"],"responses":{"200":{"description":"SERFF reviewers and objections recompute workflow triggered successfully","content":{"application/json":{"schema":{"type":"object","properties":{"workflowId":{"type":"string","description":"Temporal workflow ID"},"message":{"type":"string","description":"Success message"}},"required":["workflowId","message"]}}}},"403":{"description":"Forbidden"},"500":{"description":"Failed to trigger workflow"}}}},"/api/v1/serff/rate-impact/recompute":{"post":{"summary":"Trigger SERFF rate impact recompute workflow","description":"Repopulate the serff_rate_impact table from serff_extractions (Tenant Admin or Super Admin only).","tags":["SERFF"],"responses":{"200":{"description":"SERFF rate impact recompute workflow triggered successfully","content":{"application/json":{"schema":{"type":"object","properties":{"workflowId":{"type":"string","description":"Temporal workflow ID"},"message":{"type":"string","description":"Success message"}},"required":["workflowId","message"]}}}},"403":{"description":"Forbidden"},"500":{"description":"Failed to trigger workflow"}}}},"/api/v1/serff/florida-irfs/collection/status":{"get":{"summary":"Get Florida IRFS collection status","description":"Get the current status of the Florida IRFS continuous collection workflow","tags":["SERFF"],"responses":{"200":{"description":"Workflow status","content":{"application/json":{"schema":{"type":"object","properties":{"workflowId":{"type":"string","description":"Workflow ID"},"status":{"type":"string","description":"Workflow status"},"startTime":{"type":"string","description":"Start time (ISO 8601)"},"historyLength":{"type":"number","description":"History length"}},"required":["workflowId","status"]}}}},"404":{"description":"Workflow not found"},"500":{"description":"Failed to get status"}}}},"/api/v1/serff/florida-irfs/document-collection":{"post":{"summary":"Trigger Florida IRFS document collection workflow","description":"Starts a Temporal workflow to request documents for Florida filings without artifacts","tags":["SERFF"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"trackingNumbers":{"type":"array","items":{"type":"string"},"description":"SERFF tracking numbers (e.g., [\"FL-26-003347\", \"FL-26-003348\"]). Returns immediately for any that already have documents."},"companyName":{"type":"string","description":"Filter by company name (ILIKE match)"},"lineOfInsurance":{"type":"string","description":"Filter by type_of_insurance (ILIKE match)"},"delayMs":{"type":"number","description":"Delay between requests in ms (default 10000)"},"maxRequests":{"type":"number","description":"Max document requests per run (default: 50)"},"retry":{"type":"boolean","description":"If true, re-request all documents for filings that already have artifacts."}}}}}},"responses":{"200":{"description":"Florida IRFS document collection workflow triggered successfully","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["available","queued","partial"],"description":"Whether documents are already available, request was queued, or mix of both"},"workflowId":{"type":"string","description":"Temporal workflow ID (when status=queued)"},"artifactId":{"type":"string","description":"Artifact ID (folder) when status=available"},"message":{"type":"string","description":"Success message"},"startDate":{"type":"string","description":"Start date"},"endDate":{"type":"string","description":"End date"},"email":{"type":"string","description":"Email for document delivery"},"alreadyAvailable":{"type":"array","items":{"type":"object","properties":{"serffTrackingNumber":{"type":"string"},"artifactId":{"type":"string"}},"required":["serffTrackingNumber","artifactId"]},"description":"Filings that already have documents available"},"queued":{"type":"array","items":{"type":"string"},"description":"Tracking numbers queued for processing"}},"required":["status","message"]}}}},"400":{"description":"Invalid request parameters"},"409":{"description":"Continuous workflow already running"},"429":{"description":"Daily rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["rate_limit_exceeded"]},"message":{"type":"string","description":"Error message with remaining quota info"},"remaining":{"type":"number","description":"Requests remaining today (0 when limit exceeded)"}},"required":["error","message","remaining"]}}}},"500":{"description":"Failed to trigger workflow"}}}},"/api/v1/serff/scrape/on-demand":{"post":{"summary":"Trigger on-demand SERFF scrape","description":"Start an on-demand scrape for a specific SERFF filing. Requires tracking number and state.","tags":["SERFF"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"serffTrackingNumber":{"type":"string","minLength":1,"description":"SERFF tracking number (e.g., PRGS-134411310)"},"state":{"type":"string","minLength":2,"maxLength":2,"description":"Two-letter US state code (e.g., CA, TX)"},"action":{"type":"string","enum":["create","refresh"],"default":"create","description":"Queue action: 'create' for new filings, 'refresh' to re-scrape existing ones (default: 'create')"}},"required":["serffTrackingNumber","state"]}}}},"responses":{"200":{"description":"Workflow scheduled","content":{"application/json":{"schema":{"type":"object","properties":{"workflowId":{"type":"string"},"serffTrackingNumber":{"type":"string"},"state":{"type":"string"},"message":{"type":"string"}},"required":["workflowId","serffTrackingNumber","state","message"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/serff/scrape/batch-on-demand":{"post":{"summary":"Trigger batch on-demand SERFF scrape","description":"Scrape multiple SERFF filings with throttled concurrency. Filings are distributed across concurrent browser instances and processed sequentially within each.","tags":["SERFF"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"filings":{"type":"array","items":{"type":"object","properties":{"serffTrackingNumber":{"type":"string","minLength":1},"state":{"type":"string","minLength":2,"maxLength":2}},"required":["serffTrackingNumber","state"]},"minItems":1,"maxItems":2000,"description":"List of filings to scrape (max 2000)"},"concurrency":{"type":"integer","minimum":1,"maximum":10,"default":3,"description":"Max concurrent browser instances (default: 3)"},"priority":{"type":"integer","minimum":0,"maximum":100,"default":10,"description":"Queue priority (default: 10)"},"filingsPerBrowser":{"type":"integer","minimum":1,"maximum":50,"default":1,"description":"Filings per browser session (default: 1). Higher values share a browser for throughput."},"action":{"type":"string","enum":["create","refresh"],"default":"create","description":"Queue action: 'create' for new filings, 'refresh' to re-scrape existing ones (default: 'create')"}},"required":["filings"]}}}},"responses":{"200":{"description":"Batch workflow scheduled","content":{"application/json":{"schema":{"type":"object","properties":{"workflowId":{"type":"string"},"totalFilings":{"type":"number"},"concurrency":{"type":"number"},"message":{"type":"string"}},"required":["workflowId","totalFilings","concurrency","message"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/serff/scrape/find-state":{"post":{"summary":"Find which state a SERFF filing belongs to","description":"Start a workflow that searches across states (5 in parallel) to find which state a filing belongs to. Returns a workflow ID to poll for results.","tags":["SERFF"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"serffTrackingNumber":{"type":"string","minLength":1,"description":"SERFF tracking number to look up"},"states":{"type":"array","items":{"type":"string","minLength":2,"maxLength":2},"description":"Optional subset of states to check. Defaults to all US states."}},"required":["serffTrackingNumber"]}}}},"responses":{"200":{"description":"Workflow scheduled","content":{"application/json":{"schema":{"type":"object","properties":{"workflowId":{"type":"string"},"serffTrackingNumber":{"type":"string"},"message":{"type":"string"}},"required":["workflowId","serffTrackingNumber","message"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/serff/scrape/find-state/{workflowId}":{"get":{"summary":"Get find-state workflow result","description":"Poll the status and result of a find-state workflow.","tags":["SERFF"],"parameters":[{"schema":{"type":"string"},"required":true,"name":"workflowId","in":"path"}],"responses":{"200":{"description":"Workflow status","content":{"application/json":{"schema":{"type":"object","properties":{"workflowId":{"type":"string"},"status":{"type":"string"},"result":{"type":"object","properties":{"serffTrackingNumber":{"type":"string"},"foundStates":{"type":"array","items":{"type":"string"}},"checkedStates":{"type":"array","items":{"type":"string"}},"errorStates":{"type":"array","items":{"type":"object","properties":{"state":{"type":"string"},"error":{"type":"string"}},"required":["state","error"]}},"found":{"type":"boolean"}},"required":["serffTrackingNumber","foundStates","checkedStates","errorStates","found"]},"error":{"type":"string"}},"required":["workflowId","status"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/serff/scrape/status/{trackingNumber}":{"get":{"summary":"Get scrape status for a tracking number","description":"Check the scrape queue and filing info to see if a filing has been scraped or is in progress.","tags":["SERFF"],"parameters":[{"schema":{"type":"string"},"required":true,"name":"trackingNumber","in":"path"}],"responses":{"200":{"description":"Scrape status","content":{"application/json":{"schema":{"type":"object","properties":{"serffTrackingNumber":{"type":"string"},"queueEntries":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string"},"action":{"type":"string"},"state":{"type":"string"},"priority":{"type":"number"},"error":{"type":"string","nullable":true},"terminalReason":{"type":"string","nullable":true},"stageMetadata":{"type":"object","nullable":true,"additionalProperties":{"nullable":true}},"createdAt":{"type":"string"},"processedAt":{"type":"string","nullable":true},"statusUpdatedAt":{"type":"string","nullable":true}},"required":["id","status","action","state","priority","error","terminalReason","stageMetadata","createdAt","processedAt","statusUpdatedAt"]}},"filingInfo":{"type":"object","nullable":true,"properties":{"state":{"type":"string","nullable":true},"companyName":{"type":"string","nullable":true},"productName":{"type":"string","nullable":true},"filingType":{"type":"string","nullable":true},"filingStatus":{"type":"string","nullable":true},"submissionDate":{"type":"string","nullable":true},"artifactId":{"type":"string","nullable":true}},"required":["state","companyName","productName","filingType","filingStatus","submissionDate","artifactId"]},"everScraped":{"type":"boolean"}},"required":["serffTrackingNumber","queueEntries","filingInfo","everScraped"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/serff/scrape/queue":{"get":{"summary":"List scrape queue entries with filters","description":"Query the scrape queue with optional filters for date range, status, state, and limit.","tags":["SERFF"],"parameters":[{"schema":{"type":"string","description":"Start date (ISO 8601 or YYYY-MM-DD)"},"required":false,"description":"Start date (ISO 8601 or YYYY-MM-DD)","name":"start","in":"query"},{"schema":{"type":"string","description":"End date (ISO 8601 or YYYY-MM-DD)"},"required":false,"description":"End date (ISO 8601 or YYYY-MM-DD)","name":"end","in":"query"},{"schema":{"type":"number","nullable":true,"description":"Hours lookback (default 24, ignored if start is set)"},"required":false,"description":"Hours lookback (default 24, ignored if start is set)","name":"hours","in":"query"},{"schema":{"type":"string","description":"Filter by pipeline status"},"required":false,"description":"Filter by pipeline status","name":"status","in":"query"},{"schema":{"type":"string","description":"Filter by US state code"},"required":false,"description":"Filter by US state code","name":"state","in":"query"},{"schema":{"type":"string","description":"Filter by terminal reason"},"required":false,"description":"Filter by terminal reason","name":"terminal_reason","in":"query"},{"schema":{"type":"string","format":"date-time","description":"Only include rows with status_updated_at >= this timestamp"},"required":false,"description":"Only include rows with status_updated_at >= this timestamp","name":"updated_since","in":"query"},{"schema":{"type":"number","nullable":true,"description":"Max entries to return (default 100, max 2000)"},"required":false,"description":"Max entries to return (default 100, max 2000)","name":"limit","in":"query"},{"schema":{"type":"integer","nullable":true,"minimum":0,"default":0,"description":"Number of matching rows to skip (default 0)"},"required":false,"description":"Number of matching rows to skip (default 0)","name":"offset","in":"query"}],"responses":{"200":{"description":"Queue entries","content":{"application/json":{"schema":{"type":"object","properties":{"entries":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"serffTrackingNumber":{"type":"string"},"filingId":{"type":"string"},"status":{"type":"string"},"action":{"type":"string"},"state":{"type":"string"},"priority":{"type":"number"},"error":{"type":"string","nullable":true},"terminalReason":{"type":"string","nullable":true},"stageMetadata":{"type":"object","nullable":true,"additionalProperties":{"nullable":true}},"createdAt":{"type":"string"},"processedAt":{"type":"string","nullable":true},"statusUpdatedAt":{"type":"string","nullable":true}},"required":["id","serffTrackingNumber","filingId","status","action","state","priority","error","terminalReason","stageMetadata","createdAt","processedAt","statusUpdatedAt"]}},"total":{"type":"number"},"limit":{"type":"number"},"offset":{"type":"number"}},"required":["entries","total","limit","offset"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/search/artifacts":{"post":{"summary":"Search indexed artifacts","description":"Search through indexed artifacts using keyword search","tags":["Search"],"requestBody":{"description":"Search parameters","content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string","minLength":1,"description":"Search query text"},"topK":{"type":"integer","minimum":0,"exclusiveMinimum":true,"maximum":1200,"default":5,"description":"Number of results to return"},"filters":{"type":"object","additionalProperties":{"nullable":true},"description":"Additional filters to apply"},"textFetchMode":{"type":"string","enum":["docReader","fromTurbo","none"],"description":"Override the text fetch strategy used for grouped passages"}},"required":["query"]}}}},"responses":{"200":{"description":"Search results","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchResponse"}}}},"400":{"description":"Bad request - invalid search parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/context-base/search/documents":{"post":{"summary":"Search contextbase catalog documents","description":"Search platform-indexed catalog projections for a contextbase or Mission Control.","tags":["Context Base Search"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContextBaseSearchRequest"}}}},"responses":{"200":{"description":"Search results","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContextBaseSearchResponse"}}}},"400":{"description":"Invalid search request"},"404":{"description":"Mission Control not found"}}}},"/api/v1/context-base/search/facets":{"post":{"summary":"Get contextbase search facets","description":"Return facet counts for the same scope and filters as document search.","tags":["Context Base Search"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContextBaseSearchRequest"}}}},"responses":{"200":{"description":"Facet counts","content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string","nullable":true},"filters":{"type":"object","additionalProperties":{"type":"array","items":{"nullable":true}}},"facets":{"type":"object","additionalProperties":{"type":"array","items":{"$ref":"#/components/schemas/ContextBaseSearchFacetValue"}}}},"required":["query","filters","facets"]}}}},"400":{"description":"Invalid search request"},"404":{"description":"Mission Control not found"}}}},"/api/v1/context-base/search/facet-schema":{"get":{"summary":"Get contextbase search facet schema","description":"Return platform-known global facet fields. Catalog-specific facets can appear in results.","tags":["Context Base Search"],"responses":{"200":{"description":"Facet schema","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContextBaseSearchFacetSchemaResponse"}}}}}}},"/api/v1/context-base/search/admin/documents":{"post":{"summary":"Upsert contextbase search documents","description":"Super-admin-only endpoint for manually inserting platform search documents.","tags":["Context Base Search"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContextBaseSearchUpsertDocumentsRequest"}}}},"responses":{"200":{"description":"Documents upserted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContextBaseSearchUpsertDocumentsResponse"}}}},"400":{"description":"Invalid upsert request"},"403":{"description":"Super Admin role required"}}}},"/api/v1/context-base/search/admin/reindex":{"post":{"summary":"Reindex contextbase ontology entities","description":"Super-admin-only endpoint that reads ontology_runtime.entities directly from the contextbase database and indexes them as search documents.","tags":["Context Base Search"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContextBaseSearchReindexRequest"}}}},"responses":{"200":{"description":"Entities indexed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContextBaseSearchReindexResponse"}}}},"400":{"description":"Invalid reindex request"},"403":{"description":"Super Admin role required"}}}},"/api/v1/context-base/workflows":{"get":{"summary":"List workflows","description":"List workflow definitions from the code-first catalog. Each workflow exports id, name, description, inputSchema, and outputSchema.","tags":["Workflow Catalog"],"parameters":[{"schema":{"type":"string","description":"Filter catalog to workflows assigned to this mission control. Also scopes the context base repo lookup."},"required":false,"description":"Filter catalog to workflows assigned to this mission control. Also scopes the context base repo lookup.","name":"mission_control_id","in":"query"}],"responses":{"200":{"description":"Workflow catalog list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkflowCatalogListResponse"}}}},"404":{"description":"Context base repo or mission control not found"},"502":{"description":"Context base filesystem request failed"}}}},"/api/v1/context-base/workflows/{workflowId}":{"get":{"summary":"Get workflow detail","description":"Get a single workflow definition by id, including the description body.","tags":["Workflow Catalog"],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"workflowId","in":"path"},{"schema":{"type":"string","description":"Scope lookup to workflows assigned to this mission control. Returns 404 if the workflow exists but is not assigned to this MC."},"required":false,"description":"Scope lookup to workflows assigned to this mission control. Returns 404 if the workflow exists but is not assigned to this MC.","name":"mission_control_id","in":"query"}],"responses":{"200":{"description":"Workflow detail with body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkflowCatalogDetailResponse"}}}},"404":{"description":"Workflow not found or not assigned to this mission control"},"502":{"description":"Context base filesystem request failed"}}}},"/api/v1/context-base/workflow/draft/{draftId}/build":{"post":{"summary":"Build workflow preview","description":"Sync workflow files to the sandbox and run the Workflow SDK build to produce the graph. Returns the graph on success or build errors on failure.","tags":["Workflows"],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"draftId","in":"path"},{"schema":{"type":"string","minLength":3,"maxLength":128,"pattern":"^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$"},"required":false,"name":"workflowId","in":"query"}],"responses":{"200":{"description":"Build completed (check `success` field for outcome)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkflowBuildResult"}}}},"400":{"description":"Draft is not attached to a session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Draft not found or not a workflow draft","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/context-base/workflow/draft/{draftId}/graph":{"get":{"summary":"Get workflow graph","description":"Return the graph from the last successful build in the sandbox. Returns 404 if no build has been run yet.","tags":["Workflows"],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"draftId","in":"path"},{"schema":{"type":"string","minLength":3,"maxLength":128,"pattern":"^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$"},"required":false,"name":"workflowId","in":"query"}],"responses":{"200":{"description":"Workflow graph from last build","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkflowGraphResponse"}}}},"400":{"description":"Draft is not attached to a session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Draft not found, not a workflow draft, or no build available","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/context-base/workflow/draft/{draftId}/runs":{"post":{"summary":"Start workflow draft preview run","description":"Start a preview run from draft workflow source in the draft sandbox runtime.","tags":["Workflows"],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"draftId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StartWorkflowDraftRunRequest"}}}},"responses":{"201":{"description":"Draft preview run started","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StartWorkflowDraftRunResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Draft not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Draft workflow runtime unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"summary":"List workflow draft preview runs","description":"List preview runs started from this workflow draft.","tags":["Workflows"],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"draftId","in":"path"}],"responses":{"200":{"description":"Draft preview runs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkflowDraftRunListResponse"}}}},"404":{"description":"Draft not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Draft workflow runtime unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/context-base/workflow/draft/{draftId}/runs/{previewRunId}":{"get":{"summary":"Get workflow draft preview run","description":"Get status and result details for a draft workflow preview run.","tags":["Workflows"],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"draftId","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"previewRunId","in":"path"}],"responses":{"200":{"description":"Draft preview run","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkflowDraftRun"}}}},"404":{"description":"Run not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Draft workflow runtime unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/context-base/workflow/draft/{draftId}/runs/{previewRunId}/steps":{"get":{"summary":"List workflow draft preview run steps","description":"List Workflow SDK steps for a draft workflow preview run.","tags":["Workflows"],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"draftId","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"previewRunId","in":"path"}],"responses":{"200":{"description":"Draft preview run steps","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkflowDraftRunStepListResponse"}}}},"404":{"description":"Run not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Draft workflow runtime unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/context-base/workflow/draft/{draftId}/runs/{previewRunId}/events":{"get":{"summary":"List workflow draft preview run events","description":"List Workflow SDK events for a draft workflow preview run.","tags":["Workflows"],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"draftId","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"previewRunId","in":"path"}],"responses":{"200":{"description":"Draft preview run events","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkflowDraftRunEventListResponse"}}}},"404":{"description":"Run not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Draft workflow runtime unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/context-base/workflow/draft/{draftId}/runs/{previewRunId}/hooks":{"get":{"summary":"List workflow draft preview run hooks","description":"List pending Workflow SDK hooks for a draft workflow preview run.","tags":["Workflows"],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"draftId","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"previewRunId","in":"path"}],"responses":{"200":{"description":"Draft preview run hooks","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkflowDraftRunHookListResponse"}}}},"404":{"description":"Run not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Draft workflow runtime unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/context-base/workflow/draft/{draftId}/runs/{previewRunId}/hooks/{token}":{"post":{"summary":"Resume workflow draft preview run hook","description":"Resume a pending Workflow SDK hook for a draft workflow preview run.","tags":["Workflows"],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"draftId","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"previewRunId","in":"path"},{"schema":{"type":"string","minLength":1},"required":true,"name":"token","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResumeWorkflowDraftRunHookRequest"}}}},"responses":{"200":{"description":"Draft preview run hook resumed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkflowDraftRunActionResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Hook not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Draft workflow runtime unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/context-base/workflow/draft/{draftId}/runs/{previewRunId}/cancel":{"post":{"summary":"Cancel workflow draft preview run","description":"Cancel a draft workflow preview run.","tags":["Workflows"],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"draftId","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"previewRunId","in":"path"}],"responses":{"200":{"description":"Draft preview run cancelled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkflowDraftRunActionResponse"}}}},"404":{"description":"Run not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Draft workflow runtime unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/chat/sessions":{"post":{"summary":"Start a new chat session","description":"Create a new generic chat session","tags":["Chat"],"requestBody":{"description":"Session creation options","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StartSessionRequest"}}}},"responses":{"201":{"description":"Session created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StartChatSessionResponse"}}}},"400":{"description":"Invalid session creation request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"PresetRef target not found (agent or app does not exist)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Session creation conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit or quota exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Service temporarily unavailable (e.g., sandbox capacity)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"summary":"List chat sessions","description":"List all chat sessions for the authenticated user","tags":["Chat"],"parameters":[{"schema":{"type":"integer","minimum":0,"exclusiveMinimum":true,"maximum":100,"description":"Maximum number of sessions to return (default: 50, max: 100)"},"required":false,"description":"Maximum number of sessions to return (default: 50, max: 100)","name":"limit","in":"query"},{"schema":{"type":"integer","nullable":true,"minimum":0,"description":"Number of sessions to skip for pagination"},"required":false,"description":"Number of sessions to skip for pagination","name":"offset","in":"query"},{"schema":{"type":"string","enum":["idle","busy","deleted"],"description":"Filter by session state"},"required":false,"description":"Filter by session state","name":"state","in":"query"},{"schema":{"type":"string","description":"Ignore createdBy filter"},"required":false,"description":"Ignore createdBy filter","name":"ignoreCreatedBy","in":"query"},{"schema":{"type":"string","description":"Filter by specific user who created the session"},"required":false,"description":"Filter by specific user who created the session","name":"createdBy","in":"query"},{"schema":{"type":"string","enum":["owned","participating","any"],"description":"Filter by the authenticated user relationship: owned, participating, or any relationship"},"required":false,"description":"Filter by the authenticated user relationship: owned, participating, or any relationship","name":"involvement","in":"query"},{"schema":{"type":"boolean","nullable":true,"description":"Filter by pinned status"},"required":false,"description":"Filter by pinned status","name":"pinned","in":"query"},{"schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Filter by session tags"},"required":false,"description":"Filter by session tags","name":"tags","in":"query"},{"schema":{"type":"string","enum":["all","any"],"description":"Whether to match all tags (AND) or any tag (OR). Default: \"any\""},"required":false,"description":"Whether to match all tags (AND) or any tag (OR). Default: \"any\"","name":"tagsMatch","in":"query"},{"schema":{"type":"string","enum":["default","subagent"],"description":"Filter by session type (default: \"default\")"},"required":false,"description":"Filter by session type (default: \"default\")","name":"sessionType","in":"query"},{"schema":{"type":"boolean","nullable":true,"description":"When true, return only sessions where the user has directly sent a message. Includes both default and subagent sessions. Overrides sessionType filter."},"required":false,"description":"When true, return only sessions where the user has directly sent a message. Includes both default and subagent sessions. Overrides sessionType filter.","name":"interactive","in":"query"},{"schema":{"type":"string","description":"Filter by organization ID (requires Super Admin role)"},"required":false,"description":"Filter by organization ID (requires Super Admin role)","name":"orgId","in":"query"},{"schema":{"type":"string","description":"Filter by root session ID"},"required":false,"description":"Filter by root session ID","name":"rootSessionId","in":"query"},{"schema":{"type":"string","description":"Filter by immediate parent session ID"},"required":false,"description":"Filter by immediate parent session ID","name":"parentSessionId","in":"query"},{"schema":{"type":"string","format":"date-time","description":"Only include sessions created after this time (ISO 8601)"},"required":false,"description":"Only include sessions created after this time (ISO 8601)","name":"createdAfter","in":"query"},{"schema":{"type":"string","format":"date-time","description":"Only include sessions created before this time (ISO 8601)"},"required":false,"description":"Only include sessions created before this time (ISO 8601)","name":"createdBefore","in":"query"}],"responses":{"200":{"description":"Sessions retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListSessionsResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/chat/sessions/import":{"post":{"summary":"Import a chat thread","description":"Create a new chat session and import messages from a chat thread JSON payload","tags":["Chat"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImportChatThreadRequest"}}}},"responses":{"201":{"description":"Chat thread imported successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImportChatThreadResponse"}}}},"400":{"description":"Bad request - invalid payload","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/chat/sessions/roots":{"get":{"summary":"List root chat sessions","description":"List root chat sessions for the authenticated user, decorated with hasChildren for nested browsing.","tags":["Chat"],"parameters":[{"schema":{"type":"integer","minimum":0,"exclusiveMinimum":true,"maximum":100,"description":"Maximum number of sessions to return (default: 50, max: 100)"},"required":false,"description":"Maximum number of sessions to return (default: 50, max: 100)","name":"limit","in":"query"},{"schema":{"type":"integer","nullable":true,"minimum":0,"description":"Number of sessions to skip for pagination"},"required":false,"description":"Number of sessions to skip for pagination","name":"offset","in":"query"},{"schema":{"type":"string","enum":["idle","busy","deleted"],"description":"Filter by session state"},"required":false,"description":"Filter by session state","name":"state","in":"query"},{"schema":{"type":"string","description":"Ignore createdBy filter"},"required":false,"description":"Ignore createdBy filter","name":"ignoreCreatedBy","in":"query"},{"schema":{"type":"string","description":"Filter by specific user who created the session"},"required":false,"description":"Filter by specific user who created the session","name":"createdBy","in":"query"},{"schema":{"type":"string","enum":["owned","participating","any"],"description":"Filter by the authenticated user relationship: owned, participating, or any relationship"},"required":false,"description":"Filter by the authenticated user relationship: owned, participating, or any relationship","name":"involvement","in":"query"},{"schema":{"type":"boolean","nullable":true,"description":"Filter by pinned status"},"required":false,"description":"Filter by pinned status","name":"pinned","in":"query"},{"schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Filter by session tags"},"required":false,"description":"Filter by session tags","name":"tags","in":"query"},{"schema":{"type":"string","enum":["all","any"],"description":"Whether to match all tags (AND) or any tag (OR). Default: \"any\""},"required":false,"description":"Whether to match all tags (AND) or any tag (OR). Default: \"any\"","name":"tagsMatch","in":"query"},{"schema":{"type":"string","description":"Filter by organization ID (requires Super Admin role)"},"required":false,"description":"Filter by organization ID (requires Super Admin role)","name":"orgId","in":"query"},{"schema":{"type":"string","format":"date-time","description":"Only include sessions created after this time (ISO 8601)"},"required":false,"description":"Only include sessions created after this time (ISO 8601)","name":"createdAfter","in":"query"},{"schema":{"type":"string","format":"date-time","description":"Only include sessions created before this time (ISO 8601)"},"required":false,"description":"Only include sessions created before this time (ISO 8601)","name":"createdBefore","in":"query"}],"responses":{"200":{"description":"Root sessions retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListHierarchicalSessionsResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/chat/sessions/{sessionId}/children":{"get":{"summary":"List immediate child sessions","description":"List immediate child sessions for a specific session, decorated with hasChildren for nested browsing.","tags":["Chat"],"parameters":[{"schema":{"type":"string","description":"Parent session ID"},"required":true,"description":"Parent session ID","name":"sessionId","in":"path"},{"schema":{"type":"integer","minimum":0,"exclusiveMinimum":true,"maximum":100,"description":"Maximum number of sessions to return (default: 50, max: 100)"},"required":false,"description":"Maximum number of sessions to return (default: 50, max: 100)","name":"limit","in":"query"},{"schema":{"type":"integer","nullable":true,"minimum":0,"description":"Number of sessions to skip for pagination"},"required":false,"description":"Number of sessions to skip for pagination","name":"offset","in":"query"},{"schema":{"type":"string","enum":["idle","busy","deleted"],"description":"Filter by session state"},"required":false,"description":"Filter by session state","name":"state","in":"query"},{"schema":{"type":"string","description":"Ignore createdBy filter"},"required":false,"description":"Ignore createdBy filter","name":"ignoreCreatedBy","in":"query"},{"schema":{"type":"string","description":"Filter by specific user who created the session"},"required":false,"description":"Filter by specific user who created the session","name":"createdBy","in":"query"},{"schema":{"type":"string","enum":["owned","participating","any"],"description":"Filter by the authenticated user relationship: owned, participating, or any relationship"},"required":false,"description":"Filter by the authenticated user relationship: owned, participating, or any relationship","name":"involvement","in":"query"},{"schema":{"type":"boolean","nullable":true,"description":"Filter by pinned status"},"required":false,"description":"Filter by pinned status","name":"pinned","in":"query"},{"schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Filter by session tags"},"required":false,"description":"Filter by session tags","name":"tags","in":"query"},{"schema":{"type":"string","enum":["all","any"],"description":"Whether to match all tags (AND) or any tag (OR). Default: \"any\""},"required":false,"description":"Whether to match all tags (AND) or any tag (OR). Default: \"any\"","name":"tagsMatch","in":"query"},{"schema":{"type":"string","description":"Filter by organization ID (requires Super Admin role)"},"required":false,"description":"Filter by organization ID (requires Super Admin role)","name":"orgId","in":"query"},{"schema":{"type":"string","format":"date-time","description":"Only include sessions created after this time (ISO 8601)"},"required":false,"description":"Only include sessions created after this time (ISO 8601)","name":"createdAfter","in":"query"},{"schema":{"type":"string","format":"date-time","description":"Only include sessions created before this time (ISO 8601)"},"required":false,"description":"Only include sessions created before this time (ISO 8601)","name":"createdBefore","in":"query"}],"responses":{"200":{"description":"Child sessions retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListHierarchicalSessionsResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Parent session not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/chat/sessions/search":{"get":{"summary":"Search chat sessions","description":"Search chat sessions by title for the authenticated user","tags":["Chat"],"parameters":[{"schema":{"type":"string","minLength":1,"description":"Search query for session titles"},"required":true,"description":"Search query for session titles","name":"q","in":"query"},{"schema":{"type":"integer","minimum":0,"exclusiveMinimum":true,"maximum":100,"default":50,"description":"Maximum number of sessions to return (default: 50, max: 100)"},"required":false,"description":"Maximum number of sessions to return (default: 50, max: 100)","name":"limit","in":"query"},{"schema":{"type":"integer","nullable":true,"minimum":0,"description":"Number of sessions to skip for pagination"},"required":false,"description":"Number of sessions to skip for pagination","name":"offset","in":"query"},{"schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Filter by session tags (can be a single tag or array of tags)"},"required":false,"description":"Filter by session tags (can be a single tag or array of tags)","name":"tags","in":"query"},{"schema":{"type":"string","enum":["createdAt","lastActivityAt"],"default":"createdAt","description":"Field to sort by (default: createdAt)"},"required":false,"description":"Field to sort by (default: createdAt)","name":"orderBy","in":"query"},{"schema":{"type":"string","enum":["asc","desc"],"default":"desc","description":"Sort direction: asc (oldest first) or desc (newest first, default)"},"required":false,"description":"Sort direction: asc (oldest first) or desc (newest first, default)","name":"orderDirection","in":"query"}],"responses":{"200":{"description":"Sessions retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchSessionsResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/chat/sessions/{sessionId}/send-async":{"post":{"summary":"Send a message to chat session (Temporal workflow)","description":"Send a message to a chat session using Temporal workflow for improved reliability","tags":["Chat"],"parameters":[{"schema":{"type":"string","description":"Session ID"},"required":true,"description":"Session ID","name":"sessionId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatSendRequest"}}}},"responses":{"200":{"description":"Workflow started successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatSendResponse"}}}},"400":{"description":"Bad request - missing or invalid message","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Setup failed - sandbox init_commands failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Spending limit exceeded - cost control enforce mode active","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/chat/sessions/{sessionId}/subscribe":{"get":{"summary":"Subscribe to session stream","description":"Subscribe to a session stream and receive real-time responses via Server-Sent Events (SSE)","tags":["Chat"],"parameters":[{"schema":{"type":"string","description":"Session ID"},"required":true,"description":"Session ID","name":"sessionId","in":"path"},{"schema":{"type":"string","description":"Start reading from this offset (default: 0 for all, $ for new only)"},"required":false,"description":"Start reading from this offset (default: 0 for all, $ for new only)","name":"offset","in":"query"},{"schema":{"type":"integer","nullable":true,"minimum":0,"maximum":1000,"description":"Cold-bootstrap snapshot page size — emit a `snapshot` event carrying the last N turn loops before resuming live deltas. Used by the chat UI first-mount path. When `includeMessageId` is also set, this is the size of the scroll-up buffer past the bridged target instead of the full window. Mutually exclusive with `sinceLoopId`. All snapshot params are honored only when `offset` is the default (0/$). Bounded by 1000 as a server-side sanity ceiling — not a UX-relevant cap; the FE is expected to request whatever it needs."},"required":false,"description":"Cold-bootstrap snapshot page size — emit a `snapshot` event carrying the last N turn loops before resuming live deltas. Used by the chat UI first-mount path. When `includeMessageId` is also set, this is the size of the scroll-up buffer past the bridged target instead of the full window. Mutually exclusive with `sinceLoopId`. All snapshot params are honored only when `offset` is the default (0/$). Bounded by 1000 as a server-side sanity ceiling — not a UX-relevant cap; the FE is expected to request whatever it needs.","name":"loopLimit","in":"query"},{"schema":{"type":"string","minLength":1,"description":"Deep-link cold-bootstrap — extend the windowed snapshot back far enough to include the loop containing this message id (uncapped bridge), plus `loopLimit` more older loops as the scroll-up buffer. Mutually exclusive with `sinceLoopId`. Returns 404 when the message id does not belong to this session."},"required":false,"description":"Deep-link cold-bootstrap — extend the windowed snapshot back far enough to include the loop containing this message id (uncapped bridge), plus `loopLimit` more older loops as the scroll-up buffer. Mutually exclusive with `sinceLoopId`. Returns 404 when the message id does not belong to this session.","name":"includeMessageId","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":1000,"description":"**Deprecated.** Legacy alias for `loopLimit` kept for rolling-deploy backward compatibility. When both `loopLimit` and `windowTurns` are present, `loopLimit` wins and a deprecation warning is logged. Will be removed once all clients have migrated."},"required":false,"description":"**Deprecated.** Legacy alias for `loopLimit` kept for rolling-deploy backward compatibility. When both `loopLimit` and `windowTurns` are present, `loopLimit` wins and a deprecation warning is logged. Will be removed once all clients have migrated.","name":"windowTurns","in":"query"},{"schema":{"type":"string","description":"Warm-reconnect snapshot: emit a `snapshot` event carrying all turn loops strictly newer than this loopId before resuming live deltas. Used by the chat UI reconnect path (visibility/online/resume) so the FE can do a deterministic tail-replace without window-size guesswork. Mutually exclusive with `loopLimit`, `includeMessageId`, and the deprecated `windowTurns`. If the cursor does not resolve, the server falls back to a windowed snapshot and stamps `bootstrapRequired: true` on the snapshot."},"required":false,"description":"Warm-reconnect snapshot: emit a `snapshot` event carrying all turn loops strictly newer than this loopId before resuming live deltas. Used by the chat UI reconnect path (visibility/online/resume) so the FE can do a deterministic tail-replace without window-size guesswork. Mutually exclusive with `loopLimit`, `includeMessageId`, and the deprecated `windowTurns`. If the cursor does not resolve, the server falls back to a windowed snapshot and stamps `bootstrapRequired: true` on the snapshot.","name":"sinceLoopId","in":"query"}],"responses":{"200":{"description":"Server-Sent Events stream of agent events","content":{"text/event-stream":{"schema":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["message_parts"]},"id":{"type":"string"},"role":{"type":"string","enum":["user","assistant","system"]},"parts":{"type":"array","items":{"$ref":"#/components/schemas/MessagePart"}},"loopId":{"type":"string"},"metadata":{"$ref":"#/components/schemas/ChatMessageMetadata"},"sender":{"type":"string"},"mentionedUserIds":{"type":"array","items":{"type":"string"}}},"required":["type","role","parts","loopId"]},{"type":"object","properties":{"type":{"type":"string","enum":["message_discard"]},"id":{"type":"string"},"loopId":{"type":"string"}},"required":["type","id","loopId"]},{"type":"object","properties":{"type":{"type":"string","enum":["agent_completion"]},"reason":{"type":"string"},"loopId":{"type":"string"}},"required":["type","loopId"]},{"type":"object","properties":{"type":{"type":"string","enum":["stream_error"]},"errorType":{"type":"string","enum":["stream_not_found","stream_finished","unknown"]},"message":{"type":"string"}},"required":["type","errorType","message"]},{"type":"object","properties":{"type":{"type":"string","enum":["input_queued"]},"messageId":{"type":"string"},"parts":{"type":"array","items":{"$ref":"#/components/schemas/MessagePart"}},"source":{"type":"string","enum":["user","inbox"]},"steer":{"type":"boolean"}},"required":["type","messageId","parts"]},{"type":"object","properties":{"type":{"type":"string","enum":["input_updated"]},"messageId":{"type":"string"},"parts":{"type":"array","items":{"$ref":"#/components/schemas/MessagePart"}},"steer":{"type":"boolean"}},"required":["type","messageId"]},{"type":"object","properties":{"type":{"type":"string","enum":["input_dequeued"]},"messageId":{"type":"string"}},"required":["type","messageId"]},{"type":"object","properties":{"type":{"type":"string","enum":["snapshot"]},"messages":{"type":"array","items":{"$ref":"#/components/schemas/ChatMessage"}},"hasMore":{"type":"boolean"},"oldestLoopId":{"type":"string","nullable":true},"watermark":{"type":"string"},"metadata":{"$ref":"#/components/schemas/ChatSessionMetadata"},"streamInfo":{"type":"object","properties":{"sessionId":{"type":"string"},"streamId":{"type":"string"},"finishedAt":{"type":"string","nullable":true,"format":"date-time"}},"required":["sessionId","streamId"]},"bootstrapRequired":{"type":"boolean","enum":[true]}},"required":["type","messages","hasMore","oldestLoopId","watermark","metadata"]},{"type":"object","properties":{"type":{"type":"string","enum":["session_phase"]},"phase":{"type":"string"},"status":{"type":"string","enum":["started","succeeded","failed"]},"durationMs":{"type":"number"},"bootPath":{"type":"string","enum":["snapshot_boot","warm_reconnect"]},"loopId":{"type":"string"},"errorMessage":{"type":"string"}},"required":["type","phase","status"]}]}}}},"404":{"description":"Session, or `includeMessageId`, not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/chat/sessions/{sessionId}/tools/{toolCallId}/subscribe":{"get":{"summary":"Subscribe to tool progress stream","description":"Subscribe to tool progress events for supported tools (python, bash) via SSE","tags":["Chat"],"parameters":[{"schema":{"type":"string","description":"Session ID"},"required":true,"description":"Session ID","name":"sessionId","in":"path"},{"schema":{"type":"string","description":"Tool call ID"},"required":true,"description":"Tool call ID","name":"toolCallId","in":"path"}],"responses":{"200":{"description":"Server-Sent Events stream of tool progress events","content":{"text/event-stream":{"schema":{"nullable":true}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/chat/sessions/{sessionId}/streams/{streamId}/stop":{"post":{"summary":"Stop a chat stream","description":"Stop an active chat stream when the user explicitly requests to cancel generation","tags":["Chat"],"parameters":[{"schema":{"type":"string","description":"Session ID"},"required":true,"description":"Session ID","name":"sessionId","in":"path"},{"schema":{"type":"string","description":"Stream ID"},"required":true,"description":"Stream ID","name":"streamId","in":"path"}],"responses":{"200":{"description":"Stream stopped successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StopStreamResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/chat/sessions/{sessionId}/stop":{"post":{"summary":"Stop a chat session","description":"Stop the active stream for a session.","tags":["Chat"],"parameters":[{"schema":{"type":"string","description":"Session ID"},"required":true,"description":"Session ID","name":"sessionId","in":"path"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"loopId":{"type":"string","description":"The loopId of the turn to stop. When provided, only that turn is cancelled; if the drain pass has moved on to a different loop, the abort is ignored."}}}}}},"responses":{"200":{"description":"Session stopped successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StopStreamResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/chat/sessions/{sessionId}/cancel-subagents":{"post":{"summary":"Cancel all subagents for a session","description":"Cancel all running subagents (including nested ones) for a chat session. This sets a Redis flag that subagents poll to check for cancellation.","tags":["Chat"],"parameters":[{"schema":{"type":"string","description":"Session ID (root session)"},"required":true,"description":"Session ID (root session)","name":"sessionId","in":"path"}],"responses":{"200":{"description":"Cancellation flag set successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the cancellation flag was set successfully"},"message":{"type":"string","description":"A message describing the result"}},"required":["success","message"]}}}},"403":{"description":"Access denied - session does not belong to user","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Session not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Failed to set cancellation flag","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/chat/sessions/{sessionId}/request-access":{"post":{"summary":"Request chat session access","description":"Notify the session owner that the current user is requesting access.","tags":["Chat"],"parameters":[{"schema":{"type":"string","description":"Session ID"},"required":true,"description":"Session ID","name":"sessionId","in":"path"}],"responses":{"200":{"description":"Access request sent","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["sent"]}},"required":["status"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/chat/sessions/{sessionId}":{"get":{"summary":"Load chat session","description":"Load an existing generic chat session","tags":["Chat"],"parameters":[{"schema":{"type":"string","description":"Session ID"},"required":true,"description":"Session ID","name":"sessionId","in":"path"}],"responses":{"200":{"description":"Session loaded successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LoadSessionResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Session not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"summary":"Update chat session metadata","description":"Update metadata for a chat session (e.g., title, description, pinned status)","tags":["Chat"],"parameters":[{"schema":{"type":"string","description":"Session ID"},"required":true,"description":"Session ID","name":"sessionId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateSessionRequest"}}}},"responses":{"200":{"description":"Session updated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}},"required":["success"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Access denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Session not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"summary":"Delete chat session","description":"Soft-delete a chat session while preserving its row for metering attribution","tags":["Chat"],"parameters":[{"schema":{"type":"string","description":"Session ID"},"required":true,"description":"Session ID","name":"sessionId","in":"path"}],"responses":{"200":{"description":"Session deleted successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeleteChatSessionResponse"}}}},"404":{"description":"Session not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/chat/sessions/{sessionId}/metadata":{"get":{"summary":"Get chat session metadata","description":"Get metadata for a chat session without loading the full message history","tags":["Chat"],"parameters":[{"schema":{"type":"string","description":"Session ID"},"required":true,"description":"Session ID","name":"sessionId","in":"path"}],"responses":{"200":{"description":"Session metadata retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatSessionMetadata"}}}},"404":{"description":"Session not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/chat/sessions/{sessionId}/available-skill-commands":{"get":{"summary":"Get available skill slash commands","description":"List Contextbase skills available as slash commands for this chat session","tags":["Chat"],"parameters":[{"schema":{"type":"string","description":"Session ID"},"required":true,"description":"Session ID","name":"sessionId","in":"path"}],"responses":{"200":{"description":"Available skill slash commands retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AvailableSkillSlashCommandsResponse"}}}},"404":{"description":"Session not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/chat/sessions/{sessionId}/agent-spawn-events":{"get":{"summary":"List agent spawn events","description":"List durable agent spawn events for the requested parent tool calls","tags":["Chat"],"parameters":[{"schema":{"type":"string","description":"Parent session ID"},"required":true,"description":"Parent session ID","name":"sessionId","in":"path"},{"schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Optional parent tool call IDs (repeated or comma-separated). When omitted, returns all spawn events for the session — preferred to avoid URL bloat (was hitting HTTP 431 on sessions with many tool calls)."},"required":false,"description":"Optional parent tool call IDs (repeated or comma-separated). When omitted, returns all spawn events for the session — preferred to avoid URL bloat (was hitting HTTP 431 on sessions with many tool calls).","name":"toolCallIds","in":"query"}],"responses":{"200":{"description":"Agent spawn events retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListAgentSpawnEventsResponse"}}}},"404":{"description":"Session not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"summary":"Create agent spawn event","description":"Persist a durable child-agent spawn event for a parent tool call","tags":["Chat"],"parameters":[{"schema":{"type":"string","description":"Parent session ID"},"required":true,"description":"Parent session ID","name":"sessionId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateAgentSpawnEventRequest"}}}},"responses":{"201":{"description":"Agent spawn event persisted successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentSpawnEvent"}}}},"404":{"description":"Session not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/chat/sessions/{sessionId}/sandboxes":{"get":{"summary":"Get sandboxes for a session (debugging)","description":"Get all sandboxes associated with a session ID for debugging purposes","tags":["Chat"],"parameters":[{"schema":{"type":"string","description":"Session ID"},"required":true,"description":"Session ID","name":"sessionId","in":"path"}],"responses":{"200":{"description":"Sandboxes retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SessionSandboxesResponse"}}}},"404":{"description":"Session not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/chat/sessions/{sessionId}/logs":{"get":{"summary":"Get logs for a session","description":"Query structured logs from Oodle for a specific session ID","tags":["Chat"],"parameters":[{"schema":{"type":"string","description":"Session ID"},"required":true,"description":"Session ID","name":"sessionId","in":"path"},{"schema":{"type":"number","nullable":true,"description":"Max log entries per page (default 50)"},"required":false,"description":"Max log entries per page (default 50)","name":"limit","in":"query"},{"schema":{"type":"string","description":"Cursor for forward pagination: only return logs after this timestamp (from previous page)"},"required":false,"description":"Cursor for forward pagination: only return logs after this timestamp (from previous page)","name":"afterTimestamp","in":"query"},{"schema":{"type":"string","description":"Cursor for backward pagination: only return logs before this timestamp. Use with sortOrder=desc to walk back from the end."},"required":false,"description":"Cursor for backward pagination: only return logs before this timestamp. Use with sortOrder=desc to walk back from the end.","name":"beforeTimestamp","in":"query"},{"schema":{"type":"string","description":"Filter by log level (e.g. ERROR, WARN)"},"required":false,"description":"Filter by log level (e.g. ERROR, WARN)","name":"level","in":"query"},{"schema":{"type":"number","nullable":true,"description":"Window start as epoch millis (default: session createdAt)"},"required":false,"description":"Window start as epoch millis (default: session createdAt)","name":"startTime","in":"query"},{"schema":{"type":"number","nullable":true,"description":"Window end as epoch millis (default: startTime + 4h)"},"required":false,"description":"Window end as epoch millis (default: startTime + 4h)","name":"endTime","in":"query"},{"schema":{"type":"string","enum":["asc","desc"],"description":"Oodle query sort order. Results are always returned in chronological (asc) order. Use \"desc\" with no cursor (or with beforeTimestamp) to jump to the last page."},"required":false,"description":"Oodle query sort order. Results are always returned in chronological (asc) order. Use \"desc\" with no cursor (or with beforeTimestamp) to jump to the last page.","name":"sortOrder","in":"query"}],"responses":{"200":{"description":"Logs retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SessionLogsResponse"}}}},"404":{"description":"Session not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/chat/sessions/{sessionId}/sandbox-url":{"get":{"summary":"Get public sandbox URL for a session","description":"Get the public URL for a server running inside a session sandbox (port 3000)","tags":["Chat"],"parameters":[{"schema":{"type":"string","description":"Session ID"},"required":true,"description":"Session ID","name":"sessionId","in":"path"},{"schema":{"type":"integer","minimum":0,"exclusiveMinimum":true,"description":"Port number for the sandbox (default: 5050)"},"required":false,"description":"Port number for the sandbox (default: 5050)","name":"port","in":"query"},{"schema":{"type":"string","description":"E2B sandbox template ID override"},"required":false,"description":"E2B sandbox template ID override","name":"templateId","in":"query"}],"responses":{"200":{"description":"Sandbox URL retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SessionSandboxUrlResponse"}}}},"404":{"description":"Session or sandbox not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/chat/sessions/{sessionId}/sandbox/keep-alive":{"post":{"summary":"Keep sandbox alive","description":"Extend the timeout for the sandbox associated with a session","tags":["Chat"],"parameters":[{"schema":{"type":"string","description":"Session ID"},"required":true,"description":"Session ID","name":"sessionId","in":"path"}],"responses":{"200":{"description":"Sandbox timeout extended successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KeepSandboxAliveResponse"}}}},"404":{"description":"Session or sandbox not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/chat/sessions/{sessionId}/sandbox/update":{"post":{"summary":"Provision a fresh active sandbox","description":"Create a new sandbox for the session, copy workspace state from the currently active sandbox, and switch the session to the new sandbox.","tags":["Chat"],"parameters":[{"schema":{"type":"string","description":"Session ID"},"required":true,"description":"Session ID","name":"sessionId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateSandboxRequest"}}}},"responses":{"200":{"description":"Sandbox updated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateSandboxResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Access denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Session not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Sandbox is owned by another session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/chat/sandbox/{sessionId}/file/content":{"get":{"summary":"Get sandbox file content","description":"Read file content from a sandbox filesystem (raw bytes)","tags":["Chat"],"parameters":[{"schema":{"type":"string","description":"Session ID that owns the sandbox"},"required":true,"description":"Session ID that owns the sandbox","name":"sessionId","in":"path"},{"schema":{"type":"string","description":"File path in the sandbox"},"required":true,"description":"File path in the sandbox","name":"path","in":"query"}],"responses":{"200":{"description":"File content","content":{"text/plain":{"schema":{"type":"string"}},"application/octet-stream":{"schema":{"type":"string"}}}},"400":{"description":"Invalid path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Sandbox or file not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/chat/sandbox/{sessionId}/file/signed-url":{"get":{"summary":"Get sandbox file download URL","description":"Get a pre-signed URL for direct file download from the sandbox","tags":["Chat"],"parameters":[{"schema":{"type":"string","description":"Session ID that owns the sandbox"},"required":true,"description":"Session ID that owns the sandbox","name":"sessionId","in":"path"},{"schema":{"type":"string","description":"File path in the sandbox"},"required":true,"description":"File path in the sandbox","name":"path","in":"query"}],"responses":{"200":{"description":"Pre-signed download URL","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SandboxFileUrlResponse"}}}},"400":{"description":"Invalid path or path is not a file","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Sandbox or file not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/chat/sandbox/{sessionId}/folder/list":{"get":{"summary":"List sandbox folder contents","description":"List files and folders in a sandbox directory","tags":["Chat"],"parameters":[{"schema":{"type":"string","description":"Session ID that owns the sandbox"},"required":true,"description":"Session ID that owns the sandbox","name":"sessionId","in":"path"},{"schema":{"type":"string","description":"Directory path in the sandbox (default: /home/user/workspace)"},"required":false,"description":"Directory path in the sandbox (default: /home/user/workspace)","name":"path","in":"query"},{"schema":{"type":"integer","minimum":0,"exclusiveMinimum":true,"maximum":500,"default":100,"description":"Max items to return"},"required":false,"description":"Max items to return","name":"limit","in":"query"},{"schema":{"type":"integer","nullable":true,"minimum":0,"default":0,"description":"Pagination offset"},"required":false,"description":"Pagination offset","name":"offset","in":"query"},{"schema":{"type":"boolean","nullable":true,"default":true,"description":"Include hidden files"},"required":false,"description":"Include hidden files","name":"showHidden","in":"query"}],"responses":{"200":{"description":"List of files and folders","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListSandboxFilesResponse"}}}},"400":{"description":"Invalid path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Session not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/chat/sandbox/{sessionId}/file/info":{"get":{"summary":"Get sandbox file info","description":"Get metadata for a file or folder in a sandbox","tags":["Chat"],"parameters":[{"schema":{"type":"string","description":"Session ID that owns the sandbox"},"required":true,"description":"Session ID that owns the sandbox","name":"sessionId","in":"path"},{"schema":{"type":"string","description":"File or folder path in the sandbox"},"required":true,"description":"File or folder path in the sandbox","name":"path","in":"query"}],"responses":{"200":{"description":"File or folder info","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SandboxFileInfoResponse"}}}},"400":{"description":"Invalid path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Session or file not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/chat/sandbox/{sessionId}/files/download":{"post":{"summary":"Download sandbox files (batch)","description":"Prepare download for multiple files/folders. Returns signed URLs for client-side ZIP creation.","tags":["Chat"],"parameters":[{"schema":{"type":"string","description":"Session ID that owns the sandbox"},"required":true,"description":"Session ID that owns the sandbox","name":"sessionId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SandboxDownloadRequest"}}}},"responses":{"200":{"description":"Download metadata with signed URLs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SandboxDownloadResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Session or sandbox not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/chat/sessions/{sessionId}/participate":{"post":{"summary":"Participate in chat session","description":"Join a visible chat session as a participant so you can send messages","tags":["Chat"],"parameters":[{"schema":{"type":"string","description":"Session ID"},"required":true,"description":"Session ID","name":"sessionId","in":"path"}],"responses":{"200":{"description":"Session participation updated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SessionParticipantsResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Session not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/chat/sessions/{sessionId}/leave":{"post":{"summary":"Leave chat session","description":"Leave a chat session you previously joined as a participant","tags":["Chat"],"parameters":[{"schema":{"type":"string","description":"Session ID"},"required":true,"description":"Session ID","name":"sessionId","in":"path"}],"responses":{"200":{"description":"Session participation updated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SessionParticipantsResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Session not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/chat/sessions/{sessionId}/system-message":{"patch":{"summary":"Update system message","description":"Rewrite the persisted system message using a SystemPreset","tags":["Chat"],"parameters":[{"schema":{"type":"string","description":"Session ID"},"required":true,"description":"Session ID","name":"sessionId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateSystemMessageRequest"}}}},"responses":{"200":{"description":"System message updated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateSystemMessageResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Access denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Session or preset reference not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/chat/sessions/{sessionId}/delete-impact":{"get":{"summary":"Get chat session delete impact","description":"Return counts of subscriptions that will be deleted with a chat session","tags":["Chat"],"parameters":[{"schema":{"type":"string","description":"Session ID"},"required":true,"description":"Session ID","name":"sessionId","in":"path"}],"responses":{"200":{"description":"Session delete impact","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SessionDeleteImpactResponse"}}}},"404":{"description":"Session not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/chat/sessions/{sessionId}/cleanup":{"post":{"summary":"Clean up session resources","description":"Clean up specific resources for a session. Pass a resources array to target specific resource types (e.g., code_contexts). Without a body, falls back to legacy behavior (kill sandbox).","tags":["Chat"],"parameters":[{"schema":{"type":"string","description":"Session ID"},"required":true,"description":"Session ID","name":"sessionId","in":"path"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"resources":{"type":"array","items":{"type":"string","enum":["code_contexts","sandbox"]},"minItems":1,"description":"Resources to clean up. Each value targets a specific resource type."}},"required":["resources"]}}}},"responses":{"200":{"description":"Resources cleaned up successfully","content":{"application/json":{"schema":{"type":"object","properties":{"codeContexts":{"type":"object","properties":{"removed":{"type":"number","description":"Number of code contexts removed"}},"required":["removed"]},"sandbox":{"type":"object","properties":{"paused":{"type":"boolean","description":"Whether the sandbox timeout was reduced to trigger auto-pause"}},"required":["paused"]},"sandboxKilled":{"type":"boolean","description":"Whether a sandbox was killed (legacy)"}}}}}},"400":{"description":"Invalid request body (malformed JSON or invalid resources)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Session not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/chat/sessions/{sessionId}/clone":{"post":{"summary":"Clone chat session","description":"Clone an existing chat session with all its messages","tags":["Chat"],"parameters":[{"schema":{"type":"string","description":"Session ID to clone"},"required":true,"description":"Session ID to clone","name":"sessionId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","description":"Optional title for the cloned session"}}}}}},"responses":{"201":{"description":"Session cloned successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CloneChatSessionResponse"}}}},"404":{"description":"Original session not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Original session is currently running","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/chat/sessions/{sessionId}/messages":{"get":{"summary":"List older turn loops (paginate-up + optional bridge-to-message)","description":"Return whole turn loops strictly before `beforeLoopId`, in ascending (loop, seq) order. When `includeMessageId` is set, the result is extended back far enough to include that message’s loop, plus `overscan` more older loops, so the FE can prepend a contiguous range. When `includeMessageId` is absent, returns just `overscan` loops (default 5).","tags":["Chat"],"parameters":[{"schema":{"type":"string","description":"Session ID"},"required":true,"description":"Session ID","name":"sessionId","in":"path"},{"schema":{"type":"string","minLength":1,"description":"Required anchor cursor (exclusive). Result includes only loops strictly older."},"required":true,"description":"Required anchor cursor (exclusive). Result includes only loops strictly older.","name":"beforeLoopId","in":"query"},{"schema":{"type":"string","minLength":1,"description":"Optional. When set, the result is extended back far enough to include the loop containing this message. If the message is already in (or newer than) the rendered window, the response is `{ messages: [], hasMore: false }`."},"required":false,"description":"Optional. When set, the result is extended back far enough to include the loop containing this message. If the message is already in (or newer than) the rendered window, the response is `{ messages: [], hasMore: false }`.","name":"includeMessageId","in":"query"},{"schema":{"type":"integer","nullable":true,"minimum":0,"maximum":1000,"description":"Extra older loops to load beyond the natural target. Acts as page size when `includeMessageId` is absent. Default 5. Bounded by 1000 as a server-side sanity ceiling — not a UX-relevant cap."},"required":false,"description":"Extra older loops to load beyond the natural target. Acts as page size when `includeMessageId` is absent. Default 5. Bounded by 1000 as a server-side sanity ceiling — not a UX-relevant cap.","name":"loopLimit","in":"query"},{"schema":{"type":"integer","nullable":true,"minimum":0,"maximum":1000,"description":"**Deprecated.** Legacy alias for `loopLimit` kept for rolling-deploy backward compatibility. When both `loopLimit` and `overscan` are present, `loopLimit` wins and a deprecation warning is logged. Will be removed once all clients have migrated."},"required":false,"description":"**Deprecated.** Legacy alias for `loopLimit` kept for rolling-deploy backward compatibility. When both `loopLimit` and `overscan` are present, `loopLimit` wins and a deprecation warning is logged. Will be removed once all clients have migrated.","name":"overscan","in":"query"}],"responses":{"200":{"description":"Page of older turn loops (contiguous, ascending by (loop, seq)).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListMessagesResponse"}}}},"404":{"description":"Session, `beforeLoopId`, or `includeMessageId` not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/chat/sessions/{sessionId}/messages/edit":{"patch":{"summary":"Edit chat messages","description":"Apply multiple edits (delete or modify) to messages in a chat session","tags":["Chat"],"parameters":[{"schema":{"type":"string","description":"Session ID"},"required":true,"description":"Session ID","name":"sessionId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EditMessageRequest"}}}},"responses":{"200":{"description":"Messages edited successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EditMessageResponse"}}}},"404":{"description":"Session or message not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/chat/sessions/{sessionId}/messages/{messageId}/feedback":{"post":{"summary":"Submit feedback for a message","description":"Submit thumbs up/down feedback for an assistant message","tags":["Chat"],"parameters":[{"schema":{"type":"string","description":"Session ID"},"required":true,"description":"Session ID","name":"sessionId","in":"path"},{"schema":{"type":"string","description":"Message ID to provide feedback for"},"required":true,"description":"Message ID to provide feedback for","name":"messageId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"feedbackValue":{"type":"number","nullable":true},"feedbackBlob":{"type":"object","additionalProperties":{"nullable":true}}}}}}},"responses":{"201":{"description":"Feedback submitted successfully","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"messageId":{"type":"string"},"sessionId":{"type":"string"},"feedbackValue":{"type":"number","nullable":true},"feedbackBlob":{"type":"object","additionalProperties":{"nullable":true}},"timestamp":{"type":"string"}},"required":["id","messageId","sessionId","feedbackValue","feedbackBlob","timestamp"]}}}},"400":{"description":"Bad request - invalid feedback or message type","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Message not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"summary":"Delete feedback for a message","description":"Remove previously submitted feedback for a message","tags":["Chat"],"parameters":[{"schema":{"type":"string","description":"Session ID"},"required":true,"description":"Session ID","name":"sessionId","in":"path"},{"schema":{"type":"string","description":"Message ID to remove feedback from"},"required":true,"description":"Message ID to remove feedback from","name":"messageId","in":"path"}],"responses":{"204":{"description":"Feedback deleted successfully"},"404":{"description":"Feedback not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/chat/feedback/export":{"get":{"summary":"Export feedback data","description":"Export feedback data for training in JSONL or JSON format","tags":["Chat"],"parameters":[{"schema":{"type":"string","description":"Start date (ISO 8601)"},"required":false,"description":"Start date (ISO 8601)","name":"startDate","in":"query"},{"schema":{"type":"string","description":"End date (ISO 8601)"},"required":false,"description":"End date (ISO 8601)","name":"endDate","in":"query"}],"responses":{"200":{"description":"Feedback data exported successfully","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"user_message":{"type":"string"},"assistant_message":{"type":"string"},"feedback_value":{"type":"number","nullable":true},"feedback_blob":{"type":"object","additionalProperties":{"nullable":true}},"session_id":{"type":"string"},"timestamp":{"type":"string"}},"required":["user_message","assistant_message","feedback_value","feedback_blob","session_id","timestamp"]}},"count":{"type":"number"}},"required":["data","count"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/chat/sessions/{sessionId}/feedback":{"get":{"summary":"Get feedback for a session","description":"Get all message feedback for a session as a { messageId: feedbackValue } map. Fetched separately from session entries for performance.","tags":["Chat"],"parameters":[{"schema":{"type":"string","description":"Session ID"},"required":true,"description":"Session ID","name":"sessionId","in":"path"}],"responses":{"200":{"description":"Feedback map returned successfully","content":{"application/json":{"schema":{"type":"object","additionalProperties":{"type":"number"},"description":"Map of messageId to feedbackValue (1 = thumbs up, -1 = thumbs down)"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/chat/sessions/{sessionId}/tools/execute":{"post":{"summary":"Execute a tool directly","description":"Execute a specific tool without going through the chat loop","tags":["Chat"],"parameters":[{"schema":{"type":"string","description":"Session ID"},"required":true,"description":"Session ID","name":"sessionId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExecuteToolRequest"}}}},"responses":{"200":{"description":"Tool executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExecuteToolResponse"}}}},"404":{"description":"Session not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/chat/sessions/{sessionId}/tool-content/signed-url":{"post":{"summary":"Get signed URL for tool content","description":"Get a signed URL to directly download full tool content from GCS","tags":["Chat"],"parameters":[{"schema":{"type":"string","description":"Session ID"},"required":true,"description":"Session ID","name":"sessionId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"path":{"type":"string","description":"GCS path to tool content"},"size":{"type":"number","description":"Size of content in bytes"}},"required":["path","size"]}}}},"responses":{"200":{"description":"Signed URL generated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"signedUrl":{"type":"string","format":"uri","description":"Signed URL for direct download"}},"required":["signedUrl"]}}}},"400":{"description":"Bad request - invalid path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Session not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/chat/sessions/{sessionId}/agent-view":{"get":{"summary":"Get agent view for a session","description":"Get the agent view representation of a chat session in Claude message format","tags":["Chat"],"parameters":[{"schema":{"type":"string","description":"Session ID"},"required":true,"description":"Session ID","name":"sessionId","in":"path"}],"responses":{"200":{"description":"Agent view retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentViewResponse"}}}},"404":{"description":"Session not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/chat/sessions/{sessionId}/queued-inputs":{"get":{"summary":"List queued inputs","description":"List pending inputs in the session queue (session_loop_inputs with status=pending)","tags":["Chat"],"parameters":[{"schema":{"type":"string"},"required":true,"name":"sessionId","in":"path"}],"responses":{"200":{"description":"List of pending queued inputs","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"messageId":{"type":"string"},"message":{"type":"object","additionalProperties":{"nullable":true}},"source":{"type":"string"},"steer":{"type":"boolean"},"createdAt":{"type":"string"}},"required":["id","messageId","message","source","steer","createdAt"]}}},"required":["items"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/chat/sessions/{sessionId}/queued-inputs/{messageId}":{"delete":{"summary":"Delete a queued input","description":"Remove a pending input from the session queue","tags":["Chat"],"parameters":[{"schema":{"type":"string"},"required":true,"name":"sessionId","in":"path"},{"schema":{"type":"string"},"required":true,"name":"messageId","in":"path"}],"responses":{"200":{"description":"Whether the input was deleted","content":{"application/json":{"schema":{"type":"object","properties":{"deleted":{"type":"boolean"}},"required":["deleted"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"summary":"Update a queued input","description":"Update the message content of a pending input in the session queue","tags":["Chat"],"parameters":[{"schema":{"type":"string"},"required":true,"name":"sessionId","in":"path"},{"schema":{"type":"string"},"required":true,"name":"messageId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"$ref":"#/components/schemas/ChatMessage"},"steer":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Whether the input was updated","content":{"application/json":{"schema":{"type":"object","properties":{"updated":{"type":"boolean"}},"required":["updated"]}}}},"400":{"description":"Invalid message format","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/models":{"get":{"summary":"List available models","description":"List the chat model catalog with UI visibility metadata","tags":["Models"],"responses":{"200":{"description":"Available chat models","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListAvailableModelsResponse"}}}}}}},"/api/v1/models/preferences":{"get":{"summary":"Get user model preferences","description":"Get the current user model preferences for this organization","tags":["Models"],"responses":{"200":{"description":"User model preferences","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserModelPreferences"}}}}}},"patch":{"summary":"Update user model preferences","description":"Update the current user model preferences for this organization","tags":["Models"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserModelPreferencesPatch"}}}},"responses":{"200":{"description":"User model preferences","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserModelPreferences"}}}},"400":{"description":"Requested model is not available for this organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/mission-controls":{"get":{"summary":"List Mission Controls","description":"List Mission Controls for the current organization","tags":["Mission Controls"],"parameters":[{"schema":{"type":"string","enum":["active","archived","all"],"default":"active","description":"Filter by status. \"active\" (default) returns only active Mission Controls, \"archived\" returns only archived ones, \"all\" returns both."},"required":false,"description":"Filter by status. \"active\" (default) returns only active Mission Controls, \"archived\" returns only archived ones, \"all\" returns both.","name":"status","in":"query"}],"responses":{"200":{"description":"Mission Controls","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MissionControlListResponse"}}}}}},"post":{"summary":"Create Mission Control","description":"Create a DB-backed Mission Control for the current organization","tags":["Mission Controls"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateMissionControl"}}}},"responses":{"201":{"description":"Mission Control created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MissionControl"}}}},"400":{"description":"Invalid request"},"409":{"description":"Mission Control slug already exists"}}}},"/api/v1/mission-controls/{missionControlId}":{"get":{"summary":"Get Mission Control","description":"Get a Mission Control descriptor by slug or row ID","tags":["Mission Controls"],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"missionControlId","in":"path"}],"responses":{"200":{"description":"Mission Control descriptor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MissionControlDetailResponse"}}}},"404":{"description":"Mission Control not found"}}},"patch":{"summary":"Update Mission Control","description":"Update a DB-backed Mission Control","tags":["Mission Controls"],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"missionControlId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateMissionControl"}}}},"responses":{"200":{"description":"Mission Control updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MissionControl"}}}},"400":{"description":"Invalid request"},"403":{"description":"Forbidden – tenant admin required for status changes"},"404":{"description":"Mission Control not found"},"409":{"description":"Mission Control update conflict"}}}},"/api/v1/mission-controls/{missionControlId}/contextbases":{"get":{"summary":"List Mission Control contextbases","description":"List contextbase mounts attached to a Mission Control","tags":["Mission Controls"],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"missionControlId","in":"path"}],"responses":{"200":{"description":"Mission Control contextbases","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MissionControlContextBaseListResponse"}}}},"404":{"description":"Mission Control not found"}}},"post":{"summary":"Attach Mission Control contextbase","description":"Attach a contextbase repo to a Mission Control","tags":["Mission Controls"],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"missionControlId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateMissionControlContextBase"}}}},"responses":{"201":{"description":"Mission Control contextbase attached","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MissionControlContextBase"}}}},"400":{"description":"Invalid contextbase link"},"404":{"description":"Mission Control or contextbase not found"},"409":{"description":"Mission Control contextbase conflict"}}}},"/api/v1/mission-controls/{missionControlId}/contextbases/provision":{"post":{"summary":"Provision Mission Control contextbase","description":"Provision a contextbase repo for the current organization and attach it","tags":["Mission Controls"],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"missionControlId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProvisionMissionControlContextBase"}}}},"responses":{"201":{"description":"Mission Control contextbase provisioned and attached","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MissionControlContextBase"}}}},"400":{"description":"Invalid contextbase link"},"404":{"description":"Mission Control not found"},"409":{"description":"Mission Control contextbase conflict"}}}},"/api/v1/mission-controls/{missionControlId}/contextbases/{contextBaseLinkId}":{"patch":{"summary":"Update Mission Control contextbase","description":"Update a Mission Control contextbase attachment","tags":["Mission Controls"],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"missionControlId","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"contextBaseLinkId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateMissionControlContextBase"}}}},"responses":{"200":{"description":"Mission Control contextbase updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MissionControlContextBase"}}}},"400":{"description":"Invalid contextbase link"},"404":{"description":"Mission Control or contextbase link not found"},"409":{"description":"Mission Control contextbase conflict"}}},"delete":{"summary":"Unlink Mission Control contextbase","description":"Unlink a non-primary contextbase attachment from a Mission Control","tags":["Mission Controls"],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"missionControlId","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"contextBaseLinkId","in":"path"}],"responses":{"204":{"description":"Mission Control contextbase unlinked"},"400":{"description":"Primary contextbase links cannot be unlinked"},"404":{"description":"Mission Control or contextbase link not found"}}}},"/api/v1/mission-controls/{missionControlId}/bootstrap":{"get":{"summary":"Bootstrap Mission Control","description":"Get Mission Control descriptor and primary reference metadata for shell bootstrap","tags":["Mission Controls"],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"missionControlId","in":"path"}],"responses":{"200":{"description":"Mission Control bootstrap payload","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MissionControlBootstrapResponse"}}}},"404":{"description":"Mission Control not found"}}}},"/api/v1/mission-controls/{missionControlId}/signals":{"get":{"summary":"List Mission Control signals","description":"List signals for a Mission Control from the contextbase database.","tags":["Mission Controls"],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"missionControlId","in":"path"}],"responses":{"200":{"description":"Mission Control signals","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MissionControlSignalsResponse"}}}},"404":{"description":"Mission Control not found"}}}},"/api/v1/mission-controls/{missionControlId}/skills":{"get":{"summary":"List Mission Control skills","description":"List contextbase skills available to a Mission Control with pinned state.","tags":["Mission Controls"],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"missionControlId","in":"path"}],"responses":{"200":{"description":"Mission Control skills","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MissionControlSkillsResponse"}}}},"404":{"description":"Mission Control not found"}}}},"/api/v1/mission-controls/{missionControlId}/skill-pins":{"put":{"summary":"Update Mission Control skill pin","description":"Pin or unpin a contextbase skill for Mission Control sessions.","tags":["Mission Controls"],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"missionControlId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateMissionControlSkillPin"}}}},"responses":{"200":{"description":"Mission Control skill pin updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MissionControlSkillsResponse"}}}},"400":{"description":"Bad request – pin limit exceeded"},"403":{"description":"Forbidden – tenant admin required"},"404":{"description":"Mission Control or skill not found"}}}},"/api/v1/mission-controls/{missionControlId}/activity":{"get":{"summary":"List personal Mission Control activity","description":"Personal activity inbox for a Mission Control. Shows MC-tagged activity visible to the authenticated user, with per-user read and dismiss state.","tags":["Mission Controls"],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"missionControlId","in":"path"},{"schema":{"type":"string","default":"50","description":"Max items to return (1–200)"},"required":false,"description":"Max items to return (1–200)","name":"limit","in":"query"},{"schema":{"type":"string","description":"Composite cursor `<ISO createdAt>|<uuid id>`. Pass empty or omit for the first page."},"required":false,"description":"Composite cursor `<ISO createdAt>|<uuid id>`. Pass empty or omit for the first page.","name":"cursor","in":"query"},{"schema":{"type":"string","enum":["chat","agent","updates","other"],"description":"Optional category filter: `chat` → chat.*, `agent` → session.*, `updates` → announcement.*, `other` → none of the above."},"required":false,"description":"Optional category filter: `chat` → chat.*, `agent` → session.*, `updates` → announcement.*, `other` → none of the above.","name":"category","in":"query"}],"responses":{"200":{"description":"MC activity feed","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["event"]},"id":{"type":"string","format":"uuid"},"orgId":{"type":"string"},"actorId":{"type":"string","nullable":true},"action":{"type":"string"},"resourceType":{"type":"string"},"resourceId":{"type":"string","nullable":true},"details":{"type":"object","additionalProperties":{"nullable":true}},"createdAt":{"type":"string"},"readAt":{"type":"string","nullable":true},"recipientId":{"type":"string","nullable":true}},"required":["type","id","orgId","actorId","action","resourceType","resourceId","details","createdAt","readAt","recipientId"]}},"unreadCount":{"type":"integer"},"categoryUnreadCount":{"type":"integer"},"mentionUnreadCount":{"type":"integer"},"notificationUnreadCount":{"type":"integer"},"nextCursor":{"type":"string","nullable":true},"actors":{"type":"object","additionalProperties":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string","nullable":true},"email":{"type":"string"}},"required":["id","name","email"]}}},"required":["items","unreadCount","nextCursor"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"404":{"description":"Mission Control not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/api/v1/mission-controls/{missionControlId}/activity/read":{"post":{"summary":"Mark MC activity items as read","description":"Mark specific events or all visible events in this personal Mission Control activity inbox as read. Org/global activity may be lazily materialized for this user; targeted activity is updated only when already addressed to this user.","tags":["Mission Control"],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"missionControlId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"eventIds":{"type":"array","items":{"type":"string","format":"uuid"},"maxItems":100},"all":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Marked as read","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"eventIds":{"type":"array","items":{"type":"string","format":"uuid"}}},"required":["success","eventIds"]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Mission Control not found"},"500":{"description":"Internal error"}}}},"/api/v1/mission-controls/{missionControlId}/activity/dismiss":{"post":{"summary":"Dismiss MC activity items","description":"Dismiss visible events so they no longer appear in this personal Mission Control activity inbox.","tags":["Mission Control"],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"missionControlId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"eventIds":{"type":"array","items":{"type":"string","format":"uuid"},"minItems":1,"maxItems":100}},"required":["eventIds"]}}}},"responses":{"200":{"description":"Dismissed","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}},"required":["success"]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Mission Control not found"},"500":{"description":"Internal error"}}}},"/api/v1/presets/render":{"post":{"summary":"Render a SystemPreset into final system instructions","description":"Renders a SystemPreset configuration (presetName + optional extends + operations) into a final system prompt string.","tags":["Presets"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SystemPreset"}}}},"responses":{"200":{"description":"Rendered system instructions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RenderPresetResponse"}}}}}}},"/api/v1/presets":{"get":{"summary":"Get a preset by name","description":"Returns the full preset markdown (frontmatter + template) by presetName.","tags":["Presets"],"parameters":[{"schema":{"type":"string"},"required":true,"name":"presetName","in":"query"}],"responses":{"200":{"description":"Preset content","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetPresetResponse"}}}},"404":{"description":"Preset not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/presets/list":{"get":{"summary":"List all presets from registry","description":"Returns all presets available in the preset registry (e.g., general-agent, environment).","tags":["Presets"],"responses":{"200":{"description":"List of all presets from registry","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListPresetsResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/projects":{"get":{"summary":"List projects","description":"Get a paginated list of projects for the organization","tags":["Projects"],"parameters":[{"schema":{"type":"string"},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string"},"required":false,"name":"offset","in":"query"},{"schema":{"type":"string","enum":["active","completed","archived"]},"required":false,"name":"status","in":"query"},{"schema":{"type":"string"},"required":false,"name":"type","in":"query"},{"schema":{"type":"string"},"required":false,"name":"workflow_id","in":"query"},{"schema":{"type":"string"},"required":false,"name":"sop_id","in":"query"},{"schema":{"type":"string"},"required":false,"name":"app_id","in":"query"},{"schema":{"type":"string"},"required":false,"name":"mission_control_id","in":"query"},{"schema":{"type":"string"},"required":false,"name":"created_by","in":"query"},{"schema":{"type":"string"},"required":false,"name":"include_launcher_data","in":"query"}],"responses":{"200":{"description":"List of projects","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectListResponse"}}}}}},"post":{"summary":"Create project","description":"Create a new project","tags":["Projects"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateProject"}}}},"responses":{"201":{"description":"Project created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Project"}}}},"400":{"description":"Invalid request data"},"409":{"description":"Project name already exists in this team"}}}},"/api/v1/projects/{id}":{"get":{"summary":"Get project","description":"Get a specific project by ID","tags":["Projects"],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string"},"required":false,"name":"include_launcher_data","in":"query"}],"responses":{"200":{"description":"Project details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Project"}}}},"404":{"description":"Project not found"}}},"put":{"summary":"Update project","description":"Update an existing project","tags":["Projects"],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateProject"}}}},"responses":{"200":{"description":"Project updated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Project"}}}},"400":{"description":"Invalid request data"},"404":{"description":"Project not found"},"409":{"description":"Project name already exists in this team"}}},"delete":{"summary":"Archive project","description":"Archive a project (soft delete)","tags":["Projects"],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"204":{"description":"Project archived successfully"},"404":{"description":"Project not found"}}}},"/api/v1/projects/{id}/phases":{"get":{"summary":"List project phases","description":"Get the ordered phase plan for a project","tags":["Projects"],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Ordered project phases","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectPhaseListResponse"}}}},"404":{"description":"Project not found"}}},"post":{"summary":"Create project phase","description":"Add a phase to a project phase plan","tags":["Projects"],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateProjectPhase"}}}},"responses":{"201":{"description":"Project phase created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectPhase"}}}},"404":{"description":"Project not found"}}}},"/api/v1/projects/{id}/phases/{phaseId}":{"patch":{"summary":"Update project phase","description":"Update phase state or metadata for a project","tags":["Projects"],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"phaseId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateProjectPhase"}}}},"responses":{"200":{"description":"Project phase updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectPhase"}}}},"404":{"description":"Project phase not found"}}}},"/api/v1/projects/{id}/tasks":{"post":{"summary":"Create project task","description":"Create an agent task attached to a project","tags":["Projects"],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"project_phase_id":{"type":"string","nullable":true,"format":"uuid"},"project_phase_key":{"type":"string"},"title":{"type":"string","nullable":true},"body":{"type":"string","nullable":true},"input_artifact_id":{"type":"string","nullable":true},"payload":{"type":"object","additionalProperties":{"nullable":true}},"attachments":{"type":"array","items":{"type":"string"}},"labels":{"type":"array","items":{"type":"string"}},"status":{"type":"string","enum":["open","blocked","completed","closed"]},"creator_session_id":{"type":"string","nullable":true}}}}}},"responses":{"201":{"description":"Task created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentTask"}}}},"404":{"description":"Project not found"}}},"get":{"summary":"List project tasks","description":"Get agent tasks attached to a project","tags":["Projects"],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"},{"schema":{"type":"integer","minimum":1,"maximum":200,"default":50,"description":"Max items to return"},"required":false,"description":"Max items to return","name":"limit","in":"query"},{"schema":{"type":"integer","nullable":true,"minimum":0,"default":0,"description":"Pagination offset"},"required":false,"description":"Pagination offset","name":"offset","in":"query"},{"schema":{"type":"string","description":"Filter by creator session"},"required":false,"description":"Filter by creator session","name":"creator_session_id","in":"query"},{"schema":{"type":"string","description":"Filter by assigned session (via agent_task_assignments)"},"required":false,"description":"Filter by assigned session (via agent_task_assignments)","name":"assignee_session_id","in":"query"},{"schema":{"type":"string","description":"Comma-separated valid project UUIDs for bulk project task lookup"},"required":false,"description":"Comma-separated valid project UUIDs for bulk project task lookup","name":"project_ids","in":"query"},{"schema":{"type":"string","format":"uuid","description":"Filter by project phase ID"},"required":false,"description":"Filter by project phase ID","name":"project_phase_id","in":"query"},{"schema":{"type":"string","description":"Filter by project phase key"},"required":false,"description":"Filter by project phase key","name":"project_phase_key","in":"query"},{"schema":{"type":"string","enum":["open","blocked","completed","closed"],"description":"Filter by task status"},"required":false,"description":"Filter by task status","name":"status","in":"query"},{"schema":{"type":"string","description":"Filter to tasks containing this label (e.g. ai-overview)"},"required":false,"description":"Filter to tasks containing this label (e.g. ai-overview)","name":"label","in":"query"},{"schema":{"type":"string","format":"date-time","description":"Only tasks created after this timestamp"},"required":false,"description":"Only tasks created after this timestamp","name":"created_after","in":"query"},{"schema":{"type":"string","format":"date-time","description":"Only tasks created before this timestamp"},"required":false,"description":"Only tasks created before this timestamp","name":"created_before","in":"query"},{"schema":{"type":"string","enum":["created_at"],"default":"created_at","description":"Sort field"},"required":false,"description":"Sort field","name":"order_by","in":"query"},{"schema":{"type":"string","enum":["asc","desc"],"default":"desc","description":"Sort direction"},"required":false,"description":"Sort direction","name":"order","in":"query"},{"schema":{"type":"string","description":"Comma-separated relations to include: submissions, comments"},"required":false,"description":"Comma-separated relations to include: submissions, comments","name":"include","in":"query"}],"responses":{"200":{"description":"Paginated list of project tasks","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentTaskListResponse"}}}},"404":{"description":"Project not found"}}}},"/api/v1/projects/{id}/sessions":{"post":{"summary":"Link session to project","description":"Link a session to a project","tags":["Projects"],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"session_id":{"type":"string"},"branch_name":{"type":"string","nullable":true},"role":{"type":"string","nullable":true,"enum":["leader","subagent","observer",null]}},"required":["session_id"]}}}},"responses":{"201":{"description":"Session linked successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SessionProject"}}}},"404":{"description":"Project not found"},"409":{"description":"Session already linked to this project"}}},"get":{"summary":"List project sessions","description":"List all sessions linked to a project","tags":["Projects"],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"List of session-project links","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SessionProjectListResponse"}}}},"404":{"description":"Project not found"}}}},"/api/v1/projects/{id}/sessions/{sessionId}":{"delete":{"summary":"Unlink session from project","description":"Remove a session from a project","tags":["Projects"],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string"},"required":true,"name":"sessionId","in":"path"}],"responses":{"204":{"description":"Session unlinked successfully"},"404":{"description":"Link not found"}}}},"/api/v1/rater-apps":{"post":{"summary":"Create a new rater app","description":"Publishes a new rater app to the workspace repo main branch via the GitHub API.  Returns the URL to navigate to.","tags":["Rater Apps"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"description":"Friendly rater name, e.g. \"Progressive CO\""}},"required":["name"]}}}},"responses":{"201":{"description":"Rater app created","content":{"application/json":{"schema":{"type":"object","properties":{"app_id":{"type":"string"},"title":{"type":"string"},"project_name":{"type":"string","description":"Name of the auto-created project"},"url":{"type":"string","description":"URL to navigate to after creation"}},"required":["app_id","title","project_name","url"]}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"409":{"description":"App already exists","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/api/v1/async-jobs/greet":{"post":{"tags":["Async Jobs"],"summary":"Schedule a greet async job","description":"Schedules an async greet job that will say hello to the provided name","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100,"description":"Name to greet"}},"required":["name"]}}}},"responses":{"201":{"description":"Job scheduled successfully","content":{"application/json":{"schema":{"type":"object","properties":{"jobId":{"type":"string","description":"Unique async job ID"},"status":{"type":"string","description":"Job status"},"message":{"type":"string","description":"Success message"}},"required":["jobId","status","message"]}}}},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message"},"details":{"type":"string","description":"Additional error details"}},"required":["error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message"},"details":{"type":"string","description":"Additional error details"}},"required":["error"]}}}}}}},"/api/v1/async-jobs/{jobId}/status":{"get":{"tags":["Async Jobs"],"summary":"Get async job status","description":"Gets the current status and details of an async job by ID","parameters":[{"schema":{"type":"string","description":"Async job ID to get status for"},"required":true,"description":"Async job ID to get status for","name":"jobId","in":"path"}],"responses":{"200":{"description":"Job status retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"jobId":{"type":"string","description":"Unique async job ID"},"executionId":{"type":"string","description":"Execution ID of the job"},"status":{"type":"string","description":"Job status"},"historyLength":{"type":"number","description":"Number of events in job history"},"memo":{"type":"object","additionalProperties":{"nullable":true},"description":"Job memo"},"searchAttributes":{"type":"object","additionalProperties":{"nullable":true},"description":"Job search attributes"}},"required":["jobId","status"]}}}},"404":{"description":"Job not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message"},"details":{"type":"string","description":"Additional error details"}},"required":["error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message"},"details":{"type":"string","description":"Additional error details"}},"required":["error"]}}}}}}},"/api/v1/async-jobs/greet/{jobId}/result":{"get":{"tags":["Async Jobs"],"summary":"Get greet async job result","description":"Gets the result of a greet async job execution","parameters":[{"schema":{"type":"string","description":"Async job ID to get result for"},"required":true,"description":"Async job ID to get result for","name":"jobId","in":"path"}],"responses":{"200":{"description":"Job result retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"jobId":{"type":"string","description":"Unique async job ID"},"result":{"type":"string","description":"Async job execution result"},"status":{"type":"string","description":"Job status"}},"required":["jobId","result","status"]}}}},"404":{"description":"Job not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message"},"details":{"type":"string","description":"Additional error details"}},"required":["error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message"},"details":{"type":"string","description":"Additional error details"}},"required":["error"]}}}}}}},"/api/v1/events":{"post":{"summary":"Enqueue an event","description":"Creates a durable event and triggers processing.","tags":["Webhooks"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnqueueEventRequest"}}}},"responses":{"201":{"description":"Event queued","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnqueueEventResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Session not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/scheduled-tasks":{"post":{"summary":"Schedule a task","description":"Schedules a task to run immediately or after a delay. Each task type defines its own config schema. Idempotency key is derived from the config automatically.","tags":["Scheduled Tasks"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScheduleTaskRequest"}}}},"responses":{"201":{"description":"Task scheduled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScheduleTaskResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/inbox/items":{"get":{"summary":"List inbox items","description":"List inbox items for a session, filtered by unread/read/all.","tags":["Inbox"],"parameters":[{"schema":{"type":"string","minLength":1,"description":"Chat session ID"},"required":true,"description":"Chat session ID","name":"sessionId","in":"query"},{"schema":{"type":"string","enum":["unread","read","all"],"description":"Filter by read status (default: all)"},"required":false,"description":"Filter by read status (default: all)","name":"status","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":200,"description":"Max items to return"},"required":false,"description":"Max items to return","name":"limit","in":"query"},{"schema":{"type":"integer","nullable":true,"minimum":0,"description":"Offset for pagination"},"required":false,"description":"Offset for pagination","name":"offset","in":"query"}],"responses":{"200":{"description":"Inbox items","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListInboxItemsResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"summary":"Create an inbox item","description":"Create an inbox item directly (decoupled from events).","tags":["Inbox"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateInboxItemRequest"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateInboxItemResponse"}}}},"404":{"description":"Session not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/inbox/items/{id}/peek":{"get":{"summary":"Peek at an inbox item","description":"Get a single inbox item by ID without changing its read status.","tags":["Inbox"],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Inbox item","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InboxItem"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/inbox/items/{id}/read":{"post":{"summary":"Read an inbox item","description":"Get a single inbox item by ID and mark it as read (idempotent). Returns the item with updated status.","tags":["Inbox"],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Inbox item (marked as read)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InboxItem"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/inbox/items/mark-read":{"post":{"summary":"Mark inbox items read","description":"Mark a set of inbox items as read (idempotent).","tags":["Inbox"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarkInboxItemsReadRequest"}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarkInboxItemsReadResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/inbox/items/{id}":{"delete":{"summary":"Delete an inbox item","description":"Delete an inbox item by id.","tags":["Inbox"],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Deleted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeleteInboxItemResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/subscriptions/schedule-types":{"get":{"summary":"List supported schedule types for scheduled subscriptions","description":"Returns the supported schedule types that sessions can use.","tags":["Subscriptions"],"responses":{"200":{"description":"Supported schedule types","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionScheduleTypesResponse"}}}}}}},"/api/v1/subscriptions":{"post":{"summary":"Create a scheduled SERFF subscription","description":"Create a scheduled SERFF subscription with schedule config, optional filters, and a prompt/instruction.","tags":["Subscriptions"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateScheduledSubscriptionRequest"}}}},"responses":{"200":{"description":"Existing subscription returned (idempotent create)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateScheduledSubscriptionResponse"}}}},"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateScheduledSubscriptionResponse"}}}},"400":{"description":"Invalid filter criteria","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — insufficient permissions for requested event subtypes","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"summary":"List scheduled SERFF subscriptions","description":"List subscriptions for this org (optionally filtered by sessionId).","tags":["Subscriptions"],"parameters":[{"schema":{"type":"string","minLength":1},"required":false,"name":"sessionId","in":"query"},{"schema":{"type":"string","enum":["scheduled_trigger","serff_filing_update"]},"required":false,"name":"eventType","in":"query"},{"schema":{"type":"string","enum":["hourly","daily","weekly","cron"]},"required":false,"name":"scheduleType","in":"query"},{"schema":{"type":"string","enum":["server","agent"]},"required":false,"name":"filterMode","in":"query"},{"schema":{"type":"string","minLength":1,"description":"Filter by creator"},"required":false,"description":"Filter by creator","name":"createdBy","in":"query"},{"schema":{"type":"boolean","nullable":true,"description":"If true, show all subscriptions regardless of creator"},"required":false,"description":"If true, show all subscriptions regardless of creator","name":"ignoreCreatedBy","in":"query"},{"schema":{"type":"string","enum":["active","paused"],"description":"Filter by status (active, paused)"},"required":false,"description":"Filter by status (active, paused)","name":"status","in":"query"},{"schema":{"type":"string","minLength":1,"description":"Filter spawn-mode subscriptions whose presetRef.appId matches"},"required":false,"description":"Filter spawn-mode subscriptions whose presetRef.appId matches","name":"presetAppId","in":"query"},{"schema":{"type":"string","minLength":1,"description":"Filter spawn-mode subscriptions whose presetRef.agentName matches"},"required":false,"description":"Filter spawn-mode subscriptions whose presetRef.agentName matches","name":"presetAgentName","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":200},"required":false,"name":"limit","in":"query"},{"schema":{"type":"integer","nullable":true,"minimum":0},"required":false,"name":"offset","in":"query"}],"responses":{"200":{"description":"Subscriptions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListScheduledSerffSubscriptionsResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/subscriptions/{id}":{"get":{"summary":"Get a scheduled subscription","description":"Get a single scheduled subscription by ID.","tags":["Subscriptions"],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Subscription details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScheduledSerffSubscription"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"summary":"Update a scheduled subscription","description":"Update a scheduled subscription. Can modify filterCriteria, scheduleType, cronExpression, timezone, instruction, or filterMode.","tags":["Subscriptions"],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateSubscriptionRequest"}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateSubscriptionResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden - not authorized to modify this subscription","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"summary":"Delete a scheduled subscription","description":"Delete a scheduled subscription row.","tags":["Subscriptions"],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Deleted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeleteSessionSubscriptionResponse"}}}},"403":{"description":"Forbidden - not authorized to delete this subscription","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Subscription not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/subscriptions/{id}/cursor":{"post":{"summary":"Set a scheduled subscription cursor","description":"Sets or clears the per-subscription cursor (into the events table). Can move backward or forward. Optionally updates startTime.","tags":["Subscriptions"],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SetScheduledSubscriptionCursorRequest"}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SetScheduledSubscriptionCursorResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Not authorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/subscriptions/{id}/pause":{"post":{"summary":"Pause a subscription","description":"Pause a subscription. While paused, the subscription will not scan for events or create inbox items.","tags":["Subscriptions"],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Paused","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PauseSubscriptionResponse"}}}},"403":{"description":"Not authorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/subscriptions/{id}/resume":{"post":{"summary":"Resume a subscription","description":"Resume a paused subscription. The subscription will continue scanning for events from where it left off.","tags":["Subscriptions"],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Resumed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResumeSubscriptionResponse"}}}},"403":{"description":"Not authorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/subscriptions/{id}/run-now":{"post":{"summary":"Trigger immediate subscription run","description":"Triggers an immediate run of the subscription. By default runs in preview mode (does not advance cursor). Set advanceCursor=true to advance cursor and nextRunTs like a scheduled run. Works on both active and paused subscriptions.","tags":["Subscriptions"],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"advanceCursor":{"type":"boolean","default":false,"description":"If true, advances the cursor and nextRunTs after the run, like a scheduled run. If false (default), runs in preview mode without advancing."}},"description":"Options for the run. If not provided, runs in preview mode (advanceCursor=false)."}}}},"responses":{"200":{"description":"Triggered","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRunNowResponse"}}}},"403":{"description":"Not authorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A manual run is already in progress","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRunNowResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/subscriptions/dry-run":{"post":{"summary":"Preview subscription filter results","description":"Runs the same filter matching logic as a real subscription but returns results immediately without persisting. Use to validate filters before creating a subscription.","tags":["Subscriptions"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionDryRunRequest"}}}},"responses":{"200":{"description":"Dry run results","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionDryRunResponse"}}}},"400":{"description":"Invalid filter criteria","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/event-watchers":{"post":{"tags":["Event Watchers"],"summary":"Create an event watcher","description":"Register a push-based watcher that delivers matching events to the configured sink.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateWatcherRequest"}}}},"responses":{"201":{"description":"Watcher created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WatcherItem"}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — caller may not register a watcher in the requested scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"tags":["Event Watchers"],"summary":"List event watchers","description":"List active event watchers, optionally filtered by event type and by fields inside the polymorphic deliveryConfig (e.g. sessionId). Super-admins may pass `scope='global'` to list cross-tenant monitor watchers.","parameters":[{"schema":{"type":"string","enum":["promise","github_webhook","agent_task","session_lifecycle","serff_filing","incoming_webhook"]},"required":false,"name":"eventType","in":"query"},{"schema":{"type":"string","enum":["org","global"]},"required":false,"name":"scope","in":"query"},{"schema":{"type":"string","minLength":1,"description":"Filter watchers whose deliveryConfig targets this session. Matches on delivery_config->>\"sessionId\" and therefore covers both session_inbox and sandbox_webhook delivery variants."},"required":false,"description":"Filter watchers whose deliveryConfig targets this session. Matches on delivery_config->>\"sessionId\" and therefore covers both session_inbox and sandbox_webhook delivery variants.","name":"sessionId","in":"query"}],"responses":{"200":{"description":"List of active watchers","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListWatchersResponse"}}}},"403":{"description":"Forbidden — caller may not list watchers in the requested scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/event-watchers/{id}":{"delete":{"tags":["Event Watchers"],"summary":"Delete an event watcher","description":"Cancel and remove an event watcher by ID. Super-admins may pass `scope='global'` to delete a cross-tenant monitor watcher.","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","enum":["org","global"]},"required":false,"name":"scope","in":"query"}],"responses":{"200":{"description":"Watcher deleted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeleteWatcherResponse"}}}},"403":{"description":"Forbidden — caller may not delete watchers in the requested scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Watcher not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/config":{"get":{"summary":"List config items","description":"Get all configuration items for the organization","tags":["Config"],"responses":{"200":{"description":"List config items","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ConfigItemResponse"}}}}}}},"put":{"summary":"Update config items","description":"Upsert configuration items for the organization","tags":["Config"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/ConfigItem"}}},"required":["items"]}}}},"responses":{"200":{"description":"Upserted"}}},"delete":{"tags":["Config"],"summary":"Reset config items to default","description":"Delete org-specific overrides for the given keys, resetting them to the global default or hardcoded default.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"keys":{"type":"array","items":{"type":"string","minLength":1}}},"required":["keys"]}}}},"responses":{"200":{"description":"Overrides deleted"}}}},"/api/v1/cost-metering/sessions/{sessionId}/costs":{"get":{"summary":"Get session costs","description":"Get aggregated credit usage for a session. For root sessions, aggregates credits across all subagent sessions. For subagent sessions, returns only the direct credit usage without aggregation. Users can only view costs for sessions they created; Super Admins can view any session.","tags":["Cost Metering"],"parameters":[{"schema":{"type":"string","minLength":1,"description":"The session ID to get costs for"},"required":true,"description":"The session ID to get costs for","name":"sessionId","in":"path"}],"responses":{"200":{"description":"Session costs","content":{"application/json":{"schema":{"type":"object","properties":{"sessionId":{"type":"string"},"totalCredits":{"type":"string"}},"required":["sessionId","totalCredits"]}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden - user does not have access to this session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Session not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/cost-metering/my-usage":{"get":{"summary":"Get current user usage","description":"Credit usage for the authenticated user within a time range. No admin role required — scoped to the caller.","tags":["Cost Metering"],"parameters":[{"schema":{"type":"string","format":"date-time","description":"Start of time range (ISO 8601)"},"required":true,"description":"Start of time range (ISO 8601)","name":"from","in":"query"},{"schema":{"type":"string","format":"date-time","description":"End of time range (ISO 8601)"},"required":true,"description":"End of time range (ISO 8601)","name":"to","in":"query"}],"responses":{"200":{"description":"Usage summary for current user","content":{"application/json":{"schema":{"type":"object","properties":{"credits":{"type":"string"}},"required":["credits"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/cost-metering/my-cost-control-status":{"get":{"summary":"Get cost control status for the current user","description":"Returns pre-computed cost-control policy statuses that apply to the authenticated user (via user-scope, group-scope, or app-scope policies in warn mode). Lightweight indexed read — no aggregation. Pass sessionId to include app-scope policies resolved from the session's root tags.","tags":["Cost Metering"],"parameters":[{"schema":{"type":"string","description":"Session ID to resolve app-scope policies from root session tags"},"required":false,"description":"Session ID to resolve app-scope policies from root session tags","name":"sessionId","in":"query"}],"responses":{"200":{"description":"Cost control statuses for the current user","content":{"application/json":{"schema":{"type":"object","properties":{"entries":{"type":"array","items":{"type":"object","properties":{"policyId":{"type":"string","format":"uuid"},"scopeType":{"type":"string","enum":["user","app","group"]},"scopeId":{"type":"string"},"scopeName":{"type":"string","nullable":true},"policyScopeType":{"type":"string","enum":["user","app","group"]},"period":{"type":"string","enum":["daily","weekly","monthly"]},"mode":{"type":"string","enum":["monitor","warn","enforce"]},"status":{"type":"string","enum":["ok","warning","exceeded"]},"usedCredits":{"type":"string"},"limitCredits":{"type":"string"},"usagePercent":{"type":"string"},"periodStart":{"type":"string"},"periodEnd":{"type":"string"},"warningMessage":{"type":"string","nullable":true},"exceededMessage":{"type":"string","nullable":true}},"required":["policyId","scopeType","scopeId","scopeName","policyScopeType","period","mode","status","usedCredits","limitCredits","usagePercent","periodStart","periodEnd","warningMessage","exceededMessage"]}},"worstStatus":{"type":"string","enum":["ok","warning","exceeded"]}},"required":["entries","worstStatus"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/chat-search/search":{"post":{"summary":"Search chat messages","description":"Hybrid vector + keyword search over indexed chat messages. Returns sessions ranked by relevance, with snippets from matching messages. Results are scoped to user's org.","tags":["Chat"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string","minLength":1,"description":"Search query text"},"topK":{"type":"integer","minimum":1,"maximum":100,"default":20,"description":"Number of results to return (default: 20, max: 100)"},"messageCreatedAfter":{"type":"string","format":"date-time","description":"Only include messages with message_created_at >= this (ISO 8601)"},"messageCreatedBefore":{"type":"string","format":"date-time","description":"Only include messages with message_created_at <= this (ISO 8601)"},"sessionCreatedAfter":{"type":"string","format":"date-time","description":"Only include sessions with session_created_at >= this (ISO 8601)"},"sessionCreatedBefore":{"type":"string","format":"date-time","description":"Only include sessions with session_created_at <= this (ISO 8601)"},"role":{"type":"string","enum":["user","assistant"],"description":"Filter by message role (user or assistant)"},"users":{"type":"string","enum":["all","current"],"default":"current","description":"User scope: \"current\" (default) restricts to your chats, \"all\" searches across all users in the org (Tenant Admin or above)"},"agentType":{"type":"string","description":"Filter by agent type (case-insensitive regex, e.g. \"coder\", \"^coder$\", \"code(r|_explorer)\")"}},"required":["query"]}}}},"responses":{"200":{"description":"Search results","content":{"application/json":{"schema":{"type":"object","properties":{"sessions":{"type":"array","items":{"type":"object","properties":{"sessionId":{"type":"string"},"sessionTitle":{"type":"string","nullable":true},"userId":{"type":"string","description":"User ID of the session owner"},"score":{"type":"number"},"matchCount":{"type":"number"},"snippets":{"type":"array","items":{"type":"string"}},"createdAt":{"type":"string","format":"date-time","description":"Earliest matching message time (backward compat)"},"messageCreatedAt":{"type":"string","format":"date-time","description":"Earliest matching message timestamp"},"sessionCreatedAt":{"type":"string","format":"date-time","description":"Session creation timestamp"},"agentType":{"type":"string","nullable":true,"description":"Agent type label (e.g. \"general\", \"coder\", \"rater_builder\")"}},"required":["sessionId","sessionTitle","userId","score","matchCount","snippets","createdAt","messageCreatedAt","sessionCreatedAt","agentType"]}},"query":{"type":"string"},"topK":{"type":"number"}},"required":["sessions","query","topK"]}}}},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden - users=all requires Tenant Admin or above"},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/databases":{"post":{"summary":"Provision database","description":"Provision a managed database for the current organization","tags":["Databases"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProvisionDatabaseRequest"}}}},"responses":{"201":{"description":"Database provisioned successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProvisionDatabaseResponse"}}}},"400":{"description":"Invalid request or missing provider credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"summary":"List databases","description":"List provisioned databases for the current organization","tags":["Databases"],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"required":false,"name":"limit","in":"query"},{"schema":{"type":"integer","nullable":true,"minimum":0,"default":0},"required":false,"name":"offset","in":"query"}],"responses":{"200":{"description":"List of provisioned databases","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DatabaseListResponse"}}}}}}},"/api/v1/databases/{id}":{"get":{"summary":"Get database","description":"Get a provisioned database by ID","tags":["Databases"],"parameters":[{"schema":{"type":"string","format":"uuid","description":"Database ID"},"required":true,"description":"Database ID","name":"id","in":"path"}],"responses":{"200":{"description":"Database metadata","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Database"}}}},"404":{"description":"Database not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"summary":"Delete database","description":"Deprovision a managed database and remove its record","tags":["Databases"],"parameters":[{"schema":{"type":"string","format":"uuid","description":"Database ID"},"required":true,"description":"Database ID","name":"id","in":"path"}],"responses":{"204":{"description":"Database deleted successfully"},"400":{"description":"Missing provider credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Database not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/databases/{id}/branches":{"post":{"summary":"Create database branch","description":"Create a provider branch for a provisioned database","tags":["Databases"],"parameters":[{"schema":{"type":"string","format":"uuid","description":"Database ID"},"required":true,"description":"Database ID","name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateDatabaseBranchRequest"}}}},"responses":{"201":{"description":"Branch created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProvisionedDatabaseBranch"}}}},"400":{"description":"Invalid request or missing provider credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Database not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"summary":"List database branches","description":"List provider branches for a provisioned database","tags":["Databases"],"parameters":[{"schema":{"type":"string","format":"uuid","description":"Database ID"},"required":true,"description":"Database ID","name":"id","in":"path"}],"responses":{"200":{"description":"Database branches","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/DatabaseBranch"}}}}},"400":{"description":"Missing provider credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Database not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/databases/{id}/branches/{branch_id}":{"delete":{"summary":"Delete database branch","description":"Delete a provider branch for a provisioned database","tags":["Databases"],"parameters":[{"schema":{"type":"string","format":"uuid","description":"Database ID"},"required":true,"description":"Database ID","name":"id","in":"path"},{"schema":{"type":"string","description":"Provider branch ID"},"required":true,"description":"Provider branch ID","name":"branch_id","in":"path"}],"responses":{"204":{"description":"Branch deleted successfully"},"400":{"description":"Missing provider credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Database not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/databases/{id}/connection-uri":{"get":{"summary":"Get database connection info","description":"Get connection details for a database branch","tags":["Databases"],"parameters":[{"schema":{"type":"string","format":"uuid","description":"Database ID"},"required":true,"description":"Database ID","name":"id","in":"path"},{"schema":{"type":"string","description":"Provider branch ID"},"required":false,"description":"Provider branch ID","name":"branch_id","in":"query"},{"schema":{"type":"string","description":"Database name override"},"required":false,"description":"Database name override","name":"database","in":"query"},{"schema":{"type":"string","description":"Database role override"},"required":false,"description":"Database role override","name":"role","in":"query"}],"responses":{"200":{"description":"Database connection info","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DatabaseConnectionInfo"}}}},"400":{"description":"Missing provider credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Database or branch not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/databases/{id}/postgrest-credentials":{"get":{"summary":"Get PostgREST credentials","description":"Return PostgREST authenticator URI and JWT secret derived from a server-side root secret. Self-heals the database role hierarchy on first call.","tags":["Databases"],"parameters":[{"schema":{"type":"string","format":"uuid","description":"Database ID"},"required":true,"description":"Database ID","name":"id","in":"path"},{"schema":{"type":"string","description":"Provider branch ID"},"required":false,"description":"Provider branch ID","name":"branch_id","in":"query"}],"responses":{"200":{"description":"PostgREST authenticator URI and JWT secret","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PostgrestCredentials"}}}},"400":{"description":"Missing provider credentials or root secret","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Database or branch not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/kvstore/{namespace}/{key}":{"get":{"summary":"Get value by namespace and key","description":"Retrieve a value from the key-value store","tags":["KV Store"],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"namespace","in":"path"},{"schema":{"type":"string","minLength":1},"required":true,"name":"key","in":"path"}],"responses":{"200":{"description":"Value retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KvStoreItem"}}}},"404":{"description":"Key not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"put":{"summary":"Upsert value","description":"Create or update a value in the key-value store","tags":["KV Store"],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"namespace","in":"path"},{"schema":{"type":"string","minLength":1},"required":true,"name":"key","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/KvStoreUpsertRequest"}}}},"responses":{"200":{"description":"Value upserted successfully (created or updated)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KvStoreItem"}}}}}},"delete":{"summary":"Delete value","description":"Delete a key-value pair from the store","tags":["KV Store"],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"namespace","in":"path"},{"schema":{"type":"string","minLength":1},"required":true,"name":"key","in":"path"}],"responses":{"204":{"description":"Value deleted successfully"},"404":{"description":"Key not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/kvstore/{namespace}":{"get":{"summary":"List all keys in namespace","description":"Get all key-value pairs within a namespace","tags":["KV Store"],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"namespace","in":"path"}],"responses":{"200":{"description":"List of all key-value pairs in namespace","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/KvStoreItem"}}}}}}}},"/api/v1/retrieval-index/{id}":{"get":{"summary":"Get retrieval index entry by ID","description":"Retrieve a single retrieval index entry","tags":["Retrieval Index"],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Retrieval index entry retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RetrievalIndexItem"}}}},"404":{"description":"Entry not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/retrieval-index":{"get":{"summary":"List retrieval index entries","description":"List retrieval index entries with optional filters","tags":["Retrieval Index"],"parameters":[{"schema":{"type":"string"},"required":false,"name":"namespace","in":"query"},{"schema":{"type":"string"},"required":false,"name":"documentIdPrefix","in":"query"},{"schema":{"type":"string"},"required":false,"name":"uriPrefix","in":"query"},{"schema":{"type":"string"},"required":false,"name":"variant","in":"query"},{"schema":{"type":"string"},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"List of retrieval index entries","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/RetrievalIndexItem"}}}}}}}},"/api/v1/retrieval-index/search":{"post":{"summary":"Search retrieval index by similarity","description":"Search for retrieval index entries using semantic similarity","tags":["Retrieval Index"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchRetrievalIndexRequest"}}}},"responses":{"200":{"description":"Search results sorted by similarity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchRetrievalIndexResponse"}}}},"400":{"description":"Invalid request or embedding generation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/shares":{"post":{"summary":"Create a static conversation snapshot","description":"Stores a static, non-interactive HTML snapshot for public sharing. Returns a share slug and public URL path.","tags":["Shares"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateShareRequest"}}}},"responses":{"201":{"description":"Snapshot created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateShareResponse"}}}},"400":{"description":"Bad request"},"500":{"description":"Internal server error"}}}},"/api/v1/shares/{id}":{"delete":{"summary":"Delete a share","description":"Revokes a share by deleting it from storage and database","tags":["Shares"],"parameters":[{"schema":{"type":"string","format":"uuid","description":"Share ID"},"required":true,"description":"Share ID","name":"id","in":"path"}],"responses":{"204":{"description":"Share deleted successfully"},"404":{"description":"Share not found"},"500":{"description":"Internal server error"}}}},"/api/v1/vault/folder/list":{"post":{"summary":"List folder contents","description":"List contents of a folder with pagination and sorting. Returns 400 if URI points to a file. Returns 404 if folder does not exist. Default sort: folders first, then alphabetical by name.","tags":["Vault"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"uri":{"type":"string","minLength":1,"description":"Folder URI to list. Must be a folder, not a file."},"limit":{"type":"integer","minimum":1,"maximum":1000,"default":100,"description":"Max items to return"},"offset":{"type":"integer","minimum":0,"default":0,"description":"Pagination offset"},"orderBy":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string","enum":["name","modifiedAt","createdAt","type"],"description":"Field to sort by"},"dir":{"type":"string","enum":["asc","desc"],"default":"asc","description":"Sort direction"}},"required":["field"]},"description":"Sort order as array of {field, dir} objects. Default: [{field:\"type\",dir:\"desc\"},{field:\"name\",dir:\"asc\"}] (folders first, then alphabetical)"},"showHidden":{"type":"boolean","default":true,"description":"Whether to include hidden files (files starting with a dot). Default: true (all files are shown for backwards compatibility)"}},"required":["uri"]}}}},"responses":{"200":{"description":"Folder contents","content":{"application/json":{"schema":{"type":"object","properties":{"uri":{"type":"string","minLength":1,"description":"Listed folder URI - items are anchored at this path"},"folder":{"oneOf":[{"$ref":"#/components/schemas/FileArtifact"},{"$ref":"#/components/schemas/FolderArtifact"},{"$ref":"#/components/schemas/ReportArtifact"}],"discriminator":{"propertyName":"type","mapping":{"file":"#/components/schemas/FileArtifact","folder":"#/components/schemas/FolderArtifact","report":"#/components/schemas/ReportArtifact"}},"description":"The folder artifact being listed."},"items":{"type":"array","items":{"$ref":"#/components/schemas/Artifact"},"description":"Artifact items in the folder"},"total":{"type":"integer","description":"Total items at root level"},"limit":{"type":"integer","description":"Applied limit"},"offset":{"type":"integer","description":"Applied offset"}},"required":["uri","folder","items","total","limit","offset"]}}}},"400":{"description":"Invalid URI","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["VALIDATION_ERROR","PERMISSION_DENIED","NOT_FOUND","CONFLICT","INTERNAL_ERROR"],"description":"Error code identifying the type of error"},"message":{"type":"string","description":"Human-readable error message"}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"Permission denied","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["VALIDATION_ERROR","PERMISSION_DENIED","NOT_FOUND","CONFLICT","INTERNAL_ERROR"],"description":"Error code identifying the type of error"},"message":{"type":"string","description":"Human-readable error message"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"Folder not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["VALIDATION_ERROR","PERMISSION_DENIED","NOT_FOUND","CONFLICT","INTERNAL_ERROR"],"description":"Error code identifying the type of error"},"message":{"type":"string","description":"Human-readable error message"}},"required":["code","message"]}},"required":["error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["VALIDATION_ERROR","PERMISSION_DENIED","NOT_FOUND","CONFLICT","INTERNAL_ERROR"],"description":"Error code identifying the type of error"},"message":{"type":"string","description":"Human-readable error message"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/api/v1/vault/info":{"post":{"summary":"Get item info","description":"Get artifact metadata for a file or folder. Returns the resolved vault URI (e.g., \"personal://path\") even when called with artifact:// URIs. Returns 404 if item does not exist.","tags":["Vault"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"uri":{"type":"string","minLength":1,"description":"Item URI to get info for"},"versionId":{"type":"string","description":"Optional version ID to get info for a specific file version"}},"required":["uri"]}}}},"responses":{"200":{"description":"Artifact metadata with resolved URI","content":{"application/json":{"schema":{"type":"object","properties":{"uri":{"type":"string","minLength":1,"description":"Resolved vault URI (e.g., \"personal://path/to/item\"). For artifact:// requests, this returns the canonical vault URI."},"artifact":{"oneOf":[{"$ref":"#/components/schemas/FileArtifact"},{"$ref":"#/components/schemas/FolderArtifact"},{"$ref":"#/components/schemas/ReportArtifact"}],"discriminator":{"propertyName":"type","mapping":{"file":"#/components/schemas/FileArtifact","folder":"#/components/schemas/FolderArtifact","report":"#/components/schemas/ReportArtifact"}},"description":"Artifact metadata"}},"required":["uri","artifact"]}}}},"400":{"description":"Invalid URI","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["VALIDATION_ERROR","PERMISSION_DENIED","NOT_FOUND","CONFLICT","INTERNAL_ERROR"],"description":"Error code identifying the type of error"},"message":{"type":"string","description":"Human-readable error message"}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"Permission denied","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["VALIDATION_ERROR","PERMISSION_DENIED","NOT_FOUND","CONFLICT","INTERNAL_ERROR"],"description":"Error code identifying the type of error"},"message":{"type":"string","description":"Human-readable error message"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"Item not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["VALIDATION_ERROR","PERMISSION_DENIED","NOT_FOUND","CONFLICT","INTERNAL_ERROR"],"description":"Error code identifying the type of error"},"message":{"type":"string","description":"Human-readable error message"}},"required":["code","message"]}},"required":["error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["VALIDATION_ERROR","PERMISSION_DENIED","NOT_FOUND","CONFLICT","INTERNAL_ERROR"],"description":"Error code identifying the type of error"},"message":{"type":"string","description":"Human-readable error message"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/api/v1/vault/folder/create":{"post":{"summary":"Create folder","description":"Create a folder at the specified URI. Idempotent: if folder exists, returns it (HTTP 200). Creates intermediate folders if needed (like mkdir -p). Returns 409 if path exists but is a file. Returns 403 for library:// unless user is superadmin.","tags":["Vault"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"uri":{"type":"string","minLength":1,"description":"Full URI for the new folder (e.g., \"personal://docs/reports\")"}},"required":["uri"]}}}},"responses":{"200":{"description":"Existing folder artifact (idempotent)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Artifact"}}}},"201":{"description":"Created folder artifact","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Artifact"}}}},"400":{"description":"Invalid URI","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["VALIDATION_ERROR","PERMISSION_DENIED","NOT_FOUND","CONFLICT","INTERNAL_ERROR"],"description":"Error code identifying the type of error"},"message":{"type":"string","description":"Human-readable error message"}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"Permission denied","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["VALIDATION_ERROR","PERMISSION_DENIED","NOT_FOUND","CONFLICT","INTERNAL_ERROR"],"description":"Error code identifying the type of error"},"message":{"type":"string","description":"Human-readable error message"}},"required":["code","message"]}},"required":["error"]}}}},"409":{"description":"Path exists but is a file","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["VALIDATION_ERROR","PERMISSION_DENIED","NOT_FOUND","CONFLICT","INTERNAL_ERROR"],"description":"Error code identifying the type of error"},"message":{"type":"string","description":"Human-readable error message"}},"required":["code","message"]}},"required":["error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["VALIDATION_ERROR","PERMISSION_DENIED","NOT_FOUND","CONFLICT","INTERNAL_ERROR"],"description":"Error code identifying the type of error"},"message":{"type":"string","description":"Human-readable error message"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/api/v1/vault/file/create":{"post":{"summary":"Create file","description":"Create a file at the specified URI with optional initial content. Creates intermediate folders if needed. Returns 409 if file already exists. For uploading files from disk, use /upload/init instead. Returns 403 for library:// unless user is superadmin.","tags":["Vault"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"uri":{"type":"string","minLength":1,"description":"Full URI for the new file (e.g., \"personal://docs/notes.txt\")"},"content":{"type":"string","description":"Initial file content (UTF-8 text)"},"mimeType":{"type":"string","description":"MIME type (auto-detected from extension if omitted)"}},"required":["uri"]}}}},"responses":{"201":{"description":"Created file artifact","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Artifact"}}}},"400":{"description":"Invalid URI","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["VALIDATION_ERROR","PERMISSION_DENIED","NOT_FOUND","CONFLICT","INTERNAL_ERROR"],"description":"Error code identifying the type of error"},"message":{"type":"string","description":"Human-readable error message"}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"Permission denied","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["VALIDATION_ERROR","PERMISSION_DENIED","NOT_FOUND","CONFLICT","INTERNAL_ERROR"],"description":"Error code identifying the type of error"},"message":{"type":"string","description":"Human-readable error message"}},"required":["code","message"]}},"required":["error"]}}}},"409":{"description":"File already exists","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["VALIDATION_ERROR","PERMISSION_DENIED","NOT_FOUND","CONFLICT","INTERNAL_ERROR"],"description":"Error code identifying the type of error"},"message":{"type":"string","description":"Human-readable error message"}},"required":["code","message"]}},"required":["error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["VALIDATION_ERROR","PERMISSION_DENIED","NOT_FOUND","CONFLICT","INTERNAL_ERROR"],"description":"Error code identifying the type of error"},"message":{"type":"string","description":"Human-readable error message"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/api/v1/vault/rename":{"post":{"summary":"Rename item","description":"Rename a file or folder in place. Returns 404 if item does not exist. Returns 409 if an item with the new name already exists in the same folder. To move and rename, use /move instead. Returns 403 for library:// items unless user is superadmin.","tags":["Vault"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"uri":{"type":"string","minLength":1,"description":"Item URI to rename"},"newName":{"type":"string","minLength":1,"maxLength":255,"description":"New name for the item (just the name, not a path)"}},"required":["uri","newName"]}}}},"responses":{"200":{"description":"Renamed artifact","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Artifact"}}}},"400":{"description":"Invalid URI","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["VALIDATION_ERROR","PERMISSION_DENIED","NOT_FOUND","CONFLICT","INTERNAL_ERROR"],"description":"Error code identifying the type of error"},"message":{"type":"string","description":"Human-readable error message"}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"Permission denied","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["VALIDATION_ERROR","PERMISSION_DENIED","NOT_FOUND","CONFLICT","INTERNAL_ERROR"],"description":"Error code identifying the type of error"},"message":{"type":"string","description":"Human-readable error message"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"Item not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["VALIDATION_ERROR","PERMISSION_DENIED","NOT_FOUND","CONFLICT","INTERNAL_ERROR"],"description":"Error code identifying the type of error"},"message":{"type":"string","description":"Human-readable error message"}},"required":["code","message"]}},"required":["error"]}}}},"409":{"description":"Name conflict","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["VALIDATION_ERROR","PERMISSION_DENIED","NOT_FOUND","CONFLICT","INTERNAL_ERROR"],"description":"Error code identifying the type of error"},"message":{"type":"string","description":"Human-readable error message"}},"required":["code","message"]}},"required":["error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["VALIDATION_ERROR","PERMISSION_DENIED","NOT_FOUND","CONFLICT","INTERNAL_ERROR"],"description":"Error code identifying the type of error"},"message":{"type":"string","description":"Human-readable error message"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/api/v1/vault/move":{"post":{"summary":"Move items","description":"Move one or more items to a destination folder. Supports cross-vault moves. Returns 404 if destination folder does not exist. Use onConflict to handle name conflicts: fail (report conflict), replace (overwrite files, merge folders), rename (auto-suffix, default). Returns 403 for library:// source or destination unless user is superadmin.","tags":["Vault"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"sources":{"type":"array","items":{"type":"string","minLength":1,"description":"Vault URI in the format scheme://path. Supported schemes: personal://, team://, library://, artifact://id[/path]"},"minItems":1,"maxItems":100,"description":"URIs of items to move (max 100)"},"destination":{"type":"string","minLength":1,"description":"Destination folder URI"},"onConflict":{"type":"string","enum":["fail","replace","rename"],"default":"rename","description":"How to handle name conflicts at destination (default: rename)"}},"required":["sources","destination"]}}}},"responses":{"200":{"description":"Move results","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"array","items":{"type":"object","properties":{"source":{"type":"string","minLength":1,"description":"Source URI"},"destination":{"type":"string","minLength":1,"description":"Destination URI (if successful)"},"renamed":{"type":"boolean","description":"True if item was auto-renamed"},"replaced":{"type":"boolean","description":"True if existing item was replaced"},"success":{"type":"boolean","description":"Whether the operation succeeded"},"error":{"type":"object","properties":{"code":{"type":"string","enum":["NOT_FOUND","CONFLICT","PERMISSION_DENIED","INTERNAL_ERROR"],"description":"Error code"},"message":{"type":"string","description":"Human-readable error message"},"existing":{"type":"object","properties":{"type":{"type":"string","enum":["file","folder"],"description":"Type of the existing item"},"name":{"type":"string","description":"Name of the existing item"},"size":{"type":"integer","description":"Size of existing file in bytes"},"modifiedAt":{"type":"string","description":"Last modified time (ISO 8601)"},"itemCount":{"type":"integer","description":"Number of items in existing folder"}},"required":["type","name"],"description":"Details of existing item at destination (only for CONFLICT errors)"}},"required":["code","message"],"description":"Error details (if failed)"}},"required":["source","success"]},"description":"Results for each source item"},"renamed":{"type":"object","additionalProperties":{"type":"string","minLength":1,"description":"Vault URI in the format scheme://path. Supported schemes: personal://, team://, library://, artifact://id[/path]"},"description":"Map of source URI → actual destination URI for auto-renamed items"}},"required":["results"]}}}},"400":{"description":"Invalid URI","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["VALIDATION_ERROR","PERMISSION_DENIED","NOT_FOUND","CONFLICT","INTERNAL_ERROR"],"description":"Error code identifying the type of error"},"message":{"type":"string","description":"Human-readable error message"}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"Permission denied","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["VALIDATION_ERROR","PERMISSION_DENIED","NOT_FOUND","CONFLICT","INTERNAL_ERROR"],"description":"Error code identifying the type of error"},"message":{"type":"string","description":"Human-readable error message"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"Destination not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["VALIDATION_ERROR","PERMISSION_DENIED","NOT_FOUND","CONFLICT","INTERNAL_ERROR"],"description":"Error code identifying the type of error"},"message":{"type":"string","description":"Human-readable error message"}},"required":["code","message"]}},"required":["error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["VALIDATION_ERROR","PERMISSION_DENIED","NOT_FOUND","CONFLICT","INTERNAL_ERROR"],"description":"Error code identifying the type of error"},"message":{"type":"string","description":"Human-readable error message"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/api/v1/vault/delete":{"post":{"summary":"Delete items","description":"Delete one or more items permanently. Folders are deleted recursively. Idempotent: returns success if item does not exist. Returns per-item success/failure status. Returns PERMISSION_DENIED for library:// items unless user is superadmin.","tags":["Vault"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"uris":{"type":"array","items":{"type":"string","minLength":1,"description":"Vault URI in the format scheme://path. Supported schemes: personal://, team://, library://, artifact://id[/path]"},"minItems":1,"maxItems":100,"description":"URIs of items to delete (max 100)"}},"required":["uris"]}}}},"responses":{"200":{"description":"Delete results","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"array","items":{"type":"object","properties":{"uri":{"type":"string","minLength":1,"description":"Deleted item URI"},"success":{"type":"boolean","description":"Whether the operation succeeded"},"error":{"type":"object","properties":{"code":{"type":"string","enum":["NOT_FOUND","PERMISSION_DENIED","INTERNAL_ERROR"],"description":"Error code"},"message":{"type":"string","description":"Human-readable error message"}},"required":["code","message"],"description":"Error details (if failed)"}},"required":["uri","success"]},"description":"Results for each URI"}},"required":["results"]}}}},"400":{"description":"Invalid URI","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["VALIDATION_ERROR","PERMISSION_DENIED","NOT_FOUND","CONFLICT","INTERNAL_ERROR"],"description":"Error code identifying the type of error"},"message":{"type":"string","description":"Human-readable error message"}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"Permission denied","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["VALIDATION_ERROR","PERMISSION_DENIED","NOT_FOUND","CONFLICT","INTERNAL_ERROR"],"description":"Error code identifying the type of error"},"message":{"type":"string","description":"Human-readable error message"}},"required":["code","message"]}},"required":["error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["VALIDATION_ERROR","PERMISSION_DENIED","NOT_FOUND","CONFLICT","INTERNAL_ERROR"],"description":"Error code identifying the type of error"},"message":{"type":"string","description":"Human-readable error message"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/api/v1/vault/upload/init":{"post":{"summary":"Initialize upload","description":"Initialize bulk upload and get signed URLs for direct storage upload. Use onConflict to handle existing files: fail (report conflict), replace (overwrite), rename (auto-suffix, default). After uploading files, call /upload/complete to create artifact records. Returns 403 for library:// target unless user is superadmin.","tags":["Vault"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"targetUri":{"type":"string","minLength":1,"description":"Target folder URI where files will be uploaded (e.g., \"personal://docs/reports\"). Required unless sessionId is provided."},"sessionId":{"type":"string","description":"Chat session ID. When provided, files are uploaded to the session folder (same location as chat composer base64 uploads). Mutually exclusive with targetUri."},"files":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","minLength":1,"description":"Relative path from target folder (e.g., \"file.pdf\" or \"subfolder/file.pdf\")"},"size":{"type":"integer","minimum":0,"description":"File size in bytes"},"mimeType":{"type":"string","description":"MIME type (auto-detected from extension if omitted)"},"metadata":{"type":"object","additionalProperties":{"nullable":true},"description":"Optional metadata to attach to the artifact on creation. Merged into ArtifactBase.metadata. Use namespaced sub-keys (e.g. metadata.jsonui = {...}) to avoid collisions with other writers. Reserved top-level keys (e.g. _appScope, _prevVisibility) are managed by the server and will be overridden if present in the request."}},"required":["path","size"]},"minItems":1,"maxItems":100,"description":"Files to upload (max 100 per request)"},"onConflict":{"type":"string","enum":["fail","replace","rename"],"default":"rename","description":"How to handle name conflicts (default: rename)"}},"required":["files"]}}}},"responses":{"200":{"description":"Upload session initialized","content":{"application/json":{"schema":{"type":"object","properties":{"targetUri":{"type":"string","minLength":1,"description":"Resolved target folder URI"},"files":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","description":"Actual path for upload (may differ from request if renamed)"},"originalPath":{"type":"string","description":"Original path from request (only present if renamed)"},"signedUrl":{"type":"string","format":"uri","description":"Pre-signed URL for direct PUT upload to storage"},"headers":{"type":"object","additionalProperties":{"type":"string"},"description":"Headers to include with PUT request (e.g., Content-Type)"},"expiresAt":{"type":"string","description":"URL expiration time (ISO 8601)"},"uploadToken":{"type":"string","description":"Opaque token containing upload metadata - pass back in complete request"},"willReplace":{"type":"boolean","description":"True if upload will replace an existing file (onConflict=replace)"}},"required":["path","signedUrl","expiresAt","uploadToken"]},"description":"Upload details for files to upload"},"conflicts":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","description":"Relative path or URI of the conflicting item"},"type":{"type":"string","enum":["file","folder"],"description":"Type of the existing item"},"existingName":{"type":"string","description":"Name of the existing item"},"existingSize":{"type":"integer","description":"Size of existing file (bytes)"},"existingModifiedAt":{"type":"string","description":"Last modified time (ISO 8601)"},"existingItemCount":{"type":"integer","description":"Number of items in existing folder"}},"required":["path","type","existingName"]},"description":"Files not included due to conflict (when onConflict=fail)"}},"required":["targetUri","files"]}}}},"400":{"description":"Invalid URI","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["VALIDATION_ERROR","PERMISSION_DENIED","NOT_FOUND","CONFLICT","INTERNAL_ERROR"],"description":"Error code identifying the type of error"},"message":{"type":"string","description":"Human-readable error message"}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"Permission denied","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["VALIDATION_ERROR","PERMISSION_DENIED","NOT_FOUND","CONFLICT","INTERNAL_ERROR"],"description":"Error code identifying the type of error"},"message":{"type":"string","description":"Human-readable error message"}},"required":["code","message"]}},"required":["error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["VALIDATION_ERROR","PERMISSION_DENIED","NOT_FOUND","CONFLICT","INTERNAL_ERROR"],"description":"Error code identifying the type of error"},"message":{"type":"string","description":"Human-readable error message"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/api/v1/vault/upload/complete":{"post":{"summary":"Complete upload","description":"Confirm file uploads after uploading to signed URLs. Creates artifact records and schedules indexing for text-like files. Returns per-file success/failure status. Returns 403 if user permissions changed since init.","tags":["Vault"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"confirmations":{"type":"array","items":{"type":"object","properties":{"uploadToken":{"type":"string","description":"Opaque token from init response"}},"required":["uploadToken"]},"minItems":1,"maxItems":100,"description":"Confirmations for successfully uploaded files"}},"required":["confirmations"]}}}},"responses":{"200":{"description":"Upload completed","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"array","items":{"type":"object","properties":{"uri":{"type":"string","minLength":1,"description":"Uploaded file URI"},"success":{"type":"boolean","description":"Whether the upload was confirmed successfully"},"artifact":{"oneOf":[{"$ref":"#/components/schemas/FileArtifact"},{"$ref":"#/components/schemas/FolderArtifact"},{"$ref":"#/components/schemas/ReportArtifact"}],"discriminator":{"propertyName":"type","mapping":{"file":"#/components/schemas/FileArtifact","folder":"#/components/schemas/FolderArtifact","report":"#/components/schemas/ReportArtifact"}},"description":"Created/updated artifact (if successful)"},"error":{"type":"object","properties":{"code":{"type":"string","enum":["PERMISSION_DENIED","NOT_FOUND","CONFLICT","INTERNAL_ERROR","INVALID_TOKEN","EXPIRED"],"description":"Error code: INVALID_TOKEN (corrupt, malformed, or mismatched token), EXPIRED (token has expired), NOT_FOUND (file not in storage), CONFLICT (unexpected conflict), PERMISSION_DENIED (user permissions changed), INTERNAL_ERROR (unexpected error)"},"message":{"type":"string","description":"Human-readable error message"}},"required":["code","message"],"description":"Error details (if failed)"}},"required":["uri","success"]},"description":"Results for each confirmation"}},"required":["results"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["VALIDATION_ERROR","PERMISSION_DENIED","NOT_FOUND","CONFLICT","INTERNAL_ERROR"],"description":"Error code identifying the type of error"},"message":{"type":"string","description":"Human-readable error message"}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"Permission denied","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["VALIDATION_ERROR","PERMISSION_DENIED","NOT_FOUND","CONFLICT","INTERNAL_ERROR"],"description":"Error code identifying the type of error"},"message":{"type":"string","description":"Human-readable error message"}},"required":["code","message"]}},"required":["error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["VALIDATION_ERROR","PERMISSION_DENIED","NOT_FOUND","CONFLICT","INTERNAL_ERROR"],"description":"Error code identifying the type of error"},"message":{"type":"string","description":"Human-readable error message"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/api/v1/vault/download":{"post":{"summary":"Prepare download","description":"Prepare metadata for downloading items (files and folders). Returns signed URLs for files. Returns 404 if any requested item does not exist. For single files, client can download directly. For multiple items, client builds ZIP.","tags":["Vault"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"uris":{"type":"array","items":{"type":"string","minLength":1,"description":"Vault URI in the format scheme://path. Supported schemes: personal://, team://, library://, artifact://id[/path]"},"minItems":1,"maxItems":100,"description":"URIs of items to download (files or folders)"},"maxFiles":{"type":"integer","minimum":1,"maximum":1000,"default":1000,"description":"Maximum number of files to include"},"maxDepth":{"type":"integer","minimum":1,"maximum":25,"default":25,"description":"Maximum folder depth to traverse"},"versionId":{"type":"string","description":"Optional version ID to download a specific file version. Only valid when downloading a single file URI. Ignored for folders."}},"required":["uris"]}}}},"responses":{"200":{"description":"Download metadata with signed URLs","content":{"application/json":{"schema":{"type":"object","properties":{"files":{"type":"array","items":{"type":"object","properties":{"uri":{"type":"string","minLength":1,"description":"File URI"},"name":{"type":"string","description":"File name"},"relativePath":{"type":"string","description":"Path within the ZIP archive"},"signedUrl":{"type":"string","format":"uri","description":"Pre-signed download URL"},"size":{"type":"integer","description":"File size in bytes"},"mimeType":{"type":"string","description":"MIME type"}},"required":["uri","name","relativePath","signedUrl","size"]},"description":"Files to download with signed URLs"},"totalItems":{"type":"integer","description":"Total items found"},"downloadedItems":{"type":"integer","description":"Items included in response"},"capped":{"type":"boolean","description":"Whether results were capped due to limits"},"warnings":{"type":"array","items":{"type":"string"},"description":"Warnings (e.g., skipped items)"},"estimatedSize":{"type":"integer","description":"Estimated total size in bytes"}},"required":["files","totalItems","downloadedItems","capped","warnings","estimatedSize"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["VALIDATION_ERROR","PERMISSION_DENIED","NOT_FOUND","CONFLICT","INTERNAL_ERROR"],"description":"Error code identifying the type of error"},"message":{"type":"string","description":"Human-readable error message"}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"Permission denied","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["VALIDATION_ERROR","PERMISSION_DENIED","NOT_FOUND","CONFLICT","INTERNAL_ERROR"],"description":"Error code identifying the type of error"},"message":{"type":"string","description":"Human-readable error message"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"Item not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["VALIDATION_ERROR","PERMISSION_DENIED","NOT_FOUND","CONFLICT","INTERNAL_ERROR"],"description":"Error code identifying the type of error"},"message":{"type":"string","description":"Human-readable error message"}},"required":["code","message"]}},"required":["error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["VALIDATION_ERROR","PERMISSION_DENIED","NOT_FOUND","CONFLICT","INTERNAL_ERROR"],"description":"Error code identifying the type of error"},"message":{"type":"string","description":"Human-readable error message"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/api/v1/vault/versions":{"post":{"summary":"List file versions","description":"List all versions of a file with versioning enabled. Returns version metadata including size, creation time, and whether it is the current version. Returns 400 if URI points to a folder or storage without versioning. Returns 404 if file does not exist.","tags":["Vault"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"uri":{"type":"string","minLength":1,"description":"File URI to list versions for"},"maxResults":{"type":"integer","minimum":1,"maximum":100,"description":"Maximum number of versions to return (default: 50)"},"pageToken":{"type":"string","description":"Pagination token from previous response"}},"required":["uri"]}}}},"responses":{"200":{"description":"List of file versions","content":{"application/json":{"schema":{"type":"object","properties":{"uri":{"type":"string","minLength":1,"description":"File URI that versions were listed for"},"versions":{"type":"array","items":{"type":"object","properties":{"versionId":{"type":"string","description":"Unique version identifier"},"size":{"type":"integer","description":"File size in bytes for this version"},"contentType":{"type":"string","description":"MIME type of this version"},"createdAt":{"type":"string","format":"date-time","description":"When this version was created (ISO 8601)"},"isCurrent":{"type":"boolean","description":"Whether this is the current/live version"},"metadata":{"type":"object","additionalProperties":{"type":"string"},"description":"Custom storage metadata attached to this version"}},"required":["versionId","size","createdAt","isCurrent"]},"description":"List of file versions (newest first)"},"nextPageToken":{"type":"string","description":"Token for fetching next page of results"}},"required":["uri","versions"]}}}},"400":{"description":"Invalid request (e.g., URI is a folder or storage without versioning)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["VALIDATION_ERROR","PERMISSION_DENIED","NOT_FOUND","CONFLICT","INTERNAL_ERROR"],"description":"Error code identifying the type of error"},"message":{"type":"string","description":"Human-readable error message"}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"Permission denied","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["VALIDATION_ERROR","PERMISSION_DENIED","NOT_FOUND","CONFLICT","INTERNAL_ERROR"],"description":"Error code identifying the type of error"},"message":{"type":"string","description":"Human-readable error message"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"File not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["VALIDATION_ERROR","PERMISSION_DENIED","NOT_FOUND","CONFLICT","INTERNAL_ERROR"],"description":"Error code identifying the type of error"},"message":{"type":"string","description":"Human-readable error message"}},"required":["code","message"]}},"required":["error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["VALIDATION_ERROR","PERMISSION_DENIED","NOT_FOUND","CONFLICT","INTERNAL_ERROR"],"description":"Error code identifying the type of error"},"message":{"type":"string","description":"Human-readable error message"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/api/v1/vault/share/list":{"post":{"summary":"List sharing grants on a vault node","description":"Lists all permission grants (viewer, editor, creator, deleter, admin) on a vault node. Grants cascade to descendants via parent hierarchy in SpiceDB.","tags":["Vault"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"nodeId":{"type":"string","format":"uuid","description":"Artifact ID of the vault node"}},"required":["nodeId"]}}}},"responses":{"200":{"description":"List of grants on this vault node","content":{"application/json":{"schema":{"type":"object","properties":{"grants":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"subjectType":{"type":"string","enum":["user","group"]},"subjectId":{"type":"string"},"relation":{"type":"string","enum":["viewer","editor","creator","deleter","admin"]},"createdBy":{"type":"string","nullable":true},"createdAt":{"type":"string"}},"required":["id","subjectType","subjectId","relation","createdBy","createdAt"]}}},"required":["grants"]}}}},"403":{"description":"Forbidden — requires manage permission on the vault node","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/vault/share/grant":{"post":{"summary":"Grant permission on a vault node","description":"Grants a user or group a permission (viewer, editor, creator, deleter, admin) on a vault node. The grant is written to the authz_grants table and reconciled into SpiceDB via the outbox. Permissions cascade to all descendants via parent hierarchy.","tags":["Vault"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"nodeId":{"type":"string","format":"uuid","description":"Artifact ID of the vault node to share"},"subjectType":{"type":"string","enum":["user","group"]},"subjectId":{"type":"string","minLength":1},"relation":{"type":"string","enum":["viewer","editor","creator","deleter","admin"]}},"required":["nodeId","subjectType","subjectId","relation"]}}}},"responses":{"201":{"description":"Permission granted","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"grant":{"type":"object","properties":{"id":{"type":"string"},"subjectType":{"type":"string","enum":["user","group"]},"subjectId":{"type":"string"},"relation":{"type":"string","enum":["viewer","editor","creator","deleter","admin"]},"createdBy":{"type":"string","nullable":true},"createdAt":{"type":"string"}},"required":["id","subjectType","subjectId","relation","createdBy","createdAt"]}},"required":["success","grant"]}}}},"403":{"description":"Forbidden — requires manage permission on the vault node","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/vault/share/revoke":{"post":{"summary":"Revoke permission on a vault node","description":"Revokes a previously granted permission on a vault node. The revocation is reconciled into SpiceDB via the outbox.","tags":["Vault"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"nodeId":{"type":"string","format":"uuid","description":"Artifact ID of the vault node"},"subjectType":{"type":"string","enum":["user","group"]},"subjectId":{"type":"string","minLength":1},"relation":{"type":"string","enum":["viewer","editor","creator","deleter","admin"]}},"required":["nodeId","subjectType","subjectId","relation"]}}}},"responses":{"200":{"description":"Permission revoked","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}},"required":["success"]}}}},"403":{"description":"Forbidden — requires manage permission on the vault node","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/vault/share/shared-with-me":{"post":{"summary":"List vault nodes shared with the current user","description":"Returns all vault nodes where the current user has been explicitly granted a permission (viewer, editor, creator, deleter, admin). Includes artifact name and type for display.","tags":["Vault"],"responses":{"200":{"description":"Items shared with the current user","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"objectId":{"type":"string","format":"uuid"},"relation":{"type":"string","enum":["viewer","editor","creator","deleter","admin"]},"artifactName":{"type":"string","nullable":true},"artifactNodeKind":{"type":"string","nullable":true}},"required":["objectId","relation","artifactName","artifactNodeKind"]}}},"required":["items"]}}}},"403":{"description":"Forbidden — vault sharing not enabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/admin/billing/summary":{"get":{"summary":"Get billing summary","description":"Aggregated credit usage for the tenant within a time range. Excludes internal user activity.","tags":["Admin/Billing"],"parameters":[{"schema":{"type":"string","format":"date-time","description":"Start of time range (ISO 8601)"},"required":true,"description":"Start of time range (ISO 8601)","name":"from","in":"query"},{"schema":{"type":"string","format":"date-time","description":"End of time range (ISO 8601)"},"required":true,"description":"End of time range (ISO 8601)","name":"to","in":"query"}],"responses":{"200":{"description":"Billing summary","content":{"application/json":{"schema":{"type":"object","properties":{"totalCredits":{"type":"string"},"creditsAllocated":{"type":"string"},"creditsLeft":{"type":"string"},"sessionCount":{"type":"number"},"activeUserCount":{"type":"number"}},"required":["totalCredits","creditsAllocated","creditsLeft","sessionCount","activeUserCount"]}}}},"400":{"description":"Invalid time range","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — Tenant Admin required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/admin/billing/users":{"get":{"summary":"Get billing breakdown by user","description":"Per-user credit usage for the tenant within a time range. Excludes internal user activity.","tags":["Admin/Billing"],"parameters":[{"schema":{"type":"string","format":"date-time","description":"Start of time range (ISO 8601)"},"required":true,"description":"Start of time range (ISO 8601)","name":"from","in":"query"},{"schema":{"type":"string","format":"date-time","description":"End of time range (ISO 8601)"},"required":true,"description":"End of time range (ISO 8601)","name":"to","in":"query"}],"responses":{"200":{"description":"User billing breakdown","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"userId":{"type":"number","nullable":true},"email":{"type":"string"},"name":{"type":"string","nullable":true},"totalCredits":{"type":"string"},"sessionCount":{"type":"number"}},"required":["userId","email","name","totalCredits","sessionCount"]}}}}},"400":{"description":"Invalid time range","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — Tenant Admin required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/admin/billing/by-app":{"get":{"summary":"Get billing breakdown by app","description":"Per-app credit usage for the tenant within a time range. Excludes internal user activity. Attribution is derived from app launch session tags.","tags":["Admin/Billing"],"parameters":[{"schema":{"type":"string","format":"date-time","description":"Start of time range (ISO 8601)"},"required":true,"description":"Start of time range (ISO 8601)","name":"from","in":"query"},{"schema":{"type":"string","format":"date-time","description":"End of time range (ISO 8601)"},"required":true,"description":"End of time range (ISO 8601)","name":"to","in":"query"}],"responses":{"200":{"description":"App billing breakdown","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"appId":{"type":"string"},"totalCredits":{"type":"string"},"sessionCount":{"type":"number"},"userCount":{"type":"number"}},"required":["appId","totalCredits","sessionCount","userCount"]}}}}},"400":{"description":"Invalid time range","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — Tenant Admin required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/admin/billing/by-agent":{"get":{"summary":"Get billing breakdown by agent","description":"Per-agent credit usage for the tenant within a time range. Excludes internal user activity. Attribution is derived from the agent:* session tag at the time each cost event was recorded.","tags":["Admin/Billing"],"parameters":[{"schema":{"type":"string","format":"date-time","description":"Start of time range (ISO 8601)"},"required":true,"description":"Start of time range (ISO 8601)","name":"from","in":"query"},{"schema":{"type":"string","format":"date-time","description":"End of time range (ISO 8601)"},"required":true,"description":"End of time range (ISO 8601)","name":"to","in":"query"}],"responses":{"200":{"description":"Agent billing breakdown","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"agentId":{"type":"string"},"totalCredits":{"type":"string"},"sessionCount":{"type":"number"},"userCount":{"type":"number"}},"required":["agentId","totalCredits","sessionCount","userCount"]}}}}},"400":{"description":"Invalid time range","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — Tenant Admin required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/admin/billing/top-sessions":{"get":{"summary":"Get top sessions by credit usage","description":"Top N sessions ranked by credit usage within a time range. Excludes internal user activity. Optionally filter by userId and/or appId.","tags":["Admin/Billing"],"parameters":[{"schema":{"type":"string","format":"date-time","description":"Start of time range (ISO 8601)"},"required":true,"description":"Start of time range (ISO 8601)","name":"from","in":"query"},{"schema":{"type":"string","format":"date-time","description":"End of time range (ISO 8601)"},"required":true,"description":"End of time range (ISO 8601)","name":"to","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20,"description":"Max sessions to return (1–100, default 20)"},"required":false,"description":"Max sessions to return (1–100, default 20)","name":"limit","in":"query"},{"schema":{"type":"integer","nullable":true,"description":"Filter to sessions created by this user ID"},"required":false,"description":"Filter to sessions created by this user ID","name":"userId","in":"query"},{"schema":{"type":"string","description":"Filter to sessions launched under this app ID"},"required":false,"description":"Filter to sessions launched under this app ID","name":"appId","in":"query"}],"responses":{"200":{"description":"Top sessions by credit usage","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"sessionId":{"type":"string"},"title":{"type":"string","nullable":true},"totalCredits":{"type":"string"},"createdAt":{"type":"string"},"userEmail":{"type":"string","nullable":true},"status":{"type":"string","enum":["active","unavailable"]}},"required":["sessionId","title","totalCredits","createdAt","userEmail","status"]}}}}},"400":{"description":"Invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — Tenant Admin required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/admin/billing/daily-usage":{"get":{"summary":"Get daily usage breakdown","description":"Daily credit usage, session count, and active user count within a time range. Excludes internal user activity.","tags":["Admin/Billing"],"parameters":[{"schema":{"type":"string","format":"date-time","description":"Start of time range (ISO 8601)"},"required":true,"description":"Start of time range (ISO 8601)","name":"from","in":"query"},{"schema":{"type":"string","format":"date-time","description":"End of time range (ISO 8601)"},"required":true,"description":"End of time range (ISO 8601)","name":"to","in":"query"}],"responses":{"200":{"description":"Daily usage breakdown","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string"},"credits":{"type":"string"},"sessionCount":{"type":"number"},"activeUserCount":{"type":"number"}},"required":["date","credits","sessionCount","activeUserCount"]}}}}},"400":{"description":"Invalid time range","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — Tenant Admin required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/admin/billing/cost-controls":{"get":{"summary":"List cost controls","description":"List spending-limit policies, latest evaluation statuses, and recent audit events.","tags":["Admin/Billing"],"responses":{"200":{"description":"Cost control configuration and status","content":{"application/json":{"schema":{"type":"object","properties":{"policies":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"orgId":{"type":"string"},"scopeType":{"type":"string","enum":["user","app","group"]},"scopeId":{"type":"string"},"scopeName":{"type":"string","nullable":true},"period":{"type":"string","enum":["daily","weekly","monthly"]},"limitCredits":{"type":"string"},"warningThresholdPercent":{"type":"number"},"mode":{"type":"string","enum":["monitor","warn","enforce"]},"endsAt":{"type":"string","nullable":true},"createdBy":{"type":"string","nullable":true},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"warningMessage":{"type":"string","nullable":true},"exceededMessage":{"type":"string","nullable":true},"perUserLimitCredits":{"type":"string","nullable":true},"perUserWarningMessage":{"type":"string","nullable":true},"perUserExceededMessage":{"type":"string","nullable":true}},"required":["id","orgId","scopeType","scopeId","scopeName","period","limitCredits","warningThresholdPercent","mode","endsAt","createdBy","createdAt","updatedAt","warningMessage","exceededMessage","perUserLimitCredits","perUserWarningMessage","perUserExceededMessage"]}},"statuses":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"policyId":{"type":"string","format":"uuid"},"orgId":{"type":"string"},"scopeType":{"type":"string","enum":["user","app","group"]},"scopeId":{"type":"string"},"periodStart":{"type":"string"},"periodEnd":{"type":"string"},"usedCredits":{"type":"string"},"limitCredits":{"type":"string"},"usagePercent":{"type":"string"},"status":{"type":"string","enum":["ok","warning","exceeded"]},"computedAt":{"type":"string"},"inputWatermark":{"type":"string"}},"required":["id","policyId","orgId","scopeType","scopeId","periodStart","periodEnd","usedCredits","limitCredits","usagePercent","status","computedAt","inputWatermark"]}},"auditEvents":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"orgId":{"type":"string"},"action":{"type":"string"},"policyId":{"type":"string","nullable":true,"format":"uuid"},"actor":{"type":"string","nullable":true},"details":{"type":"object","additionalProperties":{"nullable":true}},"createdAt":{"type":"string"}},"required":["id","orgId","action","policyId","actor","details","createdAt"]}},"lastEvaluatedAt":{"type":"string","nullable":true}},"required":["policies","statuses","auditEvents","lastEvaluatedAt"]}}}},"403":{"description":"Forbidden — Tenant Admin required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/admin/billing/cost-controls/policies":{"post":{"summary":"Create cost control policy","description":"Create a user, app, or group spending-limit policy. This does not enforce in real time.","tags":["Admin/Billing"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"scopeType":{"type":"string","enum":["user","app","group"]},"scopeId":{"type":"string","minLength":1},"period":{"type":"string","enum":["daily","weekly","monthly"]},"limitCredits":{"type":"string","minLength":1},"warningThresholdPercent":{"type":"integer","minimum":1,"maximum":100},"mode":{"type":"string","enum":["monitor","warn","enforce"]},"endsAt":{"type":"string","nullable":true,"format":"date-time"},"warningMessage":{"type":"string","nullable":true,"maxLength":500},"exceededMessage":{"type":"string","nullable":true,"maxLength":500},"perUserLimitCredits":{"type":"string","nullable":true},"perUserWarningMessage":{"type":"string","nullable":true,"maxLength":500},"perUserExceededMessage":{"type":"string","nullable":true,"maxLength":500}},"required":["scopeType","scopeId","limitCredits"]}}}},"responses":{"201":{"description":"Cost control policy created","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"orgId":{"type":"string"},"scopeType":{"type":"string","enum":["user","app","group"]},"scopeId":{"type":"string"},"scopeName":{"type":"string","nullable":true},"period":{"type":"string","enum":["daily","weekly","monthly"]},"limitCredits":{"type":"string"},"warningThresholdPercent":{"type":"number"},"mode":{"type":"string","enum":["monitor","warn","enforce"]},"endsAt":{"type":"string","nullable":true},"createdBy":{"type":"string","nullable":true},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"warningMessage":{"type":"string","nullable":true},"exceededMessage":{"type":"string","nullable":true},"perUserLimitCredits":{"type":"string","nullable":true},"perUserWarningMessage":{"type":"string","nullable":true},"perUserExceededMessage":{"type":"string","nullable":true}},"required":["id","orgId","scopeType","scopeId","scopeName","period","limitCredits","warningThresholdPercent","mode","endsAt","createdBy","createdAt","updatedAt","warningMessage","exceededMessage","perUserLimitCredits","perUserWarningMessage","perUserExceededMessage"]}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — Tenant Admin required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Scope not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Active policy already exists for this scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/admin/billing/cost-controls/policies/{policyId}":{"patch":{"summary":"Update cost control policy","description":"Update a user, app, or group spending-limit policy.","tags":["Admin/Billing"],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"policyId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"scopeType":{"type":"string","enum":["user","app","group"]},"scopeId":{"type":"string","minLength":1},"period":{"type":"string","enum":["daily","weekly","monthly"]},"limitCredits":{"type":"string","minLength":1},"warningThresholdPercent":{"type":"integer","minimum":1,"maximum":100},"mode":{"type":"string","enum":["monitor","warn","enforce"]},"endsAt":{"type":"string","nullable":true,"format":"date-time"},"warningMessage":{"type":"string","nullable":true,"maxLength":500},"exceededMessage":{"type":"string","nullable":true,"maxLength":500},"perUserLimitCredits":{"type":"string","nullable":true},"perUserWarningMessage":{"type":"string","nullable":true,"maxLength":500},"perUserExceededMessage":{"type":"string","nullable":true,"maxLength":500}}}}}},"responses":{"200":{"description":"Cost control policy updated","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"orgId":{"type":"string"},"scopeType":{"type":"string","enum":["user","app","group"]},"scopeId":{"type":"string"},"scopeName":{"type":"string","nullable":true},"period":{"type":"string","enum":["daily","weekly","monthly"]},"limitCredits":{"type":"string"},"warningThresholdPercent":{"type":"number"},"mode":{"type":"string","enum":["monitor","warn","enforce"]},"endsAt":{"type":"string","nullable":true},"createdBy":{"type":"string","nullable":true},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"warningMessage":{"type":"string","nullable":true},"exceededMessage":{"type":"string","nullable":true},"perUserLimitCredits":{"type":"string","nullable":true},"perUserWarningMessage":{"type":"string","nullable":true},"perUserExceededMessage":{"type":"string","nullable":true}},"required":["id","orgId","scopeType","scopeId","scopeName","period","limitCredits","warningThresholdPercent","mode","endsAt","createdBy","createdAt","updatedAt","warningMessage","exceededMessage","perUserLimitCredits","perUserWarningMessage","perUserExceededMessage"]}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — Tenant Admin required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Policy or scope not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"summary":"Delete cost control policy","description":"Delete a spending-limit policy and its evaluation statuses.","tags":["Admin/Billing"],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"policyId","in":"path"}],"responses":{"200":{"description":"Policy deleted","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}},"required":["success"]}}}},"403":{"description":"Forbidden — Tenant Admin required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Policy not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/admin/billing/cost-controls/recompute":{"post":{"summary":"Recompute cost-control statuses","description":"Start the shared Temporal recompute workflow for the current organization.","tags":["Admin/Billing"],"responses":{"200":{"description":"Recompute result","content":{"application/json":{"schema":{"type":"object","properties":{"workflowId":{"type":"string"}},"required":["workflowId"]}}}},"403":{"description":"Forbidden — Tenant Admin required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/admin/members":{"get":{"summary":"List workspace members","description":"List all members in the current workspace. Internal (@effectiveailabs.*) users are hidden in customer tenants and included when the caller is on the internal org itself. Supports pagination, search, and role filtering.","tags":["Admin/Members"],"parameters":[{"schema":{"type":"string","default":"0","description":"Pagination offset (default 0)"},"required":false,"description":"Pagination offset (default 0)","name":"offset","in":"query"},{"schema":{"type":"string","default":"50","description":"Page size (1–10000, default 50)"},"required":false,"description":"Page size (1–10000, default 50)","name":"limit","in":"query"},{"schema":{"type":"string","description":"Search by name or email"},"required":false,"description":"Search by name or email","name":"search","in":"query"},{"schema":{"type":"string","enum":["readonly","member","admin"],"description":"Filter by role"},"required":false,"description":"Filter by role","name":"role","in":"query"},{"schema":{"type":"string","enum":["true","false"],"default":"false","description":"Include normalized Descope custom attributes for each member"},"required":false,"description":"Include normalized Descope custom attributes for each member","name":"includeAttributes","in":"query"}],"responses":{"200":{"description":"Paginated list of workspace members","content":{"application/json":{"schema":{"type":"object","properties":{"members":{"type":"array","items":{"type":"object","properties":{"id":{"type":"number"},"userId":{"type":"string"},"email":{"type":"string"},"name":{"type":"string","nullable":true},"role":{"type":"string","enum":["readonly","member","admin"],"description":"Workspace member role"},"lastLoginAt":{"type":"string","nullable":true},"createdAt":{"type":"string"},"customAttributes":{"type":"object","nullable":true,"additionalProperties":{"type":"string"}}},"required":["id","userId","email","name","role","lastLoginAt","createdAt"]}},"total":{"type":"number"},"offset":{"type":"number"},"limit":{"type":"number"}},"required":["members","total","offset","limit"]}}}},"403":{"description":"Forbidden — Tenant Admin required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/admin/members/invitations":{"get":{"summary":"List pending invitations","description":"List users who have been invited to the workspace but have not yet signed in. These are Descope users with status \"invited\".","tags":["Admin/Members"],"responses":{"200":{"description":"List of pending invitations","content":{"application/json":{"schema":{"type":"object","properties":{"invitations":{"type":"array","items":{"type":"object","properties":{"email":{"type":"string"},"name":{"type":"string","nullable":true},"role":{"type":"string","enum":["readonly","member","admin"],"description":"Workspace member role"},"createdAt":{"type":"string"}},"required":["email","name","role","createdAt"]}},"total":{"type":"number"}},"required":["invitations","total"]}}}},"403":{"description":"Forbidden — Tenant Admin required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/admin/members/invite":{"post":{"summary":"Invite a member to the workspace","description":"Invite a user to the workspace by email. Creates a new account if they don't exist, or adds them to the tenant if they do. Does not send invitation emails — use the batch email endpoint separately.","tags":["Admin/Members"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","format":"email","description":"Email address of the user to invite"},"name":{"type":"string","description":"Display name for the new member"},"role":{"type":"string","enum":["readonly","member","admin"],"default":"member","description":"Role to assign (default: member)"}},"required":["email"]}}}},"responses":{"201":{"description":"Member invited successfully","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"number"},"userId":{"type":"string"},"email":{"type":"string"},"name":{"type":"string","nullable":true},"role":{"type":"string","enum":["readonly","member","admin"],"description":"Workspace member role"},"lastLoginAt":{"type":"string","nullable":true},"createdAt":{"type":"string"},"customAttributes":{"type":"object","nullable":true,"additionalProperties":{"type":"string"}}},"required":["id","userId","email","name","role","lastLoginAt","createdAt"]}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — Tenant Admin required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"User is already a member of this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/admin/members/invitations/resend":{"post":{"summary":"Verify a pending invitation for resend","description":"Verify that a pending invitation exists. Returns the invited user name. The caller sends the email via the batch email endpoint.","tags":["Admin/Members"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","format":"email","description":"Email address of the pending invitation"}},"required":["email"]}}}},"responses":{"200":{"description":"Pending invitation verified","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"name":{"type":"string","nullable":true}},"required":["success","name"]}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — Tenant Admin required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No pending invitation found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/admin/members/invitations/revoke":{"post":{"summary":"Revoke a pending invitation","description":"Revoke a pending invitation by removing the invited user from the tenant.","tags":["Admin/Members"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","format":"email","description":"Email address of the pending invitation"}},"required":["email"]}}}},"responses":{"200":{"description":"Invitation revoked","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}},"required":["success"]}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — Tenant Admin required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No pending invitation found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/admin/members/{id}/role":{"patch":{"summary":"Update a member's role","description":"Change a workspace member's role. Cannot change your own role.","tags":["Admin/Members"],"parameters":[{"schema":{"type":"string","description":"Member user ID"},"required":true,"description":"Member user ID","name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"role":{"type":"string","enum":["readonly","member","admin"],"description":"New role for the member"}},"required":["role"]}}}},"responses":{"200":{"description":"Role updated","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"number"},"userId":{"type":"string"},"email":{"type":"string"},"name":{"type":"string","nullable":true},"role":{"type":"string","enum":["readonly","member","admin"],"description":"Workspace member role"},"lastLoginAt":{"type":"string","nullable":true},"createdAt":{"type":"string"},"customAttributes":{"type":"object","nullable":true,"additionalProperties":{"type":"string"}}},"required":["id","userId","email","name","role","lastLoginAt","createdAt"]}}}},"400":{"description":"Invalid input or self-modification","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — Tenant Admin required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Member not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/admin/members/{id}":{"delete":{"summary":"Remove a member from the workspace","description":"Remove a member from the workspace. This only removes tenant access — the user account is not deleted. Cannot remove yourself.","tags":["Admin/Members"],"parameters":[{"schema":{"type":"string","description":"Member user ID"},"required":true,"description":"Member user ID","name":"id","in":"path"}],"responses":{"200":{"description":"Member removed","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}},"required":["success"]}}}},"400":{"description":"Cannot remove yourself","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — Tenant Admin required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Member not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/admin/members/{userId}/roles":{"get":{"summary":"List roles directly assigned to a user","tags":["Admin/Members"],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"userId","in":"path"}],"responses":{"200":{"description":"Assigned roles","content":{"application/json":{"schema":{"type":"object","properties":{"roleTemplates":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"source":{"type":"string","enum":["built_in","custom"]},"permissions":{"type":"array","items":{"type":"object","properties":{"resourceType":{"type":"string","minLength":1},"action":{"type":"string","minLength":1}},"required":["resourceType","action"]}},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","name","description","source","permissions","createdAt","updatedAt"]}}},"required":["roleTemplates"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/admin/groups":{"get":{"summary":"List groups","description":"List all groups in the current workspace.","tags":["Admin/Groups"],"responses":{"200":{"description":"List of groups","content":{"application/json":{"schema":{"type":"object","properties":{"groups":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"source":{"type":"string","enum":["manual","idp","attribute"],"description":"How the group was created"},"attributeRules":{"type":"object","nullable":true,"additionalProperties":{"type":"string"},"description":"Intersection of Descope custom attribute key/value rules"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","name","source","attributeRules","createdAt","updatedAt"]}}},"required":["groups"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"summary":"Create a group","description":"Create a new group in the current workspace.","tags":["Admin/Groups"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100,"description":"Group name"},"source":{"type":"string","enum":["manual","idp","attribute"],"default":"manual","description":"How the group was created"},"attributeRules":{"type":"object","additionalProperties":{"type":"string"},"description":"Intersection of Descope custom attribute key/value rules"}},"required":["name"]}}}},"responses":{"201":{"description":"Group created","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"source":{"type":"string","enum":["manual","idp","attribute"],"description":"How the group was created"},"attributeRules":{"type":"object","nullable":true,"additionalProperties":{"type":"string"},"description":"Intersection of Descope custom attribute key/value rules"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","name","source","attributeRules","createdAt","updatedAt"]}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/admin/groups/{groupId}":{"get":{"summary":"Get a group","description":"Get a group by ID.","tags":["Admin/Groups"],"parameters":[{"schema":{"type":"string","format":"uuid","description":"Group ID"},"required":true,"description":"Group ID","name":"groupId","in":"path"}],"responses":{"200":{"description":"Group details","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"source":{"type":"string","enum":["manual","idp","attribute"],"description":"How the group was created"},"attributeRules":{"type":"object","nullable":true,"additionalProperties":{"type":"string"},"description":"Intersection of Descope custom attribute key/value rules"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","name","source","attributeRules","createdAt","updatedAt"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"summary":"Delete a group","description":"Delete a group and all associated membership and app access tuples.","tags":["Admin/Groups"],"parameters":[{"schema":{"type":"string","format":"uuid","description":"Group ID"},"required":true,"description":"Group ID","name":"groupId","in":"path"}],"responses":{"200":{"description":"Group deleted","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}},"required":["success"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/admin/groups/{groupId}/members":{"get":{"summary":"List group members","description":"List all members of a group.","tags":["Admin/Groups"],"parameters":[{"schema":{"type":"string","format":"uuid","description":"Group ID"},"required":true,"description":"Group ID","name":"groupId","in":"path"}],"responses":{"200":{"description":"Group members","content":{"application/json":{"schema":{"type":"object","properties":{"members":{"type":"array","items":{"type":"object","properties":{"userId":{"type":"string"},"email":{"type":"string"},"name":{"type":"string","nullable":true}},"required":["userId","email","name"]}}},"required":["members"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"summary":"Add a group member","description":"Add a user to a group (writes a membership tuple).","tags":["Admin/Groups"],"parameters":[{"schema":{"type":"string","format":"uuid","description":"Group ID"},"required":true,"description":"Group ID","name":"groupId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"userId":{"type":"string","minLength":1,"description":"User ID to add"}},"required":["userId"]}}}},"responses":{"201":{"description":"Member added","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}},"required":["success"]}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/admin/groups/{groupId}/members/{userId}":{"delete":{"summary":"Remove a group member","description":"Remove a user from a group.","tags":["Admin/Groups"],"parameters":[{"schema":{"type":"string","format":"uuid","description":"Group ID"},"required":true,"description":"Group ID","name":"groupId","in":"path"},{"schema":{"type":"string","description":"User ID to remove"},"required":true,"description":"User ID to remove","name":"userId","in":"path"}],"responses":{"200":{"description":"Member removed","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}},"required":["success"]}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/admin/groups/{groupId}/sync-info":{"get":{"summary":"Get group sync info","description":"Get sync status information for an attribute-synced group.","tags":["Admin/Groups"],"parameters":[{"schema":{"type":"string","format":"uuid","description":"Group ID"},"required":true,"description":"Group ID","name":"groupId","in":"path"}],"responses":{"200":{"description":"Group sync info","content":{"application/json":{"schema":{"type":"object","properties":{"lastSyncedAt":{"type":"string","nullable":true}},"required":["lastSyncedAt"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/admin/groups/{groupId}/roles":{"get":{"summary":"List roles assigned to a group","tags":["Admin/Groups"],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"groupId","in":"path"}],"responses":{"200":{"description":"Assigned roles","content":{"application/json":{"schema":{"type":"object","properties":{"roleTemplates":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"source":{"type":"string","enum":["built_in","custom"]},"permissions":{"type":"array","items":{"type":"object","properties":{"resourceType":{"type":"string","minLength":1},"action":{"type":"string","minLength":1}},"required":["resourceType","action"]}},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","name","description","source","permissions","createdAt","updatedAt"]}}},"required":["roleTemplates"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/admin/authz/tuples":{"post":{"summary":"Write a tuple","description":"Create an authorization tuple. Idempotent — writing the same tuple twice is a no-op.","tags":["Admin/Authz"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"subject":{"type":"string","description":"EntityRef in format \"orgId:type:id\"","example":"org-acme:group:underwriting"},"relation":{"type":"string","minLength":1,"description":"Relation name (e.g. \"member\", \"viewer\", \"editor\")"},"object":{"type":"string","description":"EntityRef in format \"orgId:type:id\"","example":"org-acme:group:underwriting"}},"required":["subject","relation","object"]}}}},"responses":{"201":{"description":"Tuple written","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}},"required":["success"]}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"summary":"Delete a tuple","description":"Remove an authorization tuple.","tags":["Admin/Authz"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"subject":{"type":"string","description":"EntityRef in format \"orgId:type:id\"","example":"org-acme:group:underwriting"},"relation":{"type":"string","minLength":1,"description":"Relation name (e.g. \"member\", \"viewer\", \"editor\")"},"object":{"type":"string","description":"EntityRef in format \"orgId:type:id\"","example":"org-acme:group:underwriting"}},"required":["subject","relation","object"]}}}},"responses":{"200":{"description":"Tuple deleted","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}},"required":["success"]}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"summary":"List tuples","description":"List authorization tuples matching optional filters. At least one filter is required.","tags":["Admin/Authz"],"parameters":[{"schema":{"type":"string","description":"EntityRef in format \"orgId:type:id\"","example":"org-acme:group:underwriting"},"required":false,"description":"EntityRef in format \"orgId:type:id\"","name":"subject","in":"query"},{"schema":{"type":"string"},"required":false,"name":"relation","in":"query"},{"schema":{"type":"string","description":"EntityRef in format \"orgId:type:id\"","example":"org-acme:group:underwriting"},"required":false,"description":"EntityRef in format \"orgId:type:id\"","name":"object","in":"query"}],"responses":{"200":{"description":"Matching tuples","content":{"application/json":{"schema":{"type":"object","properties":{"tuples":{"type":"array","items":{"type":"object","properties":{"subject":{"type":"string"},"relation":{"type":"string"},"object":{"type":"string"}},"required":["subject","relation","object"]}}},"required":["tuples"]}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/admin/authz/check":{"post":{"summary":"Check permission","description":"Admin introspection endpoint for tuple existence checks, including transitive group membership. Application code should use permission checks instead.","tags":["Admin/Authz"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"subject":{"type":"string","description":"EntityRef in format \"orgId:type:id\"","example":"org-acme:group:underwriting"},"relation":{"type":"string","minLength":1,"description":"Relation name (e.g. \"member\", \"viewer\", \"editor\")"},"object":{"type":"string","description":"EntityRef in format \"orgId:type:id\"","example":"org-acme:group:underwriting"}},"required":["subject","relation","object"]}}}},"responses":{"200":{"description":"Permission check result","content":{"application/json":{"schema":{"type":"object","properties":{"allowed":{"type":"boolean"}},"required":["allowed"]}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/admin/role-templates":{"get":{"summary":"List role templates","description":"List all role templates (built-in and custom) for the current org.","tags":["Admin/Role Templates"],"responses":{"200":{"description":"Role templates","content":{"application/json":{"schema":{"type":"object","properties":{"roleTemplates":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"source":{"type":"string","enum":["built_in","custom"]},"permissions":{"type":"array","items":{"type":"object","properties":{"resourceType":{"type":"string","minLength":1},"action":{"type":"string","minLength":1}},"required":["resourceType","action"]}},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","name","description","source","permissions","createdAt","updatedAt"]}}},"required":["roleTemplates"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"summary":"Create a custom role template","tags":["Admin/Role Templates"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100},"description":{"type":"string","nullable":true,"default":null},"permissions":{"type":"array","items":{"type":"object","properties":{"resourceType":{"type":"string","minLength":1},"action":{"type":"string","minLength":1}},"required":["resourceType","action"]},"minItems":1}},"required":["name","permissions"]}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"source":{"type":"string","enum":["built_in","custom"]},"permissions":{"type":"array","items":{"type":"object","properties":{"resourceType":{"type":"string","minLength":1},"action":{"type":"string","minLength":1}},"required":["resourceType","action"]}},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","name","description","source","permissions","createdAt","updatedAt"]}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/admin/role-templates/{roleTemplateId}":{"get":{"summary":"Get a role template","tags":["Admin/Role Templates"],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"roleTemplateId","in":"path"}],"responses":{"200":{"description":"Role template","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"source":{"type":"string","enum":["built_in","custom"]},"permissions":{"type":"array","items":{"type":"object","properties":{"resourceType":{"type":"string","minLength":1},"action":{"type":"string","minLength":1}},"required":["resourceType","action"]}},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","name","description","source","permissions","createdAt","updatedAt"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"summary":"Delete a custom role template","description":"Built-in role templates cannot be deleted.","tags":["Admin/Role Templates"],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"roleTemplateId","in":"path"}],"responses":{"200":{"description":"Deleted","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}},"required":["success"]}}}},"400":{"description":"Cannot delete built-in","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/admin/role-templates/{roleTemplateId}/assign":{"post":{"summary":"Assign role template to a group","tags":["Admin/Role Templates"],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"roleTemplateId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"groupId":{"type":"string","format":"uuid"}},"required":["groupId"]}}}},"responses":{"201":{"description":"Assigned","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}},"required":["success"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/admin/role-templates/{roleTemplateId}/assign/{groupId}":{"delete":{"summary":"Remove role template from a group","tags":["Admin/Role Templates"],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"roleTemplateId","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"groupId","in":"path"}],"responses":{"200":{"description":"Unassigned","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}},"required":["success"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/admin/role-templates/{roleTemplateId}/assignments":{"get":{"summary":"List groups and users assigned to a role template","tags":["Admin/Role Templates"],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"roleTemplateId","in":"path"}],"responses":{"200":{"description":"Assigned groups and users","content":{"application/json":{"schema":{"type":"object","properties":{"groups":{"type":"array","items":{"type":"string"}},"users":{"type":"array","items":{"type":"string"}}},"required":["groups","users"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/admin/role-templates/{roleTemplateId}/assign-user":{"post":{"summary":"Assign role template directly to a user","tags":["Admin/Role Templates"],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"roleTemplateId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"userId":{"type":"string","minLength":1}},"required":["userId"]}}}},"responses":{"201":{"description":"Assigned","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}},"required":["success"]}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/admin/role-templates/{roleTemplateId}/assign-user/{userId}":{"delete":{"summary":"Remove role template from a user","tags":["Admin/Role Templates"],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"roleTemplateId","in":"path"},{"schema":{"type":"string","minLength":1},"required":true,"name":"userId","in":"path"}],"responses":{"200":{"description":"Unassigned","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}},"required":["success"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/admin/activity":{"get":{"summary":"List audit events","description":"Org-wide audit log of all events. Requires users:admin permission.","tags":["Admin/Events"],"parameters":[{"schema":{"type":"string","default":"0"},"required":false,"name":"offset","in":"query"},{"schema":{"type":"string","default":"50"},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string"},"required":false,"name":"action","in":"query"},{"schema":{"type":"string"},"required":false,"name":"actorId","in":"query"},{"schema":{"type":"string"},"required":false,"name":"resourceType","in":"query"}],"responses":{"200":{"description":"Paginated event list","content":{"application/json":{"schema":{"type":"object","properties":{"events":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"orgId":{"type":"string"},"actorId":{"type":"string","nullable":true},"action":{"type":"string"},"resourceType":{"type":"string"},"resourceId":{"type":"string","nullable":true},"details":{"type":"object","additionalProperties":{"nullable":true}},"createdAt":{"type":"string"}},"required":["id","orgId","actorId","action","resourceType","resourceId","details","createdAt"]}},"total":{"type":"number"},"offset":{"type":"number"},"limit":{"type":"number"}},"required":["events","total","offset","limit"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/me/activity":{"get":{"summary":"List my activity feed","description":"Personal activity feed — events routed to the current user.  Supports offset pagination (default, used by the header ActivityBell) and cursor pagination (opt-in, used by the full inbox page).","tags":["Activity"],"parameters":[{"schema":{"type":"string","default":"0"},"required":false,"name":"offset","in":"query"},{"schema":{"type":"string","default":"50"},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","description":"Composite cursor `<ISO createdAt>|<uuid id>`. Presence of this query param (even empty) switches the endpoint into cursor mode: tie-safe pagination, `nextCursor` in the response, and no ephemeral Redis chat-notif merge. Pass an empty value (or any sentinel) to request the first page of cursor mode."},"required":false,"description":"Composite cursor `<ISO createdAt>|<uuid id>`. Presence of this query param (even empty) switches the endpoint into cursor mode: tie-safe pagination, `nextCursor` in the response, and no ephemeral Redis chat-notif merge. Pass an empty value (or any sentinel) to request the first page of cursor mode.","name":"cursor","in":"query"},{"schema":{"type":"string","enum":["chat","agent","updates","other"],"description":"Optional category filter mirroring the inbox page pill row: `chat` → `action LIKE chat.%`, `agent` → `action LIKE session.%`, `updates` → `action LIKE announcement.%` (workspace announcements feed), `other` → none of the above. Omit for the all-activity feed. When set, `nextCursor` and `hasNextPage` reflect the filtered stream, so the client can hide \"Load more\" once the category is exhausted without over-paginating."},"required":false,"description":"Optional category filter mirroring the inbox page pill row: `chat` → `action LIKE chat.%`, `agent` → `action LIKE session.%`, `updates` → `action LIKE announcement.%` (workspace announcements feed), `other` → none of the above. Omit for the all-activity feed. When set, `nextCursor` and `hasNextPage` reflect the filtered stream, so the client can hide \"Load more\" once the category is exhausted without over-paginating.","name":"category","in":"query"}],"responses":{"200":{"description":"Activity feed","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"orgId":{"type":"string"},"actorId":{"type":"string","nullable":true},"action":{"type":"string"},"resourceType":{"type":"string"},"resourceId":{"type":"string","nullable":true},"details":{"type":"object","additionalProperties":{"nullable":true}},"createdAt":{"type":"string"},"type":{"type":"string","enum":["event"]},"readAt":{"type":"string","nullable":true},"recipientId":{"type":"string","nullable":true}},"required":["id","orgId","actorId","action","resourceType","resourceId","details","createdAt","type","readAt","recipientId"]},{"type":"object","properties":{"type":{"type":"string","enum":["announcement"]},"id":{"type":"string","format":"uuid"},"orgId":{"type":"string"},"title":{"type":"string"},"bodyMd":{"type":"string"},"category":{"type":"string"},"severity":{"type":"string","enum":["info","important","critical"]},"createdAt":{"type":"string"},"publishedAt":{"type":"string","nullable":true},"readAt":{"type":"string","nullable":true},"dismissedAt":{"type":"string","nullable":true}},"required":["type","id","orgId","title","bodyMd","category","severity","createdAt","publishedAt","readAt","dismissedAt"]}]}},"unreadCount":{"type":"integer"},"categoryUnreadCount":{"type":"integer"},"nextCursor":{"type":"string","nullable":true},"actors":{"type":"object","additionalProperties":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string","nullable":true},"email":{"type":"string"}},"required":["id","name","email"]}}},"required":["items","unreadCount"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/me/activity/{id}":{"get":{"summary":"Fetch a single activity item by id","description":"Returns a single activity feed item, applying the same visibility predicate as `GET /me/activity`. Returns 404 if the caller cannot see this event under RLS (wrong org, not targeted, or dismissed). Used by deep-link routes such as `/inbox/announcements/$id`.","tags":["Activity"],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Single activity item","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"orgId":{"type":"string"},"actorId":{"type":"string","nullable":true},"action":{"type":"string"},"resourceType":{"type":"string"},"resourceId":{"type":"string","nullable":true},"details":{"type":"object","additionalProperties":{"nullable":true}},"createdAt":{"type":"string"},"type":{"type":"string","enum":["event"]},"readAt":{"type":"string","nullable":true},"recipientId":{"type":"string","nullable":true}},"required":["id","orgId","actorId","action","resourceType","resourceId","details","createdAt","type","readAt","recipientId"]},{"type":"object","properties":{"type":{"type":"string","enum":["announcement"]},"id":{"type":"string","format":"uuid"},"orgId":{"type":"string"},"title":{"type":"string"},"bodyMd":{"type":"string"},"category":{"type":"string"},"severity":{"type":"string","enum":["info","important","critical"]},"createdAt":{"type":"string"},"publishedAt":{"type":"string","nullable":true},"readAt":{"type":"string","nullable":true},"dismissedAt":{"type":"string","nullable":true}},"required":["type","id","orgId","title","bodyMd","category","severity","createdAt","publishedAt","readAt","dismissedAt"]}]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/me/activity/read":{"post":{"summary":"Mark activity items as read","description":"Mark specific events or all events as read.","tags":["Activity"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"eventIds":{"type":"array","items":{"type":"string","format":"uuid"},"minItems":1,"maxItems":100},"all":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Marked as read","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}},"required":["success"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/me/activity/dismiss":{"post":{"summary":"Dismiss activity items","description":"Dismiss events so they no longer appear in the feed.","tags":["Activity"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"eventIds":{"type":"array","items":{"type":"string","format":"uuid"},"minItems":1,"maxItems":100}},"required":["eventIds"]}}}},"responses":{"200":{"description":"Dismissed","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}},"required":["success"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/me/push/vapid-key":{"get":{"summary":"Get the application VAPID public key for Web Push subscription","tags":["Push"],"responses":{"200":{"description":"VAPID public key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PushVapidKeyResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/me/push/subscribe":{"post":{"summary":"Register a Web Push subscription for the current user","tags":["Push"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PushSubscribeBody"}}}},"responses":{"200":{"description":"Subscription registered","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PushSubscribeResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Push notifications are not enabled for this organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/me/push/subscriptions":{"get":{"summary":"List the current user's Web Push devices","tags":["Push"],"responses":{"200":{"description":"Subscription list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PushSubscriptionListResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/me/push/subscribe/{id}":{"delete":{"summary":"Revoke a Web Push device subscription","tags":["Push"],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Revoked","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}},"required":["success"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Subscription not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/me/push/pause":{"post":{"summary":"Deactivate a push subscription on logout","description":"Sets `active = false` on the matching subscription so the push sender skips it. The browser-side PushSubscription is left intact — calling POST /subscribe on next login reactivates the row.","tags":["Push"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PushPauseBody"}}}},"responses":{"200":{"description":"Subscription paused (or no matching row found — idempotent)","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}},"required":["success"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/secrets":{"get":{"tags":["Secrets"],"summary":"List secrets visible to the caller","parameters":[{"schema":{"type":"string","enum":["user","org","app","workflow"],"description":"Filter to one scope. Omit to return caller-pickable set (own + org)."},"required":false,"description":"Filter to one scope. Omit to return caller-pickable set (own + org).","name":"scope","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Required when scope=\"app\" — restricts to that app's owned secrets"},"required":false,"description":"Required when scope=\"app\" — restricts to that app's owned secrets","name":"appId","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Required when scope=\"workflow\" — restricts to that workflow's owned secrets"},"required":false,"description":"Required when scope=\"workflow\" — restricts to that workflow's owned secrets","name":"workflowId","in":"query"}],"responses":{"200":{"description":"List of secrets","content":{"application/json":{"schema":{"type":"object","properties":{"secrets":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"orgId":{"type":"string"},"ownerUserId":{"type":"string","nullable":true},"ownerAppId":{"type":"string","nullable":true},"ownerWorkflowId":{"type":"string","nullable":true},"name":{"type":"string"},"label":{"type":"string","nullable":true},"active":{"type":"boolean"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"secretValueMasked":{"type":"string"},"networkInjectionConfigJson":{"$ref":"#/components/schemas/NetworkInjectionConfig"}},"required":["id","orgId","ownerUserId","ownerAppId","ownerWorkflowId","name","label","active","createdAt","updatedAt","secretValueMasked","networkInjectionConfigJson"]}}},"required":["secrets"]}}}},"400":{"description":"Bad request — scope=app requires appId","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — cannot manage requested app","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"App not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Secrets"],"summary":"Create (or upsert by name) a secret","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100,"description":"Secret name (e.g. \"openai-key\")"},"value":{"type":"string","minLength":1,"maxLength":16000,"description":"The raw secret, up to 16,000 characters (encrypted at rest)"},"label":{"type":"string","maxLength":200,"description":"Human-readable label"},"scope":{"type":"string","enum":["user","org","app","workflow"],"default":"user","description":"Ownership scope: \"user\" = caller-owned, \"org\" = workspace-owned (admin only), \"app\" = app-owned (creator/admin; requires appId), \"workflow\" = workflow-owned (admin only; requires workflowId)"},"appId":{"type":"string","minLength":1,"maxLength":255,"description":"Required when scope=\"app\" — the app that owns this secret"},"workflowId":{"type":"string","minLength":1,"maxLength":255,"description":"Required when scope=\"workflow\" — the workflow that owns this secret"},"networkInjectionConfigJson":{"type":"object","nullable":true,"properties":{"routes":{"type":"array","items":{"$ref":"#/components/schemas/NetworkInjectionRoute"},"minItems":1,"maxItems":50}},"required":["routes"],"description":"When non-null, this secret is used for network credential injection only."}},"required":["name","value"]}}}},"responses":{"200":{"description":"Secret created","content":{"application/json":{"schema":{"type":"object","properties":{"secret":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"orgId":{"type":"string"},"ownerUserId":{"type":"string","nullable":true},"ownerAppId":{"type":"string","nullable":true},"ownerWorkflowId":{"type":"string","nullable":true},"name":{"type":"string"},"label":{"type":"string","nullable":true},"active":{"type":"boolean"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"secretValueMasked":{"type":"string"},"networkInjectionConfigJson":{"$ref":"#/components/schemas/NetworkInjectionConfig"}},"required":["id","orgId","ownerUserId","ownerAppId","ownerWorkflowId","name","label","active","createdAt","updatedAt","secretValueMasked","networkInjectionConfigJson"]}},"required":["secret"]}}}},"403":{"description":"Forbidden — admin required for scope=org, creator/admin for scope=app","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"App not found (scope=app)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/secrets/{id}":{"delete":{"tags":["Secrets"],"summary":"Delete a secret (owner, secrets.admin for org-owned, app creator/admin for app-owned)","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Secret deleted","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}},"required":["success"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Secret not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/secrets/overview":{"get":{"tags":["Secrets"],"summary":"One-shot payload for the /secrets UI page","description":"Returns the caller's user-owned secrets, the apps they can manage (admin = all; non-admin = creator-only) with each app's owned secrets and declared requirements, all org-owned secrets, and a usage rollup counting how many defaults/bindings reference each secret.","responses":{"200":{"description":"Overview payload","content":{"application/json":{"schema":{"type":"object","properties":{"isAdmin":{"type":"boolean"},"my":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"orgId":{"type":"string"},"ownerUserId":{"type":"string","nullable":true},"ownerAppId":{"type":"string","nullable":true},"ownerWorkflowId":{"type":"string","nullable":true},"name":{"type":"string"},"label":{"type":"string","nullable":true},"active":{"type":"boolean"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"secretValueMasked":{"type":"string"},"networkInjectionConfigJson":{"$ref":"#/components/schemas/NetworkInjectionConfig"}},"required":["id","orgId","ownerUserId","ownerAppId","ownerWorkflowId","name","label","active","createdAt","updatedAt","secretValueMasked","networkInjectionConfigJson"]}},"apps":{"type":"array","items":{"type":"object","properties":{"appId":{"type":"string"},"appTitle":{"type":"string","nullable":true},"canManage":{"type":"boolean","enum":[true]},"secrets":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"orgId":{"type":"string"},"ownerUserId":{"type":"string","nullable":true},"ownerAppId":{"type":"string","nullable":true},"ownerWorkflowId":{"type":"string","nullable":true},"name":{"type":"string"},"label":{"type":"string","nullable":true},"active":{"type":"boolean"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"secretValueMasked":{"type":"string"},"networkInjectionConfigJson":{"$ref":"#/components/schemas/NetworkInjectionConfig"}},"required":["id","orgId","ownerUserId","ownerAppId","ownerWorkflowId","name","label","active","createdAt","updatedAt","secretValueMasked","networkInjectionConfigJson"]}},"requirements":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"secretName":{"type":"string"},"defaultSecretId":{"type":"string","nullable":true,"format":"uuid"},"defaultSecret":{"type":"object","nullable":true,"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"ownerUserId":{"type":"string","nullable":true},"ownerAppId":{"type":"string","nullable":true},"ownerWorkflowId":{"type":"string","nullable":true},"secretValueMasked":{"type":"string","description":"Masked preview, e.g. \"••••abcd\". Never contains the raw value."},"networkInjectionConfigJson":{"$ref":"#/components/schemas/NetworkInjectionConfig"}},"required":["id","name","ownerUserId","ownerAppId","ownerWorkflowId","secretValueMasked","networkInjectionConfigJson"],"description":"Hydrated when the default is visible to the caller (own / org / this-app-owned). Masked preview only — no raw value."},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","secretName","defaultSecretId","defaultSecret","createdAt","updatedAt"]}}},"required":["appId","appTitle","canManage","secrets","requirements"]}},"org":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"orgId":{"type":"string"},"ownerUserId":{"type":"string","nullable":true},"ownerAppId":{"type":"string","nullable":true},"ownerWorkflowId":{"type":"string","nullable":true},"name":{"type":"string"},"label":{"type":"string","nullable":true},"active":{"type":"boolean"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"secretValueMasked":{"type":"string"},"networkInjectionConfigJson":{"$ref":"#/components/schemas/NetworkInjectionConfig"}},"required":["id","orgId","ownerUserId","ownerAppId","ownerWorkflowId","name","label","active","createdAt","updatedAt","secretValueMasked","networkInjectionConfigJson"]}},"usageBySecretId":{"type":"object","additionalProperties":{"type":"object","properties":{"defaults":{"type":"integer","minimum":0},"bindings":{"type":"integer","minimum":0}},"required":["defaults","bindings"]}}},"required":["isAdmin","my","apps","org","usageBySecretId"]}}}}}}},"/api/v1/admin/static-ips":{"post":{"summary":"Provision a static IP","description":"Provisions a new static IP for the org. In test mode, the IP is immediately active with a mock address. In production, starts an async GCP provisioning workflow.","tags":["Admin/Static IPs"],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"label":{"type":"string","maxLength":100,"description":"Human-friendly label"}}}}}},"responses":{"202":{"description":"Provisioning started","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StaticIp"}}}},"403":{"description":"Forbidden — Tenant Admin required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Org static IP limit reached","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"limit":{"type":"number"},"current":{"type":"number"}},"required":["error","limit","current"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"summary":"List static IPs","description":"Returns all static IPs for the org, with their assigned apps and usage vs limit.","tags":["Admin/Static IPs"],"responses":{"200":{"description":"Static IP pool","content":{"application/json":{"schema":{"type":"object","properties":{"staticIps":{"type":"array","items":{"$ref":"#/components/schemas/StaticIp"}},"limit":{"type":"number"},"usage":{"type":"number"}},"required":["staticIps","limit","usage"]}}}},"403":{"description":"Forbidden — Tenant Admin required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/admin/static-ips/{id}":{"delete":{"summary":"Deprovision a static IP","description":"Tears down the static IP. Fails if apps are still assigned. In test mode, deletes immediately. In production, starts an async GCP teardown workflow.","tags":["Admin/Static IPs"],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"202":{"description":"Deprovisioning started","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["deprovisioning"]}},"required":["id","status"]}}}},"403":{"description":"Forbidden — Tenant Admin required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Static IP not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Apps still assigned","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"apps":{"type":"array","items":{"type":"string"}}},"required":["error","apps"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/admin/static-ips/{staticIpId}/routes":{"get":{"summary":"List static IP routes","description":"Returns the route policy for a static IP — which destinations are tunneled via the static-IP VM. Tenant Admin required.","tags":["Admin/Static IPs"],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"staticIpId","in":"path"}],"responses":{"200":{"description":"Routes for the static IP","content":{"application/json":{"schema":{"type":"object","properties":{"routes":{"type":"array","items":{"$ref":"#/components/schemas/StaticIpRoute"}}},"required":["routes"]}}}},"403":{"description":"Forbidden — Tenant Admin required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Static IP not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"summary":"Create a static IP route","description":"Adds a route policy entry. https_host routes use exact or single leading-wildcard hostnames (e.g. 'api.example.com', '*.example.com'). tcp_cidr routes use IPv4 CIDR; RFC1918, link-local, loopback, multicast, and broadcast ranges are rejected. Tenant Admin required.","tags":["Admin/Static IPs"],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"staticIpId","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StaticIpRouteCreate"}}}},"responses":{"200":{"description":"Route created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StaticIpRoute"}}}},"400":{"description":"Validation failed (invalid host_pattern, cidr, or port range)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — Tenant Admin required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Static IP not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/admin/static-ips/{staticIpId}/routes/{routeId}":{"patch":{"summary":"Enable or disable a static IP route","description":"Toggles a route policy entry without deleting it — keeps the audit trail of when the route was first declared. Tenant Admin required.","tags":["Admin/Static IPs"],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"staticIpId","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"routeId","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"enabled":{"type":"boolean"}},"required":["enabled"]}}}},"responses":{"200":{"description":"Route updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StaticIpRoute"}}}},"403":{"description":"Forbidden — Tenant Admin required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Route not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"summary":"Delete a static IP route","description":"Removes a route policy entry. Tenant Admin required. Note: removing the last route on an in-use static IP means traffic from those apps will no longer be tunneled through the static IP once the route resolver lands.","tags":["Admin/Static IPs"],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"staticIpId","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"routeId","in":"path"}],"responses":{"200":{"description":"Route deleted","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"deleted":{"type":"boolean","enum":[true]}},"required":["id","deleted"]}}}},"403":{"description":"Forbidden — Tenant Admin required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Route not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/admin/oauth-provider-configs":{"get":{"summary":"List OAuth provider configs for the current org","description":"Returns all per-org OAuth provider configurations. Client secrets are never included in the response.","tags":["Admin/OAuth Configs"],"responses":{"200":{"description":"List of provider configs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuthProviderConfigListResponse"}}}},"403":{"description":"Forbidden - requires Tenant Admin role","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/admin/oauth-provider-configs/{provider}":{"get":{"summary":"Get OAuth provider config by provider name","description":"Returns the per-org config for the given provider, without the client secret. 404 if not configured.","tags":["Admin/OAuth Configs"],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":100,"description":"Provider identifier (e.g. \"microsoft\")"},"required":true,"description":"Provider identifier (e.g. \"microsoft\")","name":"provider","in":"path"}],"responses":{"200":{"description":"Provider config","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuthProviderConfigPublic"}}}},"403":{"description":"Forbidden - requires Tenant Admin role","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Provider config not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"put":{"summary":"Create or update OAuth provider config","description":"Insert or update the per-org OAuth client credentials for a provider. The client secret is encrypted at rest.","tags":["Admin/OAuth Configs"],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":100,"description":"Provider identifier (e.g. \"microsoft\")"},"required":true,"description":"Provider identifier (e.g. \"microsoft\")","name":"provider","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuthProviderConfigUpsertRequest"}}}},"responses":{"200":{"description":"Provider config upserted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuthProviderConfigPublic"}}}},"400":{"description":"Invalid request (e.g. unknown provider, missing tenantId for per_org provider)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden - requires Tenant Admin role","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"summary":"Partially update OAuth provider config","description":"Update specific fields (scopes, tenantId, clientSecretExpiresAt) without re-submitting the client secret. The config must already exist (use PUT to create). Scopes are full-replacement, not additive — send the complete list.","tags":["Admin/OAuth Configs"],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":100,"description":"Provider identifier (e.g. \"microsoft\")"},"required":true,"description":"Provider identifier (e.g. \"microsoft\")","name":"provider","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuthProviderConfigPatchRequest"}}}},"responses":{"200":{"description":"Provider config updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuthProviderConfigPublic"}}}},"400":{"description":"Invalid request (e.g. no fields provided)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden - requires Tenant Admin role","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Provider config not found (use PUT to create)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"summary":"Delete OAuth provider config","description":"Remove the per-org OAuth provider configuration. Existing user integrations remain in the DB but will fail to refresh until the provider is reconfigured.","tags":["Admin/OAuth Configs"],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":100,"description":"Provider identifier (e.g. \"microsoft\")"},"required":true,"description":"Provider identifier (e.g. \"microsoft\")","name":"provider","in":"path"}],"responses":{"204":{"description":"Provider config deleted"},"403":{"description":"Forbidden - requires Tenant Admin role","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Provider config not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/admin/org-profile":{"get":{"summary":"Get organization profile for the current org","description":"Get agent-facing organization profile fields for the current organization. Requires Tenant Admin.","tags":["Admin/Organization Profile"],"responses":{"200":{"description":"Organization profile","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdminOrgProfileResponse"}}}},"403":{"description":"Forbidden - requires Tenant Admin role","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"summary":"Update organization profile for the current org","description":"Update agent-facing organization profile fields for the current organization. Pass null to clear a field. Requires Tenant Admin.","tags":["Admin/Organization Profile"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdminOrgProfilePatch"}}}},"responses":{"200":{"description":"Updated organization profile","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdminOrgProfileResponse"}}}},"403":{"description":"Forbidden - requires Tenant Admin role","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/context-base/drafts":{"post":{"summary":"Create draft","description":"Create a new context-base draft and return session configuration","tags":["Context Base Drafts"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateContextBaseDraftBody"}}}},"responses":{"200":{"description":"Draft created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateContextBaseDraftResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Project or project phase not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"summary":"List drafts","description":"List context-base drafts visible to the current user","tags":["Context Base Drafts"],"parameters":[{"schema":{"type":"string","minLength":1,"description":"Filter by org repo ID"},"required":false,"description":"Filter by org repo ID","name":"orgRepoId","in":"query"},{"schema":{"type":"string","minLength":1,"description":"Filter by Mission Control ID"},"required":false,"description":"Filter by Mission Control ID","name":"missionControlId","in":"query"},{"schema":{"type":"string","description":"Comma-separated action-log change set IDs"},"required":false,"description":"Comma-separated action-log change set IDs","name":"actionLogChangeSetIds","in":"query"},{"schema":{"type":"boolean","nullable":true,"default":false,"description":"Include governance projections for review-requested drafts"},"required":false,"description":"Include governance projections for review-requested drafts","name":"includeGovernance","in":"query"}],"responses":{"200":{"description":"List of drafts","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListContextBaseDraftsResponse"}}}}}}},"/api/v1/context-base/sessions/{sessionId}/draft-state":{"get":{"summary":"Get session draft state","description":"Get event-derived context-base draft state for a chat session","tags":["Context Base Drafts"],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":128},"required":true,"name":"sessionId","in":"path"}],"responses":{"200":{"description":"Session draft state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContextBaseSessionDraftState"}}}}}}},"/api/v1/context-base/drafts/{draftId}":{"get":{"summary":"Get draft","description":"Get a context-base draft by ID","tags":["Context Base Drafts"],"parameters":[{"schema":{"type":"string","format":"uuid","description":"Draft ID"},"required":true,"description":"Draft ID","name":"draftId","in":"path"}],"responses":{"200":{"description":"Draft details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContextBaseDraft"}}}},"404":{"description":"Draft not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"summary":"Attach session to draft","description":"Attach a chat session to a draft and trigger workspace bootstrap","tags":["Context Base Drafts"],"parameters":[{"schema":{"type":"string","format":"uuid","description":"Draft ID"},"required":true,"description":"Draft ID","name":"draftId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AttachSessionToDraftBody"}}}},"responses":{"200":{"description":"Session attached","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContextBaseDraft"}}}},"404":{"description":"Draft not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Session already attached","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"summary":"Close draft","description":"Close a context-base draft. Removes the draft row, records terminal draft state, and preserves the chat session.","tags":["Context Base Drafts"],"parameters":[{"schema":{"type":"string","format":"uuid","description":"Draft ID"},"required":true,"description":"Draft ID","name":"draftId","in":"path"}],"responses":{"200":{"description":"Draft closed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Closed"}}}},"404":{"description":"Draft not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/context-base/drafts/{draftId}/session-config":{"get":{"summary":"Get draft session config","description":"Get chat-session launch configuration for an existing context-base draft","tags":["Context Base Drafts"],"parameters":[{"schema":{"type":"string","format":"uuid","description":"Draft ID"},"required":true,"description":"Draft ID","name":"draftId","in":"path"}],"responses":{"200":{"description":"Draft session config","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContextBaseDraftSessionConfig"}}}},"404":{"description":"Draft not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/context-base/drafts/{draftId}/status":{"get":{"summary":"Get draft status","description":"Get git status of the draft workspace","tags":["Context Base Drafts"],"parameters":[{"schema":{"type":"string","format":"uuid","description":"Draft ID"},"required":true,"description":"Draft ID","name":"draftId","in":"path"}],"responses":{"200":{"description":"Draft workspace status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContextBaseDraftStatusResponse"}}}},"404":{"description":"Draft not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/context-base/drafts/{draftId}/diff":{"get":{"summary":"Get file diff","description":"Get the diff for a single file in the draft workspace","tags":["Context Base Drafts"],"parameters":[{"schema":{"type":"string","format":"uuid","description":"Draft ID"},"required":true,"description":"Draft ID","name":"draftId","in":"path"},{"schema":{"type":"string","minLength":1,"maxLength":1024,"description":"File path relative to the context base"},"required":true,"description":"File path relative to the context base","name":"path","in":"query"}],"responses":{"200":{"description":"File diff","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContextBaseDraftDiffResponse"}}}},"404":{"description":"Draft not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/context-base/drafts/{draftId}/files/read":{"get":{"summary":"Read file","description":"Read a file from the draft workspace","tags":["Context Base Drafts"],"parameters":[{"schema":{"type":"string","format":"uuid","description":"Draft ID"},"required":true,"description":"Draft ID","name":"draftId","in":"path"},{"schema":{"type":"string","minLength":1,"maxLength":1024,"description":"File path relative to the context base"},"required":true,"description":"File path relative to the context base","name":"path","in":"query"}],"responses":{"200":{"description":"File content","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContextBaseDraftFileReadResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/context-base/drafts/{draftId}/files/write":{"post":{"summary":"Write file","description":"Write a file to the draft workspace","tags":["Context Base Drafts"],"parameters":[{"schema":{"type":"string","format":"uuid","description":"Draft ID"},"required":true,"description":"Draft ID","name":"draftId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WriteContextBaseDraftFileBody"}}}},"responses":{"200":{"description":"File written","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatusOk"}}}},"404":{"description":"Draft not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Invalid changelist body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/context-base/drafts/{draftId}/files/delete":{"post":{"summary":"Delete file","description":"Delete a file from the draft workspace","tags":["Context Base Drafts"],"parameters":[{"schema":{"type":"string","format":"uuid","description":"Draft ID"},"required":true,"description":"Draft ID","name":"draftId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeleteContextBaseDraftFileBody"}}}},"responses":{"200":{"description":"File deleted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatusOk"}}}},"404":{"description":"Draft not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/context-base/drafts/{draftId}/discard":{"post":{"summary":"Discard changes","description":"Discard all or selected file changes in the draft workspace","tags":["Context Base Drafts"],"parameters":[{"schema":{"type":"string","format":"uuid","description":"Draft ID"},"required":true,"description":"Draft ID","name":"draftId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DiscardContextBaseDraftBody"}}}},"responses":{"200":{"description":"Changes discarded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatusOk"}}}},"404":{"description":"Draft not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/context-base/drafts/{draftId}/can-publish":{"get":{"summary":"Check publish readiness","description":"Run publish preflight checks without mutating the draft or context base","tags":["Context Base Drafts"],"parameters":[{"schema":{"type":"string","format":"uuid","description":"Draft ID"},"required":true,"description":"Draft ID","name":"draftId","in":"path"}],"responses":{"200":{"description":"Publish readiness result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContextBaseDraftCanPublishResponse"}}}},"404":{"description":"Draft not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/context-base/drafts/{draftId}/publish":{"post":{"summary":"Publish draft","description":"Publish the draft changes to the context base","tags":["Context Base Drafts"],"parameters":[{"schema":{"type":"string","format":"uuid","description":"Draft ID"},"required":true,"description":"Draft ID","name":"draftId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublishContextBaseDraftBody"}}}},"responses":{"200":{"description":"Draft published","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContextBaseDraftPublishResponse"}}}},"404":{"description":"Draft not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Stale base commit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"412":{"description":"Governance approvals required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContextBaseDraftMissingApprovals"}}}}}}},"/api/v1/context-base/drafts/{draftId}/rebase":{"post":{"summary":"Rebase draft","description":"Rebase the draft workspace onto the latest context base commit","tags":["Context Base Drafts"],"parameters":[{"schema":{"type":"string","format":"uuid","description":"Draft ID"},"required":true,"description":"Draft ID","name":"draftId","in":"path"}],"responses":{"200":{"description":"Rebase result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContextBaseDraftRebaseResponse"}}}},"404":{"description":"Draft not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/context-base/drafts/{draftId}/governance":{"get":{"summary":"Get governance","description":"Get the governance projection for the draft","tags":["Context Base Drafts"],"parameters":[{"schema":{"type":"string","format":"uuid","description":"Draft ID"},"required":true,"description":"Draft ID","name":"draftId","in":"path"}],"responses":{"200":{"description":"Governance projection","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GovernanceProjection"}}}},"404":{"description":"Draft not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/context-base/drafts/{draftId}/action-log-change-set":{"get":{"summary":"Get draft action-log change set","description":"Get the linked context-side action-log change set for draft review","tags":["Context Base Drafts"],"parameters":[{"schema":{"type":"string","format":"uuid","description":"Draft ID"},"required":true,"description":"Draft ID","name":"draftId","in":"path"}],"responses":{"200":{"description":"Action-log change set details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContextBaseDraftActionLogChangeSet"}}}},"404":{"description":"Draft or change set not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Draft action-log link is incomplete","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/context-base/drafts/{draftId}/request-review":{"post":{"summary":"Request review","description":"Request governance review for the draft","tags":["Context Base Drafts"],"parameters":[{"schema":{"type":"string","format":"uuid","description":"Draft ID"},"required":true,"description":"Draft ID","name":"draftId","in":"path"}],"responses":{"200":{"description":"Review requested","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContextBaseDraft"}}}},"404":{"description":"Draft not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/context-base/drafts/{draftId}/approve":{"post":{"summary":"Approve draft","description":"Approve the draft as a governance reviewer","tags":["Context Base Drafts"],"parameters":[{"schema":{"type":"string","format":"uuid","description":"Draft ID"},"required":true,"description":"Draft ID","name":"draftId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApproveContextBaseDraftBody"}}}},"responses":{"200":{"description":"Draft approved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContextBaseDraft"}}}},"403":{"description":"Not a reviewer","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Draft not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/context-base/drafts/{draftId}/request-changes":{"post":{"summary":"Request changes","description":"Request changes on the draft as a governance reviewer","tags":["Context Base Drafts"],"parameters":[{"schema":{"type":"string","format":"uuid","description":"Draft ID"},"required":true,"description":"Draft ID","name":"draftId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestChangesContextBaseDraftBody"}}}},"responses":{"200":{"description":"Changes requested","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContextBaseDraft"}}}},"403":{"description":"Not a reviewer","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Draft not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/context-base/drafts/{draftId}/admin-override-publish":{"post":{"summary":"Admin override publish","description":"Publish the draft bypassing governance requirements (admin only)","tags":["Context Base Drafts"],"parameters":[{"schema":{"type":"string","format":"uuid","description":"Draft ID"},"required":true,"description":"Draft ID","name":"draftId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdminOverridePublishContextBaseDraftBody"}}}},"responses":{"200":{"description":"Draft published via admin override","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContextBaseDraftPublishResponse"}}}},"403":{"description":"Not an admin","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Draft not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"412":{"description":"Governance approvals required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContextBaseDraftMissingApprovals"}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Bearer token (`sk-eai-...` API key or session JWT)."}},"schemas":{"TenantResponse":{"type":"object","properties":{"id":{"type":"string","description":"The Descope tenant ID"},"name":{"type":"string","description":"The tenant name (slug)"},"displayName":{"type":"string","description":"The tenant display name"}},"required":["id","name"]},"Error":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"description":"Error response"},"PublicArtifactResponse":{"type":"object","properties":{"artifact":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"type":{"type":"string"},"nodeKind":{"type":"string"},"data":{"type":"object","properties":{"mimeType":{"type":"string"},"size":{"type":"number"}}}},"required":["id","name","type","nodeKind"]},"signedUrl":{"type":"string","format":"uri","description":"Signed download URL for the artifact file"}},"required":["artifact","signedUrl"]},"DemoBookingRequest":{"type":"object","properties":{"fullName":{"type":"string","minLength":1,"maxLength":255,"description":"Full name of the person requesting the demo"},"workEmail":{"type":"string","format":"email","description":"Work email address for demo scheduling"},"companySize":{"type":"string","minLength":1,"description":"Size of the company (e.g., \"1-10\", \"11-50\", \"51-200\", \"201-500\", \"500+\")"},"role":{"type":"string","minLength":1,"maxLength":255,"description":"Job title or role of the person requesting the demo"}},"required":["fullName","workEmail","companySize","role"],"description":"Request to book a demo meeting"},"DemoBookingResponse":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the demo booking was successful"},"message":{"type":"string","description":"Response message"},"bookingId":{"type":"string","format":"uuid","description":"Unique identifier for the demo booking"}},"required":["success","message"],"description":"Response from demo booking request"},"OAuthConnectResponse":{"type":"object","properties":{"redirectUrl":{"type":"string","format":"uri"}},"required":["redirectUrl"]},"OAuthStatusResponse":{"type":"object","properties":{"provider":{"type":"string"},"connected":{"type":"boolean"},"providerConfigured":{"type":"boolean"},"requiresReconnect":{"type":"boolean"},"account":{"type":"object","properties":{"email":{"type":"string","nullable":true},"name":{"type":"string","nullable":true},"connectedAt":{"type":"string"}},"required":["email","name","connectedAt"]}},"required":["provider","connected","providerConfigured"]},"OAuthDisconnectResponse":{"type":"object","properties":{"success":{"type":"boolean"}},"required":["success"]},"GmailPubSubPushEnvelope":{"type":"object","properties":{"message":{"type":"object","properties":{"data":{"type":"string","description":"Base64-encoded Gmail push notification payload"},"attributes":{"type":"object","additionalProperties":{"type":"string"}},"messageId":{"type":"string"},"publishTime":{"type":"string"}},"required":["data","messageId"]},"subscription":{"type":"string"}},"required":["message","subscription"]},"MintSubjectTokenResponse":{"type":"object","properties":{"subject_token":{"type":"string","minLength":1},"expires_at_epoch_seconds":{"type":"integer"}},"required":["subject_token","expires_at_epoch_seconds"]},"UserCreate":{"type":"object","properties":{"email":{"type":"string","format":"email","description":"User email address"},"name":{"type":"string","description":"User display name"},"metadata":{"type":"object","additionalProperties":{"nullable":true},"default":{},"description":"Additional user metadata"}},"required":["email"],"description":"User creation data"},"User":{"type":"object","properties":{"id":{"type":"integer","description":"User ID"},"email":{"type":"string","format":"email","description":"User email address"},"name":{"type":"string","nullable":true,"description":"User display name"},"descope_user_id":{"type":"string","description":"Descope user identifier"},"metadata":{"type":"object","additionalProperties":{"nullable":true},"default":{},"description":"User metadata"},"created_at":{"type":"string","format":"date-time","description":"Account creation timestamp"},"updated_at":{"type":"string","format":"date-time","description":"Last update timestamp"}},"required":["id","email","name","descope_user_id","created_at","updated_at"],"description":"User profile information"},"UserUpdate":{"type":"object","properties":{"name":{"type":"string"},"metadata":{"type":"object","additionalProperties":{"nullable":true}}},"description":"User update data"},"UserProfileResponse":{"type":"object","properties":{"identity":{"$ref":"#/components/schemas/UserProfileIdentity"},"profile":{"$ref":"#/components/schemas/UserProfileFields"}},"required":["identity","profile"],"description":"Authenticated user identity and profile"},"UserProfilePatch":{"type":"object","properties":{"role":{"type":"string","nullable":true,"maxLength":200},"team":{"type":"string","nullable":true,"maxLength":200},"communication":{"type":"string","nullable":true,"maxLength":1000},"instructions":{"type":"string","nullable":true,"maxLength":2000}},"additionalProperties":false,"description":"Partial user profile update"},"UserPreferences":{"type":"object","properties":{"notifications":{"$ref":"#/components/schemas/NotificationPrefs"}}},"UserPreferencesPatch":{"type":"object","properties":{"notifications":{"type":"object","properties":{"mutedEventTypes":{"type":"object","properties":{"mention":{"type":"boolean"},"participate":{"type":"boolean"},"agentLoopCompletion":{"type":"boolean"},"chatMessage":{"type":"boolean"},"email":{"type":"object","properties":{"announcement":{"type":"boolean"}}}}},"globalSnooze":{"type":"object","properties":{"until":{"type":"string","nullable":true,"format":"date-time"}}},"agentLoopCompletion":{"type":"object","properties":{"minDurationMs":{"type":"integer","nullable":true,"minimum":0,"maximum":3600000}}},"mutedSessions":{"type":"array","items":{"type":"object","properties":{"sessionId":{"type":"string","minLength":1},"expiresAt":{"type":"string","nullable":true,"format":"date-time"}},"required":["sessionId"]},"maxItems":500}}}}},"UserStats":{"type":"object","properties":{"total":{"type":"integer","description":"Total number of users"},"active":{"type":"integer","description":"Number of active users"},"inactive":{"type":"integer","description":"Number of inactive users"}},"required":["total","active","inactive"],"description":"User statistics"},"CosmosSqlQueryRequest":{"type":"object","properties":{"sql":{"type":"string","minLength":1,"description":"Read-only PostgreSQL SELECT query against Cosmos reporting schemas"},"description":{"type":"string","minLength":1,"maxLength":500,"description":"Optional human-readable description of the query intent"}},"required":["sql"],"description":"Request to execute Cosmos SQL"},"CosmosSqlQueryResponse":{"type":"object","properties":{"records":{"type":"array","items":{"type":"object","additionalProperties":{"nullable":true}}},"query_runtime_ms":{"type":"number","minimum":0}},"required":["records","query_runtime_ms"],"description":"Cosmos SQL query results"},"CosmosInsuranceSpaceDsnResponse":{"type":"object","properties":{"dsn":{"type":"string","description":"Bundle-scoped Postgres DSN for the authenticated tenant, or empty string when the provisioner is unconfigured or transiently unreachable. Empty matches the existing MissingDSNError contract — sandbox boots, toolkit raises only on actual insurance_space access."}},"required":["dsn"],"description":"Tenant insurance_space DSN response."},"ApiKeyList":{"type":"object","properties":{"apiKeys":{"type":"array","items":{"$ref":"#/components/schemas/ApiKey"}}},"required":["apiKeys"],"description":"List of API keys for a user"},"CreateApiKey":{"type":"object","properties":{"key_name":{"type":"string","minLength":1,"maxLength":255,"description":"Human-readable name for the API key"},"expires_at":{"type":"string","format":"date-time","description":"Optional expiration timestamp. Omit for a key that never expires."}},"required":["key_name"],"description":"Data for creating a new API key"},"CreateApiKeyResponse":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"API key ID"},"user_id":{"type":"integer","description":"User ID who owns this key"},"key_name":{"type":"string","description":"Human-readable name for the API key"},"role":{"type":"string","description":"Role assigned to this API key"},"is_disabled":{"type":"boolean","description":"Whether the API key is disabled"},"expires_at":{"type":"string","nullable":true,"format":"date-time","description":"Expiration timestamp, or null if the key never expires"},"created_at":{"type":"string","format":"date-time","description":"Key creation timestamp"},"updated_at":{"type":"string","format":"date-time","description":"Last update timestamp"},"key_value":{"type":"string","description":"The actual API key value (only returned on creation)"}},"required":["id","user_id","key_name","role","is_disabled","expires_at","created_at","updated_at","key_value"],"description":"API key information with value for create response"},"ApiKey":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"API key ID"},"user_id":{"type":"integer","description":"User ID who owns this key"},"key_name":{"type":"string","description":"Human-readable name for the API key"},"role":{"type":"string","description":"Role assigned to this API key"},"is_disabled":{"type":"boolean","description":"Whether the API key is disabled"},"expires_at":{"type":"string","nullable":true,"format":"date-time","description":"Expiration timestamp, or null if the key never expires"},"created_at":{"type":"string","format":"date-time","description":"Key creation timestamp"},"updated_at":{"type":"string","format":"date-time","description":"Last update timestamp"}},"required":["id","user_id","key_name","role","is_disabled","expires_at","created_at","updated_at"],"description":"API key information"},"UpdateApiKey":{"type":"object","properties":{"key_name":{"type":"string","minLength":1,"maxLength":255,"description":"Updated name for the API key"},"is_disabled":{"type":"boolean","description":"Whether to disable/enable the API key"},"expires_at":{"type":"string","nullable":true,"format":"date-time","description":"Updated expiration timestamp. Set to null to remove expiry."}},"description":"Data for updating an API key"},"AgentSyncRequest":{"type":"object","properties":{"fileId":{"type":"string","minLength":1,"maxLength":255,"description":"Claude transcript file UUID — stable per-session anchor"},"source":{"type":"string","enum":["claude-code","codex"],"description":"Originating agent; defaults to claude-code"},"metadata":{"$ref":"#/components/schemas/AgentSyncMetadata"},"events":{"type":"array","items":{"type":"string","maxLength":200000},"minItems":1,"maxItems":2000,"description":"Raw, already-client-redacted JSONL transcript lines, one per element"}},"required":["fileId","events"],"description":"A batch of raw transcript lines to sync"},"AgentSyncResponse":{"type":"object","properties":{"sessionId":{"type":"string","format":"uuid","description":"Native Effective session id (deterministic per org+file)"},"appended":{"type":"integer","description":"Number of new message entries inserted"},"received":{"type":"integer","description":"Number of message-shaped lines parsed from the batch"}},"required":["sessionId","appended","received"],"description":"Claude sync result"},"ListAgentsResponse":{"type":"object","properties":{"agents":{"type":"array","items":{"$ref":"#/components/schemas/AgentCatalogInfo"}}},"required":["agents"]},"AgentsErrorResponse":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]},"CreateAgentFunctionRunRequest":{"type":"object","properties":{"agent":{"type":"object","properties":{"presetRef":{"$ref":"#/components/schemas/PresetRef"},"systemPreset":{"$ref":"#/components/schemas/SystemPreset"},"model":{"type":"string","enum":["claude-fable-5","claude-opus-4-8","claude-opus-4-7","claude-opus-4-6","claude-sonnet-4-6","claude-sonnet-4-6-1m","claude-sonnet-4-5-20250929","claude-opus-4-5-20251101","claude-haiku-4-5-20251001","gpt-5.5","gpt-5.5-pro","gpt-5.4","gpt-5.4-mini","gpt-5.4-nano","gpt-5.4-pro","gpt-5.3-codex","gemini-3.1-pro-preview","gemini-3-flash-preview","gemini-2.5-pro","gemini-2.5-flash","gemini-2.5-flash-lite","gemini-3.1-flash-lite","gemini-flash-latest","gemini-flash-lite-latest","deepseek/deepseek-v4-pro","deepseek/deepseek-v4-flash","xai/grok-4.3","zai/glm-5.1","glm-5.2","nvidia/nemotron-3-ultra-550b-a55b","moonshotai/kimi-k2.6","moonshotai/kimi-k2.7-code","moonshotai/kimi-k2.5"]},"toolConfig":{"type":"object","properties":{"enabled":{"type":"array","items":{"type":"string"},"description":"Allowlist of tool names. When set, only tools whose declaration.name appears in this list are registered."},"disabled":{"type":"array","items":{"type":"string"},"description":"Denylist of tool names. When set, tools whose declaration.name appears in this list are excluded."}}}}},"task":{"type":"object","properties":{"name":{"type":"string","minLength":1},"instructions":{"type":"string","minLength":1},"input":{"nullable":true},"inputSchema":{"type":"object","additionalProperties":{"nullable":true}},"outputSchema":{"type":"object","additionalProperties":{"nullable":true}}},"required":["name","outputSchema"]},"execution":{"type":"object","properties":{"mode":{"type":"string","enum":["function","session"],"default":"function"},"computer":{"type":"string","enum":["shared","isolated"],"default":"isolated"},"parentSessionId":{"type":"string","minLength":1},"timeoutSeconds":{"type":"integer","minimum":1,"maximum":3600,"default":900},"wait":{"type":"boolean","default":false},"dispatch":{"type":"boolean","default":true}},"default":{"mode":"function","computer":"isolated","timeoutSeconds":900,"wait":false,"dispatch":true}},"metadata":{"type":"object","properties":{"tags":{"type":"array","items":{"type":"string"}},"workflowRunId":{"type":"string"},"workflowId":{"type":"string"},"workflowStepId":{"type":"string"},"projectPhaseKey":{"type":"string","minLength":1,"maxLength":128}}}},"required":["agent","task"]},"AgentFunctionRunResponse":{"type":"object","properties":{"runId":{"type":"string"},"status":{"type":"string","enum":["queued","running","completed","failed","timed_out"]},"taskId":{"type":"string","format":"uuid"},"sessionId":{"type":"string"},"assignmentId":{"type":"string","format":"uuid"},"submissionId":{"type":"string","format":"uuid"},"output":{"nullable":true},"outputArtifactId":{"type":"string"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["runId","status","taskId"]},"CreateAgentTask":{"type":"object","properties":{"project_id":{"type":"string","nullable":true,"format":"uuid"},"project_phase_id":{"type":"string","nullable":true,"format":"uuid"},"project_phase_key":{"type":"string"},"title":{"type":"string","nullable":true},"body":{"type":"string","nullable":true},"input_artifact_id":{"type":"string","nullable":true},"payload":{"type":"object","additionalProperties":{"nullable":true}},"attachments":{"type":"array","items":{"type":"string"}},"labels":{"type":"array","items":{"type":"string"}},"status":{"type":"string","enum":["open","blocked","completed","closed"]},"creator_session_id":{"type":"string","nullable":true}}},"AgentTask":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"project_id":{"type":"string","nullable":true,"format":"uuid"},"project_phase_id":{"type":"string","nullable":true,"format":"uuid"},"title":{"type":"string","nullable":true},"body":{"type":"string","nullable":true},"input_artifact_id":{"type":"string","nullable":true},"payload":{"type":"object","additionalProperties":{"nullable":true}},"attachments":{"type":"array","items":{"type":"string"}},"labels":{"type":"array","items":{"type":"string"}},"status":{"type":"string","enum":["open","blocked","completed","closed"]},"creator_session_id":{"type":"string","nullable":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"submissions":{"type":"array","items":{"$ref":"#/components/schemas/AgentTaskSubmission"}},"can_submit":{"type":"boolean"}},"required":["id","project_id","project_phase_id","title","body","input_artifact_id","payload","attachments","labels","status","creator_session_id","created_at","updated_at"]},"AgentTaskListResponse":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/AgentTask"}},"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"}},"required":["items","total","limit","offset"]},"AgentTaskAssignmentListResponse":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/AgentTaskAssignment"}},"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"}},"required":["items","total","limit","offset"]},"AgentTaskAssignmentsByTaskIdsResponse":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/AgentTaskAssignment"}}},"required":["items"]},"AgentTaskSubmission":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"task_id":{"type":"string","format":"uuid"},"output_artifact_id":{"type":"string","nullable":true},"body":{"type":"string","nullable":true},"payload":{"type":"object","additionalProperties":{"nullable":true}},"attachments":{"type":"array","items":{"type":"string"}},"actor_type":{"type":"string","nullable":true,"enum":["session","user","user_group","workflow","system",null]},"actor_id":{"type":"string","nullable":true},"session_id":{"type":"string","nullable":true},"actor_label":{"type":"string","nullable":true},"submitted_at":{"type":"string","format":"date-time"},"comments":{"type":"array","items":{"$ref":"#/components/schemas/AgentTaskComment"}}},"required":["id","task_id","output_artifact_id","body","payload","attachments","actor_type","actor_id","session_id","actor_label","submitted_at"]},"CreateAgentTaskComment":{"type":"object","properties":{"body":{"type":"string","nullable":true},"payload":{"type":"object","additionalProperties":{"nullable":true}},"attachments":{"type":"array","items":{"type":"string"}},"actor_type":{"type":"string","enum":["session","user","user_group","workflow","system"]},"actor_id":{"type":"string"},"input_artifact_id":{"type":"string","nullable":true},"author_session_id":{"type":"string","nullable":true}}},"AgentTaskComment":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"task_id":{"type":"string","format":"uuid"},"submission_id":{"type":"string","nullable":true,"format":"uuid"},"body":{"type":"string","nullable":true},"payload":{"type":"object","additionalProperties":{"nullable":true}},"attachments":{"type":"array","items":{"type":"string"}},"actor_type":{"type":"string","nullable":true,"enum":["session","user","user_group","workflow","system",null]},"actor_id":{"type":"string","nullable":true},"input_artifact_id":{"type":"string","nullable":true},"author_session_id":{"type":"string","nullable":true},"created_at":{"type":"string","format":"date-time"}},"required":["id","task_id","submission_id","body","payload","attachments","actor_type","actor_id","input_artifact_id","author_session_id","created_at"]},"AgentTaskCommentListResponse":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/AgentTaskComment"}},"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"}},"required":["items","total","limit","offset"]},"UpdateAgentTask":{"type":"object","properties":{"body":{"type":"string","nullable":true},"payload":{"type":"object","additionalProperties":{"nullable":true}},"status":{"type":"string","enum":["open","blocked","completed","closed"]},"labels":{"type":"array","items":{"type":"string"}}}},"CreateAgentTaskLink":{"type":"object","properties":{"target_task_id":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["blocks","relates_to","duplicates","parent"]},"metadata":{"type":"object","additionalProperties":{"nullable":true}}},"required":["target_task_id","type"]},"AgentTaskLink":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"source_task_id":{"type":"string","format":"uuid"},"target_task_id":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["blocks","relates_to","duplicates","parent"]},"metadata":{"type":"object","additionalProperties":{"nullable":true}},"created_by_user_id":{"type":"string","nullable":true},"created_at":{"type":"string","format":"date-time"}},"required":["id","source_task_id","target_task_id","type","metadata","created_by_user_id","created_at"]},"AgentTaskLinkListResponse":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/AgentTaskLink"}},"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"}},"required":["items","total","limit","offset"]},"CreateAgentTaskAssignment":{"type":"object","properties":{"session_id":{"type":"string","nullable":true},"assignee_type":{"type":"string","enum":["session","user","user_group"]},"assignee_id":{"type":"string"}}},"AgentTaskAssignment":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"task_id":{"type":"string","format":"uuid"},"session_id":{"type":"string","nullable":true},"assignee_type":{"type":"string","enum":["session","user","user_group"]},"assignee_id":{"type":"string"},"assignee_label":{"type":"string","nullable":true},"created_at":{"type":"string","format":"date-time"}},"required":["id","task_id","session_id","assignee_type","assignee_id","created_at"]},"CreateAgentTaskSubmission":{"type":"object","properties":{"output_artifact_id":{"type":"string","nullable":true},"body":{"type":"string","nullable":true},"payload":{"type":"object","additionalProperties":{"nullable":true}},"attachments":{"type":"array","items":{"type":"string"}},"actor_type":{"type":"string","enum":["session","user","user_group","workflow","system"]},"actor_id":{"type":"string"},"session_id":{"type":"string","nullable":true}}},"AgentTaskSubmissionListResponse":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/AgentTaskSubmission"}},"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"}},"required":["items","total","limit","offset"]},"SummarizeResourcesRequest":{"type":"object","properties":{"refs":{"type":"array","items":{"$ref":"#/components/schemas/ResourceRef"},"minItems":1,"maxItems":100}},"required":["refs"]},"SummarizeResourcesResponse":{"type":"object","properties":{"summaries":{"type":"array","items":{"$ref":"#/components/schemas/ResourceSummary"}}},"required":["summaries"]},"CreateThreadRequest":{"type":"object","properties":{"ref":{"$ref":"#/components/schemas/ResourceRef"},"body":{"type":"string","minLength":1,"maxLength":20000},"anchor":{"$ref":"#/components/schemas/ResourceAnchor"},"mentionedUserIds":{"type":"array","items":{"type":"string","minLength":1},"maxItems":50,"description":"User ids mentioned via @ tokens (same shape as chat send-async)"},"missionControlId":{"type":"string","minLength":1,"description":"Mission control (slug) the comment was made from; preferred for notification deep links when the resource is mounted in several mission controls"}},"required":["ref","body"]},"CreateThreadResponse":{"type":"object","properties":{"thread":{"$ref":"#/components/schemas/ResourceThread"},"firstComment":{"$ref":"#/components/schemas/ResourceThreadComment"}},"required":["thread","firstComment"]},"ResourceThreadPage":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/ResourceThread"}},"nextCursor":{"type":"string","nullable":true}},"required":["items","nextCursor"]},"ResourceThread":{"type":"object","properties":{"id":{"type":"string"},"resourceType":{"type":"string"},"resourceKey":{"type":"object","additionalProperties":{"type":"string"}},"status":{"type":"string","enum":["open","resolved"]},"anchor":{"$ref":"#/components/schemas/ResourceAnchor"},"createdBy":{"type":"string"},"resolvedBy":{"type":"string","nullable":true},"resolvedAt":{"type":"string","nullable":true},"lastActivityAt":{"type":"string"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","resourceType","resourceKey","status","createdBy","resolvedBy","resolvedAt","lastActivityAt","createdAt","updatedAt"]},"ResourceThreadCommentPage":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/ResourceThreadComment"}},"nextCursor":{"type":"string","nullable":true}},"required":["items","nextCursor"]},"AddCommentRequest":{"type":"object","properties":{"body":{"type":"string","minLength":1,"maxLength":20000},"parentCommentId":{"type":"string","format":"uuid"},"mentionedUserIds":{"type":"array","items":{"type":"string","minLength":1},"maxItems":50,"description":"User ids mentioned via @ tokens (same shape as chat send-async)"},"missionControlId":{"type":"string","minLength":1,"description":"Mission control (slug) the comment was made from; preferred for notification deep links when the resource is mounted in several mission controls"}},"required":["body"]},"ResourceThreadComment":{"type":"object","properties":{"id":{"type":"string"},"threadId":{"type":"string"},"parentCommentId":{"type":"string","nullable":true},"commentType":{"type":"string","enum":["message","system","status_change"]},"actor":{"type":"string"},"body":{"type":"string","nullable":true},"data":{"type":"object","additionalProperties":{"nullable":true}},"deleted":{"type":"boolean"},"editedAt":{"type":"string","nullable":true},"createdAt":{"type":"string"}},"required":["id","threadId","parentCommentId","commentType","actor","body","data","deleted","editedAt","createdAt"]},"EditCommentRequest":{"type":"object","properties":{"body":{"type":"string","minLength":1,"maxLength":20000},"mentionedUserIds":{"type":"array","items":{"type":"string","minLength":1},"maxItems":50,"description":"User ids mentioned via @ tokens (same shape as chat send-async)"}},"required":["body"]},"SaveBookmarkRequest":{"type":"object","properties":{"ref":{"$ref":"#/components/schemas/ResourceRef"},"note":{"type":"string","maxLength":2000},"missionControlId":{"type":"string","minLength":1,"description":"Mission control (slug) the bookmark was saved from; stored as link context so bookmark lists can deep-link back to where the user found the resource"}},"required":["ref"]},"ResourceBookmark":{"type":"object","properties":{"id":{"type":"string"},"resourceType":{"type":"string"},"resourceKey":{"type":"object","additionalProperties":{"type":"string"}},"note":{"type":"string","nullable":true},"data":{"type":"object","additionalProperties":{"nullable":true}},"createdAt":{"type":"string"}},"required":["id","resourceType","resourceKey","note","data","createdAt"]},"ResourceBookmarkPage":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/ResourceBookmark"}},"nextCursor":{"type":"string","nullable":true}},"required":["items","nextCursor"]},"AiOverviewTargetKind":{"type":"string","enum":["mission_control","project","agent_task"]},"AiOverviewResponse":{"type":"object","properties":{"overview":{"$ref":"#/components/schemas/AiOverview"}},"required":["overview"]},"RegenerateAiOverview":{"type":"object","properties":{"target_kind":{"$ref":"#/components/schemas/AiOverviewTargetKind"},"target_id":{"type":"string","minLength":1,"maxLength":255},"max_chars":{"type":"integer","minimum":500,"maximum":4000}},"required":["target_kind","target_id"],"description":"Regenerate an AI overview for a target"},"WorkflowRealtimeEvent":{"type":"object","properties":{"type":{"type":"string","enum":["project.updated","project_phase.updated","workflow_run.updated","agent_task.updated","task_comment.created","keep_alive"]},"orgId":{"type":"string"},"projectId":{"type":"string","nullable":true},"missionControlId":{"type":"string","nullable":true},"taskId":{"type":"string","nullable":true},"workflowRunId":{"type":"string","nullable":true},"phaseId":{"type":"string","nullable":true},"timestamp":{"type":"string"}},"required":["type","orgId","timestamp"]},"StartWorkflowRun":{"type":"object","properties":{"project_id":{"type":"string","nullable":true,"format":"uuid","description":"Existing project to attach. If omitted, required project-backed workflows create a project from their catalog template."},"workflow_id":{"type":"string","description":"L1 catalog workflow id, e.g. iso-circular-processing"},"workflow_version":{"type":"string","nullable":true},"mission_control_id":{"type":"string","description":"Mission Control instance for an auto-created workflow project"},"input":{"type":"object","additionalProperties":{"nullable":true}},"metadata":{"type":"object","additionalProperties":{"nullable":true}}},"required":["workflow_id"]},"WorkflowRun":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"project_id":{"type":"string","nullable":true,"format":"uuid"},"workflow_id":{"type":"string"},"workflow_version":{"type":"string","nullable":true},"engine_run_id":{"type":"string","nullable":true},"status":{"type":"string","enum":["running","waiting","completed","failed","cancelled"]},"input":{"type":"object","additionalProperties":{"nullable":true}},"metadata":{"type":"object","additionalProperties":{"nullable":true}},"failure":{"type":"object","nullable":true,"properties":{"message":{"type":"string"},"step_name":{"type":"string","nullable":true},"step_display_name":{"type":"string","nullable":true},"phase_key":{"type":"string","nullable":true},"failed_at":{"type":"string","nullable":true,"format":"date-time"},"code":{"type":"string","nullable":true}},"required":["message","step_name","step_display_name","phase_key","failed_at","code"]},"started_at":{"type":"string","format":"date-time"},"completed_at":{"type":"string","nullable":true,"format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","project_id","workflow_id","workflow_version","engine_run_id","status","input","metadata","failure","started_at","completed_at","created_at","updated_at"]},"WorkflowRunListResponse":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/WorkflowRun"}},"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"}},"required":["items","total","limit","offset"]},"WorkflowRunEngineEventListResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/WorkflowRunEngineEvent"}},"cursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}},"required":["data","hasMore"]},"WorkflowRunTaskListResponse":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/WorkflowRunTask"}}},"required":["items"]},"RegisterWorkflowTask":{"type":"object","properties":{"wait_key":{"type":"string","description":"SDK hook token (resume credential). Stored server-only."},"title":{"type":"string","nullable":true},"body":{"type":"string","nullable":true},"input_artifact_id":{"type":"string","nullable":true},"payload":{"type":"object","additionalProperties":{"nullable":true},"description":"Workflow task payload (human_review.v1 or agent_function.v1). The shape is validated server-side at materialization."},"attachments":{"type":"array","items":{"type":"string"}},"expected_actions":{"type":"array","items":{"type":"string"}},"assignees":{"type":"array","items":{"type":"object","properties":{"assignee_type":{"type":"string","enum":["session","user","user_group","agent"]},"assignee_ref":{"type":"string","description":"Canonical ref for user/user_group/session assignees (required); optional label for an agent assignee (the API creates a session assignment internally)."}},"required":["assignee_type"]},"description":"Who the materialized task is assigned to. The workflow conveys this (user / user_group / session / request-only agent); created atomically with the task where possible. Agent assignees create a session assignment internally."}},"required":["wait_key"]},"RegisterWorkflowTaskResponse":{"type":"object","properties":{"task_id":{"type":"string","format":"uuid"},"wait":{"$ref":"#/components/schemas/WorkflowWait"}},"required":["task_id","wait"]},"RegisterWorkflowDraftTask":{"type":"object","properties":{"wait_key":{"type":"string","description":"SDK hook token (resume credential). Stored server-only."},"title":{"type":"string","nullable":true},"body":{"type":"string","nullable":true},"input_artifact_id":{"type":"string","nullable":true},"payload":{"type":"object","additionalProperties":{"nullable":true},"description":"Workflow task payload (human_review.v1 or agent_function.v1). The shape is validated server-side at materialization."},"attachments":{"type":"array","items":{"type":"string"}},"expected_actions":{"type":"array","items":{"type":"string"}},"assignees":{"type":"array","items":{"type":"object","properties":{"assignee_type":{"type":"string","enum":["session","user","user_group","agent"]},"assignee_ref":{"type":"string","description":"Canonical ref for user/user_group/session assignees (required); optional label for an agent assignee (the API creates a session assignment internally)."}},"required":["assignee_type"]},"description":"Who the materialized task is assigned to. The workflow conveys this (user / user_group / session / request-only agent); created atomically with the task where possible. Agent assignees create a session assignment internally."},"context_base_draft":{"type":"object","properties":{"mode":{"type":"string","enum":["edit"],"description":"Context Base draft mode. Only `edit` is supported (the default)."},"org_repo_id":{"type":"string","minLength":1},"mission_control_id":{"type":"string","minLength":1}},"description":"Directs the platform to create a Context Base draft up front, start the agent session bound to it, and guarantee the created draftId in the task output."}},"required":["wait_key","context_base_draft"]},"RegisterWorkflowDraftWait":{"type":"object","properties":{"wait_key":{"type":"string","description":"SDK hook token (resume credential). Stored server-only."},"draft_id":{"type":"string","format":"uuid","description":"Context Base draft id. The wait attaches to the draft lifecycle task and resumes when the draft reaches a terminal lifecycle state."},"expected_statuses":{"type":"array","items":{"type":"string","enum":["published","abandoned"]},"minItems":1,"default":["published","abandoned"],"description":"Terminal draft statuses that should satisfy the wait."}},"required":["wait_key","draft_id"]},"NetworkInjectionConfig":{"type":"object","nullable":true,"properties":{"routes":{"type":"array","items":{"$ref":"#/components/schemas/NetworkInjectionRoute"},"minItems":1,"maxItems":50}},"required":["routes"]},"CreateIncomingWebhookRequest":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":128}},"required":["name"]},"CreateIncomingWebhookResponse":{"type":"object","properties":{"webhook":{"$ref":"#/components/schemas/IncomingWebhook"},"webhookUrl":{"type":"string"}},"required":["webhook","webhookUrl"]},"ListIncomingWebhooksResponse":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/IncomingWebhook"}}},"required":["items"]},"RevokeIncomingWebhookResponse":{"type":"object","properties":{"success":{"type":"boolean"}},"required":["success"]},"IncomingWebhookBearerFireResponse":{"type":"object","properties":{"ok":{"type":"boolean"},"duplicate":{"type":"boolean"},"idempotencyKey":{"type":"string"},"fireId":{"type":"string","format":"uuid"},"eventId":{"type":"string","nullable":true,"format":"uuid"},"sessionId":{"type":"string","nullable":true},"sessionUrl":{"type":"string","nullable":true,"format":"uri"},"status":{"type":"string","enum":["accepted","in_flight","failed"]}},"required":["ok","duplicate","idempotencyKey","fireId","eventId","sessionId","sessionUrl","status"]},"ListAppsNdjsonResponse":{"type":"string","description":"application/x-ndjson stream of AppsStreamEvent lines"},"AppShareResponse":{"type":"object","properties":{"app_id":{"type":"string"},"visibility":{"type":"string","enum":["team"]}},"required":["app_id","visibility"]},"AppUnshareResponse":{"type":"object","properties":{"app_id":{"type":"string"},"visibility":{"type":"string","enum":["private"]}},"required":["app_id","visibility"]},"BookmarkResponse":{"type":"object","properties":{"app_id":{"type":"string"},"bookmarked":{"type":"boolean","enum":[true]}},"required":["app_id","bookmarked"]},"UnbookmarkResponse":{"type":"object","properties":{"app_id":{"type":"string"},"bookmarked":{"type":"boolean","enum":[false]}},"required":["app_id","bookmarked"]},"AppLogsResponse":{"type":"object","properties":{"logs":{"type":"array","items":{"$ref":"#/components/schemas/AppLogEntry"}},"total":{"type":"number"},"tookMs":{"type":"number"},"success":{"type":"boolean"},"error":{"type":"string","nullable":true}},"required":["logs","total","tookMs","success","error"]},"OrgSandboxUrlResponse":{"type":"object","properties":{"publicUrl":{"type":"string","format":"uri","description":"Base URL for the org sandbox root gateway (no trailing slash)"},"sandboxId":{"type":"string","description":"E2B sandbox ID (debug)"},"tenantSlug":{"type":"string","description":"Tenant slug used in the gateway hostname"}},"required":["publicUrl","sandboxId","tenantSlug"]},"ArtifactListResponse":{"type":"object","properties":{"artifacts":{"type":"array","items":{"$ref":"#/components/schemas/Artifact"}},"total":{"type":"number"}},"required":["artifacts","total"]},"ArtifactLsResponse":{"type":"object","properties":{"contents":{"type":"array","items":{"$ref":"#/components/schemas/Artifact"}},"total":{"type":"number"}},"required":["contents","total"]},"ArtifactFlattenResponse":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/FlattenedArtifact"},"description":"All artifacts (files and optionally folders) with path and depth info"},"files":{"type":"array","items":{"$ref":"#/components/schemas/Artifact"},"description":"DEPRECATED: Use items instead. File artifacts only (for backwards compat)"},"total":{"type":"number","description":"Total number of items returned"},"capped":{"type":"boolean","description":"True if results were truncated due to maxItems limit"},"signedUrls":{"type":"object","additionalProperties":{"type":"string"},"description":"Map of artifact ID to signed URL (only included when includeSignedUrls=true)"},"extractedTextUrls":{"type":"object","additionalProperties":{"type":"string"},"description":"Map of artifact ID to extracted-text signed URL (only included when includeExtractedTextUrls=true)"}},"required":["items","files","total","capped"]},"Artifact":{"oneOf":[{"$ref":"#/components/schemas/FileArtifact"},{"$ref":"#/components/schemas/FolderArtifact"},{"$ref":"#/components/schemas/ReportArtifact"}],"discriminator":{"propertyName":"type","mapping":{"file":"#/components/schemas/FileArtifact","folder":"#/components/schemas/FolderArtifact","report":"#/components/schemas/ReportArtifact"}},"description":"Generic artifact representation"},"SetPublicAccessResponse":{"type":"object","properties":{"artifact":{"$ref":"#/components/schemas/Artifact"},"publicUrl":{"type":"string","description":"Public URL path for accessing the artifact (e.g. /p/{id})"}},"required":["artifact","publicUrl"]},"BookmarkedArtifactsResponse":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/Artifact"},"description":"Map of artifact ID to artifact"},"SaveToCacheRequest":{"type":"object","properties":{"fileName":{"type":"string","minLength":1,"description":"Name of the file to save"},"contentBase64":{"type":"string","description":"Base64-encoded file content"},"cacheName":{"type":"string","enum":["rate-tables"],"description":"Cache name. Currently supported: rate-tables"},"metadata":{"type":"object","properties":{"filingTrackingNumber":{"type":"string","description":"Filing tracking number"},"runId":{"type":"string","format":"uuid","description":"Unique run identifier"}},"required":["filingTrackingNumber","runId"],"description":"Cache-specific metadata"}},"required":["fileName","contentBase64","cacheName","metadata"]},"SaveToCacheResponse":{"type":"object","properties":{"success":{"type":"boolean"},"artifactId":{"type":"string"},"path":{"type":"string"},"cacheName":{"type":"string"}},"required":["success","artifactId","path","cacheName"]},"CreateReportBody":{"type":"object","properties":{"missionControlId":{"type":"string","minLength":1,"description":"Mission Control instance ID"},"name":{"type":"string","description":"Report file name (required for new reports)"},"content":{"type":"string","description":"Base64-encoded file content (required for new reports)"},"mimeType":{"type":"string","description":"MIME type of the content"},"artifactId":{"type":"string","format":"uuid","description":"Existing artifact ID to assign as report"},"category":{"type":"string","description":"Report category"},"title":{"type":"string","description":"Report title"},"description":{"type":"string","description":"Report description"}},"required":["missionControlId"]},"ReportError":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]},"ReportListResponse":{"type":"object","properties":{"reports":{"type":"array","items":{"$ref":"#/components/schemas/Artifact"}},"total":{"type":"number"}},"required":["reports","total"]},"SignedUrlResponse":{"type":"object","properties":{"signedUrl":{"type":"string","format":"uri"},"expiresIn":{"type":"number","description":"Expiration time in milliseconds"}},"required":["signedUrl","expiresIn"]},"SerffSqlQueryRequest":{"type":"object","properties":{"sql":{"type":"string","minLength":1,"description":"Read-only PostgreSQL SELECT query against tables granted to sql_query_tool"},"description":{"type":"string","minLength":1,"maxLength":500,"description":"Optional human-readable description of the query intent"}},"required":["sql"],"description":"Request to execute SERFF SQL"},"SerffSqlQueryResponse":{"type":"object","properties":{"records":{"type":"array","items":{"type":"object","additionalProperties":{"nullable":true}}},"query_runtime_ms":{"type":"number","minimum":0}},"required":["records","query_runtime_ms"],"description":"SERFF SQL query results"},"SearchResponse":{"type":"object","properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/SearchResult"}},"total":{"type":"number"},"groupedPassages":{"type":"array","items":{"type":"object","properties":{"artifactId":{"type":"string"},"artifactName":{"type":"string"},"artifactType":{"type":"string"},"hitCount":{"type":"number"},"topScore":{"type":"number"},"passages":{"type":"array","items":{"type":"object","properties":{"text":{"type":"string"},"location":{"type":"object","properties":{"page":{"type":"number"},"pageStart":{"type":"number"},"pageEnd":{"type":"number"},"charStart":{"type":"number"},"charEnd":{"type":"number"},"chunkIndex":{"type":"number"}}},"highlights":{"type":"array","items":{"type":"object","properties":{"start":{"type":"number"},"end":{"type":"number"}},"required":["start","end"]}},"score":{"type":"number"}},"required":["text","location"]}}},"required":["artifactId","hitCount","topScore","passages"]}}},"required":["results","total"]},"ContextBaseSearchRequest":{"type":"object","properties":{"missionControlId":{"type":"string","minLength":1},"contextBaseRepoId":{"type":"string","format":"uuid"},"q":{"type":"string"},"mode":{"type":"string","enum":["keyword","vector","hybrid"],"default":"keyword"},"embedding":{"type":"array","items":{"type":"number"}},"kind":{"type":"string","minLength":1},"kinds":{"type":"array","items":{"type":"string","minLength":1}},"filters":{"type":"object","additionalProperties":{"type":"array","items":{"nullable":true}},"default":{}},"limit":{"type":"integer","minimum":1,"maximum":100,"default":25},"offset":{"type":"integer","minimum":0,"default":0},"facetLimit":{"type":"integer","minimum":1,"maximum":100,"default":25}}},"ContextBaseSearchResponse":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/ContextBaseSearchResult"}},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","minimum":1},"offset":{"type":"integer","minimum":0},"query":{"type":"string","nullable":true},"filters":{"type":"object","additionalProperties":{"type":"array","items":{"nullable":true}}},"facets":{"type":"object","additionalProperties":{"type":"array","items":{"$ref":"#/components/schemas/ContextBaseSearchFacetValue"}}}},"required":["items","total","limit","offset","query","filters","facets"]},"ContextBaseSearchFacetValue":{"type":"object","properties":{"value":{"type":"string"},"count":{"type":"integer","minimum":0}},"required":["value","count"]},"ContextBaseSearchFacetSchemaResponse":{"type":"object","properties":{"fields":{"type":"array","items":{"$ref":"#/components/schemas/ContextBaseSearchFacetSchemaField"}}},"required":["fields"]},"ContextBaseSearchUpsertDocumentsRequest":{"type":"object","properties":{"contextBaseRepoId":{"type":"string","format":"uuid"},"documents":{"type":"array","items":{"$ref":"#/components/schemas/ContextBaseSearchDocumentProjection"},"minItems":1,"maxItems":500}},"required":["contextBaseRepoId","documents"]},"ContextBaseSearchUpsertDocumentsResponse":{"type":"object","properties":{"contextBaseRepoId":{"type":"string","format":"uuid"},"upserted":{"type":"integer","minimum":0}},"required":["contextBaseRepoId","upserted"]},"ContextBaseSearchReindexRequest":{"type":"object","properties":{"missionControlId":{"type":"string","minLength":1},"contextBaseRepoId":{"type":"string","format":"uuid"}}},"ContextBaseSearchReindexResponse":{"type":"object","properties":{"workflowId":{"type":"string"},"runId":{"type":"string","nullable":true},"status":{"type":"string","enum":["queued"]}},"required":["workflowId","runId","status"]},"WorkflowCatalogListResponse":{"type":"object","properties":{"workflows":{"type":"array","items":{"$ref":"#/components/schemas/WorkflowCatalogEntry"}},"errors":{"type":"number"}},"required":["workflows"]},"WorkflowCatalogDetailResponse":{"allOf":[{"$ref":"#/components/schemas/WorkflowCatalogEntry"},{"type":"object","properties":{"body":{"type":"string"}},"required":["body"]}]},"WorkflowBuildResult":{"type":"object","properties":{"success":{"type":"boolean"},"graph":{"$ref":"#/components/schemas/WorkflowGraph"},"errors":{"type":"array","items":{"type":"string"}}},"required":["success"]},"WorkflowGraphResponse":{"type":"object","properties":{"workflowId":{"type":"string"},"graph":{"$ref":"#/components/schemas/WorkflowGraph"}},"required":["workflowId","graph"]},"StartWorkflowDraftRunRequest":{"type":"object","properties":{"workflowId":{"type":"string","minLength":3,"maxLength":128,"pattern":"^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$"},"input":{"type":"object","additionalProperties":{"nullable":true},"default":{}},"metadata":{"type":"object","additionalProperties":{"nullable":true}},"missionControlId":{"type":"string"},"projectId":{"type":"string","format":"uuid"}}},"StartWorkflowDraftRunResponse":{"type":"object","properties":{"previewRunId":{"type":"string","format":"uuid"},"draftId":{"type":"string","format":"uuid"},"workflowId":{"type":"string"},"engineRunId":{"type":"string","nullable":true},"status":{"$ref":"#/components/schemas/WorkflowDraftRunStatus"},"input":{"type":"object","additionalProperties":{"nullable":true}},"metadata":{"type":"object","additionalProperties":{"nullable":true}},"returnValue":{"type":"object","nullable":true,"additionalProperties":{"nullable":true}},"error":{"type":"string","nullable":true},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["previewRunId","draftId","workflowId","engineRunId","status","input","metadata","createdAt","updatedAt"]},"WorkflowDraftRunListResponse":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/WorkflowDraftRun"}}},"required":["items"]},"WorkflowDraftRun":{"type":"object","properties":{"previewRunId":{"type":"string","format":"uuid"},"draftId":{"type":"string","format":"uuid"},"workflowId":{"type":"string"},"engineRunId":{"type":"string","nullable":true},"status":{"$ref":"#/components/schemas/WorkflowDraftRunStatus"},"input":{"type":"object","additionalProperties":{"nullable":true}},"metadata":{"type":"object","additionalProperties":{"nullable":true}},"returnValue":{"type":"object","nullable":true,"additionalProperties":{"nullable":true}},"error":{"type":"string","nullable":true},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["previewRunId","draftId","workflowId","engineRunId","status","input","metadata","createdAt","updatedAt"]},"WorkflowDraftRunStepListResponse":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/WorkflowDraftRunStep"}}},"required":["items"]},"WorkflowDraftRunEventListResponse":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/WorkflowDraftRunEvent"}},"cursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}},"required":["items"]},"WorkflowDraftRunHookListResponse":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/WorkflowDraftRunHook"}}},"required":["items"]},"ResumeWorkflowDraftRunHookRequest":{"type":"object","properties":{"payload":{"nullable":true}}},"WorkflowDraftRunActionResponse":{"type":"object","properties":{"ok":{"type":"boolean"}},"required":["ok"]},"StartSessionRequest":{"type":"object","properties":{"tags":{"type":"array","items":{"type":"string"}},"sessionType":{"type":"string","enum":["default","subagent"]},"parentSessionId":{"type":"string","description":"Parent session ID for subagent sessions - used to inherit rootSessionId"},"presetRef":{"type":"object","nullable":true,"properties":{"agentName":{"type":"string","description":"Resolve an agent preset by presetName from the sandbox agent registry"},"appId":{"type":"string","description":"Resolve an app preset by app ID from the sandbox app registry"}},"description":"Server-side preset reference — the server resolves the preset from sandbox-registry-discovered agents/apps by agent name or app ID. Alternative to sending the full systemPreset from the client."},"systemPreset":{"type":"object","properties":{"presetName":{"type":"string","description":"Unique identifier for this preset"},"operations":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["fill"]},"slot":{"type":"string"},"value":{"type":"string"}},"required":["type","slot","value"]},{"type":"object","properties":{"type":{"type":"string","enum":["include"]},"name":{"type":"string"}},"required":["type","name"]},{"type":"object","properties":{"type":{"type":"string","enum":["append"]},"value":{"type":"string"}},"required":["type","value"]},{"type":"object","properties":{"type":{"type":"string","enum":["include_vault"]},"uri":{"type":"string","description":"Vault URI (e.g. \"team://agent-context.md\", \"personal://instructions.md\")"}},"required":["type","uri"]}]},"description":"Ordered operations: fill slots, apply includes, append content"}},"required":["presetName"],"description":"System preset configuration for dynamic prompt composition. Takes precedence over presetRef."},"systemInstructions":{"type":"string","description":"DEPRECATED: Use presetConfig instead. Optional custom system instructions to override the default ones"},"agentInfo":{"type":"object","properties":{"presetName":{"type":"string","description":"Unique identifier for the agent preset"},"displayName":{"type":"string","description":"Human-readable agent name from Identity.name (e.g. \"RSL Editor\")"},"agentId":{"type":"string","description":"Agent registry ID (may differ from presetName for code:library agents)"},"source":{"type":"string","enum":["code:library","code:team"],"description":"Source identifier for the agent preset"},"filename":{"type":"string","description":"The filename of the agent preset"}},"required":["presetName","source","filename"],"description":"Info about the agent preset used to create this session (for display purposes)"},"model":{"type":"string","enum":["claude-fable-5","claude-opus-4-8","claude-opus-4-7","claude-opus-4-6","claude-sonnet-4-6","claude-sonnet-4-6-1m","claude-sonnet-4-5-20250929","claude-opus-4-5-20251101","claude-haiku-4-5-20251001","gpt-5.5","gpt-5.5-pro","gpt-5.4","gpt-5.4-mini","gpt-5.4-nano","gpt-5.4-pro","gpt-5.3-codex","gemini-3.1-pro-preview","gemini-3-flash-preview","gemini-2.5-pro","gemini-2.5-flash","gemini-2.5-flash-lite","gemini-3.1-flash-lite","gemini-flash-latest","gemini-flash-lite-latest","deepseek/deepseek-v4-pro","deepseek/deepseek-v4-flash","xai/grok-4.3","zai/glm-5.1","glm-5.2","nvidia/nemotron-3-ultra-550b-a55b","moonshotai/kimi-k2.6","moonshotai/kimi-k2.7-code","moonshotai/kimi-k2.5"],"description":"Chat model for this session"},"modelAlias":{"type":"string","enum":["opus","sonnet","gpt"],"description":"Customer-facing model alias for this session"},"modelEffort":{"type":"string","enum":["low","medium","high","xhigh","max"],"description":"Chat model effort for this session"},"inheritParentModel":{"type":"boolean","description":"When true, subagent sessions spawned from this session are forced to use this session's model."},"visibility":{"type":"string","enum":["org","restricted"],"description":"Session visibility mode: 'org' (default) for everyone, 'restricted' for specific people"},"visibleTo":{"type":"array","items":{"type":"string"},"description":"User IDs to share this session with (when visibility is \"restricted\")"},"agentEngine":{"type":"string","enum":["legacy","salad","codex"],"description":"Agent engine for this session. When omitted, the server uses the org default."},"codex":{"type":"object","properties":{"codexThreadId":{"type":"string","description":"Existing Codex thread id to resume."},"runtime":{"$ref":"#/components/schemas/CodexRuntimeRequest"},"appServerUrl":{"type":"string","description":"Codex app-server endpoint. If omitted for sandbox runtimes, server starts one."},"cwd":{"type":"string","description":"Codex working directory. Defaults to sandbox workspace."},"model":{"type":"string","description":"Codex model override."},"approvalPolicy":{"type":"string","description":"Codex approval policy. Defaults to never for hosted sessions."},"sandboxPolicy":{"nullable":true,"description":"Codex sandbox policy override."},"startAppServer":{"type":"boolean","description":"When false, bind metadata without starting a sandbox app-server."}},"description":"Initial Codex binding options. Only used when agentEngine resolves to codex."},"initCommands":{"type":"array","items":{"type":"string"},"description":"Shell commands to run before agent starts"},"initCode":{"type":"array","items":{"type":"string"},"description":"Python code snippets to execute in the kernel before agent starts"},"resources":{"type":"object","properties":{"sandbox":{"type":"object","properties":{"provider":{"type":"string","enum":["e2b","agent-sandbox"],"description":"Sandbox provider for creating a new sandbox. Agent-sandbox uses the server-owned session pod executor path."},"templateId":{"type":"string","description":"Provider-specific template reference for creating a new sandbox"},"fromSession":{"type":"string","description":"Session ID to share sandbox from. Must match parentSessionId."},"useSelfHostedE2b":{"type":"boolean","description":"When true, the session sandbox targets the self-hosted E2B instance instead of the cloud. Defaults to the global config value."}},"description":"Sandbox configuration. Omit for own sandbox with default template."},"project":{"type":"object","properties":{"name":{"type":"string","description":"Project name or ID to link this session to"}},"required":["name"],"description":"Explicit project config. Omit to inherit from parent session."}},"description":"Resource configuration. sandbox.from: session ID to share from (\"parent\" or ID). sandbox.templateId: E2B template. project: explicit config (default: inherit)."},"toolConfig":{"type":"object","properties":{"enabled":{"type":"array","items":{"type":"string"},"description":"Allowlist of tool names. When set, only tools whose declaration.name appears in this list are registered."},"disabled":{"type":"array","items":{"type":"string"},"description":"Denylist of tool names. When set, tools whose declaration.name appears in this list are excluded."}},"description":"Tool availability configuration. Use enabled (allowlist) or disabled (denylist) to control which tools are available. Mutually exclusive — cannot set both."},"pluginsConfig":{"type":"object","properties":{"systemContext":{"type":"object","properties":{"namespaces":{"type":"array","items":{"type":"string"},"description":"Retrieval index namespaces to search for context enrichment. Defaults to all enabled namespaces when omitted."}},"description":"Configuration for the system-context plugin (retrieval index enrichment)."}},"description":"Plugin configuration for this session. Controls plugin behavior such as which retrieval namespaces the system-context plugin searches."},"background":{"type":"object","properties":{"kind":{"type":"string","enum":["mission-control","product-mission-control","context-base-editor"],"description":"Machine-readable background bundle type."},"source":{"type":"string","minLength":1,"maxLength":120,"description":"Surface or integration that supplied this background."},"title":{"type":"string","minLength":1,"maxLength":200,"description":"Short title for this background bundle."},"summary":{"type":"string","minLength":1,"maxLength":4000,"description":"Freeform summary rendered before itemized background."},"items":{"type":"array","items":{"$ref":"#/components/schemas/SessionBackgroundItem"},"maxItems":50,"description":"Structured background items rendered into the session prompt."}},"description":"Additional background rendered into the session system prompt and persisted on the session."}}},"StartChatSessionResponse":{"type":"object","properties":{"sessionId":{"type":"string"}},"required":["sessionId"]},"ListSessionsResponse":{"type":"object","properties":{"sessions":{"type":"array","items":{"$ref":"#/components/schemas/ChatSessionMetadata"}},"total":{"type":"number","description":"Total number of sessions (when available)"}},"required":["sessions"]},"ImportChatThreadRequest":{"type":"object","properties":{"metadata":{"type":"object","properties":{"sessionId":{"type":"string","nullable":true,"description":"Original session ID (will be ignored)"},"createdBy":{"type":"string","nullable":true,"description":"Original creator (will be ignored)"},"orgId":{"type":"string","nullable":true,"description":"Original org ID (will be ignored)"},"state":{"type":"string","nullable":true,"description":"Session state (will be ignored)"},"createdAt":{"type":"string","nullable":true,"description":"Creation timestamp (will be ignored)"},"lastActivityAt":{"type":"string","nullable":true,"description":"Last activity timestamp (will be ignored)"},"title":{"type":"string","nullable":true,"description":"Session title"},"description":{"type":"string","nullable":true,"description":"Session description"},"tags":{"type":"array","nullable":true,"items":{"type":"string"},"description":"Session tags"}},"description":"Session metadata (optional, will use defaults from context)"},"messages":{"type":"array","items":{"$ref":"#/components/schemas/ChatMessage"},"description":"Array of chat messages to import"}},"required":["messages"]},"ImportChatThreadResponse":{"type":"object","properties":{"sessionId":{"type":"string","description":"ID of the newly created session"},"messageCount":{"type":"number","description":"Number of messages imported"}},"required":["sessionId","messageCount"]},"ListHierarchicalSessionsResponse":{"type":"object","properties":{"sessions":{"type":"array","items":{"$ref":"#/components/schemas/HierarchicalSessionItem"}}},"required":["sessions"]},"SearchSessionsResponse":{"type":"object","properties":{"sessions":{"type":"array","items":{"$ref":"#/components/schemas/ChatSessionMetadata"}},"query":{"type":"string","description":"The search query that was used"}},"required":["sessions","query"]},"ChatSendRequest":{"type":"object","properties":{"message":{"type":"object","properties":{"id":{"type":"string"},"timestamp":{"type":"string"},"role":{"type":"string","enum":["user","assistant","system"]},"parts":{"type":"array","items":{"$ref":"#/components/schemas/MessagePart"}},"loopId":{"type":"string","description":"Identifier for the processing loop this message belongs to"},"compacted":{"type":"boolean","description":"Whether the specified message was compacted out -- removed from the LLM context window"},"feedbackValue":{"type":"number","nullable":true,"description":"User feedback: 1 for thumbs up, -1 for thumbs down, null for no feedback"},"metadata":{"type":"object","properties":{"lastStreamOffset":{"type":"string","description":"Event ID offset for stream processing"},"optimistic":{"type":"boolean","description":"Whether the message is optimistic"}},"additionalProperties":{"nullable":true},"description":"Extensible metadata (lastStreamOffset, etc.)"},"sender":{"type":"string","description":"Identifier of the message sender (user ID or session ID)"},"mentionedUserIds":{"type":"array","items":{"type":"string"},"description":"User IDs explicitly @-mentioned by the sender. Server filters against session visibility before emitting notifications."}},"required":["id","timestamp","role","parts"],"description":"User message"},"systemInstructions":{"type":"string","description":"Optional custom system instructions to override the default ones"},"steer":{"type":"boolean","description":"When true, inject the message into the active agent loop at tool-result boundaries instead of starting a new turn"}},"required":["message"]},"ChatSendResponse":{"type":"object","properties":{"streamInfo":{"type":"object","properties":{"sessionId":{"type":"string"},"streamId":{"type":"string"},"finishedAt":{"type":"string","nullable":true,"format":"date-time"}},"required":["sessionId","streamId"],"description":"Stream information for subscribing to the response"}},"required":["streamInfo"]},"MessagePart":{"oneOf":[{"$ref":"#/components/schemas/TextMessagePart"},{"$ref":"#/components/schemas/ArtifactMessagePart"},{"$ref":"#/components/schemas/ThoughtMessagePart"},{"$ref":"#/components/schemas/ToolCallMessagePart"},{"$ref":"#/components/schemas/ToolResultMessagePart"},{"$ref":"#/components/schemas/ErrorMessagePart"},{"$ref":"#/components/schemas/EndOfMessageMessagePart"},{"$ref":"#/components/schemas/UsageInfoMessagePart"},{"$ref":"#/components/schemas/CheckpointMessagePart"}],"discriminator":{"propertyName":"type","mapping":{"text":"#/components/schemas/TextMessagePart","artifact":"#/components/schemas/ArtifactMessagePart","thought":"#/components/schemas/ThoughtMessagePart","tool_call":"#/components/schemas/ToolCallMessagePart","tool_result":"#/components/schemas/ToolResultMessagePart","error":"#/components/schemas/ErrorMessagePart","end_of_message":"#/components/schemas/EndOfMessageMessagePart","usage_info":"#/components/schemas/UsageInfoMessagePart","checkpoint":"#/components/schemas/CheckpointMessagePart"}},"description":"Union of all message part types"},"ChatMessageMetadata":{"type":"object","properties":{"lastStreamOffset":{"type":"string","description":"Event ID offset for stream processing"},"optimistic":{"type":"boolean","description":"Whether the message is optimistic"}},"additionalProperties":{"nullable":true},"description":"Chat message metadata"},"ChatMessage":{"type":"object","properties":{"id":{"type":"string"},"timestamp":{"type":"string"},"role":{"type":"string","enum":["user","assistant","system"]},"parts":{"type":"array","items":{"$ref":"#/components/schemas/MessagePart"}},"loopId":{"type":"string","description":"Identifier for the processing loop this message belongs to"},"compacted":{"type":"boolean","description":"Whether the specified message was compacted out -- removed from the LLM context window"},"feedbackValue":{"type":"number","nullable":true,"description":"User feedback: 1 for thumbs up, -1 for thumbs down, null for no feedback"},"metadata":{"type":"object","properties":{"lastStreamOffset":{"type":"string","description":"Event ID offset for stream processing"},"optimistic":{"type":"boolean","description":"Whether the message is optimistic"}},"additionalProperties":{"nullable":true},"description":"Extensible metadata (lastStreamOffset, etc.)"},"sender":{"type":"string","description":"Identifier of the message sender (user ID or session ID)"},"mentionedUserIds":{"type":"array","items":{"type":"string"},"description":"User IDs explicitly @-mentioned by the sender. Server filters against session visibility before emitting notifications."}},"required":["id","timestamp","role","parts"],"description":"Chat message with parts"},"ChatSessionMetadata":{"type":"object","properties":{"sessionId":{"$ref":"#/components/schemas/SessionId"},"createdBy":{"type":"string"},"orgId":{"type":"string"},"state":{"$ref":"#/components/schemas/ChatSessionState"},"createdAt":{"type":"string"},"lastActivityAt":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"pinned":{"type":"boolean","default":false},"sessionType":{"type":"string","enum":["default","subagent"],"default":"default","description":"Session type: default for customer-visible sessions, subagent for internal sessions"},"visibility":{"type":"string","enum":["org","restricted"],"default":"org","description":"Session visibility mode: 'org' for shared with team (everyone), 'restricted' for private (specific people)"},"visibleTo":{"type":"array","items":{"type":"string"},"default":[]},"participants":{"type":"array","items":{"type":"string"},"default":[]},"participantPreviews":{"type":"array","items":{"$ref":"#/components/schemas/ParticipantPreview"}},"context":{"type":"object","properties":{"todos":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1},"content":{"type":"string"},"status":{"type":"string","enum":["pending","in_progress","completed","cancelled"]}},"required":["id","content","status"]}},"sandboxes":{"type":"array","items":{"type":"object","properties":{"sandboxId":{"type":"string","description":"The E2B sandbox ID"},"createdAt":{"type":"string","description":"ISO timestamp when the sandbox was created"},"templateAlias":{"type":"string","description":"The template alias used to create the sandbox (e.g., effectiveai-sandbox-3-dev)"}},"required":["sandboxId","createdAt"]}},"codeContexts":{"type":"object","additionalProperties":{"type":"object","properties":{"python":{"type":"object","properties":{"contextId":{"type":"string","description":"The E2B code context ID"},"cwd":{"type":"string","description":"Working directory for the context"},"createdAt":{"type":"string","description":"ISO timestamp when the context was created"}},"required":["contextId","createdAt"]},"r":{"type":"object","properties":{"contextId":{"type":"string","description":"The E2B code context ID"},"cwd":{"type":"string","description":"Working directory for the context"},"createdAt":{"type":"string","description":"ISO timestamp when the context was created"}},"required":["contextId","createdAt"]}}},"description":"E2B code contexts map: sandboxId -> language -> context. Each context maintains execution state across runCode() calls."},"templateAlias":{"type":"string","description":"The template alias used to create the sandbox (e.g., effectiveai-sandbox-3-dev)"},"systemPresetName":{"type":"string","description":"The system preset name used for this session"},"agentInfo":{"type":"object","nullable":true,"properties":{"presetName":{"type":"string","description":"Unique identifier for the agent preset"},"displayName":{"type":"string","description":"Human-readable agent name from Identity.name (e.g. \"RSL Editor\")"},"agentId":{"type":"string","description":"Agent registry ID (may differ from presetName for code:library agents)"},"source":{"type":"string","enum":["code:library","code:team"],"description":"Source identifier for the agent preset"},"filename":{"type":"string","description":"The filename of the agent preset"}},"required":["presetName","source","filename"],"description":"Agent info for display in session UI"},"model":{"type":"string","enum":["claude-fable-5","claude-opus-4-8","claude-opus-4-7","claude-opus-4-6","claude-sonnet-4-6","claude-sonnet-4-6-1m","claude-sonnet-4-5-20250929","claude-opus-4-5-20251101","claude-haiku-4-5-20251001","gpt-5.5","gpt-5.5-pro","gpt-5.4","gpt-5.4-mini","gpt-5.4-nano","gpt-5.4-pro","gpt-5.3-codex","gemini-3.1-pro-preview","gemini-3-flash-preview","gemini-2.5-pro","gemini-2.5-flash","gemini-2.5-flash-lite","gemini-3.1-flash-lite","gemini-flash-latest","gemini-flash-lite-latest","deepseek/deepseek-v4-pro","deepseek/deepseek-v4-flash","xai/grok-4.3","zai/glm-5.1","glm-5.2","nvidia/nemotron-3-ultra-550b-a55b","moonshotai/kimi-k2.6","moonshotai/kimi-k2.7-code","moonshotai/kimi-k2.5"],"description":"Chat model for this session"},"modelAlias":{"type":"string","enum":["opus","sonnet","gpt"],"description":"Customer-facing chat model alias for this session"},"modelEffort":{"type":"string","enum":["low","medium","high","xhigh","max"],"description":"Chat model effort override for this session"},"inheritParentModel":{"type":"boolean","description":"When true, subagent sessions spawned from this session are forced to use this session's model instead of their configured/default model. Propagates down the subagent tree."},"agentEngine":{"type":"string","enum":["salad","codex","acp"],"description":"Agent engine for this session. Defaults to org config when omitted."},"resources":{"type":"object","properties":{"sandbox":{"type":"object","properties":{"provider":{"type":"string","enum":["e2b","agent-sandbox"],"description":"Sandbox provider for creating a new sandbox. Agent-sandbox uses the server-owned session pod executor path."},"templateId":{"type":"string","description":"Provider-specific template reference for creating a new sandbox"},"fromSession":{"type":"string","description":"Session ID to share sandbox from. Must match parentSessionId."},"useSelfHostedE2b":{"type":"boolean","description":"When true, the session sandbox targets the self-hosted E2B instance instead of the cloud. Defaults to the global config value."}},"description":"Sandbox configuration. Omit for own sandbox with default template."},"project":{"type":"object","properties":{"name":{"type":"string","description":"Project name or ID to link this session to"}},"required":["name"],"description":"Explicit project config. Omit to inherit from parent session."}},"description":"Resource configuration for this session. Controls sandbox sharing and project settings."},"runtimeUpgrade":{"type":"object","properties":{"status":{"$ref":"#/components/schemas/RuntimeUpgradeStatus"},"action":{"type":"string","enum":["in_place","recycle"]},"fromVersion":{"type":"string","nullable":true},"toVersion":{"type":"string"},"releaseId":{"type":"string"},"message":{"type":"string"},"startedAt":{"type":"string"},"updatedAt":{"type":"string"},"completedAt":{"type":"string"}},"required":["status","action","fromVersion","toVersion","updatedAt"],"description":"Current or most recent runtime upgrade state for the session sandbox."},"runtimeDiagnostics":{"type":"object","properties":{"checkedAt":{"type":"string"},"isStale":{"type":"boolean"},"reason":{"type":"string"},"currentRuntime":{"type":"object","nullable":true,"properties":{"sandboxId":{"type":"string","nullable":true},"version":{"type":"string","nullable":true},"effectiveToolsCommitSha":{"type":"string","nullable":true},"templateRef":{"type":"string","nullable":true},"templateBuildId":{"type":"string","nullable":true}},"required":["sandboxId","version","effectiveToolsCommitSha","templateRef","templateBuildId"]},"requiredRuntime":{"type":"object","properties":{"mode":{"type":"string","enum":["latest","pinned","unresolved"]},"source":{"type":"string"},"channel":{"type":"string","enum":["latest","stable"]},"releaseId":{"type":"string"},"version":{"type":"string","nullable":true},"effectiveToolsCommitSha":{"type":"string","nullable":true},"templateRef":{"type":"string","nullable":true},"templateBuildId":{"type":"string","nullable":true},"templateId":{"type":"string","nullable":true},"upgradeStrategy":{"type":"string","nullable":true},"reason":{"type":"string"}},"required":["mode","source","version","effectiveToolsCommitSha","templateRef","templateBuildId","templateId","upgradeStrategy"]}},"required":["checkedAt","isStale","currentRuntime","requiredRuntime"],"description":"Derived runtime staleness diagnostics for the session sandbox."},"toolConfig":{"type":"object","properties":{"enabled":{"type":"array","items":{"type":"string"},"description":"Allowlist of tool names. When set, only tools whose declaration.name appears in this list are registered."},"disabled":{"type":"array","items":{"type":"string"},"description":"Denylist of tool names. When set, tools whose declaration.name appears in this list are excluded."}},"description":"Tool availability configuration for this session."},"pluginsConfig":{"type":"object","properties":{"systemContext":{"type":"object","properties":{"namespaces":{"type":"array","items":{"type":"string"},"description":"Retrieval index namespaces to search for context enrichment. Defaults to all enabled namespaces when omitted."}},"description":"Configuration for the system-context plugin (retrieval index enrichment)."}},"description":"Plugin configuration for this session (e.g. system-context namespaces)."},"background":{"type":"object","properties":{"kind":{"type":"string","enum":["mission-control","product-mission-control","context-base-editor"],"description":"Machine-readable background bundle type."},"source":{"type":"string","minLength":1,"maxLength":120,"description":"Surface or integration that supplied this background."},"title":{"type":"string","minLength":1,"maxLength":200,"description":"Short title for this background bundle."},"summary":{"type":"string","minLength":1,"maxLength":4000,"description":"Freeform summary rendered before itemized background."},"items":{"type":"array","items":{"$ref":"#/components/schemas/SessionBackgroundItem"},"maxItems":50,"description":"Structured background items rendered into the session prompt."}},"description":"Additional background supplied when this session was created."},"codex":{"type":"object","properties":{"threadId":{"type":"string"},"activeTurnId":{"type":"string"},"runtime":{"$ref":"#/components/schemas/CodexRuntimeContext"},"cwd":{"type":"string"},"model":{"type":"string"},"approvalPolicy":{"type":"string","default":"never","description":"Codex app-server approval policy. Hosted sessions default to no prompts."},"sandboxPolicy":{"nullable":true},"status":{"type":"string","enum":["binding","ready","running","waiting_on_approval","error","closed"]},"lastError":{"type":"string"},"lastSeenAt":{"type":"string"},"boundAt":{"type":"string"},"lastResumedAt":{"type":"string"},"importedFromThreadId":{"type":"string"},"importStatus":{"type":"string","enum":["native","rehydrated","partial"]}},"description":"Codex app-server binding metadata."},"titleSetByUser":{"type":"boolean","description":"When true, the title was manually set by the user and should not be overwritten by auto-generation."}}},"latestLoopId":{"type":"string","nullable":true,"description":"The ID of the current turn loop for this session"},"rootSessionId":{"type":"string","description":"The root session ID for subagent hierarchies. For root sessions, equals sessionId. For subagents, equals the top-level parent session ID."},"parentSessionId":{"type":"string","description":"The immediate parent session ID for subagent hierarchies. Root sessions use their own session ID."},"depth":{"type":"number","description":"Nesting depth for subagent hierarchies. Root sessions have depth=0, subagents have depth=parent.depth+1."},"setupStatus":{"type":"string","nullable":true,"enum":["pending","running","completed","failed",null],"description":"Setup status for init_commands execution"}},"required":["sessionId","orgId","createdAt","rootSessionId","parentSessionId","depth"],"description":"Chat session metadata"},"StopStreamResponse":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the stream was successfully stopped"}},"required":["success"]},"LoadSessionResponse":{"type":"object","properties":{"metadata":{"$ref":"#/components/schemas/ChatSessionMetadata"},"messages":{"type":"array","items":{"$ref":"#/components/schemas/ChatMessage"}},"streamInfo":{"type":"object","properties":{"sessionId":{"type":"string"},"streamId":{"type":"string"},"finishedAt":{"type":"string","nullable":true,"format":"date-time"}},"required":["sessionId","streamId"]}},"required":["metadata","messages"]},"UpdateSessionRequest":{"type":"object","properties":{"title":{"type":"string","description":"New title for the session"},"description":{"type":"string","description":"New description for the session"},"pinned":{"type":"boolean","description":"Whether the session should be pinned"},"tags":{"type":"array","items":{"type":"string"},"description":"Session tags"},"context":{"type":"object","properties":{"todos":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1},"content":{"type":"string"},"status":{"type":"string","enum":["pending","in_progress","completed","cancelled"]}},"required":["id","content","status"]}},"sandboxes":{"type":"array","items":{"type":"object","properties":{"sandboxId":{"type":"string","description":"The E2B sandbox ID"},"createdAt":{"type":"string","description":"ISO timestamp when the sandbox was created"},"templateAlias":{"type":"string","description":"The template alias used to create the sandbox (e.g., effectiveai-sandbox-3-dev)"}},"required":["sandboxId","createdAt"]}},"codeContexts":{"type":"object","additionalProperties":{"type":"object","properties":{"python":{"type":"object","properties":{"contextId":{"type":"string","description":"The E2B code context ID"},"cwd":{"type":"string","description":"Working directory for the context"},"createdAt":{"type":"string","description":"ISO timestamp when the context was created"}},"required":["contextId","createdAt"]},"r":{"type":"object","properties":{"contextId":{"type":"string","description":"The E2B code context ID"},"cwd":{"type":"string","description":"Working directory for the context"},"createdAt":{"type":"string","description":"ISO timestamp when the context was created"}},"required":["contextId","createdAt"]}}},"description":"E2B code contexts map: sandboxId -> language -> context. Each context maintains execution state across runCode() calls."},"templateAlias":{"type":"string","description":"The template alias used to create the sandbox (e.g., effectiveai-sandbox-3-dev)"},"systemPresetName":{"type":"string","description":"The system preset name used for this session"},"agentInfo":{"type":"object","nullable":true,"properties":{"presetName":{"type":"string","description":"Unique identifier for the agent preset"},"displayName":{"type":"string","description":"Human-readable agent name from Identity.name (e.g. \"RSL Editor\")"},"agentId":{"type":"string","description":"Agent registry ID (may differ from presetName for code:library agents)"},"source":{"type":"string","enum":["code:library","code:team"],"description":"Source identifier for the agent preset"},"filename":{"type":"string","description":"The filename of the agent preset"}},"required":["presetName","source","filename"],"description":"Agent info for display in session UI"},"model":{"type":"string","enum":["claude-fable-5","claude-opus-4-8","claude-opus-4-7","claude-opus-4-6","claude-sonnet-4-6","claude-sonnet-4-6-1m","claude-sonnet-4-5-20250929","claude-opus-4-5-20251101","claude-haiku-4-5-20251001","gpt-5.5","gpt-5.5-pro","gpt-5.4","gpt-5.4-mini","gpt-5.4-nano","gpt-5.4-pro","gpt-5.3-codex","gemini-3.1-pro-preview","gemini-3-flash-preview","gemini-2.5-pro","gemini-2.5-flash","gemini-2.5-flash-lite","gemini-3.1-flash-lite","gemini-flash-latest","gemini-flash-lite-latest","deepseek/deepseek-v4-pro","deepseek/deepseek-v4-flash","xai/grok-4.3","zai/glm-5.1","glm-5.2","nvidia/nemotron-3-ultra-550b-a55b","moonshotai/kimi-k2.6","moonshotai/kimi-k2.7-code","moonshotai/kimi-k2.5"],"description":"Chat model for this session"},"modelAlias":{"type":"string","enum":["opus","sonnet","gpt"],"description":"Customer-facing chat model alias for this session"},"modelEffort":{"type":"string","enum":["low","medium","high","xhigh","max"],"description":"Chat model effort override for this session"},"inheritParentModel":{"type":"boolean","description":"When true, subagent sessions spawned from this session are forced to use this session's model instead of their configured/default model. Propagates down the subagent tree."},"agentEngine":{"type":"string","enum":["legacy","salad"],"description":"Mutable agent engine for this session. `legacy` is accepted for backwards compatibility and normalized to `salad`."},"resources":{"type":"object","properties":{"sandbox":{"type":"object","properties":{"provider":{"type":"string","enum":["e2b","agent-sandbox"],"description":"Sandbox provider for creating a new sandbox. Agent-sandbox uses the server-owned session pod executor path."},"templateId":{"type":"string","description":"Provider-specific template reference for creating a new sandbox"},"fromSession":{"type":"string","description":"Session ID to share sandbox from. Must match parentSessionId."},"useSelfHostedE2b":{"type":"boolean","description":"When true, the session sandbox targets the self-hosted E2B instance instead of the cloud. Defaults to the global config value."}},"description":"Sandbox configuration. Omit for own sandbox with default template."},"project":{"type":"object","properties":{"name":{"type":"string","description":"Project name or ID to link this session to"}},"required":["name"],"description":"Explicit project config. Omit to inherit from parent session."}},"description":"Resource configuration for this session. Controls sandbox sharing and project settings."},"runtimeUpgrade":{"type":"object","properties":{"status":{"$ref":"#/components/schemas/RuntimeUpgradeStatus"},"action":{"type":"string","enum":["in_place","recycle"]},"fromVersion":{"type":"string","nullable":true},"toVersion":{"type":"string"},"releaseId":{"type":"string"},"message":{"type":"string"},"startedAt":{"type":"string"},"updatedAt":{"type":"string"},"completedAt":{"type":"string"}},"required":["status","action","fromVersion","toVersion","updatedAt"],"description":"Current or most recent runtime upgrade state for the session sandbox."},"runtimeDiagnostics":{"type":"object","properties":{"checkedAt":{"type":"string"},"isStale":{"type":"boolean"},"reason":{"type":"string"},"currentRuntime":{"type":"object","nullable":true,"properties":{"sandboxId":{"type":"string","nullable":true},"version":{"type":"string","nullable":true},"effectiveToolsCommitSha":{"type":"string","nullable":true},"templateRef":{"type":"string","nullable":true},"templateBuildId":{"type":"string","nullable":true}},"required":["sandboxId","version","effectiveToolsCommitSha","templateRef","templateBuildId"]},"requiredRuntime":{"type":"object","properties":{"mode":{"type":"string","enum":["latest","pinned","unresolved"]},"source":{"type":"string"},"channel":{"type":"string","enum":["latest","stable"]},"releaseId":{"type":"string"},"version":{"type":"string","nullable":true},"effectiveToolsCommitSha":{"type":"string","nullable":true},"templateRef":{"type":"string","nullable":true},"templateBuildId":{"type":"string","nullable":true},"templateId":{"type":"string","nullable":true},"upgradeStrategy":{"type":"string","nullable":true},"reason":{"type":"string"}},"required":["mode","source","version","effectiveToolsCommitSha","templateRef","templateBuildId","templateId","upgradeStrategy"]}},"required":["checkedAt","isStale","currentRuntime","requiredRuntime"],"description":"Derived runtime staleness diagnostics for the session sandbox."},"toolConfig":{"type":"object","properties":{"enabled":{"type":"array","items":{"type":"string"},"description":"Allowlist of tool names. When set, only tools whose declaration.name appears in this list are registered."},"disabled":{"type":"array","items":{"type":"string"},"description":"Denylist of tool names. When set, tools whose declaration.name appears in this list are excluded."}},"description":"Tool availability configuration for this session."},"pluginsConfig":{"type":"object","properties":{"systemContext":{"type":"object","properties":{"namespaces":{"type":"array","items":{"type":"string"},"description":"Retrieval index namespaces to search for context enrichment. Defaults to all enabled namespaces when omitted."}},"description":"Configuration for the system-context plugin (retrieval index enrichment)."}},"description":"Plugin configuration for this session (e.g. system-context namespaces)."},"background":{"type":"object","properties":{"kind":{"type":"string","enum":["mission-control","product-mission-control","context-base-editor"],"description":"Machine-readable background bundle type."},"source":{"type":"string","minLength":1,"maxLength":120,"description":"Surface or integration that supplied this background."},"title":{"type":"string","minLength":1,"maxLength":200,"description":"Short title for this background bundle."},"summary":{"type":"string","minLength":1,"maxLength":4000,"description":"Freeform summary rendered before itemized background."},"items":{"type":"array","items":{"$ref":"#/components/schemas/SessionBackgroundItem"},"maxItems":50,"description":"Structured background items rendered into the session prompt."}},"description":"Additional background supplied when this session was created."},"titleSetByUser":{"type":"boolean","description":"When true, the title was manually set by the user and should not be overwritten by auto-generation."}},"description":"Session context data"},"model":{"type":"string","nullable":true,"enum":["claude-fable-5","claude-opus-4-8","claude-opus-4-7","claude-opus-4-6","claude-sonnet-4-6","claude-sonnet-4-6-1m","claude-sonnet-4-5-20250929","claude-opus-4-5-20251101","claude-haiku-4-5-20251001","gpt-5.5","gpt-5.5-pro","gpt-5.4","gpt-5.4-mini","gpt-5.4-nano","gpt-5.4-pro","gpt-5.3-codex","gemini-3.1-pro-preview","gemini-3-flash-preview","gemini-2.5-pro","gemini-2.5-flash","gemini-2.5-flash-lite","gemini-3.1-flash-lite","gemini-flash-latest","gemini-flash-lite-latest","deepseek/deepseek-v4-pro","deepseek/deepseek-v4-flash","xai/grok-4.3","zai/glm-5.1","glm-5.2","nvidia/nemotron-3-ultra-550b-a55b","moonshotai/kimi-k2.6","moonshotai/kimi-k2.7-code","moonshotai/kimi-k2.5",null],"description":"Chat model for this session. Send null to clear and revert to org default."},"modelAlias":{"type":"string","nullable":true,"enum":["opus","sonnet","gpt",null],"description":"Customer-facing model alias. Send null to clear and revert to org default."},"modelEffort":{"type":"string","nullable":true,"enum":["low","medium","high","xhigh","max",null],"description":"Chat model effort. Send null to clear and revert to model default."},"sessionType":{"type":"string","enum":["default","subagent"],"description":"Session type (default or subagent)"},"visibility":{"type":"string","enum":["org","restricted"],"description":"Session visibility mode: 'org' for everyone, 'restricted' for specific people"},"visibleTo":{"type":"array","items":{"type":"string"},"description":"User IDs to share this session with"}}},"DeleteChatSessionResponse":{"type":"object","properties":{"success":{"type":"boolean"},"deletedSubscriptionCount":{"type":"integer"},"deletedActiveSubscriptionCount":{"type":"integer"}},"required":["success","deletedSubscriptionCount","deletedActiveSubscriptionCount"]},"AvailableSkillSlashCommandsResponse":{"type":"object","properties":{"skills":{"type":"array","items":{"$ref":"#/components/schemas/AvailableSkillSlashCommand"}}},"required":["skills"]},"ListAgentSpawnEventsResponse":{"type":"object","properties":{"events":{"type":"array","items":{"$ref":"#/components/schemas/AgentSpawnEvent"}}},"required":["events"]},"CreateAgentSpawnEventRequest":{"type":"object","properties":{"parentToolCallId":{"type":"string","minLength":1},"childSessionId":{"type":"string","minLength":1},"agentInfo":{"type":"object","nullable":true,"additionalProperties":{"nullable":true}},"inputPreview":{"type":"string","nullable":true}},"required":["parentToolCallId","childSessionId"]},"AgentSpawnEvent":{"type":"object","properties":{"id":{"type":"string"},"parentSessionId":{"type":"string"},"parentToolCallId":{"type":"string"},"childSessionId":{"type":"string"},"agentInfo":{"type":"object","nullable":true,"additionalProperties":{"nullable":true}},"inputPreview":{"type":"string","nullable":true},"spawnedAt":{"type":"string"},"createdAt":{"type":"string"}},"required":["id","parentSessionId","parentToolCallId","childSessionId","agentInfo","inputPreview","spawnedAt","createdAt"]},"SessionSandboxesResponse":{"type":"object","properties":{"sessionId":{"type":"string","description":"Session ID"},"sessionMetadata":{"type":"object","properties":{"sessionId":{"$ref":"#/components/schemas/SessionId"},"createdBy":{"type":"string"},"orgId":{"type":"string"},"state":{"$ref":"#/components/schemas/ChatSessionState"},"createdAt":{"type":"string"},"lastActivityAt":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"pinned":{"type":"boolean","default":false},"sessionType":{"type":"string","enum":["default","subagent"],"default":"default","description":"Session type: default for customer-visible sessions, subagent for internal sessions"},"visibility":{"type":"string","enum":["org","restricted"],"default":"org","description":"Session visibility mode: 'org' for shared with team (everyone), 'restricted' for private (specific people)"},"visibleTo":{"type":"array","items":{"type":"string"},"default":[]},"participants":{"type":"array","items":{"type":"string"},"default":[]},"participantPreviews":{"type":"array","items":{"$ref":"#/components/schemas/ParticipantPreview"}},"context":{"type":"object","properties":{"todos":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1},"content":{"type":"string"},"status":{"type":"string","enum":["pending","in_progress","completed","cancelled"]}},"required":["id","content","status"]}},"sandboxes":{"type":"array","items":{"type":"object","properties":{"sandboxId":{"type":"string","description":"The E2B sandbox ID"},"createdAt":{"type":"string","description":"ISO timestamp when the sandbox was created"},"templateAlias":{"type":"string","description":"The template alias used to create the sandbox (e.g., effectiveai-sandbox-3-dev)"}},"required":["sandboxId","createdAt"]}},"codeContexts":{"type":"object","additionalProperties":{"type":"object","properties":{"python":{"type":"object","properties":{"contextId":{"type":"string","description":"The E2B code context ID"},"cwd":{"type":"string","description":"Working directory for the context"},"createdAt":{"type":"string","description":"ISO timestamp when the context was created"}},"required":["contextId","createdAt"]},"r":{"type":"object","properties":{"contextId":{"type":"string","description":"The E2B code context ID"},"cwd":{"type":"string","description":"Working directory for the context"},"createdAt":{"type":"string","description":"ISO timestamp when the context was created"}},"required":["contextId","createdAt"]}}},"description":"E2B code contexts map: sandboxId -> language -> context. Each context maintains execution state across runCode() calls."},"templateAlias":{"type":"string","description":"The template alias used to create the sandbox (e.g., effectiveai-sandbox-3-dev)"},"systemPresetName":{"type":"string","description":"The system preset name used for this session"},"agentInfo":{"type":"object","nullable":true,"properties":{"presetName":{"type":"string","description":"Unique identifier for the agent preset"},"displayName":{"type":"string","description":"Human-readable agent name from Identity.name (e.g. \"RSL Editor\")"},"agentId":{"type":"string","description":"Agent registry ID (may differ from presetName for code:library agents)"},"source":{"type":"string","enum":["code:library","code:team"],"description":"Source identifier for the agent preset"},"filename":{"type":"string","description":"The filename of the agent preset"}},"required":["presetName","source","filename"],"description":"Agent info for display in session UI"},"model":{"type":"string","enum":["claude-fable-5","claude-opus-4-8","claude-opus-4-7","claude-opus-4-6","claude-sonnet-4-6","claude-sonnet-4-6-1m","claude-sonnet-4-5-20250929","claude-opus-4-5-20251101","claude-haiku-4-5-20251001","gpt-5.5","gpt-5.5-pro","gpt-5.4","gpt-5.4-mini","gpt-5.4-nano","gpt-5.4-pro","gpt-5.3-codex","gemini-3.1-pro-preview","gemini-3-flash-preview","gemini-2.5-pro","gemini-2.5-flash","gemini-2.5-flash-lite","gemini-3.1-flash-lite","gemini-flash-latest","gemini-flash-lite-latest","deepseek/deepseek-v4-pro","deepseek/deepseek-v4-flash","xai/grok-4.3","zai/glm-5.1","glm-5.2","nvidia/nemotron-3-ultra-550b-a55b","moonshotai/kimi-k2.6","moonshotai/kimi-k2.7-code","moonshotai/kimi-k2.5"],"description":"Chat model for this session"},"modelAlias":{"type":"string","enum":["opus","sonnet","gpt"],"description":"Customer-facing chat model alias for this session"},"modelEffort":{"type":"string","enum":["low","medium","high","xhigh","max"],"description":"Chat model effort override for this session"},"inheritParentModel":{"type":"boolean","description":"When true, subagent sessions spawned from this session are forced to use this session's model instead of their configured/default model. Propagates down the subagent tree."},"agentEngine":{"type":"string","enum":["salad","codex","acp"],"description":"Agent engine for this session. Defaults to org config when omitted."},"resources":{"type":"object","properties":{"sandbox":{"type":"object","properties":{"provider":{"type":"string","enum":["e2b","agent-sandbox"],"description":"Sandbox provider for creating a new sandbox. Agent-sandbox uses the server-owned session pod executor path."},"templateId":{"type":"string","description":"Provider-specific template reference for creating a new sandbox"},"fromSession":{"type":"string","description":"Session ID to share sandbox from. Must match parentSessionId."},"useSelfHostedE2b":{"type":"boolean","description":"When true, the session sandbox targets the self-hosted E2B instance instead of the cloud. Defaults to the global config value."}},"description":"Sandbox configuration. Omit for own sandbox with default template."},"project":{"type":"object","properties":{"name":{"type":"string","description":"Project name or ID to link this session to"}},"required":["name"],"description":"Explicit project config. Omit to inherit from parent session."}},"description":"Resource configuration for this session. Controls sandbox sharing and project settings."},"runtimeUpgrade":{"type":"object","properties":{"status":{"$ref":"#/components/schemas/RuntimeUpgradeStatus"},"action":{"type":"string","enum":["in_place","recycle"]},"fromVersion":{"type":"string","nullable":true},"toVersion":{"type":"string"},"releaseId":{"type":"string"},"message":{"type":"string"},"startedAt":{"type":"string"},"updatedAt":{"type":"string"},"completedAt":{"type":"string"}},"required":["status","action","fromVersion","toVersion","updatedAt"],"description":"Current or most recent runtime upgrade state for the session sandbox."},"runtimeDiagnostics":{"type":"object","properties":{"checkedAt":{"type":"string"},"isStale":{"type":"boolean"},"reason":{"type":"string"},"currentRuntime":{"type":"object","nullable":true,"properties":{"sandboxId":{"type":"string","nullable":true},"version":{"type":"string","nullable":true},"effectiveToolsCommitSha":{"type":"string","nullable":true},"templateRef":{"type":"string","nullable":true},"templateBuildId":{"type":"string","nullable":true}},"required":["sandboxId","version","effectiveToolsCommitSha","templateRef","templateBuildId"]},"requiredRuntime":{"type":"object","properties":{"mode":{"type":"string","enum":["latest","pinned","unresolved"]},"source":{"type":"string"},"channel":{"type":"string","enum":["latest","stable"]},"releaseId":{"type":"string"},"version":{"type":"string","nullable":true},"effectiveToolsCommitSha":{"type":"string","nullable":true},"templateRef":{"type":"string","nullable":true},"templateBuildId":{"type":"string","nullable":true},"templateId":{"type":"string","nullable":true},"upgradeStrategy":{"type":"string","nullable":true},"reason":{"type":"string"}},"required":["mode","source","version","effectiveToolsCommitSha","templateRef","templateBuildId","templateId","upgradeStrategy"]}},"required":["checkedAt","isStale","currentRuntime","requiredRuntime"],"description":"Derived runtime staleness diagnostics for the session sandbox."},"toolConfig":{"type":"object","properties":{"enabled":{"type":"array","items":{"type":"string"},"description":"Allowlist of tool names. When set, only tools whose declaration.name appears in this list are registered."},"disabled":{"type":"array","items":{"type":"string"},"description":"Denylist of tool names. When set, tools whose declaration.name appears in this list are excluded."}},"description":"Tool availability configuration for this session."},"pluginsConfig":{"type":"object","properties":{"systemContext":{"type":"object","properties":{"namespaces":{"type":"array","items":{"type":"string"},"description":"Retrieval index namespaces to search for context enrichment. Defaults to all enabled namespaces when omitted."}},"description":"Configuration for the system-context plugin (retrieval index enrichment)."}},"description":"Plugin configuration for this session (e.g. system-context namespaces)."},"background":{"type":"object","properties":{"kind":{"type":"string","enum":["mission-control","product-mission-control","context-base-editor"],"description":"Machine-readable background bundle type."},"source":{"type":"string","minLength":1,"maxLength":120,"description":"Surface or integration that supplied this background."},"title":{"type":"string","minLength":1,"maxLength":200,"description":"Short title for this background bundle."},"summary":{"type":"string","minLength":1,"maxLength":4000,"description":"Freeform summary rendered before itemized background."},"items":{"type":"array","items":{"$ref":"#/components/schemas/SessionBackgroundItem"},"maxItems":50,"description":"Structured background items rendered into the session prompt."}},"description":"Additional background supplied when this session was created."},"codex":{"type":"object","properties":{"threadId":{"type":"string"},"activeTurnId":{"type":"string"},"runtime":{"$ref":"#/components/schemas/CodexRuntimeContext"},"cwd":{"type":"string"},"model":{"type":"string"},"approvalPolicy":{"type":"string","default":"never","description":"Codex app-server approval policy. Hosted sessions default to no prompts."},"sandboxPolicy":{"nullable":true},"status":{"type":"string","enum":["binding","ready","running","waiting_on_approval","error","closed"]},"lastError":{"type":"string"},"lastSeenAt":{"type":"string"},"boundAt":{"type":"string"},"lastResumedAt":{"type":"string"},"importedFromThreadId":{"type":"string"},"importStatus":{"type":"string","enum":["native","rehydrated","partial"]}},"description":"Codex app-server binding metadata."},"titleSetByUser":{"type":"boolean","description":"When true, the title was manually set by the user and should not be overwritten by auto-generation."}}},"latestLoopId":{"type":"string","nullable":true,"description":"The ID of the current turn loop for this session"},"rootSessionId":{"type":"string","description":"The root session ID for subagent hierarchies. For root sessions, equals sessionId. For subagents, equals the top-level parent session ID."},"parentSessionId":{"type":"string","description":"The immediate parent session ID for subagent hierarchies. Root sessions use their own session ID."},"depth":{"type":"number","description":"Nesting depth for subagent hierarchies. Root sessions have depth=0, subagents have depth=parent.depth+1."},"setupStatus":{"type":"string","nullable":true,"enum":["pending","running","completed","failed",null],"description":"Setup status for init_commands execution"}},"required":["sessionId","orgId","createdAt","rootSessionId","parentSessionId","depth"],"description":"Session metadata from database"},"sandboxes":{"type":"array","items":{"$ref":"#/components/schemas/SandboxInfo"},"description":"Array of sandboxes associated with the session"},"total":{"type":"number","description":"Total number of sandboxes found"}},"required":["sessionId","sandboxes","total"]},"SessionLogsResponse":{"type":"object","properties":{"logs":{"type":"array","items":{"type":"object","additionalProperties":{"nullable":true},"description":"Raw log entry from Oodle"},"description":"Log entries"},"total":{"type":"number","description":"Total matching logs"},"tookMs":{"type":"number","description":"Query execution time in ms"},"success":{"type":"boolean","description":"Whether the query succeeded"},"error":{"type":"string","nullable":true,"description":"Error message if query failed"},"sessionCreatedAt":{"type":"string","description":"Session creation timestamp (ISO 8601)"}},"required":["logs","total","tookMs","success","error"]},"SessionSandboxUrlResponse":{"type":"object","properties":{"sessionId":{"type":"string","description":"Session ID"},"sandboxId":{"type":"string","description":"Sandbox ID"},"port":{"type":"integer","description":"Sandbox port number"},"host":{"type":"string","description":"Public host for the sandbox port"},"publicUrl":{"type":"string","format":"uri","description":"Public URL for the sandbox port"},"authToken":{"type":"string","description":"Auth token for sandbox access (include as _auth_token query param)"}},"required":["sessionId","sandboxId","port","host","publicUrl"]},"KeepSandboxAliveResponse":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the sandbox timeout was extended"},"message":{"type":"string","description":"Status message"}},"required":["success","message"]},"UpdateSandboxRequest":{"type":"object","properties":{"expectedSourceSandboxId":{"type":"string","nullable":true,"description":"Optional source-sandbox precondition. When provided, the rotate request only succeeds if that sandbox ID is still active. Use null when the caller expects no active sandbox yet."},"additionalFilesToCopy":{"type":"array","items":{"type":"string"},"description":"Additional sandbox paths to copy from the current active sandbox into the new sandbox. Relative paths are resolved under /home/user/workspace."}}},"UpdateSandboxResponse":{"type":"object","properties":{"success":{"type":"boolean"},"sandboxId":{"type":"string","description":"The newly provisioned active sandbox ID"},"sourceSandboxId":{"type":"string","nullable":true,"description":"The previously active sandbox ID, if one existed"},"templateId":{"type":"string","description":"The template used to create the new sandbox"},"copiedPaths":{"type":"array","items":{"type":"string"},"description":"Sandbox paths copied from the previous sandbox into the new one"}},"required":["success","sandboxId","sourceSandboxId","templateId","copiedPaths"]},"SandboxFileUrlResponse":{"type":"object","properties":{"url":{"type":"string","format":"uri","description":"Pre-signed URL for direct download"},"expiresIn":{"type":"number","description":"URL expiration time in milliseconds"}},"required":["url","expiresIn"]},"ListSandboxFilesResponse":{"type":"object","properties":{"path":{"type":"string","description":"Directory path that was listed"},"folder":{"oneOf":[{"$ref":"#/components/schemas/FileArtifact"},{"$ref":"#/components/schemas/FolderArtifact"},{"$ref":"#/components/schemas/ReportArtifact"}],"discriminator":{"propertyName":"type","mapping":{"file":"#/components/schemas/FileArtifact","folder":"#/components/schemas/FolderArtifact","report":"#/components/schemas/ReportArtifact"}},"description":"Artifact representing the folder"},"items":{"type":"array","items":{"$ref":"#/components/schemas/Artifact"},"description":"Files and folders in the directory"},"total":{"type":"number","description":"Total number of items"},"limit":{"type":"number","description":"Max items returned"},"offset":{"type":"number","description":"Pagination offset"}},"required":["path","folder","items","total","limit","offset"]},"SandboxFileInfoResponse":{"type":"object","properties":{"path":{"type":"string","description":"File or folder path"},"artifact":{"oneOf":[{"$ref":"#/components/schemas/FileArtifact"},{"$ref":"#/components/schemas/FolderArtifact"},{"$ref":"#/components/schemas/ReportArtifact"}],"discriminator":{"propertyName":"type","mapping":{"file":"#/components/schemas/FileArtifact","folder":"#/components/schemas/FolderArtifact","report":"#/components/schemas/ReportArtifact"}},"description":"Artifact representing the file or folder"}},"required":["path","artifact"]},"SandboxDownloadRequest":{"type":"object","properties":{"paths":{"type":"array","items":{"type":"string","minLength":1},"minItems":1,"maxItems":100,"description":"File paths to download (max 100). Can include files and folders."},"maxFiles":{"type":"integer","minimum":1,"maximum":500,"default":500,"description":"Maximum number of files to include when downloading folders"},"maxDepth":{"type":"integer","minimum":1,"maximum":25,"default":10,"description":"Maximum folder depth to traverse"}},"required":["paths"]},"SandboxDownloadResponse":{"type":"object","properties":{"files":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","description":"File path in sandbox"},"name":{"type":"string","description":"File name"},"relativePath":{"type":"string","description":"Path relative to download root (for ZIP structure)"},"signedUrl":{"type":"string","format":"uri","description":"Pre-signed download URL"},"size":{"type":"integer","description":"File size in bytes"},"mimeType":{"type":"string","description":"MIME type"}},"required":["path","name","relativePath","signedUrl","size"]},"description":"Files to download with signed URLs"},"totalItems":{"type":"integer","description":"Total items found"},"downloadedItems":{"type":"integer","description":"Items included in response"},"capped":{"type":"boolean","description":"Whether results were capped due to limits"},"warnings":{"type":"array","items":{"type":"string"},"description":"Warnings (e.g., skipped items)"},"estimatedSize":{"type":"integer","description":"Estimated total size in bytes"}},"required":["files","totalItems","downloadedItems","capped","warnings","estimatedSize"]},"SessionParticipantsResponse":{"type":"object","properties":{"participants":{"type":"array","items":{"type":"string"},"description":"User IDs participating in the session"}},"required":["participants"]},"UpdateSystemMessageRequest":{"type":"object","properties":{"systemPreset":{"type":"object","properties":{"presetName":{"type":"string","description":"Unique identifier for this preset"},"operations":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["fill"]},"slot":{"type":"string"},"value":{"type":"string"}},"required":["type","slot","value"]},{"type":"object","properties":{"type":{"type":"string","enum":["include"]},"name":{"type":"string"}},"required":["type","name"]},{"type":"object","properties":{"type":{"type":"string","enum":["append"]},"value":{"type":"string"}},"required":["type","value"]},{"type":"object","properties":{"type":{"type":"string","enum":["include_vault"]},"uri":{"type":"string","description":"Vault URI (e.g. \"team://agent-context.md\", \"personal://instructions.md\")"}},"required":["type","uri"]}]},"description":"Ordered operations: fill slots, apply includes, append content"}},"required":["presetName"],"description":"System preset configuration to rebuild the system message. Takes precedence over presetRef."},"presetRef":{"type":"object","nullable":true,"properties":{"agentName":{"type":"string","description":"Resolve an agent preset by presetName from the sandbox agent registry"},"appId":{"type":"string","description":"Resolve an app preset by app ID from the sandbox app registry"}},"description":"Server-side preset reference. Resolved if systemPreset is not provided."},"agentInfo":{"type":"object","nullable":true,"properties":{"presetName":{"type":"string","description":"Unique identifier for the agent preset"},"displayName":{"type":"string","description":"Human-readable agent name from Identity.name (e.g. \"RSL Editor\")"},"agentId":{"type":"string","description":"Agent registry ID (may differ from presetName for code:library agents)"},"source":{"type":"string","enum":["code:library","code:team"],"description":"Source identifier for the agent preset"},"filename":{"type":"string","description":"The filename of the agent preset"}},"required":["presetName","source","filename"],"description":"Agent info to store in session context (null clears the agent)"}}},"UpdateSystemMessageResponse":{"type":"object","properties":{"success":{"type":"boolean"}},"required":["success"]},"SessionDeleteImpactResponse":{"type":"object","properties":{"subscriptionCount":{"type":"integer"},"activeSubscriptionCount":{"type":"integer"}},"required":["subscriptionCount","activeSubscriptionCount"]},"CloneChatSessionResponse":{"type":"object","properties":{"sessionId":{"type":"string","description":"ID of the newly cloned session"},"originalSessionId":{"type":"string","description":"ID of the original session that was cloned"}},"required":["sessionId","originalSessionId"]},"ListMessagesResponse":{"type":"object","properties":{"messages":{"type":"array","items":{"$ref":"#/components/schemas/ChatMessage"}},"hasMore":{"type":"boolean"},"oldestLoopId":{"type":"string","nullable":true}},"required":["messages","hasMore","oldestLoopId"]},"EditMessageRequest":{"type":"object","properties":{"edits":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["delete"]},"messageId":{"type":"string","description":"ID of the message to delete"}},"required":["type","messageId"]},{"type":"object","properties":{"type":{"type":"string","enum":["modify"]},"messageId":{"type":"string","description":"ID of the message to modify"},"payload":{"type":"object","properties":{"parts":{"type":"array","items":{"$ref":"#/components/schemas/MessagePart"},"description":"New message parts"},"role":{"type":"string","enum":["user","assistant","system"],"description":"New role (optional)"}},"required":["parts"],"description":"New message payload"}},"required":["type","messageId","payload"]}]},"minItems":1,"description":"Array of edits to apply"}},"required":["edits"]},"EditMessageResponse":{"type":"object","properties":{"results":{"type":"array","items":{"type":"object","properties":{"messageId":{"type":"string","description":"ID of the message that was edited"},"success":{"type":"boolean","description":"Whether the edit was successful"},"error":{"type":"string","description":"Error message if edit failed"}},"required":["messageId","success"]}}},"required":["results"]},"ExecuteToolRequest":{"type":"object","properties":{"toolName":{"type":"string","description":"The name of the tool to execute"},"toolArgs":{"type":"object","additionalProperties":{"nullable":true},"description":"Arguments to pass to the tool"}},"required":["toolName","toolArgs"]},"ExecuteToolResponse":{"type":"object","properties":{"result":{"type":"string","description":"The tool execution result as a JSON string"},"error":{"type":"string","description":"Error message if tool execution failed"}}},"AgentViewResponse":{"type":"object","properties":{"messages":{"type":"array","items":{"type":"object","additionalProperties":{"nullable":true}}}},"required":["messages"]},"ListAvailableModelsResponse":{"type":"object","properties":{"models":{"type":"array","items":{"$ref":"#/components/schemas/AvailableModel"}},"defaultModel":{"type":"string","enum":["claude-fable-5","claude-opus-4-8","claude-opus-4-7","claude-opus-4-6","claude-sonnet-4-6","claude-sonnet-4-6-1m","claude-sonnet-4-5-20250929","claude-opus-4-5-20251101","claude-haiku-4-5-20251001","gpt-5.5","gpt-5.5-pro","gpt-5.4","gpt-5.4-mini","gpt-5.4-nano","gpt-5.4-pro","gpt-5.3-codex","gemini-3.1-pro-preview","gemini-3-flash-preview","gemini-2.5-pro","gemini-2.5-flash","gemini-2.5-flash-lite","gemini-3.1-flash-lite","gemini-flash-latest","gemini-flash-lite-latest","deepseek/deepseek-v4-pro","deepseek/deepseek-v4-flash","xai/grok-4.3","zai/glm-5.1","glm-5.2","nvidia/nemotron-3-ultra-550b-a55b","moonshotai/kimi-k2.6","moonshotai/kimi-k2.7-code","moonshotai/kimi-k2.5"]},"orgDefaultModel":{"type":"string","enum":["claude-fable-5","claude-opus-4-8","claude-opus-4-7","claude-opus-4-6","claude-sonnet-4-6","claude-sonnet-4-6-1m","claude-sonnet-4-5-20250929","claude-opus-4-5-20251101","claude-haiku-4-5-20251001","gpt-5.5","gpt-5.5-pro","gpt-5.4","gpt-5.4-mini","gpt-5.4-nano","gpt-5.4-pro","gpt-5.3-codex","gemini-3.1-pro-preview","gemini-3-flash-preview","gemini-2.5-pro","gemini-2.5-flash","gemini-2.5-flash-lite","gemini-3.1-flash-lite","gemini-flash-latest","gemini-flash-lite-latest","deepseek/deepseek-v4-pro","deepseek/deepseek-v4-flash","xai/grok-4.3","zai/glm-5.1","glm-5.2","nvidia/nemotron-3-ultra-550b-a55b","moonshotai/kimi-k2.6","moonshotai/kimi-k2.7-code","moonshotai/kimi-k2.5"]},"userDefaultModel":{"type":"string","nullable":true,"enum":["claude-fable-5","claude-opus-4-8","claude-opus-4-7","claude-opus-4-6","claude-sonnet-4-6","claude-sonnet-4-6-1m","claude-sonnet-4-5-20250929","claude-opus-4-5-20251101","claude-haiku-4-5-20251001","gpt-5.5","gpt-5.5-pro","gpt-5.4","gpt-5.4-mini","gpt-5.4-nano","gpt-5.4-pro","gpt-5.3-codex","gemini-3.1-pro-preview","gemini-3-flash-preview","gemini-2.5-pro","gemini-2.5-flash","gemini-2.5-flash-lite","gemini-3.1-flash-lite","gemini-flash-latest","gemini-flash-lite-latest","deepseek/deepseek-v4-pro","deepseek/deepseek-v4-flash","xai/grok-4.3","zai/glm-5.1","glm-5.2","nvidia/nemotron-3-ultra-550b-a55b","moonshotai/kimi-k2.6","moonshotai/kimi-k2.7-code","moonshotai/kimi-k2.5",null]},"dataRetentionPolicy":{"$ref":"#/components/schemas/LlmDataRetentionPolicy"}},"required":["models","defaultModel","orgDefaultModel","userDefaultModel","dataRetentionPolicy"]},"UserModelPreferences":{"type":"object","properties":{"defaultModel":{"type":"string","nullable":true,"enum":["claude-fable-5","claude-opus-4-8","claude-opus-4-7","claude-opus-4-6","claude-sonnet-4-6","claude-sonnet-4-6-1m","claude-sonnet-4-5-20250929","claude-opus-4-5-20251101","claude-haiku-4-5-20251001","gpt-5.5","gpt-5.5-pro","gpt-5.4","gpt-5.4-mini","gpt-5.4-nano","gpt-5.4-pro","gpt-5.3-codex","gemini-3.1-pro-preview","gemini-3-flash-preview","gemini-2.5-pro","gemini-2.5-flash","gemini-2.5-flash-lite","gemini-3.1-flash-lite","gemini-flash-latest","gemini-flash-lite-latest","deepseek/deepseek-v4-pro","deepseek/deepseek-v4-flash","xai/grok-4.3","zai/glm-5.1","glm-5.2","nvidia/nemotron-3-ultra-550b-a55b","moonshotai/kimi-k2.6","moonshotai/kimi-k2.7-code","moonshotai/kimi-k2.5",null],"default":null}}},"UserModelPreferencesPatch":{"type":"object","properties":{"defaultModel":{"type":"string","nullable":true,"enum":["claude-fable-5","claude-opus-4-8","claude-opus-4-7","claude-opus-4-6","claude-sonnet-4-6","claude-sonnet-4-6-1m","claude-sonnet-4-5-20250929","claude-opus-4-5-20251101","claude-haiku-4-5-20251001","gpt-5.5","gpt-5.5-pro","gpt-5.4","gpt-5.4-mini","gpt-5.4-nano","gpt-5.4-pro","gpt-5.3-codex","gemini-3.1-pro-preview","gemini-3-flash-preview","gemini-2.5-pro","gemini-2.5-flash","gemini-2.5-flash-lite","gemini-3.1-flash-lite","gemini-flash-latest","gemini-flash-lite-latest","deepseek/deepseek-v4-pro","deepseek/deepseek-v4-flash","xai/grok-4.3","zai/glm-5.1","glm-5.2","nvidia/nemotron-3-ultra-550b-a55b","moonshotai/kimi-k2.6","moonshotai/kimi-k2.7-code","moonshotai/kimi-k2.5",null]}},"required":["defaultModel"]},"MissionControlListResponse":{"type":"object","properties":{"schema":{"type":"string","enum":["contextbase-mission-controls@v1"]},"loadedAt":{"type":"string","format":"date-time"},"missionControls":{"type":"array","items":{"$ref":"#/components/schemas/MissionControlSummary"}},"lastError":{"type":"string","nullable":true}},"required":["schema","loadedAt","missionControls","lastError"]},"CreateMissionControl":{"type":"object","properties":{"slug":{"type":"string","minLength":2,"maxLength":128,"pattern":"^[a-z0-9][a-z0-9-]{0,126}[a-z0-9]$"},"name":{"type":"string","minLength":1,"maxLength":255},"title":{"type":"string","minLength":1,"maxLength":255},"kind":{"$ref":"#/components/schemas/MissionControlKind"},"sourcePath":{"type":"string"},"primaryContextBaseRepoId":{"type":"string","nullable":true,"format":"uuid"},"primaryRef":{"$ref":"#/components/schemas/MissionControlPrimaryRef"},"sourceRefs":{"type":"array","items":{"$ref":"#/components/schemas/MissionControlBlock"}},"views":{"type":"array","items":{"$ref":"#/components/schemas/MissionControlConfiguredView"}},"actions":{"type":"array","items":{"$ref":"#/components/schemas/MissionControlBlock"}},"apps":{"type":"array","items":{"$ref":"#/components/schemas/MissionControlApp"}},"metadata":{"$ref":"#/components/schemas/MissionControlMetadata"}},"required":["name"]},"MissionControl":{"type":"object","properties":{"id":{"type":"string","description":"Stable Mission Control slug"},"rowId":{"type":"string","format":"uuid","description":"Database row ID"},"name":{"type":"string"},"kind":{"$ref":"#/components/schemas/MissionControlKind"},"status":{"$ref":"#/components/schemas/MissionControlStatus"},"sourcePath":{"type":"string"},"title":{"type":"string"},"primaryContextBaseRepoId":{"type":"string","nullable":true,"format":"uuid"},"primaryRef":{"$ref":"#/components/schemas/MissionControlPrimaryRef"},"sourceRefs":{"type":"array","items":{"$ref":"#/components/schemas/MissionControlBlock"}},"views":{"type":"array","items":{"$ref":"#/components/schemas/MissionControlConfiguredView"}},"actions":{"type":"array","items":{"$ref":"#/components/schemas/MissionControlBlock"}},"apps":{"type":"array","items":{"$ref":"#/components/schemas/MissionControlApp"}},"metadata":{"$ref":"#/components/schemas/MissionControlMetadata"},"createdBy":{"type":"string","nullable":true},"updatedBy":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"deletedAt":{"type":"string","nullable":true,"format":"date-time"}},"required":["id","rowId","name","kind","status","sourcePath","title","primaryContextBaseRepoId","primaryRef","sourceRefs","views","actions","apps","createdBy","updatedBy","createdAt","updatedAt"]},"MissionControlDetailResponse":{"type":"object","properties":{"missionControl":{"$ref":"#/components/schemas/MissionControl"},"loadedAt":{"type":"string","format":"date-time"},"lastError":{"type":"string","nullable":true}},"required":["missionControl","loadedAt","lastError"]},"UpdateMissionControl":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":255},"title":{"type":"string","nullable":true,"minLength":1,"maxLength":255},"kind":{"$ref":"#/components/schemas/MissionControlKind"},"status":{"$ref":"#/components/schemas/MissionControlStatus"},"sourcePath":{"type":"string","nullable":true},"primaryContextBaseRepoId":{"type":"string","nullable":true,"format":"uuid"},"primaryRef":{"$ref":"#/components/schemas/MissionControlPrimaryRef"},"sourceRefs":{"type":"array","items":{"$ref":"#/components/schemas/MissionControlBlock"}},"views":{"type":"array","items":{"$ref":"#/components/schemas/MissionControlConfiguredView"}},"actions":{"type":"array","items":{"$ref":"#/components/schemas/MissionControlBlock"}},"apps":{"type":"array","items":{"$ref":"#/components/schemas/MissionControlApp"}},"metadata":{"$ref":"#/components/schemas/MissionControlMetadata"}}},"MissionControlContextBaseListResponse":{"type":"object","properties":{"missionControlId":{"type":"string"},"contextbases":{"type":"array","items":{"$ref":"#/components/schemas/MissionControlContextBase"}},"loadedAt":{"type":"string","format":"date-time"},"lastError":{"type":"string","nullable":true}},"required":["missionControlId","contextbases","loadedAt","lastError"]},"CreateMissionControlContextBase":{"type":"object","properties":{"orgRepoId":{"type":"string","format":"uuid"},"alias":{"type":"string","minLength":2,"maxLength":128,"pattern":"^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$","description":"Canonical contextbase ref alias: primary for the primary link, otherwise the repo-derived <name> alias."},"access":{"$ref":"#/components/schemas/MissionControlContextBaseAccess"},"isPrimary":{"type":"boolean","default":false},"mountPath":{"type":"string","minLength":1,"maxLength":512,"description":"Canonical contextbase ref mount path."}},"required":["orgRepoId"]},"MissionControlContextBase":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"missionControlId":{"type":"string"},"missionControlRowId":{"type":"string","format":"uuid"},"orgRepoId":{"type":"string","format":"uuid"},"repoName":{"type":"string"},"alias":{"type":"string","minLength":2,"maxLength":128,"pattern":"^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$","description":"Canonical contextbase ref alias: primary for the primary link, otherwise the repo-derived <name> alias."},"access":{"$ref":"#/components/schemas/MissionControlContextBaseAccess"},"mountPath":{"type":"string","description":"Canonical contextbase ref mount path."},"isPrimary":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","missionControlId","missionControlRowId","orgRepoId","repoName","alias","access","mountPath","isPrimary","createdAt","updatedAt"]},"ProvisionMissionControlContextBase":{"type":"object","properties":{"repoName":{"type":"string","minLength":1,"maxLength":255},"alias":{"type":"string","minLength":2,"maxLength":128,"pattern":"^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$","description":"Canonical contextbase ref alias: primary for the primary link, otherwise the repo-derived <name> alias."},"access":{"$ref":"#/components/schemas/MissionControlContextBaseAccess"},"isPrimary":{"type":"boolean","default":false},"mountPath":{"type":"string","minLength":1,"maxLength":512,"description":"Canonical contextbase ref mount path."}},"required":["repoName"]},"UpdateMissionControlContextBase":{"type":"object","properties":{"alias":{"type":"string","minLength":2,"maxLength":128,"pattern":"^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$","description":"Canonical contextbase ref alias: primary for the primary link, otherwise the repo-derived <name> alias."},"access":{"$ref":"#/components/schemas/MissionControlContextBaseAccess"},"isPrimary":{"type":"boolean"},"mountPath":{"type":"string","minLength":1,"maxLength":512,"description":"Canonical contextbase ref mount path."}}},"MissionControlBootstrapResponse":{"type":"object","properties":{"missionControl":{"$ref":"#/components/schemas/MissionControl"},"primaryRef":{"$ref":"#/components/schemas/MissionControlPrimaryRef"},"primaryContextBase":{"$ref":"#/components/schemas/MissionControlBootstrapContextBase"},"loadedAt":{"type":"string","format":"date-time"},"lastError":{"type":"string","nullable":true}},"required":["missionControl","primaryRef","primaryContextBase","loadedAt","lastError"]},"MissionControlSignalsResponse":{"type":"object","properties":{"missionControlId":{"type":"string"},"signals":{"type":"array","items":{"nullable":true},"default":[]},"loadedAt":{"type":"string","format":"date-time"},"lastError":{"type":"string","nullable":true}},"required":["missionControlId","loadedAt","lastError"]},"MissionControlSkillsResponse":{"type":"object","properties":{"missionControlId":{"type":"string"},"skills":{"type":"array","items":{"$ref":"#/components/schemas/MissionControlSkill"}},"loadedAt":{"type":"string","format":"date-time"},"lastError":{"type":"string","nullable":true}},"required":["missionControlId","skills","loadedAt","lastError"]},"UpdateMissionControlSkillPin":{"type":"object","properties":{"orgRepoId":{"type":"string","format":"uuid"},"skillPath":{"type":"string","minLength":1,"maxLength":512},"pinned":{"type":"boolean"}},"required":["orgRepoId","skillPath","pinned"]},"SystemPreset":{"type":"object","properties":{"presetName":{"type":"string","description":"Unique identifier for this preset"},"operations":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["fill"]},"slot":{"type":"string"},"value":{"type":"string"}},"required":["type","slot","value"]},{"type":"object","properties":{"type":{"type":"string","enum":["include"]},"name":{"type":"string"}},"required":["type","name"]},{"type":"object","properties":{"type":{"type":"string","enum":["append"]},"value":{"type":"string"}},"required":["type","value"]},{"type":"object","properties":{"type":{"type":"string","enum":["include_vault"]},"uri":{"type":"string","description":"Vault URI (e.g. \"team://agent-context.md\", \"personal://instructions.md\")"}},"required":["type","uri"]}]},"description":"Ordered operations: fill slots, apply includes, append content"}},"required":["presetName"],"description":"System preset configuration for prompt generation"},"RenderPresetResponse":{"type":"object","properties":{"output":{"type":"string"}},"required":["output"]},"GetPresetResponse":{"type":"object","properties":{"presetName":{"type":"string"},"content":{"type":"string"}},"required":["presetName","content"]},"ErrorResponse":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]},"ListPresetsResponse":{"type":"object","properties":{"presets":{"type":"array","items":{"$ref":"#/components/schemas/PresetInfo"}}},"required":["presets"]},"ProjectListResponse":{"type":"object","properties":{"projects":{"type":"array","items":{"$ref":"#/components/schemas/Project"},"description":"List of projects"},"total":{"type":"integer","description":"Total number of projects"}},"required":["projects","total"],"description":"List of projects response"},"CreateProject":{"type":"object","properties":{"name":{"type":"string","minLength":2,"maxLength":64,"pattern":"^[a-z0-9][a-z0-9-]{0,62}[a-z0-9]$","description":"Project name slug (unique within org+app)"},"title":{"type":"string","minLength":1,"maxLength":255,"description":"Project title"},"body":{"type":"string","nullable":true,"description":"Project description or brief"},"type":{"type":"string","minLength":1,"maxLength":50,"description":"Project type"},"app_id":{"type":"string","nullable":true,"minLength":1,"maxLength":255,"description":"App this project is scoped to (e.g., \"app-filing-monitor\")"},"mission_control_id":{"type":"string","nullable":true,"minLength":1,"description":"Mission Control instance this project belongs to"},"storage":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","enum":["vault_only"]},"vault_path":{"type":"string"}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","enum":["git_backed"]},"repo_name":{"type":"string"}},"required":["type"]}],"description":"Storage configuration"},"metadata":{"type":"object","nullable":true,"additionalProperties":{"nullable":true},"description":"Optional metadata including app_relationships"},"attachments":{"type":"array","items":{"type":"string"},"description":"Attached artifact IDs"},"phases":{"type":"array","items":{"type":"object","properties":{"phase_key":{"type":"string","minLength":1,"maxLength":100},"name":{"type":"string","minLength":1,"maxLength":255},"body":{"type":"string","nullable":true},"sort_order":{"type":"integer"},"status":{"type":"string","enum":["not_started","active","blocked","completed","skipped"]},"metadata":{"type":"object","nullable":true,"additionalProperties":{"nullable":true}}},"required":["phase_key","name","sort_order"]}},"current_phase_key":{"type":"string","description":"Phase key to set as the current phase when creating phases"}},"description":"Create project request"},"Project":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Project ID"},"name":{"type":"string","description":"Project name (unique within org, or within org+app)"},"title":{"type":"string","nullable":true,"description":"Human-readable project title"},"body":{"type":"string","nullable":true,"description":"Project description or brief"},"type":{"type":"string","description":"Project type (rater_builder, filing_review, app_dev, analysis, etc.)"},"status":{"type":"string","enum":["active","completed","archived"],"description":"Project lifecycle status"},"current_phase_id":{"type":"string","nullable":true,"format":"uuid","description":"Canonical current project phase ID"},"mission_control_id":{"type":"string","nullable":true,"description":"Mission Control instance this project belongs to"},"app_id":{"type":"string","nullable":true,"description":"App this project is scoped to (e.g., \"app-filing-monitor\"). When set, git branch is {appId}/{name}."},"storage":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","enum":["vault_only"]},"vault_path":{"type":"string"}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","enum":["git_backed"]},"repo_name":{"type":"string"}},"required":["type"]}],"description":"Storage configuration"},"metadata":{"type":"object","nullable":true,"additionalProperties":{"nullable":true},"description":"Flexible metadata including app_relationships"},"attachments":{"type":"array","items":{"type":"string"},"description":"Attached artifact IDs"},"launcher_data":{"type":"object","nullable":true,"properties":{"title":{"type":"string"},"subtitle":{"type":"string"},"state":{"type":"string","enum":["active","attention","ready","idle"]},"stage":{"type":"string"},"work":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"completed":{"type":"integer","minimum":0},"active":{"type":"integer","minimum":0},"blocked":{"type":"integer","minimum":0},"pendingReview":{"type":"integer","minimum":0}}},"chips":{"type":"array","items":{"type":"object","properties":{"label":{"type":"string"},"tone":{"type":"string","enum":["default","warning","danger","success"]}},"required":["label"]}},"metrics":{"type":"array","items":{"type":"object","properties":{"label":{"type":"string"},"value":{"anyOf":[{"type":"string"},{"type":"number"}]}},"required":["label","value"]}},"updatedAt":{"type":"string"},"sortKey":{"type":"number"}},"additionalProperties":{"nullable":true},"description":"Optional app launcher payload derived from project metadata when requested via include_launcher_data"},"created_by":{"type":"string","nullable":true,"description":"User who created the project"},"updated_by":{"type":"string","nullable":true,"description":"User who last updated the project"},"created_by_actor_type":{"type":"string","nullable":true,"enum":["session","user","user_group","workflow","system",null],"description":"Actor type that created the project"},"created_by_actor_id":{"type":"string","nullable":true,"description":"Actor ID that created the project"},"created_at":{"type":"string","format":"date-time","description":"Project creation timestamp"},"updated_at":{"type":"string","format":"date-time","description":"Last update timestamp"},"deleted_at":{"type":"string","nullable":true,"format":"date-time","description":"Soft delete timestamp"}},"required":["id","name","title","body","type","status","current_phase_id","mission_control_id","storage","attachments","created_by_actor_type","created_by_actor_id","created_at","updated_at"],"description":"Project definition"},"UpdateProject":{"type":"object","properties":{"name":{"type":"string","minLength":2,"maxLength":64,"pattern":"^[a-z0-9][a-z0-9-]{0,62}[a-z0-9]$","description":"Project name slug"},"title":{"type":"string","minLength":1,"maxLength":255,"description":"Project title"},"body":{"type":"string","nullable":true,"description":"Project description or brief"},"status":{"type":"string","enum":["active","completed","archived"],"description":"Project status"},"current_phase_id":{"type":"string","nullable":true,"format":"uuid","description":"Canonical current project phase ID"},"mission_control_id":{"type":"string","nullable":true,"minLength":1,"description":"Mission Control instance this project belongs to"},"storage":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","enum":["vault_only"]},"vault_path":{"type":"string"}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","enum":["git_backed"]},"repo_name":{"type":"string"}},"required":["type"]}],"description":"Storage configuration"},"metadata":{"type":"object","nullable":true,"additionalProperties":{"nullable":true},"description":"Project metadata"},"attachments":{"type":"array","items":{"type":"string"},"description":"Attached artifact IDs"}},"description":"Update project request"},"ProjectPhaseListResponse":{"type":"object","properties":{"phases":{"type":"array","items":{"$ref":"#/components/schemas/ProjectPhase"}},"total":{"type":"integer"}},"required":["phases","total"],"description":"List of project phases"},"CreateProjectPhase":{"type":"object","properties":{"phase_key":{"type":"string","minLength":1,"maxLength":100},"name":{"type":"string","minLength":1,"maxLength":255},"body":{"type":"string","nullable":true},"sort_order":{"type":"integer"},"status":{"type":"string","enum":["not_started","active","blocked","completed","skipped"]},"metadata":{"type":"object","nullable":true,"additionalProperties":{"nullable":true}},"make_current":{"type":"boolean"}},"required":["phase_key","name","sort_order"],"description":"Create a project phase"},"ProjectPhase":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Project phase ID"},"project_id":{"type":"string","format":"uuid","description":"Project ID"},"phase_key":{"type":"string","description":"Stable phase key within the project"},"name":{"type":"string","description":"Human-readable phase name"},"body":{"type":"string","nullable":true,"description":"Phase description, instructions, or notes"},"sort_order":{"type":"integer","description":"Ordering key for the project phase plan"},"status":{"type":"string","enum":["not_started","active","blocked","completed","skipped"],"description":"Phase lifecycle status"},"metadata":{"type":"object","nullable":true,"additionalProperties":{"nullable":true}},"started_at":{"type":"string","nullable":true,"format":"date-time"},"completed_at":{"type":"string","nullable":true,"format":"date-time"},"skipped_at":{"type":"string","nullable":true,"format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","project_id","phase_key","name","body","sort_order","status","started_at","completed_at","skipped_at","created_at","updated_at"],"description":"Project phase definition and state"},"UpdateProjectPhase":{"type":"object","properties":{"phase_key":{"type":"string","minLength":1,"maxLength":100},"name":{"type":"string","minLength":1,"maxLength":255},"body":{"type":"string","nullable":true},"sort_order":{"type":"integer"},"status":{"type":"string","enum":["not_started","active","blocked","completed","skipped"]},"metadata":{"type":"object","nullable":true,"additionalProperties":{"nullable":true}},"make_current":{"type":"boolean"}},"description":"Update a project phase"},"SessionProject":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Link ID"},"session_id":{"type":"string","description":"Session ID"},"project_id":{"type":"string","format":"uuid","description":"Project ID"},"branch_name":{"type":"string","nullable":true,"description":"Git branch name (for git-backed projects)"},"role":{"type":"string","nullable":true,"enum":["leader","subagent","observer",null],"description":"Role in the project"},"created_at":{"type":"string","format":"date-time","description":"Link creation timestamp"}},"required":["id","session_id","project_id","created_at"],"description":"Session-project link"},"SessionProjectListResponse":{"type":"object","properties":{"links":{"type":"array","items":{"$ref":"#/components/schemas/SessionProject"},"description":"List of session-project links"},"total":{"type":"integer","description":"Total number of links"}},"required":["links","total"],"description":"List of session-project links response"},"EnqueueEventRequest":{"type":"object","properties":{"type":{"type":"string","enum":["serff_filing_update","promise_completion"],"description":"Event type"},"payload":{"type":"object","additionalProperties":{"nullable":true},"description":"Event payload (validated per type)"}},"required":["type","payload"]},"EnqueueEventResponse":{"type":"object","properties":{"eventId":{"type":"string","description":"Created event ID (direct path only)"},"inboxItemId":{"type":"string","description":"Created agent inbox item ID (direct path only)"},"pubsubEventId":{"type":"string","description":"Pub/Sub event ID"},"status":{"type":"string","enum":["queued"],"description":"Queueing status"}},"required":["status"]},"ScheduleTaskRequest":{"type":"object","properties":{"task_type":{"type":"string","minLength":1,"description":"Task type to schedule"},"config":{"type":"object","additionalProperties":{"nullable":true},"description":"Task-type-specific configuration"},"delay_secs":{"type":"integer","minimum":0,"maximum":86400,"description":"Delay before execution in seconds (max 86400 = 24h). Omit for immediate."}},"required":["task_type","config"]},"ScheduleTaskResponse":{"type":"object","properties":{"workflowId":{"type":"string","description":"Temporal workflow ID"},"alreadyScheduled":{"type":"boolean","description":"Whether the task was already scheduled"}},"required":["workflowId","alreadyScheduled"]},"ListInboxItemsResponse":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/InboxItem"}},"limit":{"type":"number"},"offset":{"type":"number"}},"required":["items","limit","offset"]},"CreateInboxItemRequest":{"type":"object","properties":{"sessionId":{"type":"string","minLength":1},"instruction":{"type":"string","minLength":1},"facet":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["agent-completion"]},"sessionId":{"type":"string","format":"uuid"},"title":{"type":"string","minLength":1},"summary":{"type":"string"}},"required":["type","sessionId","title"]},{"type":"object","properties":{"type":{"type":"string","enum":["generic"]},"source":{"type":"string"}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","enum":["scheduled"]},"source":{"type":"string"}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","enum":["webhook"]},"source":{"type":"string"}},"required":["type"]}]}},"required":["sessionId","instruction"]},"CreateInboxItemResponse":{"type":"object","properties":{"id":{"type":"string"},"status":{"$ref":"#/components/schemas/InboxItemStatus"}},"required":["id","status"]},"InboxItem":{"type":"object","properties":{"id":{"type":"string"},"sessionId":{"type":"string"},"instruction":{"type":"string"},"status":{"$ref":"#/components/schemas/InboxItemStatus"},"sender":{"type":"string","nullable":true},"createdAt":{"type":"string"},"readAt":{"type":"string","nullable":true}},"required":["id","sessionId","instruction","status","sender","createdAt","readAt"]},"MarkInboxItemsReadRequest":{"type":"object","properties":{"ids":{"type":"array","items":{"type":"string"},"minItems":1}},"required":["ids"]},"MarkInboxItemsReadResponse":{"type":"object","properties":{"updated":{"type":"number"}},"required":["updated"]},"DeleteInboxItemResponse":{"type":"object","properties":{"success":{"type":"boolean"}},"required":["success"]},"SubscriptionScheduleTypesResponse":{"type":"object","properties":{"scheduleTypes":{"type":"array","items":{"$ref":"#/components/schemas/ScheduledSubscriptionScheduleType"}}},"required":["scheduleTypes"]},"CreateScheduledSubscriptionRequest":{"type":"object","properties":{"sessionId":{"type":"string","minLength":1,"description":"Target session ID. Required for inbox and spawn modes. Not used for workflow_run mode."},"eventType":{"type":"string","enum":["scheduled_trigger","serff_filing_update"],"description":"Subscription type. Use 'scheduled_trigger' for generic periodic wakeups, or 'serff_filing_update' to scan SERFF events."},"scheduleType":{"$ref":"#/components/schemas/ScheduledSubscriptionScheduleType"},"cronExpression":{"type":"array","items":{"type":"string","minLength":1},"minItems":1,"maxItems":10,"description":"Array of cron expressions (required when scheduleType=cron). Temporal fires at the union of all patterns. Max 10."},"timezone":{"type":"string","minLength":1,"description":"Timezone (defaults to UTC)"},"startTime":{"type":"string","minLength":1,"description":"ISO start time (defaults to now). Can be moved back to reprocess."},"filterMode":{"type":"string","enum":["server","agent"],"description":"Where filters are applied: 'server' filters before messaging; 'agent' asks the agent to apply filters."},"filterCriteria":{"type":"object","additionalProperties":{"nullable":true},"description":"Filter criteria (typed per eventType when supported)"},"instruction":{"type":"string","description":"Prompt/instruction included in the agent inbox message. Mutually exclusive with runCommand."},"runCommand":{"type":"string","minLength":1,"description":"Shell command to execute on each tick directly in the session sandbox (LLM not invoked). Output is captured to log files in the sandbox; `command-started` and `command-result` inbox items carry the paths and exit code. Mutually exclusive with instruction."},"notificationConfig":{"type":"object","nullable":true,"properties":{"email":{"type":"object","properties":{"to":{"type":"array","items":{"type":"string","format":"email"},"minItems":1,"description":"Recipient email addresses"}},"required":["to"]}},"description":"Optional notification delivery channels (e.g. email) in addition to agent inbox"},"deliveryMode":{"type":"string","enum":["inbox","spawn","workflow_run"],"default":"inbox","description":"Delivery mode: 'inbox' sends to existing session (default), 'spawn' creates a fresh session per tick"},"presetRef":{"type":"object","nullable":true,"properties":{"agentName":{"type":"string","description":"Resolve an agent preset by presetName from the sandbox agent registry"},"appId":{"type":"string","description":"Resolve an app preset by app ID from the sandbox app registry"}},"description":"Agent preset reference for spawn mode. Required when deliveryMode is 'spawn'."},"spawnConfig":{"type":"object","properties":{"model":{"type":"string","description":"Model override for spawned sessions"},"tags":{"type":"array","items":{"type":"string"},"description":"Additional tags for spawned sessions"}},"description":"Optional overrides (model, tags) for spawned sessions."},"workflowConfig":{"type":"object","nullable":true,"properties":{"workflowId":{"type":"string","minLength":1,"description":"ID of the contextbase workflow to trigger"},"input":{"type":"object","additionalProperties":{"nullable":true},"description":"Input passed to the workflow on each tick"}},"required":["workflowId"],"description":"Workflow configuration for workflow_run delivery mode. Required when deliveryMode is workflow_run."},"maxRuns":{"type":"integer","nullable":true,"minimum":1,"description":"Maximum number of times the subscription should fire. NULL = unlimited (default). When reached, the subscription is auto-paused."}},"required":["eventType","scheduleType"]},"CreateScheduledSubscriptionResponse":{"type":"object","properties":{"id":{"type":"string"}},"required":["id"]},"ListScheduledSerffSubscriptionsResponse":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/ScheduledSerffSubscription"}},"limit":{"type":"number"},"offset":{"type":"number"}},"required":["items","limit","offset"]},"ScheduledSerffSubscription":{"type":"object","properties":{"id":{"type":"string"},"sessionId":{"type":"string","nullable":true},"eventType":{"$ref":"#/components/schemas/SubscriptionEventType"},"scheduleType":{"$ref":"#/components/schemas/ScheduledSubscriptionScheduleType"},"cronExpression":{"type":"array","nullable":true,"items":{"type":"string"},"description":"Array of cron expressions"},"timezone":{"type":"string","nullable":true},"startTime":{"type":"string"},"nextRunTs":{"type":"string","nullable":true},"cursorLastEventCreatedAt":{"type":"string","nullable":true},"cursorLastEventId":{"type":"string","nullable":true},"filterMode":{"$ref":"#/components/schemas/SubscriptionFilterMode"},"filterCriteria":{"type":"object","nullable":true,"additionalProperties":{"nullable":true}},"instruction":{"type":"string","nullable":true},"runCommand":{"type":"string","nullable":true,"description":"Shell command run on each tick via bash tool. Mutually exclusive with instruction."},"createdAt":{"type":"string"},"createdBy":{"type":"string","nullable":true},"status":{"$ref":"#/components/schemas/SubscriptionStatus"},"notificationConfig":{"type":"object","nullable":true,"properties":{"email":{"type":"object","properties":{"to":{"type":"array","items":{"type":"string","format":"email"},"minItems":1,"description":"Recipient email addresses"}},"required":["to"]}},"description":"Optional notification channels beyond the agent inbox"},"deliveryMode":{"$ref":"#/components/schemas/SubscriptionDeliveryMode"},"presetRef":{"$ref":"#/components/schemas/PresetRef"},"spawnConfig":{"type":"object","nullable":true,"properties":{"model":{"type":"string","description":"Model override for spawned sessions"},"tags":{"type":"array","items":{"type":"string"},"description":"Additional tags for spawned sessions"}},"description":"Optional configuration overrides for spawned sessions"},"workflowConfig":{"type":"object","nullable":true,"properties":{"workflowId":{"type":"string","minLength":1,"description":"ID of the contextbase workflow to trigger"},"input":{"type":"object","additionalProperties":{"nullable":true},"description":"Input passed to the workflow on each tick"}},"required":["workflowId"],"description":"Configuration for workflow_run delivery mode"},"maxRuns":{"type":"integer","nullable":true,"description":"Maximum number of times the subscription should fire. NULL = unlimited."},"runCount":{"type":"integer","description":"How many times the subscription has fired so far."},"sessionTitle":{"type":"string","nullable":true,"description":"Title of the linked session, joined server-side"}},"required":["id","sessionId","eventType","scheduleType","cronExpression","timezone","startTime","nextRunTs","cursorLastEventCreatedAt","cursorLastEventId","filterMode","filterCriteria","instruction","runCommand","createdAt","createdBy","status","notificationConfig","deliveryMode","presetRef","spawnConfig","workflowConfig","maxRuns","runCount","sessionTitle"]},"UpdateSubscriptionRequest":{"type":"object","properties":{"filterCriteria":{"type":"object","additionalProperties":{"nullable":true}},"scheduleType":{"$ref":"#/components/schemas/ScheduledSubscriptionScheduleType"},"cronExpression":{"type":"array","items":{"type":"string","minLength":1},"minItems":1,"maxItems":10,"description":"Array of cron expressions (max 10)"},"timezone":{"type":"string","minLength":1},"instruction":{"type":"string","nullable":true,"description":"Set/clear the LLM instruction. Pass null to clear. Mutually exclusive with runCommand."},"runCommand":{"type":"string","nullable":true,"minLength":1,"description":"Set/clear the shell command run directly in the session sandbox (no LLM invocation). Pass null to clear. Mutually exclusive with instruction."},"filterMode":{"$ref":"#/components/schemas/SubscriptionFilterMode"},"notificationConfig":{"type":"object","nullable":true,"properties":{"email":{"type":"object","properties":{"to":{"type":"array","items":{"type":"string","format":"email"},"minItems":1,"description":"Recipient email addresses"}},"required":["to"]}},"description":"Set notification channels. Pass null to remove email notifications."},"deliveryMode":{"$ref":"#/components/schemas/SubscriptionDeliveryMode"},"presetRef":{"$ref":"#/components/schemas/PresetRef"},"spawnConfig":{"type":"object","nullable":true,"properties":{"model":{"type":"string","description":"Model override for spawned sessions"},"tags":{"type":"array","items":{"type":"string"},"description":"Additional tags for spawned sessions"}},"description":"Optional configuration overrides for spawned sessions"},"workflowConfig":{"type":"object","nullable":true,"properties":{"workflowId":{"type":"string","minLength":1,"description":"ID of the contextbase workflow to trigger"},"input":{"type":"object","additionalProperties":{"nullable":true},"description":"Input passed to the workflow on each tick"}},"required":["workflowId"],"description":"Configuration for workflow_run delivery mode"},"maxRuns":{"type":"integer","nullable":true,"minimum":1,"description":"Maximum number of times the subscription should fire. Pass null to make unlimited."}}},"UpdateSubscriptionResponse":{"type":"object","properties":{"success":{"type":"boolean"}},"required":["success"]},"DeleteSessionSubscriptionResponse":{"type":"object","properties":{"success":{"type":"boolean"}},"required":["success"]},"SetScheduledSubscriptionCursorRequest":{"type":"object","properties":{"cursorAt":{"type":"string","minLength":1,"description":"Optional ISO time to set the cursor. If omitted, cursor is cleared (subscription resumes from startTime). If provided, cursor is set to the latest event at or before this time (or to this time if no events exist)."},"startTime":{"type":"string","minLength":1,"description":"Optional ISO start time to set (lower bound)."}}},"SetScheduledSubscriptionCursorResponse":{"type":"object","properties":{"success":{"type":"boolean"}},"required":["success"]},"PauseSubscriptionResponse":{"type":"object","properties":{"success":{"type":"boolean"}},"required":["success"]},"ResumeSubscriptionResponse":{"type":"object","properties":{"success":{"type":"boolean"}},"required":["success"]},"SubscriptionRunNowResponse":{"type":"object","properties":{"success":{"type":"boolean"},"triggered":{"type":"boolean"},"status":{"$ref":"#/components/schemas/SubscriptionStatus"},"advanceCursor":{"type":"boolean","description":"Whether the cursor was advanced"},"error":{"type":"string","description":"Error message when the run could not be triggered"}},"required":["success","triggered","status","advanceCursor"]},"SubscriptionDryRunRequest":{"type":"object","properties":{"eventType":{"type":"string","enum":["scheduled_trigger","serff_filing_update"],"description":"Subscription type. Use 'scheduled_trigger' for generic periodic wakeups, or 'serff_filing_update' to scan SERFF events."},"filterMode":{"type":"string","enum":["server","agent"],"description":"Where filters are applied: 'server' filters before messaging; 'agent' asks the agent to apply filters. Defaults to 'agent'. Dry-run always uses 'server'."},"filterCriteria":{"type":"object","additionalProperties":{"nullable":true},"description":"Filter criteria (typed per eventType when supported)"},"startTime":{"type":"string","minLength":1,"description":"ISO start time for the scan window. Defaults to 7 days ago."}},"required":["eventType"]},"SubscriptionDryRunResponse":{"type":"object","properties":{"filterValid":{"type":"boolean"},"filterErrors":{"type":"array","items":{"type":"string"}},"windowStart":{"type":"string"},"windowEnd":{"type":"string"},"matchCount":{"type":"number"},"scannedCount":{"type":"number"},"sample":{"type":"array","items":{"$ref":"#/components/schemas/SubscriptionDryRunSampleItem"}},"truncated":{"type":"boolean","description":"True if matchCount >= maxListed (100)"},"scanTruncated":{"type":"boolean","description":"True if we hit maxScanned limit (1000)"}},"required":["filterValid","windowStart","windowEnd","matchCount","scannedCount","sample","truncated","scanTruncated"]},"CreateWatcherRequest":{"type":"object","properties":{"eventType":{"type":"string","enum":["promise","github_webhook","agent_task","session_lifecycle","serff_filing","incoming_webhook"]},"matchCriteria":{"type":"object","additionalProperties":{"nullable":true},"default":{}},"deliveryConfig":{"$ref":"#/components/schemas/DeliveryConfig"},"maxDeliveries":{"type":"integer","nullable":true,"minimum":0,"exclusiveMinimum":true,"default":null},"expiresAt":{"type":"string","format":"date-time"},"scope":{"type":"string","enum":["org","global"]}},"required":["eventType","deliveryConfig"]},"WatcherItem":{"type":"object","properties":{"id":{"type":"string"},"orgId":{"type":"string"},"eventType":{"type":"string"},"matchCriteria":{"type":"object","additionalProperties":{"nullable":true}},"deliveryConfig":{"type":"object","additionalProperties":{"nullable":true}},"maxDeliveries":{"type":"number","nullable":true},"deliveryCount":{"type":"number"},"status":{"type":"string"},"createdBy":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"expiresAt":{"type":"string","nullable":true,"format":"date-time"}},"required":["id","orgId","eventType","matchCriteria","deliveryConfig","maxDeliveries","deliveryCount","status","createdBy","createdAt","expiresAt"]},"ListWatchersResponse":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/ListedWatcherItem"}}},"required":["items"]},"DeleteWatcherResponse":{"type":"object","properties":{"success":{"type":"boolean"}},"required":["success"]},"ConfigItemResponse":{"allOf":[{"$ref":"#/components/schemas/ConfigItem"},{"type":"object","properties":{"description":{"type":"string","nullable":true},"resolutionScope":{"type":"string","enum":["hardcoded","global","org"],"description":"Where the resolved value comes from: hardcoded default, global override, or org-specific override.","example":"hardcoded"}},"required":["description","resolutionScope"]}]},"ConfigItem":{"type":"object","properties":{"key":{"type":"string","minLength":1,"example":"feature_x_enabled"},"value":{"nullable":true,"example":{"enabled":true}},"description":{"type":"string"},"type":{"type":"string","enum":["boolean","string","number","json","date"]},"options":{"type":"array","items":{"type":"object","properties":{"value":{"type":"string"},"label":{"type":"string"}},"required":["value","label"]}}},"required":["key"]},"ProvisionDatabaseRequest":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":255,"description":"Database name"},"region":{"type":"string","description":"Provider region identifier"},"pg_version":{"type":"integer","minimum":0,"exclusiveMinimum":true,"description":"Postgres version"}},"required":["name"],"description":"Create database request"},"ProvisionDatabaseResponse":{"type":"object","properties":{"database":{"$ref":"#/components/schemas/Database"},"region":{"type":"string","description":"Provisioned database region"},"default_branch":{"$ref":"#/components/schemas/ProvisionedDatabaseBranch"}},"required":["database","region","default_branch"],"description":"Create database response"},"DatabaseListResponse":{"type":"object","properties":{"databases":{"type":"array","items":{"$ref":"#/components/schemas/Database"},"description":"Provisioned databases"},"total":{"type":"integer","description":"Total number of databases"}},"required":["databases","total"],"description":"List databases response"},"Database":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Database ID"},"name":{"type":"string","description":"Database name"},"provider":{"$ref":"#/components/schemas/DatabaseProvider"},"external_id":{"type":"string","description":"External provider project ID"},"status":{"$ref":"#/components/schemas/DatabaseStatus"},"created_at":{"type":"string","format":"date-time","description":"Creation timestamp"},"updated_at":{"type":"string","format":"date-time","description":"Last update timestamp"}},"required":["id","name","provider","external_id","status","created_at","updated_at"],"description":"Provisioned database metadata"},"CreateDatabaseBranchRequest":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":255,"description":"Branch name"},"parent_branch_id":{"type":"string","description":"Optional parent branch ID"}},"required":["name"],"description":"Create branch request"},"ProvisionedDatabaseBranch":{"type":"object","properties":{"external_branch_id":{"type":"string","description":"External provider branch ID"},"name":{"type":"string","description":"Branch name"},"connection_uri":{"type":"string","description":"Postgres connection URI"},"host":{"type":"string","description":"Branch host"},"database":{"type":"string","description":"Default database name"},"role":{"type":"string","description":"Default database role"},"endpoint_id":{"type":"string","description":"Provider endpoint ID"}},"required":["external_branch_id","name","connection_uri","host","database","role"],"description":"Provisioned database branch with connection details"},"DatabaseBranch":{"type":"object","properties":{"external_branch_id":{"type":"string","description":"External provider branch ID"},"name":{"type":"string","description":"Branch name"},"parent_branch_id":{"type":"string","nullable":true,"description":"Parent branch ID"},"created_at":{"type":"string","format":"date-time","description":"Branch creation timestamp"}},"required":["external_branch_id","name","parent_branch_id"],"description":"Database branch metadata"},"DatabaseConnectionInfo":{"type":"object","properties":{"connection_uri":{"type":"string","description":"Postgres connection URI"},"host":{"type":"string","description":"Database host"},"database":{"type":"string","description":"Database name"},"role":{"type":"string","description":"Database role"}},"required":["connection_uri","host","database","role"],"description":"Database connection details"},"PostgrestCredentials":{"type":"object","properties":{"authenticator_uri":{"type":"string","description":"Postgres connection URI for the PostgREST 'authenticator' role with the derived password."},"jwt_secret":{"type":"string","description":"PostgREST JWT secret for signing/validating role-switching tokens. Distinct from the authenticator password."}},"required":["authenticator_uri","jwt_secret"],"description":"Server-derived PostgREST credentials. Both values are HMAC-SHA-256 of a server-side root secret keyed by database and endpoint."},"KvStoreItem":{"type":"object","properties":{"namespace":{"type":"string","minLength":1,"example":"feature_flags"},"key":{"type":"string","minLength":1,"example":"new_ui_enabled"},"value":{"nullable":true,"example":{"enabled":true}},"createdAt":{"type":"string","example":"2025-10-11T12:00:00Z"},"updatedAt":{"type":"string","example":"2025-10-11T12:00:00Z"}},"required":["namespace","key","createdAt","updatedAt"]},"KvStoreUpsertRequest":{"type":"object","properties":{"value":{"nullable":true,"example":{"enabled":true}}}},"RetrievalIndexItem":{"type":"object","properties":{"id":{"type":"string","format":"uuid","example":"123e4567-e89b-12d3-a456-426614174000"},"orgId":{"type":"string","example":"org-123"},"namespace":{"type":"string","example":"code"},"documentId":{"type":"string","example":"wiki:/docs/insurance/rate-filing"},"uri":{"type":"string","example":"wiki://docs/insurance/rate-filing"},"variant":{"type":"string","example":"content"},"content":{"type":"string","example":"Rate filing process involves..."},"metadata":{"type":"object","additionalProperties":{"nullable":true},"example":{"source":"wiki"}},"embedding":{"type":"array","nullable":true,"items":{"type":"number"},"example":null},"embeddingModel":{"type":"string","example":"gemini-embedding-001"},"createdAt":{"type":"string","example":"2025-12-27T12:00:00Z"},"updatedAt":{"type":"string","example":"2025-12-27T12:00:00Z"},"batchId":{"type":"string","nullable":true,"format":"uuid","example":null}},"required":["id","orgId","namespace","documentId","uri","variant","content","metadata","embedding","embeddingModel","createdAt","updatedAt","batchId"]},"SearchRetrievalIndexRequest":{"type":"object","properties":{"query":{"type":"string","minLength":1},"embedding":{"type":"array","items":{"type":"number"}},"topK":{"type":"integer","minimum":1,"maximum":100,"default":10,"example":10},"namespace":{"type":"string","example":"code"},"documentIdPrefix":{"type":"string"},"uriPrefix":{"type":"string"},"variant":{"type":"string"}}},"SearchRetrievalIndexResponse":{"type":"object","properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/RetrievalIndexSearchResultItem"}},"query":{"type":"string","nullable":true,"example":"how do I file insurance rates"},"topK":{"type":"number","example":10}},"required":["results","query","topK"]},"CreateShareRequest":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":200,"description":"Title used to help generate the slug"},"html":{"type":"string","minLength":1,"description":"Complete self-contained HTML to store"},"noindex":{"type":"boolean","default":true,"description":"If true, indicates search engines should not index"},"artifactId":{"type":"string","description":"Optional artifact ID to link this share to"}},"required":["title","html"]},"CreateShareResponse":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Share ID"},"slug":{"type":"string","description":"Public share slug"},"url":{"type":"string","description":"Public URL path for the snapshot, e.g. /share/{slug}"},"path":{"type":"string","description":"Storage path of the HTML within the provider"}},"required":["id","slug","url","path"]},"FileArtifact":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the artifact"},"name":{"type":"string","description":"Display name of the artifact"},"parentId":{"type":"string","description":"Parent artifact ID"},"nodeKind":{"type":"string","enum":["file","folder"],"description":"Kind of node this artifact represents"},"isIndexed":{"type":"boolean","description":"Whether the artifact content has been indexed for search"},"indexingStatus":{"type":"string","description":"Status of the indexing workflow (pending, running, completed, failed, cancelled, unknown)"},"workflowId":{"type":"string","description":"Temporal workflow ID for the indexing job, if one exists"},"metadata":{"type":"object","additionalProperties":{"nullable":true},"description":"Additional metadata for tracking batch processes and other information"},"orgId":{"type":"string","default":"","description":"Organization ID that owns this artifact"},"createdAt":{"type":"string","format":"date-time","description":"Timestamp when the artifact was created"},"updatedAt":{"type":"string","format":"date-time","description":"Timestamp when the artifact was last updated"},"path":{"type":"string","description":"Path of the artifact"},"relativePath":{"type":"string","description":"Relative path from parent folder (used for ZIP downloads)"},"extractedTextPath":{"type":"string","description":"Path in blob storage where extracted text is stored, if available"},"stringFacet1":{"type":"string","description":"Generic indexed string facet for application-defined labels (e.g., serff_tracking_number). Meaning is defined at the application layer."},"stringFacet2":{"type":"string","description":"Generic indexed string facet for application-defined labels. Meaning is defined at the application layer."},"stringFacet3":{"type":"string","description":"Generic indexed string facet for application-defined labels. Meaning is defined at the application layer."},"createdBy":{"type":"string","description":"User ID of the artifact creator"},"sessionId":{"type":"string","description":"Session ID this artifact belongs to (set for session-scoped artifacts)"},"visibility":{"type":"string","enum":["org","private","session","public"],"description":"Artifact visibility mode: 'org' for team-wide (default), 'private' for owner-only, 'session' for session-inherited, 'public' for anyone with the link"},"visibleTo":{"type":"array","items":{"type":"string"},"description":"User IDs with explicit access to this artifact"},"type":{"type":"string","enum":["file"],"description":"Type discriminator for file artifacts"},"data":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the file"},"name":{"type":"string","description":"File name"},"size":{"type":"number","description":"File size in bytes"},"pageCount":{"type":"number","description":"Page count of the file"},"mimeType":{"type":"string","enum":["text/plain","text/markdown","text/csv","application/json","application/xml","text/xml","text/html","text/css","text/javascript","application/javascript","application/typescript","text/x-python","text/x-rsl","application/pdf","application/vnd.openxmlformats-officedocument.spreadsheetml.sheet","application/vnd.ms-excel","application/vnd.ms-excel.sheet.macroEnabled.12","application/vnd.openxmlformats-officedocument.spreadsheetml.sheet.macroEnabled.12","application/vnd.ms-excel.sheet.macroenabled.12","application/vnd.ms-excel.sheet.binary.macroEnabled.12","application/vnd.openxmlformats-officedocument.wordprocessingml.document","application/vnd.openxmlformats-officedocument.presentationml.presentation","application/vnd.ms-outlook","application/zip","application/x-tar","application/gzip","application/octet-stream","image/jpeg","image/png","image/gif","image/webp","image/svg+xml","audio/mpeg","audio/wav","audio/ogg","audio/mp4","audio/webm","video/mp4","video/webm","video/quicktime","video/x-msvideo","video/ogg"],"description":"MIME type of the file"},"lastModified":{"type":"number","description":"Last modified timestamp"},"path":{"type":"string","description":"Storage path"},"storageInfo":{"oneOf":[{"type":"object","properties":{"location":{"type":"string","enum":["gcs"]},"object":{"type":"string"},"url":{"type":"string"}},"required":["location","object"]},{"type":"object","properties":{"location":{"type":"string","enum":["filesystem"]}},"required":["location"]}],"description":"Storage location information"},"indexed":{"type":"boolean","description":"Whether the artifact content has been indexed for search"}},"required":["id","name","size","mimeType","path","storageInfo"],"description":"File metadata associated with this artifact"}},"required":["id","name","nodeKind","isIndexed","createdAt","updatedAt","type","data"],"description":"File artifact with metadata"},"FolderArtifact":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the artifact"},"name":{"type":"string","description":"Display name of the artifact"},"parentId":{"type":"string","description":"Parent artifact ID"},"nodeKind":{"type":"string","enum":["file","folder"],"description":"Kind of node this artifact represents"},"isIndexed":{"type":"boolean","description":"Whether the artifact content has been indexed for search"},"indexingStatus":{"type":"string","description":"Status of the indexing workflow (pending, running, completed, failed, cancelled, unknown)"},"workflowId":{"type":"string","description":"Temporal workflow ID for the indexing job, if one exists"},"metadata":{"type":"object","additionalProperties":{"nullable":true},"description":"Additional metadata for tracking batch processes and other information"},"orgId":{"type":"string","default":"","description":"Organization ID that owns this artifact"},"createdAt":{"type":"string","format":"date-time","description":"Timestamp when the artifact was created"},"updatedAt":{"type":"string","format":"date-time","description":"Timestamp when the artifact was last updated"},"path":{"type":"string","description":"Path of the artifact"},"relativePath":{"type":"string","description":"Relative path from parent folder (used for ZIP downloads)"},"extractedTextPath":{"type":"string","description":"Path in blob storage where extracted text is stored, if available"},"stringFacet1":{"type":"string","description":"Generic indexed string facet for application-defined labels (e.g., serff_tracking_number). Meaning is defined at the application layer."},"stringFacet2":{"type":"string","description":"Generic indexed string facet for application-defined labels. Meaning is defined at the application layer."},"stringFacet3":{"type":"string","description":"Generic indexed string facet for application-defined labels. Meaning is defined at the application layer."},"createdBy":{"type":"string","description":"User ID of the artifact creator"},"sessionId":{"type":"string","description":"Session ID this artifact belongs to (set for session-scoped artifacts)"},"visibility":{"type":"string","enum":["org","private","session","public"],"description":"Artifact visibility mode: 'org' for team-wide (default), 'private' for owner-only, 'session' for session-inherited, 'public' for anyone with the link"},"visibleTo":{"type":"array","items":{"type":"string"},"description":"User IDs with explicit access to this artifact"},"type":{"type":"string","enum":["folder"],"description":"Type discriminator for folder artifacts"},"data":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the folder"},"name":{"type":"string","description":"Folder name"}},"required":["id","name"],"description":"Folder metadata associated with this artifact"}},"required":["id","name","nodeKind","isIndexed","createdAt","updatedAt","type","data"],"description":"Folder artifact"},"ReportArtifact":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the artifact"},"name":{"type":"string","description":"Display name of the artifact"},"parentId":{"type":"string","description":"Parent artifact ID"},"nodeKind":{"type":"string","enum":["file","folder"],"description":"Kind of node this artifact represents"},"isIndexed":{"type":"boolean","description":"Whether the artifact content has been indexed for search"},"indexingStatus":{"type":"string","description":"Status of the indexing workflow (pending, running, completed, failed, cancelled, unknown)"},"workflowId":{"type":"string","description":"Temporal workflow ID for the indexing job, if one exists"},"metadata":{"type":"object","additionalProperties":{"nullable":true},"description":"Additional metadata for tracking batch processes and other information"},"orgId":{"type":"string","default":"","description":"Organization ID that owns this artifact"},"createdAt":{"type":"string","format":"date-time","description":"Timestamp when the artifact was created"},"updatedAt":{"type":"string","format":"date-time","description":"Timestamp when the artifact was last updated"},"path":{"type":"string","description":"Path of the artifact"},"relativePath":{"type":"string","description":"Relative path from parent folder (used for ZIP downloads)"},"extractedTextPath":{"type":"string","description":"Path in blob storage where extracted text is stored, if available"},"stringFacet1":{"type":"string","description":"Generic indexed string facet for application-defined labels (e.g., serff_tracking_number). Meaning is defined at the application layer."},"stringFacet2":{"type":"string","description":"Generic indexed string facet for application-defined labels. Meaning is defined at the application layer."},"stringFacet3":{"type":"string","description":"Generic indexed string facet for application-defined labels. Meaning is defined at the application layer."},"createdBy":{"type":"string","description":"User ID of the artifact creator"},"sessionId":{"type":"string","description":"Session ID this artifact belongs to (set for session-scoped artifacts)"},"visibility":{"type":"string","enum":["org","private","session","public"],"description":"Artifact visibility mode: 'org' for team-wide (default), 'private' for owner-only, 'session' for session-inherited, 'public' for anyone with the link"},"visibleTo":{"type":"array","items":{"type":"string"},"description":"User IDs with explicit access to this artifact"},"type":{"type":"string","enum":["report"],"description":"Type discriminator for report artifacts"},"data":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the file"},"name":{"type":"string","description":"File name"},"size":{"type":"number","description":"File size in bytes"},"pageCount":{"type":"number","description":"Page count of the file"},"mimeType":{"type":"string","enum":["text/plain","text/markdown","text/csv","application/json","application/xml","text/xml","text/html","text/css","text/javascript","application/javascript","application/typescript","text/x-python","text/x-rsl","application/pdf","application/vnd.openxmlformats-officedocument.spreadsheetml.sheet","application/vnd.ms-excel","application/vnd.ms-excel.sheet.macroEnabled.12","application/vnd.openxmlformats-officedocument.spreadsheetml.sheet.macroEnabled.12","application/vnd.ms-excel.sheet.macroenabled.12","application/vnd.ms-excel.sheet.binary.macroEnabled.12","application/vnd.openxmlformats-officedocument.wordprocessingml.document","application/vnd.openxmlformats-officedocument.presentationml.presentation","application/vnd.ms-outlook","application/zip","application/x-tar","application/gzip","application/octet-stream","image/jpeg","image/png","image/gif","image/webp","image/svg+xml","audio/mpeg","audio/wav","audio/ogg","audio/mp4","audio/webm","video/mp4","video/webm","video/quicktime","video/x-msvideo","video/ogg"],"description":"MIME type of the file"},"lastModified":{"type":"number","description":"Last modified timestamp"},"path":{"type":"string","description":"Storage path"},"storageInfo":{"oneOf":[{"type":"object","properties":{"location":{"type":"string","enum":["gcs"]},"object":{"type":"string"},"url":{"type":"string"}},"required":["location","object"]},{"type":"object","properties":{"location":{"type":"string","enum":["filesystem"]}},"required":["location"]}],"description":"Storage location information"},"indexed":{"type":"boolean","description":"Whether the artifact content has been indexed for search"}},"required":["id","name","size","mimeType","path","storageInfo"],"description":"File metadata for the report content"}},"required":["id","name","nodeKind","isIndexed","createdAt","updatedAt","type","data"],"description":"Report artifact associated with Mission Control"},"PushVapidKeyResponse":{"type":"object","properties":{"vapidPublicKey":{"type":"string","nullable":true,"description":"Application server public key (URL-safe base64). Null when not configured."}},"required":["vapidPublicKey"]},"PushSubscribeBody":{"type":"object","properties":{"endpoint":{"type":"string","maxLength":2000,"format":"uri"},"keys":{"type":"object","properties":{"p256dh":{"type":"string","minLength":1,"maxLength":256},"auth":{"type":"string","minLength":1,"maxLength":64}},"required":["p256dh","auth"]},"expirationTime":{"type":"integer","nullable":true,"minimum":0,"exclusiveMinimum":true},"userAgent":{"type":"string","maxLength":500},"deviceLabel":{"type":"string","maxLength":100}},"required":["endpoint","keys"]},"PushSubscribeResponse":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"endpoint":{"type":"string"},"expirationTime":{"type":"string","nullable":true},"userAgent":{"type":"string","nullable":true},"deviceLabel":{"type":"string","nullable":true},"createdAt":{"type":"string"},"lastSeenAt":{"type":"string"}},"required":["id","endpoint","expirationTime","userAgent","deviceLabel","createdAt","lastSeenAt"]},"PushSubscriptionListResponse":{"type":"object","properties":{"subscriptions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"endpoint":{"type":"string"},"expirationTime":{"type":"string","nullable":true},"userAgent":{"type":"string","nullable":true},"deviceLabel":{"type":"string","nullable":true},"createdAt":{"type":"string"},"lastSeenAt":{"type":"string"}},"required":["id","endpoint","expirationTime","userAgent","deviceLabel","createdAt","lastSeenAt"]}}},"required":["subscriptions"]},"PushPauseBody":{"type":"object","properties":{"endpoint":{"type":"string","maxLength":2000,"format":"uri","description":"The push endpoint URL to deactivate. Obtained from the browser PushSubscription."}},"required":["endpoint"]},"NetworkInjectionRoute":{"type":"object","properties":{"protocol":{"type":"string","enum":["https"],"default":"https"},"host":{"type":"string","minLength":1,"maxLength":253},"port":{"type":"integer","minimum":1,"maximum":65535,"default":443},"authHeaderName":{"type":"string","nullable":true,"minLength":1,"maxLength":128,"pattern":"^[!#$%&'*+\\-.^_`|~0-9A-Za-z]+$","default":null},"authScheme":{"type":"string","nullable":true,"minLength":1,"maxLength":128,"pattern":"^[!#$%&'*+\\-.^_`|~0-9A-Za-z]+$","default":null},"authValueTemplate":{"type":"string","nullable":true,"minLength":1,"maxLength":256,"default":null}},"required":["host"]},"StaticIp":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["provisioning","active","deprovisioning"]},"ipAddress":{"type":"string","nullable":true},"label":{"type":"string","nullable":true},"apps":{"type":"array","items":{"type":"string"}},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","status","ipAddress","label","apps","createdAt","updatedAt"]},"StaticIpRoute":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"staticIpId":{"type":"string","format":"uuid"},"appId":{"type":"string","nullable":true},"routeType":{"type":"string","enum":["https_host","tcp_cidr"]},"hostPattern":{"type":"string","nullable":true},"cidr":{"type":"string","nullable":true},"portMin":{"type":"integer"},"portMax":{"type":"integer"},"enabled":{"type":"boolean"},"label":{"type":"string","nullable":true},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","staticIpId","appId","routeType","hostPattern","cidr","portMin","portMax","enabled","label","createdAt","updatedAt"]},"StaticIpRouteCreate":{"type":"object","properties":{"appId":{"type":"string","nullable":true,"minLength":1,"description":"null/omitted = applies to every app assigned to this static IP"},"routeType":{"type":"string","enum":["https_host","tcp_cidr"]},"hostPattern":{"type":"string","nullable":true,"description":"Required when routeType=https_host. Exact host or single leading-wildcard."},"cidr":{"type":"string","nullable":true,"description":"Required when routeType=tcp_cidr. Public-unicast IPv4 CIDR."},"portMin":{"type":"integer","minimum":1,"maximum":65535},"portMax":{"type":"integer","minimum":1,"maximum":65535},"enabled":{"type":"boolean"},"label":{"type":"string","nullable":true,"maxLength":200}},"required":["routeType"]},"OAuthProviderConfigListResponse":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/OAuthProviderConfigPublic"}}},"required":["items"]},"OAuthProviderConfigPublic":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"orgId":{"type":"string"},"provider":{"type":"string"},"credentialSource":{"type":"string","enum":["env","per_org"],"description":"How credentials are sourced: 'env' = platform app, 'per_org' = org's own app"},"tenantId":{"type":"string","nullable":true},"clientId":{"type":"string"},"clientSecretExpiresAt":{"type":"string","nullable":true},"scopes":{"type":"array","nullable":true,"items":{"type":"string"}},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","orgId","provider","credentialSource","tenantId","clientId","clientSecretExpiresAt","scopes","createdAt","updatedAt"],"description":"Per-org OAuth provider configuration (without client secret)"},"OAuthProviderConfigUpsertRequest":{"type":"object","properties":{"credentialSource":{"type":"string","enum":["env","per_org"],"description":"Explicit credential source. 'env' = use platform app (credentials must be omitted). 'per_org' = bring your own app (clientId + clientSecret required). When omitted, inferred from whether clientId is present."},"tenantId":{"type":"string","minLength":1,"description":"IdP tenant identifier (required for per-org providers)"},"clientId":{"type":"string","minLength":1,"description":"OAuth client ID. Required when credentialSource is 'per_org'."},"clientSecret":{"type":"string","minLength":1,"description":"Client secret value; encrypted at rest. Required when credentialSource is 'per_org'."},"clientSecretExpiresAt":{"type":"string","nullable":true,"format":"date-time","description":"ISO 8601 expiry; used by rotation reminders"},"scopes":{"type":"array","nullable":true,"items":{"type":"string"},"description":"Scopes to request during OAuth. Null/omitted = use the registry default for the provider."}}},"OAuthProviderConfigPatchRequest":{"type":"object","properties":{"tenantId":{"type":"string","minLength":1,"description":"IdP tenant identifier"},"clientSecretExpiresAt":{"type":"string","nullable":true,"format":"date-time","description":"ISO 8601 expiry; used by rotation reminders"},"scopes":{"type":"array","nullable":true,"items":{"type":"string"},"description":"Full replacement of the scopes array. Send the complete list of scopes you want — this is not additive. Null = revert to the registry default for the provider."}}},"AdminOrgProfileResponse":{"type":"object","properties":{"orgId":{"type":"string"},"profile":{"$ref":"#/components/schemas/AdminOrgProfileFields"}},"required":["orgId","profile"],"description":"Organization profile"},"AdminOrgProfilePatch":{"type":"object","properties":{"overview":{"type":"string","nullable":true,"maxLength":2000},"communication":{"type":"string","nullable":true,"maxLength":1000},"stage":{"type":"string","nullable":true,"maxLength":200}},"description":"Partial organization profile update"},"CreateContextBaseDraftBody":{"type":"object","properties":{"mode":{"$ref":"#/components/schemas/CreateContextBaseDraftMode"},"orgRepoId":{"type":"string","minLength":1},"productName":{"type":"string","maxLength":256},"productId":{"type":"string","minLength":1},"missionControlId":{"type":"string","minLength":1},"actionLogChangeSetId":{"type":"string","minLength":1,"maxLength":256},"actionLogProductId":{"type":"string","minLength":1,"maxLength":256},"productSourcePath":{"type":"string","minLength":1},"workflowPath":{"type":"string","minLength":1,"maxLength":1024},"workflowTitle":{"type":"string","minLength":1,"maxLength":120},"workflowDescription":{"type":"string","minLength":1,"maxLength":500},"workflowRunId":{"type":"string","format":"uuid"},"projectPhaseKey":{"type":"string","minLength":1,"maxLength":128},"newWorkflowId":{"type":"string","minLength":3,"maxLength":128,"pattern":"^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$"}}},"CreateContextBaseDraftResponse":{"type":"object","properties":{"draftId":{"type":"string","format":"uuid"},"sessionConfig":{"$ref":"#/components/schemas/ContextBaseDraftSessionConfig"}},"required":["draftId","sessionConfig"]},"ListContextBaseDraftsResponse":{"type":"object","properties":{"drafts":{"type":"array","items":{"$ref":"#/components/schemas/ContextBaseDraft"}}},"required":["drafts"]},"ContextBaseSessionDraftState":{"oneOf":[{"type":"object","properties":{"kind":{"type":"string","enum":["none"]},"sessionId":{"type":"string"}},"required":["kind","sessionId"]},{"type":"object","properties":{"kind":{"type":"string","enum":["active"]},"sessionId":{"type":"string"},"draftId":{"type":"string","format":"uuid"},"orgRepoId":{"type":"string"},"missionControlId":{"type":"string","nullable":true},"workspaceState":{"type":"string","enum":["provisioning","ready","failed"]}},"required":["kind","sessionId","draftId","orgRepoId","missionControlId","workspaceState"]},{"type":"object","properties":{"kind":{"type":"string","enum":["terminal"]},"sessionId":{"type":"string"},"draftId":{"type":"string","format":"uuid"},"missionControlId":{"type":"string","nullable":true},"reason":{"type":"string","enum":["published","closed","replaced"]}},"required":["kind","sessionId","draftId","missionControlId","reason"]}]},"ContextBaseDraft":{"type":"object","properties":{"draftId":{"type":"string","format":"uuid"},"sessionId":{"type":"string","nullable":true},"contextBaseRepoId":{"type":"string"},"contextBaseOrgId":{"type":"string"},"contextBaseRepoName":{"type":"string"},"missionControlId":{"type":"string","nullable":true},"actionLogChangeSetId":{"type":"string","nullable":true},"actionLogProductId":{"type":"string","nullable":true},"title":{"type":"string"},"body":{"type":"string","maxLength":65536},"baseCommitSha":{"type":"string"},"workspaceDir":{"type":"string"},"startedAt":{"type":"string","format":"date-time"},"setupStatus":{"type":"string","nullable":true,"enum":["pending","running","completed","failed",null]},"ready":{"type":"boolean"},"isClean":{"type":"boolean"},"pendingChangeCount":{"type":"integer"},"authorUserId":{"type":"string"},"authorPreview":{"type":"object","properties":{"id":{"type":"string"},"displayName":{"type":"string"}},"required":["id","displayName"]},"taskId":{"type":"string","nullable":true,"format":"uuid"},"lifecycleStatus":{"$ref":"#/components/schemas/ContextBaseDraftLifecycleStatus"},"publishedAt":{"type":"string","format":"date-time"},"publishedDiffBaseCommitSha":{"type":"string"},"publishedCommitSha":{"type":"string"},"publishedChanges":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"op":{"type":"string","enum":["put","delete"]}},"required":["path","op"]}},"governance":{"$ref":"#/components/schemas/GovernanceProjection"},"preflightPassedAt":{"type":"string","nullable":true,"format":"date-time"},"draftMode":{"$ref":"#/components/schemas/CreateContextBaseDraftMode"},"newWorkflowId":{"type":"string","nullable":true}},"required":["draftId","sessionId","contextBaseRepoId","contextBaseOrgId","contextBaseRepoName","missionControlId","actionLogChangeSetId","actionLogProductId","baseCommitSha","workspaceDir","startedAt","ready","isClean","pendingChangeCount","taskId","lifecycleStatus"]},"AttachSessionToDraftBody":{"type":"object","properties":{"sessionId":{"type":"string","minLength":1,"maxLength":128}},"required":["sessionId"]},"Closed":{"type":"object","properties":{"closed":{"type":"boolean","enum":[true]}},"required":["closed"]},"ContextBaseDraftSessionConfig":{"type":"object","properties":{"tags":{"type":"array","items":{"type":"string"}},"presetRef":{"type":"object","properties":{"agentName":{"type":"string","minLength":1}},"required":["agentName"]},"toolConfig":{"type":"object","properties":{"enabled":{"type":"array","items":{"type":"string"}}},"required":["enabled"]},"resources":{"type":"object","properties":{"sandbox":{"type":"object","properties":{"provider":{"type":"string","enum":["e2b","agent-sandbox"],"description":"Sandbox provider for creating a new sandbox. Agent-sandbox uses the server-owned session pod executor path."},"templateId":{"type":"string","description":"Provider-specific template reference for creating a new sandbox"},"fromSession":{"type":"string","description":"Session ID to share sandbox from. Must match parentSessionId."},"useSelfHostedE2b":{"type":"boolean","description":"When true, the session sandbox targets the self-hosted E2B instance instead of the cloud. Defaults to the global config value."}},"description":"Sandbox configuration. Omit for own sandbox with default template."},"project":{"type":"object","properties":{"name":{"type":"string","description":"Project name or ID to link this session to"}},"required":["name"],"description":"Explicit project config. Omit to inherit from parent session."}},"description":"Resource configuration for the session"},"background":{"nullable":true}},"required":["tags","toolConfig"]},"ContextBaseDraftStatusResponse":{"type":"object","properties":{"sessionId":{"type":"string","nullable":true},"baseCommitSha":{"type":"string"},"modified":{"type":"array","items":{"type":"string"}},"added":{"type":"array","items":{"type":"string"}},"deleted":{"type":"array","items":{"type":"string"}},"renamed":{"type":"array","items":{"type":"object","properties":{"oldPath":{"type":"string"},"newPath":{"type":"string"}},"required":["oldPath","newPath"]},"default":[]},"untracked":{"type":"array","items":{"type":"string"}},"isClean":{"type":"boolean"},"workspaceState":{"type":"string","enum":["ready","provisioning","failed"]},"message":{"type":"string"},"fileStats":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"additions":{"type":"integer","minimum":0},"deletions":{"type":"integer","minimum":0}},"required":["path","additions","deletions"]}}},"required":["sessionId","baseCommitSha","modified","added","deleted","untracked","isClean"]},"ContextBaseDraftDiffResponse":{"type":"object","properties":{"path":{"type":"string"},"diff":{"type":"string"},"isBinary":{"type":"boolean"}},"required":["path","diff","isBinary"]},"ContextBaseDraftFileReadResponse":{"type":"object","properties":{"path":{"type":"string"},"content":{"type":"string"},"encoding":{"type":"string","enum":["utf8","base64"]},"sizeBytes":{"type":"integer","minimum":0}},"required":["path","content","encoding","sizeBytes"]},"WriteContextBaseDraftFileBody":{"type":"object","properties":{"path":{"type":"string","minLength":1,"maxLength":1024},"content":{"type":"string"},"encoding":{"type":"string","enum":["utf8","base64"],"default":"utf8"}},"required":["path","content"]},"StatusOk":{"type":"object","properties":{"status":{"type":"string","enum":["ok"]}},"required":["status"]},"DeleteContextBaseDraftFileBody":{"type":"object","properties":{"path":{"type":"string","minLength":1,"maxLength":1024}},"required":["path"]},"DiscardContextBaseDraftBody":{"type":"object","properties":{"all":{"type":"boolean"},"paths":{"type":"array","items":{"type":"string","minLength":1,"maxLength":1024},"maxItems":500}}},"ContextBaseDraftCanPublishResponse":{"type":"object","properties":{"draftId":{"type":"string","format":"uuid"},"canPublish":{"type":"boolean"},"blockingReasons":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"nullable":true}},"required":["code","message"]}},"baseCommitSha":{"type":"string"},"currentHeadCommitSha":{"type":"string","nullable":true},"status":{"$ref":"#/components/schemas/ContextBaseDraftStatusResponse"},"hasDataChanges":{"type":"boolean"},"pushedChanges":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"op":{"type":"string","enum":["put","delete"]}},"required":["path","op"]}},"governance":{"$ref":"#/components/schemas/GovernanceProjection"},"actionLogPreflight":{"nullable":true}},"required":["draftId","canPublish","blockingReasons"]},"PublishContextBaseDraftBody":{"type":"object","properties":{"message":{"type":"string","minLength":1,"maxLength":4096,"description":"Commit message — required, user-entered"}},"required":["message"]},"ContextBaseDraftPublishResponse":{"type":"object","properties":{"commitSha":{"type":"string"},"parentCommitSha":{"type":"string","nullable":true},"taskId":{"type":"string","format":"uuid"},"taskSubmissionId":{"type":"string","format":"uuid"},"applied":{"type":"object","properties":{"puts":{"type":"integer","minimum":0},"deletes":{"type":"integer","minimum":0}},"required":["puts","deletes"]},"pushedChanges":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"op":{"type":"string","enum":["put","delete"]}},"required":["path","op"]}},"dataChangeSet":{"type":"object","properties":{"status":{"type":"string"},"changeSetId":{"type":"string"},"commitId":{"type":"string"},"revision":{"type":"integer"},"streamId":{"type":"string"},"alreadyPublished":{"type":"boolean"}},"required":["status","changeSetId"]}},"required":["commitSha","parentCommitSha","applied","pushedChanges"]},"ContextBaseDraftMissingApprovals":{"type":"object","properties":{"error":{"type":"string","enum":["Approvals required"]},"missingRules":{"type":"array","items":{"type":"object","properties":{"glob":{"type":"string"},"reviewers":{"type":"array","items":{"type":"string"}},"required":{"type":"integer","minimum":0,"exclusiveMinimum":true},"satisfied":{"type":"integer","minimum":0}},"required":["glob","reviewers","required","satisfied"]}}},"required":["error","missingRules"]},"ContextBaseDraftRebaseResponse":{"type":"object","properties":{"sessionId":{"type":"string","nullable":true},"rebaseId":{"type":"string"},"oldBaseCommitSha":{"type":"string"},"newBaseCommitSha":{"type":"string"},"status":{"type":"string","enum":["reapplied","conflicts"]},"reappliedPaths":{"type":"array","items":{"type":"string"}},"conflictPaths":{"type":"array","items":{"type":"string"}},"conflictBundlePath":{"type":"string","nullable":true},"stashPath":{"type":"string"}},"required":["sessionId","rebaseId","oldBaseCommitSha","newBaseCommitSha","status","reappliedPaths","conflictPaths","conflictBundlePath","stashPath"]},"GovernanceProjection":{"type":"object","properties":{"governancePresent":{"type":"boolean"},"parseError":{"type":"string"},"rules":{"type":"array","items":{"type":"object","properties":{"glob":{"type":"string"},"description":{"type":"string"},"reviewers":{"type":"array","items":{"type":"object","properties":{"handle":{"type":"string"},"userId":{"type":"string"},"displayName":{"type":"string"},"email":{"type":"string"}},"required":["handle","userId"]}},"required":{"type":"integer","minimum":0,"exclusiveMinimum":true},"matchedPaths":{"type":"array","items":{"type":"string"}},"satisfiedBy":{"type":"array","items":{"type":"string"}},"blockedBy":{"type":"array","items":{"type":"string"}},"satisfied":{"type":"boolean"},"unsatisfiable":{"type":"boolean"}},"required":["glob","reviewers","required","matchedPaths","satisfiedBy","blockedBy","satisfied"]}},"unmatchedPaths":{"type":"array","items":{"type":"string"}},"unresolvedHandles":{"type":"array","items":{"type":"string"}},"canPublish":{"type":"boolean"},"canPublishViaOverride":{"type":"boolean"},"hasChangesRequested":{"type":"boolean"},"decisions":{"type":"array","items":{"type":"object","properties":{"reviewerUserId":{"type":"string"},"decision":{"type":"string","enum":["approved","changes_requested"]},"decidedAt":{"type":"string","format":"date-time"},"requirementSetId":{"type":"string"},"comment":{"type":"string"},"reason":{"type":"string"}},"required":["reviewerUserId","decision","decidedAt"]}}},"required":["governancePresent","rules","unmatchedPaths","unresolvedHandles","canPublish","canPublishViaOverride","hasChangesRequested","decisions"]},"ContextBaseDraftActionLogChangeSet":{"type":"object","properties":{"changeSet":{"type":"object","additionalProperties":{"nullable":true}},"actions":{"type":"array","items":{"type":"object","additionalProperties":{"nullable":true}}},"commits":{"type":"array","items":{"type":"object","additionalProperties":{"nullable":true}}},"effects":{"type":"array","items":{"type":"object","additionalProperties":{"nullable":true}}}},"required":["changeSet","actions","commits","effects"]},"ApproveContextBaseDraftBody":{"type":"object","properties":{"comment":{"type":"string","maxLength":2000}}},"RequestChangesContextBaseDraftBody":{"type":"object","properties":{"reason":{"type":"string","minLength":1,"maxLength":2000,"description":"Required: why the changes are being rejected"}},"required":["reason"]},"AdminOverridePublishContextBaseDraftBody":{"type":"object","properties":{"message":{"type":"string","minLength":1,"maxLength":4096,"description":"Commit message — required"},"reason":{"type":"string","minLength":1,"maxLength":2000,"description":"Required justification for the override; recorded on the submission artifact"}},"required":["message","reason"]},"UserProfileIdentity":{"type":"object","properties":{"id":{"type":"integer","description":"User ID"},"email":{"type":"string","description":"User email address"},"name":{"type":"string","nullable":true,"description":"User display name"}},"required":["id","email","name"],"description":"Authenticated user identity"},"UserProfileFields":{"type":"object","properties":{"role":{"type":"string","nullable":true,"description":"Job role"},"team":{"type":"string","nullable":true,"description":"Team or department"},"communication":{"type":"string","nullable":true,"description":"Response formatting preferences"},"instructions":{"type":"string","nullable":true,"description":"Standing instructions for agents"}},"required":["role","team","communication","instructions"],"description":"Agent-facing user profile fields"},"NotificationPrefs":{"type":"object","properties":{"mutedEventTypes":{"$ref":"#/components/schemas/MutedEventTypes"},"globalSnooze":{"$ref":"#/components/schemas/GlobalSnooze"},"agentLoopCompletion":{"$ref":"#/components/schemas/AgentLoopCompletionPrefs"},"mutedSessions":{"type":"array","items":{"$ref":"#/components/schemas/MutedSession"},"maxItems":500,"default":[]}},"default":{}},"AgentSyncMetadata":{"type":"object","properties":{"title":{"type":"string","maxLength":500,"description":"Human-readable session title"},"cwd":{"type":"string","description":"Working directory of the Claude session"},"project":{"type":"string","description":"Project name/path for the session"},"client":{"type":"string","maxLength":100,"description":"Client identifier (e.g. claude-code version)"},"startedAt":{"type":"string","format":"date-time","description":"When the session started (ISO 8601)"}},"description":"Optional Claude Code session metadata"},"AgentCatalogInfo":{"type":"object","properties":{"id":{"type":"string"},"summary":{"type":"string","nullable":true}},"required":["id"]},"PresetRef":{"type":"object","nullable":true,"properties":{"agentName":{"type":"string","description":"Resolve an agent preset by presetName from the sandbox agent registry"},"appId":{"type":"string","description":"Resolve an app preset by app ID from the sandbox app registry"}},"description":"Server-side reference to a preset (agent or app)"},"ResourceRef":{"oneOf":[{"$ref":"#/components/schemas/EntityResourceRef"},{"$ref":"#/components/schemas/ArtifactResourceRef"},{"$ref":"#/components/schemas/EntityViewResourceRef"},{"$ref":"#/components/schemas/SessionResourceRef"}],"discriminator":{"propertyName":"type","mapping":{"entity":"#/components/schemas/EntityResourceRef","artifact":"#/components/schemas/ArtifactResourceRef","entity_view":"#/components/schemas/EntityViewResourceRef","session":"#/components/schemas/SessionResourceRef"}},"description":"Typed pointer to an annotatable resource"},"ResourceSummary":{"type":"object","properties":{"openThreads":{"type":"integer"},"totalThreads":{"type":"integer"},"bookmarked":{"type":"boolean"}},"required":["openThreads","totalThreads","bookmarked"]},"ResourceAnchor":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["whole_resource"]}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","enum":["field"]},"path":{"type":"string","minLength":1}},"required":["type","path"]}],"description":"Structural location within a resource"},"AiOverview":{"type":"object","nullable":true,"properties":{"id":{"type":"string","format":"uuid"},"target_kind":{"$ref":"#/components/schemas/AiOverviewTargetKind"},"target_id":{"type":"string"},"content":{"type":"string"},"model":{"type":"string"},"source_digest":{"type":"string"},"metadata":{"type":"object","additionalProperties":{"nullable":true}},"created_by":{"type":"string","nullable":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","target_kind","target_id","content","model","source_digest","metadata","created_by","created_at","updated_at"],"description":"Persisted AI-generated overview for a target"},"WorkflowRunEngineEvent":{"type":"object","properties":{"eventId":{"type":"string"},"eventType":{"type":"string"},"type":{"type":"string"},"correlationId":{"type":"string"},"runId":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"timestamp":{"type":"string","format":"date-time"},"eventData":{"nullable":true}},"required":["eventId"],"additionalProperties":{"nullable":true}},"WorkflowRunTask":{"type":"object","properties":{"wait":{"$ref":"#/components/schemas/WorkflowWait"},"task":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"project_id":{"type":"string","nullable":true,"format":"uuid"},"title":{"type":"string","nullable":true},"body":{"type":"string","nullable":true},"status":{"type":"string","enum":["open","blocked","completed","closed"]},"payload":{"type":"object","additionalProperties":{"nullable":true}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","project_id","title","body","status","payload","created_at","updated_at"]},"assignments":{"type":"array","items":{"$ref":"#/components/schemas/WorkflowRunTaskAssignment"}},"can_submit":{"type":"boolean"}},"required":["wait","task","assignments","can_submit"]},"WorkflowWait":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"task_id":{"type":"string","format":"uuid"},"workflow_run_id":{"type":"string","nullable":true,"format":"uuid"},"engine_run_id":{"type":"string"},"status":{"type":"string","enum":["waiting","satisfied","cancelled","expired"]},"expected_actions":{"type":"array","items":{"type":"string"}},"satisfied_by_submission_id":{"type":"string","nullable":true,"format":"uuid"},"created_at":{"type":"string","format":"date-time"},"resolved_at":{"type":"string","nullable":true,"format":"date-time"}},"required":["id","task_id","workflow_run_id","engine_run_id","status","expected_actions","satisfied_by_submission_id","created_at","resolved_at"]},"IncomingWebhook":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"pathSlug":{"type":"string"},"ownerType":{"type":"string","enum":["app","session"]},"ownerId":{"type":"string"},"eventWatcherId":{"type":"string","nullable":true,"format":"uuid"},"createdBy":{"type":"string","nullable":true},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"lastUsedAt":{"type":"string","nullable":true},"revokedAt":{"type":"string","nullable":true}},"required":["id","name","pathSlug","ownerType","ownerId","eventWatcherId","createdBy","createdAt","updatedAt","lastUsedAt","revokedAt"]},"AppLogEntry":{"type":"object","properties":{"timestamp":{"type":"string"},"level":{"type":"string"},"source":{"type":"string"},"message":{"type":"string"},"data":{"type":"object","nullable":true,"additionalProperties":{"nullable":true}}},"required":["timestamp","level","source","message","data"]},"FlattenedArtifact":{"oneOf":[{"$ref":"#/components/schemas/FlattenedFileArtifact"},{"$ref":"#/components/schemas/FlattenedFolderArtifact"}],"discriminator":{"propertyName":"type","mapping":{"file":"#/components/schemas/FlattenedFileArtifact","folder":"#/components/schemas/FlattenedFolderArtifact"}},"description":"Artifact with path and depth info"},"SearchResult":{"type":"object","properties":{"artifactId":{"type":"string"},"artifactName":{"type":"string"},"artifactType":{"type":"string"},"score":{"type":"number"},"chunkIndex":{"type":"number"},"totalChunks":{"type":"number"}},"required":["artifactId","artifactName","artifactType","score","chunkIndex","totalChunks"]},"ContextBaseSearchResult":{"type":"object","properties":{"id":{"type":"string"},"context_base_repo_id":{"type":"string","format":"uuid"},"context_base_alias":{"type":"string","nullable":true},"source_schema":{"type":"string"},"source_table":{"type":"string"},"source_pk":{"type":"object","additionalProperties":{"nullable":true}},"kind":{"type":"string"},"title":{"type":"string"},"subtitle":{"type":"string","nullable":true},"snippet":{"type":"string"},"facets":{"type":"object","additionalProperties":{"nullable":true}},"fields":{"type":"object","additionalProperties":{"nullable":true}},"href":{"type":"string","nullable":true},"rank":{"type":"number"},"updated_at":{"type":"string"}},"required":["id","context_base_repo_id","context_base_alias","source_schema","source_table","source_pk","kind","title","subtitle","snippet","facets","fields","href","rank","updated_at"]},"ContextBaseSearchFacetSchemaField":{"type":"object","properties":{"name":{"type":"string"},"label":{"type":"string"},"type":{"type":"string","enum":["string","number","boolean","date"]},"appliesTo":{"type":"array","items":{"type":"string"}},"multiValue":{"type":"boolean"},"description":{"type":"string","nullable":true},"source":{"type":"string","enum":["platform","search_enrichment"]},"allowedValues":{"type":"array","nullable":true,"items":{"nullable":true}}},"required":["name","label","type","appliesTo"]},"ContextBaseSearchDocumentProjection":{"type":"object","properties":{"id":{"type":"string","minLength":1},"kind":{"type":"string","minLength":1},"title":{"type":"string","minLength":1},"subtitle":{"type":"string","nullable":true},"body":{"type":"string","default":""},"facets":{"type":"object","additionalProperties":{"nullable":true},"default":{}},"fields":{"type":"object","additionalProperties":{"nullable":true},"default":{}},"target":{"type":"object","nullable":true,"properties":{"entityId":{"type":"string"},"href":{"type":"string","nullable":true}}},"source":{"type":"object","nullable":true,"properties":{"schema":{"type":"string"},"table":{"type":"string"},"pk":{"type":"object","additionalProperties":{"nullable":true}}}},"embedding":{"type":"array","items":{"type":"number"}},"embeddingModel":{"type":"string"},"skipEmbedding":{"type":"boolean"},"updatedAt":{"type":"string","nullable":true},"visibility":{"type":"string","enum":["public","private"],"default":"public"},"accessTags":{"type":"array","items":{"type":"string"},"default":[]}},"required":["id","kind","title"]},"WorkflowCatalogEntry":{"type":"object","properties":{"id":{"type":"string","example":"hello"},"name":{"type":"string","example":"Hello"},"description":{"type":"string","default":""},"inputSchema":{"type":"object","additionalProperties":{"nullable":true},"description":"JSON Schema for the workflow input."},"outputSchema":{"type":"object","additionalProperties":{"nullable":true},"description":"JSON Schema for the workflow output."},"graph":{"type":"object","properties":{"nodes":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"label":{"type":"string"},"data":{"type":"object","additionalProperties":{"nullable":true}},"metadata":{"type":"object","additionalProperties":{"nullable":true}}},"required":["id"]}},"edges":{"type":"array","items":{"type":"object","properties":{"source":{"type":"string"},"target":{"type":"string"},"type":{"type":"string"},"label":{"type":"string"},"data":{"type":"object","additionalProperties":{"nullable":true}},"metadata":{"type":"object","additionalProperties":{"nullable":true}}},"required":["source","target"]}}},"required":["nodes","edges"],"description":"Build manifest graph (from StandaloneBuilder). Present for executable workflows."},"project":{"oneOf":[{"type":"object","properties":{"mode":{"type":"string","enum":["none"]}},"required":["mode"]},{"type":"object","properties":{"mode":{"type":"string","enum":["optional","required"]},"type":{"type":"string","minLength":1},"title":{"anyOf":[{"type":"string"},{"type":"object","properties":{"kind":{"type":"string","enum":["literal"]},"value":{"type":"string"}},"required":["kind","value"]},{"type":"object","properties":{"kind":{"type":"string","enum":["template"]},"template":{"type":"string"}},"required":["kind","template"]}]},"body":{"anyOf":[{"type":"string"},{"type":"object","properties":{"kind":{"type":"string","enum":["literal"]},"value":{"type":"string"}},"required":["kind","value"]},{"type":"object","properties":{"kind":{"type":"string","enum":["template"]},"template":{"type":"string"}},"required":["kind","template"]}]},"phases":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string","minLength":1},"title":{"type":"string","minLength":1},"order":{"type":"integer"},"description":{"type":"string"},"status":{"type":"string","enum":["not_started","active","blocked","completed","skipped"]},"metadata":{"type":"object","additionalProperties":{"nullable":true}},"activities":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string","minLength":1},"step":{"type":"string","minLength":1},"label":{"type":"string","minLength":1},"description":{"type":"string"},"required":{"type":"boolean"}},"required":["key","step","label"]}}},"required":["key","title","order"]}},"currentPhaseKey":{"type":"string"},"metadata":{"type":"object","additionalProperties":{"nullable":true}}},"required":["mode","type"]}],"description":"Optional project template. The API server creates concrete project/phase rows from this when starting project-backed runs."},"schedule":{"$ref":"#/components/schemas/WorkflowSchedule"},"sops":{"type":"array","items":{"$ref":"#/components/schemas/WorkflowSopRef"},"description":"SOP documents implemented by this workflow."},"missionControlIds":{"type":"array","items":{"type":"string"},"description":"Mission control slugs/ids this workflow is assigned to. When absent, the workflow is visible to all mission controls."}},"required":["id","name","inputSchema","outputSchema"]},"WorkflowGraph":{"type":"object","properties":{"nodes":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"label":{"type":"string"},"data":{"type":"object","additionalProperties":{"nullable":true}},"metadata":{"type":"object","additionalProperties":{"nullable":true}}},"required":["id"]}},"edges":{"type":"array","items":{"type":"object","properties":{"source":{"type":"string"},"target":{"type":"string"},"type":{"type":"string"},"label":{"type":"string"},"data":{"type":"object","additionalProperties":{"nullable":true}},"metadata":{"type":"object","additionalProperties":{"nullable":true}}},"required":["source","target"]}}},"required":["nodes","edges"]},"WorkflowDraftRunStatus":{"type":"string","enum":["pending","running","waiting","completed","failed","cancelled"]},"WorkflowDraftRunStep":{"type":"object","properties":{"stepId":{"type":"string"},"stepName":{"type":"string"},"displayName":{"type":"string"},"status":{"type":"string"},"input":{"nullable":true},"output":{"nullable":true},"error":{"nullable":true},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"completedAt":{"type":"string"}},"additionalProperties":{"nullable":true}},"WorkflowDraftRunEvent":{"type":"object","properties":{"eventId":{"type":"string"},"eventType":{"type":"string"},"type":{"type":"string"},"runId":{"type":"string"},"createdAt":{"type":"string"},"timestamp":{"type":"string"},"eventData":{"nullable":true}},"additionalProperties":{"nullable":true}},"WorkflowDraftRunHook":{"type":"object","properties":{"token":{"type":"string"},"hookId":{"type":"string"},"name":{"type":"string"},"status":{"type":"string"},"payload":{"nullable":true},"createdAt":{"type":"string"}},"additionalProperties":{"nullable":true}},"CodexRuntimeRequest":{"type":"object","properties":{"kind":{"type":"string","enum":["sandbox","remote","local"],"description":"Runtime kind. Defaults to sandbox."},"runtimeId":{"type":"string","description":"Runtime identifier, e.g. sandbox ID."},"endpoint":{"type":"string","description":"Codex app-server WebSocket or HTTP endpoint."},"transport":{"type":"string","enum":["stdio","websocket"],"description":"Transport. Only websocket is supported."}}},"SessionBackgroundItem":{"type":"object","properties":{"kind":{"type":"string","minLength":1,"maxLength":80,"description":"Machine-readable category for this background item."},"label":{"type":"string","minLength":1,"maxLength":120,"description":"Human-readable label for this item."},"value":{"type":"string","minLength":1,"maxLength":4000,"description":"Background value rendered for the agent."}},"required":["label","value"],"description":"One session background fact or reference"},"HierarchicalSessionItem":{"type":"object","properties":{"sessionId":{"$ref":"#/components/schemas/SessionId"},"createdBy":{"type":"string"},"orgId":{"type":"string"},"state":{"$ref":"#/components/schemas/ChatSessionState"},"createdAt":{"type":"string"},"lastActivityAt":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"pinned":{"type":"boolean","default":false},"sessionType":{"type":"string","enum":["default","subagent"],"default":"default","description":"Session type: default for customer-visible sessions, subagent for internal sessions"},"visibility":{"type":"string","enum":["org","restricted"],"default":"org","description":"Session visibility mode: 'org' for shared with team (everyone), 'restricted' for private (specific people)"},"visibleTo":{"type":"array","items":{"type":"string"},"default":[]},"participants":{"type":"array","items":{"type":"string"},"default":[]},"participantPreviews":{"type":"array","items":{"$ref":"#/components/schemas/ParticipantPreview"}},"context":{"type":"object","properties":{"todos":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1},"content":{"type":"string"},"status":{"type":"string","enum":["pending","in_progress","completed","cancelled"]}},"required":["id","content","status"]}},"sandboxes":{"type":"array","items":{"type":"object","properties":{"sandboxId":{"type":"string","description":"The E2B sandbox ID"},"createdAt":{"type":"string","description":"ISO timestamp when the sandbox was created"},"templateAlias":{"type":"string","description":"The template alias used to create the sandbox (e.g., effectiveai-sandbox-3-dev)"}},"required":["sandboxId","createdAt"]}},"codeContexts":{"type":"object","additionalProperties":{"type":"object","properties":{"python":{"type":"object","properties":{"contextId":{"type":"string","description":"The E2B code context ID"},"cwd":{"type":"string","description":"Working directory for the context"},"createdAt":{"type":"string","description":"ISO timestamp when the context was created"}},"required":["contextId","createdAt"]},"r":{"type":"object","properties":{"contextId":{"type":"string","description":"The E2B code context ID"},"cwd":{"type":"string","description":"Working directory for the context"},"createdAt":{"type":"string","description":"ISO timestamp when the context was created"}},"required":["contextId","createdAt"]}}},"description":"E2B code contexts map: sandboxId -> language -> context. Each context maintains execution state across runCode() calls."},"templateAlias":{"type":"string","description":"The template alias used to create the sandbox (e.g., effectiveai-sandbox-3-dev)"},"systemPresetName":{"type":"string","description":"The system preset name used for this session"},"agentInfo":{"type":"object","nullable":true,"properties":{"presetName":{"type":"string","description":"Unique identifier for the agent preset"},"displayName":{"type":"string","description":"Human-readable agent name from Identity.name (e.g. \"RSL Editor\")"},"agentId":{"type":"string","description":"Agent registry ID (may differ from presetName for code:library agents)"},"source":{"type":"string","enum":["code:library","code:team"],"description":"Source identifier for the agent preset"},"filename":{"type":"string","description":"The filename of the agent preset"}},"required":["presetName","source","filename"],"description":"Agent info for display in session UI"},"model":{"type":"string","enum":["claude-fable-5","claude-opus-4-8","claude-opus-4-7","claude-opus-4-6","claude-sonnet-4-6","claude-sonnet-4-6-1m","claude-sonnet-4-5-20250929","claude-opus-4-5-20251101","claude-haiku-4-5-20251001","gpt-5.5","gpt-5.5-pro","gpt-5.4","gpt-5.4-mini","gpt-5.4-nano","gpt-5.4-pro","gpt-5.3-codex","gemini-3.1-pro-preview","gemini-3-flash-preview","gemini-2.5-pro","gemini-2.5-flash","gemini-2.5-flash-lite","gemini-3.1-flash-lite","gemini-flash-latest","gemini-flash-lite-latest","deepseek/deepseek-v4-pro","deepseek/deepseek-v4-flash","xai/grok-4.3","zai/glm-5.1","glm-5.2","nvidia/nemotron-3-ultra-550b-a55b","moonshotai/kimi-k2.6","moonshotai/kimi-k2.7-code","moonshotai/kimi-k2.5"],"description":"Chat model for this session"},"modelAlias":{"type":"string","enum":["opus","sonnet","gpt"],"description":"Customer-facing chat model alias for this session"},"modelEffort":{"type":"string","enum":["low","medium","high","xhigh","max"],"description":"Chat model effort override for this session"},"inheritParentModel":{"type":"boolean","description":"When true, subagent sessions spawned from this session are forced to use this session's model instead of their configured/default model. Propagates down the subagent tree."},"agentEngine":{"type":"string","enum":["salad","codex","acp"],"description":"Agent engine for this session. Defaults to org config when omitted."},"resources":{"type":"object","properties":{"sandbox":{"type":"object","properties":{"provider":{"type":"string","enum":["e2b","agent-sandbox"],"description":"Sandbox provider for creating a new sandbox. Agent-sandbox uses the server-owned session pod executor path."},"templateId":{"type":"string","description":"Provider-specific template reference for creating a new sandbox"},"fromSession":{"type":"string","description":"Session ID to share sandbox from. Must match parentSessionId."},"useSelfHostedE2b":{"type":"boolean","description":"When true, the session sandbox targets the self-hosted E2B instance instead of the cloud. Defaults to the global config value."}},"description":"Sandbox configuration. Omit for own sandbox with default template."},"project":{"type":"object","properties":{"name":{"type":"string","description":"Project name or ID to link this session to"}},"required":["name"],"description":"Explicit project config. Omit to inherit from parent session."}},"description":"Resource configuration for this session. Controls sandbox sharing and project settings."},"runtimeUpgrade":{"type":"object","properties":{"status":{"$ref":"#/components/schemas/RuntimeUpgradeStatus"},"action":{"type":"string","enum":["in_place","recycle"]},"fromVersion":{"type":"string","nullable":true},"toVersion":{"type":"string"},"releaseId":{"type":"string"},"message":{"type":"string"},"startedAt":{"type":"string"},"updatedAt":{"type":"string"},"completedAt":{"type":"string"}},"required":["status","action","fromVersion","toVersion","updatedAt"],"description":"Current or most recent runtime upgrade state for the session sandbox."},"runtimeDiagnostics":{"type":"object","properties":{"checkedAt":{"type":"string"},"isStale":{"type":"boolean"},"reason":{"type":"string"},"currentRuntime":{"type":"object","nullable":true,"properties":{"sandboxId":{"type":"string","nullable":true},"version":{"type":"string","nullable":true},"effectiveToolsCommitSha":{"type":"string","nullable":true},"templateRef":{"type":"string","nullable":true},"templateBuildId":{"type":"string","nullable":true}},"required":["sandboxId","version","effectiveToolsCommitSha","templateRef","templateBuildId"]},"requiredRuntime":{"type":"object","properties":{"mode":{"type":"string","enum":["latest","pinned","unresolved"]},"source":{"type":"string"},"channel":{"type":"string","enum":["latest","stable"]},"releaseId":{"type":"string"},"version":{"type":"string","nullable":true},"effectiveToolsCommitSha":{"type":"string","nullable":true},"templateRef":{"type":"string","nullable":true},"templateBuildId":{"type":"string","nullable":true},"templateId":{"type":"string","nullable":true},"upgradeStrategy":{"type":"string","nullable":true},"reason":{"type":"string"}},"required":["mode","source","version","effectiveToolsCommitSha","templateRef","templateBuildId","templateId","upgradeStrategy"]}},"required":["checkedAt","isStale","currentRuntime","requiredRuntime"],"description":"Derived runtime staleness diagnostics for the session sandbox."},"toolConfig":{"type":"object","properties":{"enabled":{"type":"array","items":{"type":"string"},"description":"Allowlist of tool names. When set, only tools whose declaration.name appears in this list are registered."},"disabled":{"type":"array","items":{"type":"string"},"description":"Denylist of tool names. When set, tools whose declaration.name appears in this list are excluded."}},"description":"Tool availability configuration for this session."},"pluginsConfig":{"type":"object","properties":{"systemContext":{"type":"object","properties":{"namespaces":{"type":"array","items":{"type":"string"},"description":"Retrieval index namespaces to search for context enrichment. Defaults to all enabled namespaces when omitted."}},"description":"Configuration for the system-context plugin (retrieval index enrichment)."}},"description":"Plugin configuration for this session (e.g. system-context namespaces)."},"background":{"type":"object","properties":{"kind":{"type":"string","enum":["mission-control","product-mission-control","context-base-editor"],"description":"Machine-readable background bundle type."},"source":{"type":"string","minLength":1,"maxLength":120,"description":"Surface or integration that supplied this background."},"title":{"type":"string","minLength":1,"maxLength":200,"description":"Short title for this background bundle."},"summary":{"type":"string","minLength":1,"maxLength":4000,"description":"Freeform summary rendered before itemized background."},"items":{"type":"array","items":{"$ref":"#/components/schemas/SessionBackgroundItem"},"maxItems":50,"description":"Structured background items rendered into the session prompt."}},"description":"Additional background supplied when this session was created."},"codex":{"type":"object","properties":{"threadId":{"type":"string"},"activeTurnId":{"type":"string"},"runtime":{"$ref":"#/components/schemas/CodexRuntimeContext"},"cwd":{"type":"string"},"model":{"type":"string"},"approvalPolicy":{"type":"string","default":"never","description":"Codex app-server approval policy. Hosted sessions default to no prompts."},"sandboxPolicy":{"nullable":true},"status":{"type":"string","enum":["binding","ready","running","waiting_on_approval","error","closed"]},"lastError":{"type":"string"},"lastSeenAt":{"type":"string"},"boundAt":{"type":"string"},"lastResumedAt":{"type":"string"},"importedFromThreadId":{"type":"string"},"importStatus":{"type":"string","enum":["native","rehydrated","partial"]}},"description":"Codex app-server binding metadata."},"titleSetByUser":{"type":"boolean","description":"When true, the title was manually set by the user and should not be overwritten by auto-generation."}}},"latestLoopId":{"type":"string","nullable":true,"description":"The ID of the current turn loop for this session"},"rootSessionId":{"type":"string","description":"The root session ID for subagent hierarchies. For root sessions, equals sessionId. For subagents, equals the top-level parent session ID."},"parentSessionId":{"type":"string","description":"The immediate parent session ID for subagent hierarchies. Root sessions use their own session ID."},"depth":{"type":"number","description":"Nesting depth for subagent hierarchies. Root sessions have depth=0, subagents have depth=parent.depth+1."},"setupStatus":{"type":"string","nullable":true,"enum":["pending","running","completed","failed",null],"description":"Setup status for init_commands execution"},"hasChildren":{"type":"boolean","description":"Whether this session has any visible child sessions"}},"required":["sessionId","orgId","createdAt","rootSessionId","parentSessionId","depth","hasChildren"]},"TextMessagePart":{"type":"object","properties":{"type":{"type":"string","enum":["text"]},"cache_control":{"$ref":"#/components/schemas/CacheControl"},"provider_metadata":{"type":"object","additionalProperties":{"nullable":true}},"execution_metadata":{"$ref":"#/components/schemas/ExecutionMetadata"},"id":{"type":"string"},"text":{"type":"string"},"systemTag":{"type":"string","description":"Present only when the text is a system tag"}},"required":["type","text"],"description":"Text message part"},"ArtifactMessagePart":{"type":"object","properties":{"type":{"type":"string","enum":["artifact"]},"cache_control":{"$ref":"#/components/schemas/CacheControl"},"provider_metadata":{"type":"object","additionalProperties":{"nullable":true}},"execution_metadata":{"$ref":"#/components/schemas/ExecutionMetadata"},"id":{"type":"string"},"artifactId":{"type":"string","description":"ID of the referenced artifact"},"systemTag":{"type":"string","description":"Present only when the artifact has a system tag"},"artifact":{"oneOf":[{"$ref":"#/components/schemas/FileArtifact"},{"$ref":"#/components/schemas/FolderArtifact"},{"$ref":"#/components/schemas/ReportArtifact"}],"discriminator":{"propertyName":"type","mapping":{"file":"#/components/schemas/FileArtifact","folder":"#/components/schemas/FolderArtifact","report":"#/components/schemas/ReportArtifact"}},"description":"Full artifact data, if available"}},"required":["type","artifactId"],"description":"Artifact reference message part"},"ThoughtMessagePart":{"type":"object","properties":{"type":{"type":"string","enum":["thought"]},"cache_control":{"$ref":"#/components/schemas/CacheControl"},"provider_metadata":{"type":"object","additionalProperties":{"nullable":true}},"execution_metadata":{"$ref":"#/components/schemas/ExecutionMetadata"},"id":{"type":"string"},"thought":{"type":"string"},"complete":{"type":"boolean"}},"required":["type","thought"],"description":"AI thought message part"},"ToolCallMessagePart":{"type":"object","properties":{"type":{"type":"string","enum":["tool_call"]},"cache_control":{"$ref":"#/components/schemas/CacheControl"},"provider_metadata":{"type":"object","additionalProperties":{"nullable":true}},"execution_metadata":{"$ref":"#/components/schemas/ExecutionMetadata"},"id":{"type":"string"},"toolCallId":{"type":"string"},"toolName":{"type":"string"},"toolArgs":{"type":"object","additionalProperties":{"nullable":true}},"partialArgsRaw":{"type":"string"},"compacted":{"type":"boolean","description":"Whether the tool call was compacted -- removed from the LLM context window"},"contentRef":{"type":"object","properties":{"path":{"type":"string"},"size":{"type":"number"}},"required":["path","size"],"description":"Reference to full toolArgs stored in GCS when truncated"},"streaming_metadata":{"type":"object","properties":{"input_duration_ms":{"type":"number","minimum":0},"input_chars":{"type":"integer","minimum":0}},"additionalProperties":{"nullable":true},"description":"Model-side tool call input streaming metadata"}},"required":["type","toolCallId","toolName","toolArgs"],"description":"Tool call message part"},"ToolResultMessagePart":{"type":"object","properties":{"type":{"type":"string","enum":["tool_result"]},"cache_control":{"$ref":"#/components/schemas/CacheControl"},"provider_metadata":{"type":"object","additionalProperties":{"nullable":true}},"execution_metadata":{"type":"object","properties":{"duration_ms":{"type":"number","minimum":0},"timings":{"type":"object","properties":{"total_ms":{"type":"number","minimum":0},"execution_ms":{"type":"number","minimum":0},"sandbox_init_ms":{"type":"number","minimum":0},"network_overhead_ms":{"type":"number","minimum":0},"time_to_first_output_ms":{"type":"number","minimum":0}},"additionalProperties":{"nullable":true}},"sandbox":{"type":"object","properties":{"cold_start":{"type":"boolean"},"sandbox_id":{"type":"string"}},"additionalProperties":{"nullable":true}}},"additionalProperties":{"nullable":true},"description":"Execution metadata captured by the tool runner"},"id":{"type":"string"},"toolName":{"type":"string"},"toolCallId":{"type":"string"},"error":{"type":"string"},"result":{"anyOf":[{"type":"object","properties":{"fragment":{"$ref":"#/components/schemas/ArtifactFragment"},"content":{"type":"string","description":"The content of the fragment"},"conversionType":{"type":"string","enum":["ocr"],"description":"Type of conversion, if the content has been converted to another format"}},"required":["fragment"]},{"type":"string"},{"nullable":true}]},"compacted":{"type":"boolean","description":"Whether the result was compacted -- removed from the LLM context window"},"contentRef":{"type":"object","properties":{"path":{"type":"string"},"size":{"type":"number"}},"required":["path","size"],"description":"Reference to full result stored in GCS when truncated"}},"required":["type","toolName","toolCallId"],"description":"Tool result message part"},"ErrorMessagePart":{"type":"object","properties":{"type":{"type":"string","enum":["error"]},"cache_control":{"$ref":"#/components/schemas/CacheControl"},"provider_metadata":{"type":"object","additionalProperties":{"nullable":true}},"execution_metadata":{"$ref":"#/components/schemas/ExecutionMetadata"},"id":{"type":"string"},"error":{"type":"string"},"stage":{"type":"string"}},"required":["type","error"],"description":"Error message part"},"EndOfMessageMessagePart":{"type":"object","properties":{"type":{"type":"string","enum":["end_of_message"]},"cache_control":{"$ref":"#/components/schemas/CacheControl"},"provider_metadata":{"type":"object","additionalProperties":{"nullable":true}},"execution_metadata":{"$ref":"#/components/schemas/ExecutionMetadata"},"id":{"type":"string"}},"required":["type"],"description":"End of message message part"},"UsageInfoMessagePart":{"type":"object","properties":{"type":{"type":"string","enum":["usage_info"]},"cache_control":{"$ref":"#/components/schemas/CacheControl"},"provider_metadata":{"type":"object","additionalProperties":{"nullable":true}},"execution_metadata":{"$ref":"#/components/schemas/ExecutionMetadata"},"id":{"type":"string"},"underlyingProvider":{"type":"string","enum":["anthropic","openai","google","gateway"],"description":"Actual LLM provider (e.g. anthropic, openai, google); when routed via gateway this is the upstream provider"},"model":{"type":"string","enum":["claude-fable-5","claude-opus-4-8","claude-opus-4-7","claude-opus-4-6","claude-sonnet-4-6","claude-sonnet-4-6-1m","claude-sonnet-4-5-20250929","claude-opus-4-5-20251101","claude-haiku-4-5-20251001","gpt-5.5","gpt-5.5-pro","gpt-5.4","gpt-5.4-mini","gpt-5.4-nano","gpt-5.4-pro","gpt-5.3-codex","gemini-3.1-pro-preview","gemini-3-flash-preview","gemini-2.5-pro","gemini-2.5-flash","gemini-2.5-flash-lite","gemini-3.1-flash-lite","gemini-flash-latest","gemini-flash-lite-latest","deepseek/deepseek-v4-pro","deepseek/deepseek-v4-flash","xai/grok-4.3","zai/glm-5.1","glm-5.2","nvidia/nemotron-3-ultra-550b-a55b","moonshotai/kimi-k2.6","moonshotai/kimi-k2.7-code","moonshotai/kimi-k2.5"],"description":"Model identifier"},"cachedInput":{"type":"number","description":"Cached input tokens"},"cacheWriteTokens":{"type":"number","description":"Tokens written to cache by the provider.\n         Incremental: only tokens newly written in this request. \n         This is not the same as (inputTokens - cachedInput).\n         can be less when only part of the prompt is cached (e.g. up to breakpoints).\n         For how we apply cache breakpoints, see applyCacheBreakpoints in api-server/src/ai/providers/bridge/messages.ts"},"inputTokens":{"type":"number","description":"Total input tokens including cached input"},"outputTokens":{"type":"number","description":"Total output tokens"},"totalTokens":{"type":"number","description":"Total tokens = input tokens + output tokens"},"finishReason":{"type":"string","enum":["stop","length","content-filter","tool-calls","error","other"],"description":"Why the LLM stopped generating for this step"}},"required":["type","inputTokens","outputTokens","totalTokens"],"description":"Usage info message part"},"CheckpointMessagePart":{"type":"object","properties":{"type":{"type":"string","enum":["checkpoint"]},"cache_control":{"$ref":"#/components/schemas/CacheControl"},"provider_metadata":{"type":"object","additionalProperties":{"nullable":true}},"execution_metadata":{"$ref":"#/components/schemas/ExecutionMetadata"},"id":{"type":"string"},"checkpointType":{"type":"string","enum":["clear","summary_request","summary"]},"taskState":{"type":"string","enum":["completed","ongoing"]},"checkpointId":{"type":"string","description":"Client-generated ID to stitch related checkpoint parts across messages"},"text":{"type":"string"}},"required":["type","checkpointType"],"description":"Checkpoint message part for resetting chat history"},"SessionId":{"type":"string","description":"Session identifier"},"ChatSessionState":{"type":"string","enum":["idle","busy","deleted"],"default":"idle","description":"Chat session state"},"ParticipantPreview":{"type":"object","properties":{"id":{"type":"string"},"displayName":{"type":"string"}},"required":["id","displayName"]},"RuntimeUpgradeStatus":{"type":"string","enum":["updating","ready","recycle_required","failed"],"description":"Sandbox runtime upgrade status"},"CodexRuntimeContext":{"type":"object","properties":{"kind":{"type":"string","enum":["sandbox","remote","local"]},"runtimeId":{"type":"string"},"sandboxId":{"type":"string"},"endpoint":{"type":"string"},"codexVersion":{"type":"string"},"transport":{"type":"string","enum":["stdio","websocket"],"default":"websocket"}},"required":["kind","runtimeId"]},"AvailableSkillSlashCommand":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"path":{"type":"string"},"orgRepoId":{"type":"string"},"repoName":{"type":"string"},"contextBaseAlias":{"type":"string"},"mountPath":{"type":"string"},"skillPath":{"type":"string"},"pinned":{"type":"boolean","default":false}},"required":["name","description","path"]},"SandboxInfo":{"type":"object","properties":{"sandboxId":{"type":"string","description":"Unique sandbox identifier"},"state":{"type":"string","description":"Current state (running, paused, terminated, etc.)"},"templateId":{"type":"string","description":"E2B template ID used"},"name":{"type":"string","description":"Optional sandbox name"},"startedAt":{"type":"string","description":"ISO timestamp when sandbox started"},"age":{"type":"string","description":"Human-readable age (calculated from startedAt)"},"cpuCount":{"type":"number","description":"Number of CPUs allocated"},"memoryMB":{"type":"number","description":"Memory in MB"},"memoryGB":{"type":"number","description":"Memory in GB (calculated)"},"envdVersion":{"type":"string","description":"Envd version"},"metadata":{"type":"object","additionalProperties":{"nullable":true},"description":"Custom metadata object (includes sessionId)"}},"required":["sandboxId"]},"AvailableModel":{"type":"object","properties":{"id":{"type":"string","enum":["claude-fable-5","claude-opus-4-8","claude-opus-4-7","claude-opus-4-6","claude-sonnet-4-6","claude-sonnet-4-6-1m","claude-sonnet-4-5-20250929","claude-opus-4-5-20251101","claude-haiku-4-5-20251001","gpt-5.5","gpt-5.5-pro","gpt-5.4","gpt-5.4-mini","gpt-5.4-nano","gpt-5.4-pro","gpt-5.3-codex","gemini-3.1-pro-preview","gemini-3-flash-preview","gemini-2.5-pro","gemini-2.5-flash","gemini-2.5-flash-lite","gemini-3.1-flash-lite","gemini-flash-latest","gemini-flash-lite-latest","deepseek/deepseek-v4-pro","deepseek/deepseek-v4-flash","xai/grok-4.3","zai/glm-5.1","glm-5.2","nvidia/nemotron-3-ultra-550b-a55b","moonshotai/kimi-k2.6","moonshotai/kimi-k2.7-code","moonshotai/kimi-k2.5"]},"provider":{"type":"string"},"displayName":{"type":"string"},"visibility":{"$ref":"#/components/schemas/ModelVisibility"},"uiAlias":{"type":"string"},"aliases":{"type":"array","items":{"type":"string"}},"contextWindow":{"type":"number"},"maxOutputTokens":{"type":"number"},"supportsThinking":{"type":"boolean"},"defaultEffort":{"$ref":"#/components/schemas/Effort"},"structuredOutputs":{"type":"boolean"},"zdrSupported":{"type":"boolean"}},"required":["id","provider","displayName","visibility","aliases","contextWindow","supportsThinking","structuredOutputs","zdrSupported"]},"LlmDataRetentionPolicy":{"type":"string","enum":["standard","zdr_required"],"description":"Organization-level LLM data retention policy"},"MissionControlSummary":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"kind":{"$ref":"#/components/schemas/MissionControlKind"},"sourcePath":{"type":"string"},"primaryRef":{"$ref":"#/components/schemas/MissionControlPrimaryRef"}},"required":["id","name","kind","sourcePath","primaryRef"]},"MissionControlKind":{"type":"string","enum":["product","role-center","governance-center","catalog","contextbase","personal"]},"MissionControlPrimaryRef":{"type":"object","nullable":true,"properties":{"id":{"type":"string"},"source_path":{"type":"string"},"type":{"type":"string"}},"required":["id","type"],"additionalProperties":{"nullable":true}},"MissionControlBlock":{"type":"object","properties":{"id":{"type":"string"},"source_path":{"type":"string"}},"required":["id"],"additionalProperties":{"nullable":true}},"MissionControlConfiguredView":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/MissionControlConfigurableViewId"}},"required":["id"]},"MissionControlApp":{"type":"object","properties":{"id":{"type":"string"},"source_path":{"type":"string"},"source":{"type":"string","enum":["contextbase-service","workspace-app"]},"label":{"type":"string"}},"required":["id","source"],"additionalProperties":{"nullable":true}},"MissionControlMetadata":{"type":"object","nullable":true,"properties":{"pinned_entity_kinds":{"type":"array","items":{"$ref":"#/components/schemas/MissionControlPinnedEntityKind"}},"pinned_entity_views":{"type":"array","items":{"$ref":"#/components/schemas/MissionControlPinnedEntityView"}},"pinned_context_base_paths":{"type":"array","items":{"$ref":"#/components/schemas/MissionControlPinnedContextBasePath"}},"pinned_context_base_pages":{"type":"array","items":{"$ref":"#/components/schemas/MissionControlPinnedContextBasePage"},"description":"Deprecated alias for pinned_context_base_paths."},"pinned_context_base_skills":{"type":"array","items":{"$ref":"#/components/schemas/MissionControlPinnedContextBaseSkill"}}},"additionalProperties":{"nullable":true}},"MissionControlStatus":{"type":"string","enum":["active","archived"]},"MissionControlContextBaseAccess":{"type":"string","enum":["read","write"]},"MissionControlBootstrapContextBase":{"type":"object","nullable":true,"properties":{"id":{"type":"string","format":"uuid"},"orgRepoId":{"type":"string","format":"uuid"},"repoName":{"type":"string"},"alias":{"type":"string","minLength":2,"maxLength":128,"pattern":"^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$","description":"Canonical contextbase ref alias: primary for the primary link, otherwise the repo-derived <name> alias."},"access":{"$ref":"#/components/schemas/MissionControlContextBaseAccess"},"mountPath":{"type":"string","description":"Canonical contextbase ref mount path."},"isPrimary":{"type":"boolean"}},"required":["id","orgRepoId","repoName","alias","access","mountPath","isPrimary"]},"MissionControlSkill":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"path":{"type":"string"},"orgRepoId":{"type":"string","format":"uuid"},"repoName":{"type":"string"},"contextBaseAlias":{"type":"string"},"mountPath":{"type":"string"},"skillPath":{"type":"string"},"pinned":{"type":"boolean"}},"required":["name","description","path","orgRepoId","repoName","contextBaseAlias","mountPath","skillPath","pinned"]},"PresetInfo":{"type":"object","properties":{"name":{"type":"string"},"content":{"type":"string"}},"required":["name","content"]},"InboxItemStatus":{"type":"string","enum":["unread","read"]},"ScheduledSubscriptionScheduleType":{"type":"string","enum":["hourly","daily","weekly","cron"]},"SubscriptionEventType":{"type":"string","enum":["scheduled_trigger","serff_filing_update"]},"SubscriptionFilterMode":{"type":"string","enum":["server","agent"]},"SubscriptionStatus":{"type":"string","enum":["active","paused"],"description":"Subscription status: active or paused"},"SubscriptionDeliveryMode":{"type":"string","enum":["inbox","spawn","workflow_run"],"description":"Delivery mode: 'inbox' sends to existing session, 'spawn' creates a fresh session per tick, 'workflow_run' triggers a contextbase workflow"},"SubscriptionDryRunSampleItem":{"type":"object","properties":{"serffTrackingNumber":{"type":"string"},"state":{"type":"string","nullable":true},"toiCode":{"type":"string","nullable":true},"filingType":{"type":"string","nullable":true},"naicGroupCode":{"type":"string","nullable":true},"naicCompanyCode":{"type":"string","nullable":true},"eventSubtype":{"type":"string","nullable":true},"eventCreatedAt":{"type":"string"}},"required":["serffTrackingNumber","state","toiCode","filingType","naicGroupCode","naicCompanyCode","eventSubtype","eventCreatedAt"]},"DeliveryConfig":{"oneOf":[{"$ref":"#/components/schemas/SessionInboxDelivery"},{"$ref":"#/components/schemas/SandboxWebhookDelivery"},{"$ref":"#/components/schemas/AppSessionDelivery"},{"$ref":"#/components/schemas/TemporalSignalDelivery"}],"discriminator":{"propertyName":"type","mapping":{"session_inbox":"#/components/schemas/SessionInboxDelivery","sandbox_webhook":"#/components/schemas/SandboxWebhookDelivery","app_session":"#/components/schemas/AppSessionDelivery","temporal_signal":"#/components/schemas/TemporalSignalDelivery"}}},"ListedWatcherItem":{"type":"object","properties":{"id":{"type":"string"},"orgId":{"type":"string"},"eventType":{"type":"string"},"matchCriteria":{"type":"object","additionalProperties":{"nullable":true}},"deliveryConfig":{"type":"object","additionalProperties":{"nullable":true}},"maxDeliveries":{"type":"number","nullable":true},"deliveryCount":{"type":"number"},"status":{"type":"string"},"createdBy":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"expiresAt":{"type":"string","nullable":true,"format":"date-time"},"deliveries":{"$ref":"#/components/schemas/WatcherDeliveryStats"}},"required":["id","orgId","eventType","matchCriteria","deliveryConfig","maxDeliveries","deliveryCount","status","createdBy","createdAt","expiresAt","deliveries"]},"DatabaseProvider":{"type":"string","enum":["neon"],"description":"Supported database provider"},"DatabaseStatus":{"type":"string","enum":["ready","provisioning","error","deleted"],"description":"Provisioned database status"},"RetrievalIndexSearchResultItem":{"type":"object","properties":{"id":{"type":"string","format":"uuid","example":"123e4567-e89b-12d3-a456-426614174000"},"orgId":{"type":"string","example":"org-123"},"namespace":{"type":"string","example":"code"},"documentId":{"type":"string","example":"wiki:/docs/insurance/rate-filing"},"uri":{"type":"string","example":"wiki://docs/insurance/rate-filing"},"variant":{"type":"string","example":"content"},"content":{"type":"string","example":"Rate filing process involves..."},"metadata":{"type":"object","additionalProperties":{"nullable":true},"example":{"source":"wiki"}},"embedding":{"type":"array","nullable":true,"items":{"type":"number"},"example":null},"embeddingModel":{"type":"string","example":"gemini-embedding-001"},"createdAt":{"type":"string","example":"2025-12-27T12:00:00Z"},"updatedAt":{"type":"string","example":"2025-12-27T12:00:00Z"},"batchId":{"type":"string","nullable":true,"format":"uuid","example":null},"distance":{"type":"number","example":0.15},"similarity":{"type":"number","example":0.85}},"required":["id","orgId","namespace","documentId","uri","variant","content","metadata","embedding","embeddingModel","createdAt","updatedAt","batchId","distance","similarity"]},"AdminOrgProfileFields":{"type":"object","properties":{"overview":{"type":"string","nullable":true,"maxLength":2000},"communication":{"type":"string","nullable":true,"maxLength":1000},"stage":{"type":"string","nullable":true,"maxLength":200}},"required":["overview","communication","stage"],"description":"Agent-facing organization profile fields"},"CreateContextBaseDraftMode":{"type":"string","enum":["edit","create-workflow"],"default":"edit"},"ContextBaseDraftLifecycleStatus":{"type":"string","enum":["in_progress","done","draft","review_requested","changes_requested","approved","published","abandoned"]},"MutedEventTypes":{"type":"object","properties":{"mention":{"type":"boolean","default":false},"participate":{"type":"boolean","default":false},"agentLoopCompletion":{"type":"boolean","default":false},"chatMessage":{"type":"boolean","default":true},"email":{"$ref":"#/components/schemas/MutedEmailEventTypes"}},"default":{}},"GlobalSnooze":{"type":"object","properties":{"until":{"type":"string","nullable":true,"format":"date-time","default":null}},"default":{}},"AgentLoopCompletionPrefs":{"type":"object","properties":{"minDurationMs":{"type":"integer","nullable":true,"minimum":0,"maximum":3600000,"default":null}},"default":{}},"MutedSession":{"type":"object","properties":{"sessionId":{"type":"string","minLength":1},"expiresAt":{"type":"string","nullable":true,"format":"date-time","default":null}},"required":["sessionId"]},"EntityResourceRef":{"type":"object","properties":{"type":{"type":"string","enum":["entity"]},"key":{"type":"object","properties":{"repoId":{"type":"string","minLength":1},"entityId":{"type":"string","minLength":1}},"required":["repoId","entityId"]}},"required":["type","key"]},"ArtifactResourceRef":{"type":"object","properties":{"type":{"type":"string","enum":["artifact"]},"key":{"type":"object","properties":{"id":{"type":"string","minLength":1}},"required":["id"]}},"required":["type","key"]},"EntityViewResourceRef":{"type":"object","properties":{"type":{"type":"string","enum":["entity_view"]},"key":{"type":"object","properties":{"repoId":{"type":"string","minLength":1},"viewId":{"type":"string","minLength":1}},"required":["repoId","viewId"]}},"required":["type","key"]},"SessionResourceRef":{"type":"object","properties":{"type":{"type":"string","enum":["session"]},"key":{"type":"object","properties":{"sessionId":{"type":"string","minLength":1}},"required":["sessionId"]}},"required":["type","key"]},"WorkflowRunTaskAssignment":{"type":"object","properties":{"assignee_type":{"type":"string","enum":["session","user","user_group"]},"assignee_id":{"type":"string"},"display_name":{"type":"string","nullable":true}},"required":["assignee_type","assignee_id","display_name"]},"FlattenedFileArtifact":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the artifact"},"name":{"type":"string","description":"Display name of the artifact"},"parentId":{"type":"string","description":"Parent artifact ID"},"nodeKind":{"type":"string","enum":["file","folder"],"description":"Kind of node this artifact represents"},"isIndexed":{"type":"boolean","description":"Whether the artifact content has been indexed for search"},"indexingStatus":{"type":"string","description":"Status of the indexing workflow (pending, running, completed, failed, cancelled, unknown)"},"workflowId":{"type":"string","description":"Temporal workflow ID for the indexing job, if one exists"},"metadata":{"type":"object","additionalProperties":{"nullable":true},"description":"Additional metadata for tracking batch processes and other information"},"orgId":{"type":"string","default":"","description":"Organization ID that owns this artifact"},"createdAt":{"type":"string","format":"date-time","description":"Timestamp when the artifact was created"},"updatedAt":{"type":"string","format":"date-time","description":"Timestamp when the artifact was last updated"},"path":{"type":"string","description":"Full path from vault root"},"relativePath":{"type":"string","description":"Path relative to the queried parent folder"},"extractedTextPath":{"type":"string","description":"Path in blob storage where extracted text is stored, if available"},"stringFacet1":{"type":"string","description":"Generic indexed string facet for application-defined labels (e.g., serff_tracking_number). Meaning is defined at the application layer."},"stringFacet2":{"type":"string","description":"Generic indexed string facet for application-defined labels. Meaning is defined at the application layer."},"stringFacet3":{"type":"string","description":"Generic indexed string facet for application-defined labels. Meaning is defined at the application layer."},"createdBy":{"type":"string","description":"User ID of the artifact creator"},"sessionId":{"type":"string","description":"Session ID this artifact belongs to (set for session-scoped artifacts)"},"visibility":{"type":"string","enum":["org","private","session","public"],"description":"Artifact visibility mode: 'org' for team-wide (default), 'private' for owner-only, 'session' for session-inherited, 'public' for anyone with the link"},"visibleTo":{"type":"array","items":{"type":"string"},"description":"User IDs with explicit access to this artifact"},"type":{"type":"string","enum":["file"],"description":"Type discriminator for file artifacts"},"data":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the file"},"name":{"type":"string","description":"File name"},"size":{"type":"number","description":"File size in bytes"},"pageCount":{"type":"number","description":"Page count of the file"},"mimeType":{"type":"string","enum":["text/plain","text/markdown","text/csv","application/json","application/xml","text/xml","text/html","text/css","text/javascript","application/javascript","application/typescript","text/x-python","text/x-rsl","application/pdf","application/vnd.openxmlformats-officedocument.spreadsheetml.sheet","application/vnd.ms-excel","application/vnd.ms-excel.sheet.macroEnabled.12","application/vnd.openxmlformats-officedocument.spreadsheetml.sheet.macroEnabled.12","application/vnd.ms-excel.sheet.macroenabled.12","application/vnd.ms-excel.sheet.binary.macroEnabled.12","application/vnd.openxmlformats-officedocument.wordprocessingml.document","application/vnd.openxmlformats-officedocument.presentationml.presentation","application/vnd.ms-outlook","application/zip","application/x-tar","application/gzip","application/octet-stream","image/jpeg","image/png","image/gif","image/webp","image/svg+xml","audio/mpeg","audio/wav","audio/ogg","audio/mp4","audio/webm","video/mp4","video/webm","video/quicktime","video/x-msvideo","video/ogg"],"description":"MIME type of the file"},"lastModified":{"type":"number","description":"Last modified timestamp"},"path":{"type":"string","description":"Storage path"},"storageInfo":{"oneOf":[{"type":"object","properties":{"location":{"type":"string","enum":["gcs"]},"object":{"type":"string"},"url":{"type":"string"}},"required":["location","object"]},{"type":"object","properties":{"location":{"type":"string","enum":["filesystem"]}},"required":["location"]}],"description":"Storage location information"},"indexed":{"type":"boolean","description":"Whether the artifact content has been indexed for search"}},"required":["id","name","size","mimeType","path","storageInfo"],"description":"File metadata associated with this artifact"},"depth":{"type":"integer","minimum":1,"description":"Depth level from the queried parent (1 = direct child)"}},"required":["id","name","nodeKind","isIndexed","createdAt","updatedAt","path","relativePath","type","data","depth"],"description":"File artifact with path and depth info"},"FlattenedFolderArtifact":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the artifact"},"name":{"type":"string","description":"Display name of the artifact"},"parentId":{"type":"string","description":"Parent artifact ID"},"nodeKind":{"type":"string","enum":["file","folder"],"description":"Kind of node this artifact represents"},"isIndexed":{"type":"boolean","description":"Whether the artifact content has been indexed for search"},"indexingStatus":{"type":"string","description":"Status of the indexing workflow (pending, running, completed, failed, cancelled, unknown)"},"workflowId":{"type":"string","description":"Temporal workflow ID for the indexing job, if one exists"},"metadata":{"type":"object","additionalProperties":{"nullable":true},"description":"Additional metadata for tracking batch processes and other information"},"orgId":{"type":"string","default":"","description":"Organization ID that owns this artifact"},"createdAt":{"type":"string","format":"date-time","description":"Timestamp when the artifact was created"},"updatedAt":{"type":"string","format":"date-time","description":"Timestamp when the artifact was last updated"},"path":{"type":"string","description":"Full path from vault root"},"relativePath":{"type":"string","description":"Path relative to the queried parent folder"},"extractedTextPath":{"type":"string","description":"Path in blob storage where extracted text is stored, if available"},"stringFacet1":{"type":"string","description":"Generic indexed string facet for application-defined labels (e.g., serff_tracking_number). Meaning is defined at the application layer."},"stringFacet2":{"type":"string","description":"Generic indexed string facet for application-defined labels. Meaning is defined at the application layer."},"stringFacet3":{"type":"string","description":"Generic indexed string facet for application-defined labels. Meaning is defined at the application layer."},"createdBy":{"type":"string","description":"User ID of the artifact creator"},"sessionId":{"type":"string","description":"Session ID this artifact belongs to (set for session-scoped artifacts)"},"visibility":{"type":"string","enum":["org","private","session","public"],"description":"Artifact visibility mode: 'org' for team-wide (default), 'private' for owner-only, 'session' for session-inherited, 'public' for anyone with the link"},"visibleTo":{"type":"array","items":{"type":"string"},"description":"User IDs with explicit access to this artifact"},"type":{"type":"string","enum":["folder"],"description":"Type discriminator for folder artifacts"},"data":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the folder"},"name":{"type":"string","description":"Folder name"}},"required":["id","name"],"description":"Folder metadata associated with this artifact"},"depth":{"type":"integer","minimum":1,"description":"Depth level from the queried parent (1 = direct child)"}},"required":["id","name","nodeKind","isIndexed","createdAt","updatedAt","path","relativePath","type","data","depth"],"description":"Folder artifact with path and depth info"},"WorkflowSchedule":{"type":"object","properties":{"cron":{"type":"string","description":"Standard 5-field cron expression"},"timezone":{"type":"string","description":"IANA timezone (default UTC)"},"defaultInput":{"nullable":true,"description":"Input passed to workflow on each tick"},"paused":{"type":"boolean","description":"Deploy in paused state (default false)"}},"required":["cron"],"description":"Declared schedule for automatic execution via subscription infrastructure."},"WorkflowSopRef":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Stable SOP identifier implemented by this workflow."},"path":{"type":"string","minLength":1,"description":"Context-base path to the SOP document."},"role":{"type":"string","enum":["implements"],"description":"Relationship between the workflow and SOP."}},"required":["id","path","role"]},"CacheControl":{"type":"object","properties":{"type":{"type":"string","enum":["ephemeral"]}},"required":["type"],"description":"Cache control hint for LLM providers"},"ExecutionMetadata":{"type":"object","properties":{"runtime_hints":{"type":"string"},"duration_ms":{"type":"number"}},"additionalProperties":{"nullable":true},"description":"Tool execution metadata from sandbox"},"ArtifactFragment":{"type":"object","properties":{"artifact":{"$ref":"#/components/schemas/Artifact"},"fragmentInfo":{"type":"object","properties":{"pageNumbers":{"type":"array","items":{"type":"number"},"description":"Page numbers of the fragment"},"offset":{"type":"number","description":"Offset of the fragment"},"limit":{"type":"number","description":"Limit of the fragment"}},"description":"Fragment information, if absent, then full artifact is used."}},"required":["artifact"],"description":"Fragment of artifact information"},"ModelVisibility":{"type":"string","enum":["public","internal","hidden"]},"Effort":{"type":"string","enum":["low","medium","high","xhigh","max"]},"MissionControlConfigurableViewId":{"type":"string","enum":["library","search","sources","entities","procedures","projects","apps","skills","signals"]},"MissionControlPinnedEntityKind":{"type":"object","properties":{"namespaceId":{"type":"string","minLength":1,"maxLength":255},"entityKind":{"type":"string","minLength":1,"maxLength":255},"label":{"type":"string","minLength":1,"maxLength":255},"description":{"type":"string","minLength":1,"maxLength":1024},"icon":{"type":"string","minLength":1,"maxLength":128},"order":{"type":"integer"}},"required":["namespaceId","entityKind"]},"MissionControlPinnedEntityView":{"type":"object","properties":{"namespaceId":{"type":"string","minLength":1,"maxLength":255},"viewId":{"type":"string","minLength":1,"maxLength":255},"label":{"type":"string","minLength":1,"maxLength":255},"description":{"type":"string","minLength":1,"maxLength":1024},"entityKind":{"type":"string","minLength":1,"maxLength":255},"params":{"type":"object","additionalProperties":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"}]}},"icon":{"type":"string","minLength":1,"maxLength":128},"order":{"type":"integer"}},"required":["namespaceId","viewId"]},"MissionControlPinnedContextBasePath":{"type":"object","properties":{"path":{"type":"string","minLength":1},"label":{"type":"string","minLength":1,"maxLength":255}},"required":["path","label"]},"MissionControlPinnedContextBasePage":{"type":"object","properties":{"path":{"type":"string","minLength":1},"label":{"type":"string","minLength":1,"maxLength":255}},"required":["path","label"]},"MissionControlPinnedContextBaseSkill":{"type":"object","properties":{"org_repo_id":{"type":"string","format":"uuid"},"skill_path":{"type":"string","minLength":1,"maxLength":512},"pinned_at":{"type":"string","format":"date-time"},"pinned_by":{"type":"string","nullable":true}},"required":["org_repo_id","skill_path"]},"SessionInboxDelivery":{"type":"object","properties":{"type":{"type":"string","enum":["session_inbox"]},"sessionId":{"type":"string","minLength":1},"instruction":{"type":"string"},"facet":{"$ref":"#/components/schemas/InboxItemFacet"},"sender":{"type":"string","minLength":1},"ackPolicy":{"$ref":"#/components/schemas/AckPolicy"}},"required":["type","sessionId"]},"SandboxWebhookDelivery":{"type":"object","properties":{"type":{"type":"string","enum":["sandbox_webhook"]},"sessionId":{"type":"string","minLength":1},"kernelId":{"type":"string","minLength":1},"ackPolicy":{"$ref":"#/components/schemas/AckPolicy"}},"required":["type","sessionId"]},"AppSessionDelivery":{"type":"object","properties":{"type":{"type":"string","enum":["app_session"]},"appId":{"type":"string","minLength":1},"messageTemplate":{"type":"string"},"tags":{"type":"array","items":{"type":"string","minLength":1}}},"required":["type","appId"]},"TemporalSignalDelivery":{"type":"object","properties":{"type":{"type":"string","enum":["temporal_signal"]},"workflowId":{"type":"string","minLength":1},"signal":{"type":"string","minLength":1}},"required":["type","workflowId","signal"]},"WatcherDeliveryStats":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"byStatus":{"type":"object","properties":{"pending_ack":{"type":"integer","minimum":0},"acked":{"type":"integer","minimum":0},"timed_out":{"type":"integer","minimum":0},"failed":{"type":"integer","minimum":0}},"required":["pending_ack","acked","timed_out","failed"]},"recent":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["pending_ack","acked","timed_out","failed"]},"statusUpdatedAt":{"type":"string","format":"date-time"},"errorMessage":{"type":"string","nullable":true},"errorCode":{"type":"string","nullable":true}},"required":["id","status","statusUpdatedAt","errorMessage","errorCode"]}}},"required":["total","byStatus","recent"]},"MutedEmailEventTypes":{"type":"object","properties":{"announcement":{"type":"boolean","default":false}},"default":{}},"InboxItemFacet":{"oneOf":[{"$ref":"#/components/schemas/AgentCompletionFacet"},{"$ref":"#/components/schemas/GenericFacet"},{"$ref":"#/components/schemas/ScheduledFacet"},{"$ref":"#/components/schemas/CommandStartedFacet"},{"$ref":"#/components/schemas/CommandResultFacet"},{"$ref":"#/components/schemas/WebhookFacet"},{"$ref":"#/components/schemas/SlackMentionFacet"}],"discriminator":{"propertyName":"type","mapping":{"agent-completion":"#/components/schemas/AgentCompletionFacet","generic":"#/components/schemas/GenericFacet","scheduled":"#/components/schemas/ScheduledFacet","command-started":"#/components/schemas/CommandStartedFacet","command-result":"#/components/schemas/CommandResultFacet","webhook":"#/components/schemas/WebhookFacet","slack-mention":"#/components/schemas/SlackMentionFacet"}}},"AckPolicy":{"type":"object","properties":{"required":{"type":"boolean"},"timeoutSeconds":{"type":"integer","minimum":0,"exclusiveMinimum":true},"onTimeout":{"type":"string","enum":["nudge_session","notify_session"]}}},"AgentCompletionFacet":{"type":"object","properties":{"type":{"type":"string","enum":["agent-completion"]},"sessionId":{"type":"string","minLength":1},"title":{"type":"string"},"summary":{"type":"string"}},"required":["type","sessionId","title"]},"GenericFacet":{"type":"object","properties":{"type":{"type":"string","enum":["generic"]},"source":{"type":"string"}},"required":["type"]},"ScheduledFacet":{"type":"object","properties":{"type":{"type":"string","enum":["scheduled"]},"source":{"type":"string"}},"required":["type"]},"CommandStartedFacet":{"type":"object","properties":{"type":{"type":"string","enum":["command-started"]},"subscriptionId":{"type":"string","minLength":1},"runId":{"type":"string","minLength":1},"command":{"type":"string"},"startedAt":{"type":"string"},"stdoutPath":{"type":"string"},"stderrPath":{"type":"string"},"workingDir":{"type":"string"}},"required":["type","subscriptionId","runId","command","startedAt","stdoutPath","stderrPath","workingDir"]},"CommandResultFacet":{"type":"object","properties":{"type":{"type":"string","enum":["command-result"]},"subscriptionId":{"type":"string","minLength":1},"runId":{"type":"string","minLength":1},"command":{"type":"string"},"exitCode":{"type":"integer"},"startedAt":{"type":"string"},"finishedAt":{"type":"string"},"durationMs":{"type":"integer","minimum":0},"stdoutPath":{"type":"string"},"stderrPath":{"type":"string"},"workingDir":{"type":"string"}},"required":["type","subscriptionId","runId","command","exitCode","startedAt","finishedAt","durationMs","stdoutPath","stderrPath","workingDir"]},"WebhookFacet":{"type":"object","properties":{"type":{"type":"string","enum":["webhook"]},"source":{"type":"string"}},"required":["type"]},"SlackMentionFacet":{"type":"object","properties":{"type":{"type":"string","enum":["slack-mention"]},"channelId":{"type":"string","minLength":1},"slackUserId":{"type":"string","minLength":1},"messageTs":{"type":"string"},"placeholderTs":{"type":"string"},"artifactIds":{"type":"array","items":{"type":"string"}}},"required":["type","channelId","slackUserId"]}},"parameters":{}}}