{ "openapi": "3.0.3", "info": { "title": "Operalta API", "version": "1.4.0", "description": "Operalta is a conversational memory platform for startups and their investors. This API provides programmatic access to company context, KPI metrics, stream entries (decisions, insights), organizational structure, artifacts, and the unified document upload pipeline. Some TTFT extraction and room preview routes are browser-session endpoints and are marked accordingly.", "contact": { "name": "Operalta Support", "url": "https://www.operalta.ai/help" } }, "servers": [ { "url": "https://www.operalta.ai", "description": "Production" } ], "security": [ { "BearerAuth": [] } ], "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "description": "API key obtained from Operalta Settings \u2192 API Keys. Format: `op_xxxxx`. Pass as `Authorization: Bearer op_...`." }, "SessionCookie": { "type": "apiKey", "in": "header", "name": "Cookie", "description": "Authenticated Operalta web session Cookie header. In practice this usually contains `sb--auth-token=...` and may include chunked siblings; use the full Cookie header copied from a logged-in browser session." } }, "parameters": { "companyId": { "name": "companyId", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID of the company. Alternatively, pass as `X-Company-Id` request header." }, "XCompanyId": { "name": "X-Company-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Company UUID. Alternative to the `companyId` query parameter." } }, "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "string" }, "status": { "type": "integer", "description": "HTTP status code." }, "details": { "type": "object", "description": "Optional validation error details.", "nullable": true } } }, "CompanyContext": { "type": "object", "properties": { "exists": { "type": "boolean" }, "contextType": { "type": "string", "example": "startup" }, "context": { "type": "object", "properties": { "name": { "type": "string" }, "oneLiner": { "type": "string" }, "description": { "type": "string" }, "website": { "type": "string" }, "founded": { "type": "string" }, "headquarters": { "type": "string" }, "industry": { "type": "string" }, "stage": { "type": "string" }, "teamSize": { "type": "string" }, "businessModel": { "type": "string" }, "targetCustomer": { "type": "string" }, "competitors": { "type": "string" }, "keyDifferentiator": { "type": "string" }, "marketSegment": { "type": "string" }, "currentFocus": { "type": "string" } } } } }, "Metrics": { "type": "object", "properties": { "metrics": { "type": "object", "properties": { "mrr": { "type": "number", "description": "Monthly Recurring Revenue" }, "arr": { "type": "number", "description": "Annual Recurring Revenue" }, "runway": { "type": "number" }, "headcount": { "type": "number" }, "customer_count": { "type": "number" }, "churn_rate": { "type": "number" }, "mrr_growth": { "type": "number" }, "burn": { "type": "number" }, "nrr": { "type": "number" }, "ltv": { "type": "number" }, "cac": { "type": "number" }, "ltv_cac_ratio": { "type": "number" } } }, "source": { "type": "string", "enum": [ "company_metrics_actual", "none" ] }, "mode": { "type": "string", "enum": [ "live_actual" ] }, "periodKey": { "type": [ "string", "null" ] } } }, "Decision": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "content": { "type": "string" }, "domain": { "type": "string" }, "made_at": { "type": "string", "format": "date-time" }, "context": { "type": "string" } } }, "StreamEntry": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "title": { "type": "string", "nullable": true }, "content": { "type": "string" }, "type": { "type": "string" }, "lifecycle": { "type": "string", "enum": [ "vision", "strategy", "execution", "review" ] }, "domain": { "type": "string", "enum": [ "product", "growth", "people", "finance", "operations" ] }, "reversibility": { "type": "string", "nullable": true, "enum": [ "irreversible", "costly", "reversible" ] }, "confidence": { "type": "string", "nullable": true, "enum": [ "validated", "hypothesis", "speculation" ] }, "priority": { "type": "string", "enum": [ "low", "medium", "high" ] }, "status": { "type": "string", "enum": [ "active", "superseded", "archived" ] }, "superseded_by": { "type": "string", "format": "uuid", "nullable": true }, "superseded_at": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "SearchResult": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "title": { "type": "string", "nullable": true }, "content": { "type": "string" }, "domain": { "type": "string", "enum": [ "product", "growth", "people", "finance", "operations" ] }, "type": { "type": "string" }, "lifecycle": { "type": "string", "enum": [ "vision", "strategy", "execution", "review" ] }, "reversibility": { "type": "string", "nullable": true, "enum": [ "irreversible", "costly", "reversible" ] }, "confidence": { "type": "string", "nullable": true, "enum": [ "validated", "hypothesis", "speculation" ] }, "priority": { "type": "string", "enum": [ "low", "medium", "high" ], "description": "Priority level derived from entry's priority score." }, "status": { "type": "string", "enum": [ "active", "superseded", "archived" ] }, "superseded_by": { "type": "string", "format": "uuid", "nullable": true }, "superseded_at": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "SavedViewFilters": { "type": "object", "properties": { "folder_ids": { "type": "array", "items": { "type": "string" } }, "content_type": { "type": "array", "items": { "type": "string" } }, "document_type": { "type": "array", "items": { "type": "string" } }, "domain": { "type": "array", "items": { "type": "string" } }, "sub_domain": { "type": "array", "items": { "type": "string" } }, "sensitivity": { "type": "array", "items": { "type": "string" } }, "lifecycle": { "type": "array", "items": { "type": "string" } }, "status": { "type": "array", "items": { "type": "string" } }, "date_from": { "type": "string" }, "date_to": { "type": "string" }, "created_by": { "type": "array", "items": { "type": "string" } }, "search": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } } } }, "SavedView": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "room_id": { "type": "string", "format": "uuid" }, "company_id": { "type": "string", "format": "uuid" }, "created_by": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "icon": { "type": "string" }, "filters": { "$ref": "#/components/schemas/SavedViewFilters" }, "position": { "type": "integer" }, "is_pinned": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "Artifact": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "company_id": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "description": { "type": "string", "nullable": true }, "content": { "type": "string" }, "type": { "type": "string" }, "version": { "type": "integer" }, "origin_type": { "type": "string", "enum": [ "conversation", "standalone", "import", "cli", "document", "room", "web", "synthesis", "fork" ] }, "content_type": { "type": "string", "nullable": true }, "content_format": { "type": "string" }, "conversation_id": { "type": "string", "format": "uuid", "nullable": true }, "status": { "type": "string", "nullable": true }, "tags": { "type": "array", "items": { "type": "string" } }, "file_path": { "type": "string", "nullable": true }, "artifact_group_id": { "type": "string", "format": "uuid", "nullable": true }, "parent_artifact_id": { "type": "string", "format": "uuid", "nullable": true }, "is_final_version": { "type": "boolean" }, "generated_by": { "type": "string", "nullable": true, "enum": [ "ai", "human", "hybrid" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "ArtifactSearchResult": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "type": { "type": "string" }, "status": { "type": "string" }, "version": { "type": "integer" }, "excerpt": { "type": "string", "description": "First 200 characters of content." }, "created_at": { "type": "string", "format": "date-time" } } }, "Room": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "label": { "type": "string", "description": "URL-safe slug (lowercase alphanumeric with hyphens)." }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "icon": { "type": "string", "nullable": true }, "visibility": { "type": "string", "enum": [ "private", "team", "shared" ] }, "created_at": { "type": "string", "format": "date-time" }, "company_id": { "type": "string", "format": "uuid", "nullable": true }, "artifact_count": { "type": "integer" }, "member_count": { "type": "integer" }, "last_activity_at": { "type": "string", "format": "date-time", "nullable": true }, "created_by": { "type": "string", "format": "uuid", "nullable": true }, "updated_at": { "type": "string", "format": "date-time", "nullable": true }, "charter": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "format": "uuid" }, "label": { "type": "string", "nullable": true }, "name": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true }, "audience": { "type": "array", "items": { "type": "string" } }, "objectives": { "type": "array", "items": { "type": "string" } }, "constraints": { "type": "array", "items": { "type": "string" } }, "data_sources": { "type": "array", "items": { "type": "string" } }, "policies": { "type": "array", "items": { "type": "string" } }, "sensitivity_allowlist": { "type": "array", "items": { "type": "string" } }, "grid_columns": { "type": "array", "items": { "type": "string" } }, "auto_sync_enabled": { "type": "boolean", "nullable": true }, "sync_target_id": { "type": "string", "format": "uuid", "nullable": true } } } } }, "ReportCompany": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "nullable": true }, "slug": { "type": "string", "nullable": true }, "vertical": { "type": "string", "nullable": true } } }, "ReportListItem": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "template_id": { "type": "string", "nullable": true }, "date_range_start": { "type": "string", "format": "date", "nullable": true }, "date_range_end": { "type": "string", "format": "date", "nullable": true }, "date_preset": { "type": "string", "nullable": true }, "generation_time_ms": { "type": "integer", "nullable": true }, "total_entries": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "created_by": { "type": "string", "format": "uuid", "nullable": true }, "report_json": { "type": "object", "nullable": true, "properties": { "summary": { "type": "object", "additionalProperties": true } } }, "markdown_summary": { "type": "string", "nullable": true }, "status": { "type": "string", "nullable": true, "enum": [ "queued", "generating", "draft", "published", "archived", "failed" ] }, "annotations_enabled": { "type": "boolean", "nullable": true } } }, "Report": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "company_id": { "type": "string", "format": "uuid", "nullable": true }, "title": { "type": "string" }, "template_id": { "type": "string", "nullable": true }, "markdown": { "type": "string", "nullable": true }, "markdown_bundle": { "type": "object", "nullable": true, "additionalProperties": { "type": "string" } }, "report_json": { "type": "object", "nullable": true, "additionalProperties": true }, "date_range_start": { "type": "string", "format": "date", "nullable": true }, "date_range_end": { "type": "string", "format": "date", "nullable": true }, "date_preset": { "type": "string", "nullable": true }, "generation_time_ms": { "type": "integer", "nullable": true }, "total_entries": { "type": "integer" }, "created_by": { "type": "string", "format": "uuid", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time", "nullable": true }, "status": { "type": "string", "nullable": true, "enum": [ "queued", "generating", "draft", "published", "archived", "failed" ] }, "edited_markdown": { "type": "string", "nullable": true }, "edited_at": { "type": "string", "format": "date-time", "nullable": true }, "edited_by": { "type": "string", "format": "uuid", "nullable": true }, "last_autosave_at": { "type": "string", "format": "date-time", "nullable": true }, "variant": { "type": "string", "nullable": true, "enum": [ "summary", "executive", "detailed" ] }, "markdown_summary": { "type": "string", "nullable": true }, "markdown_executive": { "type": "string", "nullable": true }, "markdown_detailed": { "type": "string", "nullable": true }, "annotations_enabled": { "type": "boolean", "nullable": true }, "memorized_at": { "type": "string", "format": "date-time", "nullable": true }, "sent_at": { "type": "string", "format": "date-time", "nullable": true }, "error_message": { "type": "string", "nullable": true }, "source_type": { "type": "string", "nullable": true }, "source_attachment_id": { "type": "string", "format": "uuid", "nullable": true }, "parent_report_id": { "type": "string", "format": "uuid", "nullable": true }, "child_report_ids": { "type": "array", "nullable": true, "items": { "type": "string", "format": "uuid" } }, "rollup_summary": { "type": "string", "nullable": true }, "content": { "type": "string", "nullable": true }, "metadata": { "type": "object", "nullable": true, "additionalProperties": true }, "source_entry_ids": { "type": "array", "nullable": true, "items": { "type": "string", "format": "uuid" } }, "source_query": { "type": "object", "nullable": true, "additionalProperties": true }, "company": { "allOf": [ { "$ref": "#/components/schemas/ReportCompany" } ], "nullable": true } } }, "ReportVersionProfile": { "type": "object", "properties": { "name": { "type": "string", "nullable": true }, "email": { "type": "string", "format": "email", "nullable": true } } }, "ReportVersion": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "report_id": { "type": "string", "format": "uuid" }, "markdown": { "type": "string" }, "variant": { "type": "string", "nullable": true, "enum": [ "summary", "executive", "detailed" ] }, "version_number": { "type": "integer" }, "created_by": { "type": "string", "format": "uuid", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "change_description": { "type": "string", "nullable": true }, "created_by_profile": { "allOf": [ { "$ref": "#/components/schemas/ReportVersionProfile" } ], "nullable": true } } }, "ListSelectOption": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "tone": { "type": "string", "enum": [ "charcoal", "taupe", "stone", "sand", "cobalt", "steel", "sage", "mint" ], "nullable": true }, "color": { "type": "string", "nullable": true } } }, "ListAttributeConfig": { "type": "object", "properties": { "options": { "type": "array", "items": { "$ref": "#/components/schemas/ListSelectOption" } }, "currency": { "type": "string" }, "min": { "type": "number" }, "max": { "type": "number" } } }, "CustomListAttribute": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "list_id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "slug": { "type": "string" }, "attribute_type": { "type": "string", "enum": [ "text", "number", "currency", "date", "url", "email", "select", "multi_select", "status", "checkbox", "rating" ] }, "config": { "$ref": "#/components/schemas/ListAttributeConfig" }, "is_required": { "type": "boolean" }, "position": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "CustomListEntry": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "list_id": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "values": { "type": "object", "additionalProperties": true }, "position": { "type": "integer" }, "archived": { "type": "boolean" }, "linked_entity_type": { "type": "string", "nullable": true }, "linked_entity_id": { "type": "string", "format": "uuid", "nullable": true }, "created_by": { "type": "string", "format": "uuid", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "CustomListSummary": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "network_id": { "type": "string", "format": "uuid", "nullable": true }, "company_id": { "type": "string", "format": "uuid", "nullable": true }, "name": { "type": "string" }, "slug": { "type": "string" }, "description": { "type": "string", "nullable": true }, "icon": { "type": "string", "nullable": true }, "color": { "type": "string", "nullable": true }, "entity_type": { "type": "string" }, "context_type": { "type": "string", "nullable": true }, "is_system": { "type": "boolean" }, "position": { "type": "integer" }, "created_by": { "type": "string", "format": "uuid", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "list_attributes_count": { "type": "integer" } } }, "CustomListWithAttributes": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "network_id": { "type": "string", "format": "uuid", "nullable": true }, "company_id": { "type": "string", "format": "uuid", "nullable": true }, "name": { "type": "string" }, "slug": { "type": "string" }, "description": { "type": "string", "nullable": true }, "icon": { "type": "string", "nullable": true }, "color": { "type": "string", "nullable": true }, "entity_type": { "type": "string" }, "context_type": { "type": "string", "nullable": true }, "is_system": { "type": "boolean" }, "position": { "type": "integer" }, "created_by": { "type": "string", "format": "uuid", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "list_attributes": { "type": "array", "items": { "$ref": "#/components/schemas/CustomListAttribute" } } } }, "CompanyInitiativeChild": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "slug": { "type": "string" }, "name": { "type": "string" }, "kind": { "type": "string", "enum": [ "key_result", "blocker", "action" ] }, "completed": { "type": "boolean" }, "owner": { "type": "string", "nullable": true } } }, "CompanyInitiativeTask": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "string", "enum": [ "backlog", "open", "done", "passed", "postponed" ] }, "owner": { "type": "string", "nullable": true }, "sourceKind": { "type": "string", "enum": [ "manual", "suggested_action" ] }, "sourceActionTitle": { "type": "string", "nullable": true }, "position": { "type": "integer" }, "isVirtual": { "type": "boolean" } } }, "CompanyInitiativeSourceEntry": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "domain": { "type": "string" }, "type": { "type": "string" } } }, "CompanyInitiative": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "slug": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "status": { "type": "string" }, "quarter": { "type": "string", "nullable": true }, "owner": { "type": "string", "nullable": true }, "children": { "type": "array", "items": { "$ref": "#/components/schemas/CompanyInitiativeChild" } }, "executionTasks": { "type": "array", "items": { "$ref": "#/components/schemas/CompanyInitiativeTask" } }, "linkedEntityCount": { "type": "integer" }, "sourceEntries": { "type": "array", "items": { "$ref": "#/components/schemas/CompanyInitiativeSourceEntry" } } } }, "PipelineList": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "slug": { "type": "string" }, "created_by": { "type": "string", "format": "uuid", "nullable": true }, "created_at": { "type": "string", "format": "date-time", "nullable": true } } }, "PipelineCreatorProfile": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "nullable": true }, "avatar_url": { "type": "string", "nullable": true } } }, "PipelineFirm": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "nullable": true }, "name": { "type": "string", "nullable": true }, "context_type": { "type": "string", "nullable": true }, "enrichment_level": { "type": "string", "nullable": true }, "enrichment_data": { "type": "object", "nullable": true, "additionalProperties": true }, "enriched_at": { "type": "string", "format": "date-time", "nullable": true }, "context_markdown": { "type": "string", "nullable": true }, "linked_company_id": { "type": "string", "format": "uuid", "nullable": true } } }, "PipelineOperaltaMatch": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "slug": { "type": "string", "nullable": true }, "contextType": { "type": "string", "nullable": true }, "publicPageEnabled": { "type": "boolean" }, "stage": { "type": "string", "nullable": true }, "vertical": { "type": "string", "nullable": true }, "accessStatus": { "type": "string", "enum": [ "member", "pending", "requestable", "unavailable" ] } } }, "PipelineCommunicationLane": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "network", "workspace" ] }, "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "surfaceLabel": { "type": "string" }, "surfaceLabelPlural": { "type": "string" }, "description": { "type": "string" } } }, "PipelineSequenceStage": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "isTerminal": { "type": "boolean" }, "control": { "type": "string", "enum": [ "light", "review", "gated" ] }, "requiredTaskKeys": { "type": "array", "items": { "type": "string" } }, "allowedNextStages": { "type": "array", "items": { "type": "string" } }, "guidance": { "type": "string", "nullable": true } } }, "PipelineSequenceTemplate": { "type": "object", "properties": { "key": { "type": "string" }, "dimension": { "type": "string" }, "contextType": { "type": "string", "nullable": true }, "vertical": { "type": "string", "nullable": true }, "defaultStage": { "type": "string" }, "templateFamily": { "type": "string", "enum": [ "legacy_pipeline", "v3_default" ] }, "stages": { "type": "array", "items": { "$ref": "#/components/schemas/PipelineSequenceStage" } } } }, "PipelineSequence": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "sequenceType": { "type": "string" }, "stage": { "type": "string" }, "stageLabel": { "type": "string" }, "status": { "type": "string" }, "ownerId": { "type": "string", "format": "uuid", "nullable": true }, "startedAt": { "type": "string", "format": "date-time", "nullable": true }, "completedAt": { "type": "string", "format": "date-time", "nullable": true }, "notes": { "type": "string", "nullable": true }, "templateKey": { "type": "string", "nullable": true }, "templateDimension": { "type": "string", "nullable": true }, "template": { "allOf": [ { "$ref": "#/components/schemas/PipelineSequenceTemplate" } ], "nullable": true }, "readiness": { "allOf": [ { "$ref": "#/components/schemas/PipelineSequenceReadiness" } ], "nullable": true }, "pendingStageTransitionApproval": { "allOf": [ { "$ref": "#/components/schemas/PipelinePendingStageTransitionApproval" } ], "nullable": true }, "pendingTypeSwitchApproval": { "allOf": [ { "$ref": "#/components/schemas/PipelinePendingTypeSwitchApproval" } ], "nullable": true } } }, "PipelinePendingStageTransitionApproval": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "requestType": { "type": "string", "enum": [ "pipeline_stage_transition" ] }, "status": { "type": "string", "enum": [ "pending" ] }, "currentStage": { "type": "string" }, "targetStage": { "type": "string" }, "currentStageControl": { "type": "string", "enum": [ "review", "gated" ] }, "requesterId": { "type": "string", "format": "uuid", "nullable": true }, "approverId": { "type": "string", "format": "uuid", "nullable": true }, "requesterName": { "type": "string", "nullable": true }, "companyName": { "type": "string", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "isRequester": { "type": "boolean" }, "isApprover": { "type": "boolean" } } }, "PipelinePendingTypeSwitchApproval": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "requestType": { "type": "string", "enum": [ "pipeline_sequence_type_switch" ] }, "status": { "type": "string", "enum": [ "pending" ] }, "sourceSequenceType": { "type": "string" }, "sourceStage": { "type": "string" }, "targetSequenceType": { "type": "string" }, "targetStage": { "type": "string" }, "completeSource": { "type": "boolean", "enum": [ true ] }, "requesterId": { "type": "string", "format": "uuid", "nullable": true }, "approverId": { "type": "string", "format": "uuid", "nullable": true }, "requesterName": { "type": "string", "nullable": true }, "companyName": { "type": "string", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "isRequester": { "type": "boolean" }, "isApprover": { "type": "boolean" } } }, "PipelineSequenceReadiness": { "type": "object", "properties": { "isReady": { "type": "boolean" }, "requiredTaskCount": { "type": "integer" }, "completedTaskCount": { "type": "integer" }, "incompleteTaskCount": { "type": "integer" }, "missingTaskKeys": { "type": "array", "items": { "type": "string" } }, "openTasks": { "type": "array", "items": { "$ref": "#/components/schemas/PipelineSequenceTask" } } } }, "PipelineSequenceTask": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "nullable": true }, "taskKey": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "string" } } }, "PipelineDealListItem": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "domain": { "type": "string", "nullable": true }, "normalized_domain": { "type": "string", "nullable": true }, "lifecycle_state": { "type": "string", "nullable": true }, "type": { "type": "string" }, "context_type": { "type": "string", "nullable": true }, "stage": { "type": "string", "nullable": true }, "is_lead": { "type": "boolean" }, "is_active": { "type": "boolean" }, "investment_stage": { "type": "string", "nullable": true }, "investment_decision": { "type": "string", "nullable": true }, "investment_rationale": { "type": "string", "nullable": true }, "research_notes": { "type": "string", "nullable": true }, "research_sources": { "type": "string", "nullable": true }, "dd_notes": { "type": "string", "nullable": true }, "dd_checklist": { "type": "string", "nullable": true }, "deck_url": { "type": "string", "nullable": true }, "metrics_url": { "type": "string", "nullable": true }, "source": { "type": "string", "nullable": true }, "confidence": { "type": "number", "nullable": true }, "firm_id": { "type": "string", "format": "uuid", "nullable": true }, "company_id": { "type": "string", "format": "uuid", "nullable": true }, "created_by": { "type": "string", "format": "uuid", "nullable": true }, "created_by_profile": { "allOf": [ { "$ref": "#/components/schemas/PipelineCreatorProfile" } ], "nullable": true }, "owner_id": { "type": "string", "format": "uuid", "nullable": true }, "owner_profile": { "allOf": [ { "$ref": "#/components/schemas/PipelineCreatorProfile" } ], "nullable": true }, "list_id": { "type": "string", "format": "uuid", "nullable": true }, "list_name": { "type": "string", "nullable": true }, "firms": { "allOf": [ { "$ref": "#/components/schemas/PipelineFirm" } ], "nullable": true }, "operaltaMatch": { "allOf": [ { "$ref": "#/components/schemas/PipelineOperaltaMatch" } ], "nullable": true }, "metric_summary": { "type": "object", "nullable": true, "additionalProperties": { "type": "number", "nullable": true } }, "metric_summary_updated_at": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time", "nullable": true }, "updated_at": { "type": "string", "format": "date-time", "nullable": true }, "last_seen_at": { "type": "string", "format": "date-time", "nullable": true }, "sequences": { "type": "array", "items": { "$ref": "#/components/schemas/PipelineSequence" } }, "owner_actor_type": { "type": "string", "nullable": true }, "owner_profile_id": { "type": "string", "format": "uuid", "nullable": true }, "owner_agent_id": { "type": "string", "nullable": true }, "owner_label": { "type": "string", "nullable": true } } }, "PipelineDealDetail": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "domain": { "type": "string", "nullable": true }, "normalized_domain": { "type": "string", "nullable": true }, "lifecycle_state": { "type": "string", "nullable": true }, "type": { "type": "string" }, "context_type": { "type": "string", "nullable": true }, "investment_stage": { "type": "string", "nullable": true }, "investment_decision": { "type": "string", "nullable": true }, "investment_rationale": { "type": "string", "nullable": true }, "research_notes": { "type": "string", "nullable": true }, "research_sources": { "type": "string", "nullable": true }, "dd_notes": { "type": "string", "nullable": true }, "dd_checklist": { "type": "string", "nullable": true }, "deck_url": { "type": "string", "nullable": true }, "metrics_url": { "type": "string", "nullable": true }, "source": { "type": "string", "nullable": true }, "confidence": { "type": "number", "nullable": true }, "firm_id": { "type": "string", "format": "uuid", "nullable": true }, "company_id": { "type": "string", "format": "uuid", "nullable": true }, "created_by": { "type": "string", "format": "uuid", "nullable": true }, "owner_id": { "type": "string", "format": "uuid", "nullable": true }, "created_at": { "type": "string", "format": "date-time", "nullable": true }, "updated_at": { "type": "string", "format": "date-time", "nullable": true }, "last_seen_at": { "type": "string", "format": "date-time", "nullable": true }, "firm": { "allOf": [ { "$ref": "#/components/schemas/PipelineFirm" } ], "nullable": true }, "sequences": { "type": "array", "items": { "$ref": "#/components/schemas/PipelineSequence" } }, "owner_actor_type": { "type": "string", "nullable": true }, "owner_profile_id": { "type": "string", "format": "uuid", "nullable": true }, "owner_agent_id": { "type": "string", "nullable": true }, "owner_label": { "type": "string", "nullable": true } } }, "PipelineMetricObservation": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "metricId": { "type": "string" }, "label": { "type": "string" }, "value": { "type": "number" }, "formattedValue": { "type": "string" }, "periodKey": { "type": "string" }, "periodType": { "type": "string", "enum": [ "month", "quarter", "year" ] }, "source": { "type": "string", "enum": [ "manual", "vc_shared", "ai_inbox", "import", "integration", "founder_provided", "founder_company_metrics" ] }, "sourceLabel": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "verified", "disputed", "rejected" ] }, "origin": { "type": "string", "enum": [ "account", "company" ] }, "confidence": { "type": "number", "nullable": true }, "notes": { "type": "string", "nullable": true }, "updatedAt": { "type": "string", "format": "date-time", "nullable": true } } }, "PipelineMetricTimelineItem": { "type": "object", "properties": { "metricId": { "type": "string" }, "label": { "type": "string" }, "activeObservation": { "allOf": [ { "$ref": "#/components/schemas/PipelineMetricObservation" } ], "nullable": true }, "observations": { "type": "array", "items": { "$ref": "#/components/schemas/PipelineMetricObservation" } }, "hasMultipleSources": { "type": "boolean" } } }, "PipelineMetricTimelinePeriod": { "type": "object", "properties": { "periodKey": { "type": "string" }, "periodType": { "type": "string", "enum": [ "month", "quarter", "year" ] }, "label": { "type": "string" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/PipelineMetricTimelineItem" } } } }, "PipelineDealMetricsResponse": { "type": "object", "properties": { "accountId": { "type": "string", "format": "uuid" }, "companyId": { "type": "string", "format": "uuid", "nullable": true }, "metricsUrl": { "type": "string", "nullable": true }, "timeline": { "type": "array", "items": { "$ref": "#/components/schemas/PipelineMetricTimelinePeriod" } } } }, "PipelineDealMetricMutationResponse": { "type": "object", "properties": { "success": { "type": "boolean" }, "metric": { "allOf": [ { "$ref": "#/components/schemas/PipelineMetricObservation" } ], "nullable": true } } }, "AgentRunInput": { "type": "object", "required": [ "objective", "companyId" ], "properties": { "objective": { "type": "string", "description": "The objective for the agent orchestration run." }, "companyId": { "type": "string", "format": "uuid", "description": "UUID of the target company." }, "context": { "type": "string", "description": "Additional context for the agent." }, "pattern": { "type": "string", "enum": [ "chain", "parallel", "route", "orchestrator-workers", "evaluator-optimizer" ], "description": "Orchestration pattern to use." }, "effort": { "type": "string", "enum": [ "low", "medium", "high", "max" ], "description": "Effort level for the run." }, "skillTrigger": { "type": "string", "description": "Optional skill trigger identifier." }, "callbackEvent": { "type": "string", "description": "Optional event name for async callback notification." } } }, "AgentRunResponse": { "type": "object", "required": [ "success", "runId", "progressUrl", "statusUrl" ], "properties": { "success": { "type": "boolean" }, "runId": { "type": "string", "format": "uuid" }, "progressUrl": { "type": "string", "description": "URL to stream progress events via SSE." }, "statusUrl": { "type": "string", "description": "URL to poll for run status and results." } } }, "AgentRunStatus": { "type": "object", "required": [ "runId", "status", "createdAt", "activeToolClasses", "canCreateArtifacts", "canWriteStreamEntries" ], "properties": { "runId": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "pending", "running", "completed", "failed" ] }, "input": { "type": "object", "description": "The original input for the run." }, "output": { "type": "string", "nullable": true, "description": "Final output text when completed." }, "metrics": { "type": "object", "nullable": true, "description": "Performance metrics for the run." }, "workerResults": { "type": "array", "nullable": true, "items": { "type": "object" }, "description": "Results from individual workers (orchestrator-workers pattern)." }, "evalHistory": { "type": "array", "nullable": true, "items": { "type": "object" }, "description": "Evaluation history (evaluator-optimizer pattern)." }, "error": { "type": "string", "nullable": true, "description": "Error message if the run failed." }, "createdAt": { "type": "string", "format": "date-time" }, "completedAt": { "type": "string", "format": "date-time", "nullable": true }, "parentRunId": { "type": "string", "format": "uuid", "nullable": true }, "role": { "type": "string", "nullable": true }, "target": { "type": "object", "nullable": true, "description": "Structured target metadata for the run or child run." }, "budget": { "type": "object", "nullable": true, "description": "Budget guardrails captured for the run." }, "writePolicy": { "type": "string", "nullable": true, "enum": [ "read_only", "artifact_allowed", "artifact_and_chat_event_allowed" ] }, "childRuns": { "type": "array", "nullable": true, "items": { "type": "object", "required": [ "runId", "parentRunId", "objective", "status", "createdAt" ], "properties": { "runId": { "type": "string", "format": "uuid" }, "parentRunId": { "type": "string", "format": "uuid", "nullable": true }, "role": { "type": "string", "nullable": true }, "taskClass": { "type": "string", "nullable": true }, "objective": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "running", "completed", "failed" ] }, "phase": { "type": "string", "nullable": true, "enum": [ "queued", "planning", "executing", "evaluating", "synthesizing", "finalizing", "complete", "error" ] }, "activeToolClasses": { "type": "array", "nullable": true, "items": { "type": "string", "enum": [ "read", "analyze", "write", "publish", "sync" ] } }, "activeRiskClass": { "type": "string", "nullable": true, "enum": [ "standard", "financial_analysis", "sensitive_write", "external_publish" ] }, "target": { "type": "object", "nullable": true }, "budget": { "type": "object", "nullable": true }, "writePolicy": { "type": "string", "nullable": true, "enum": [ "read_only", "artifact_allowed", "artifact_and_chat_event_allowed" ] }, "toolClasses": { "type": "array", "nullable": true, "items": { "type": "string", "enum": [ "read", "analyze", "write", "publish", "sync" ] } }, "riskClass": { "type": "string", "nullable": true, "enum": [ "standard", "financial_analysis", "sensitive_write", "external_publish" ] }, "output": { "type": "string", "nullable": true }, "error": { "type": "string", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "completedAt": { "type": "string", "format": "date-time", "nullable": true }, "canCreateArtifacts": { "type": "boolean", "description": "Whether this child run may currently persist artifact side effects in its current phase." }, "canWriteStreamEntries": { "type": "boolean", "description": "Whether this child run may currently persist stream-entry side effects in its current phase." } } } }, "activeToolClasses": { "type": "array", "items": { "type": "string", "enum": [ "read", "analyze", "write", "publish", "sync" ] } }, "activeRiskClass": { "type": "string", "nullable": true, "enum": [ "standard", "financial_analysis", "sensitive_write", "external_publish" ] }, "canCreateArtifacts": { "type": "boolean", "description": "Whether the current runtime phase may currently persist artifact side effects." }, "canWriteStreamEntries": { "type": "boolean", "description": "Whether the current runtime phase may currently persist stream-entry side effects." } }, "example": { "activeToolClasses": [], "activeRiskClass": null, "canCreateArtifacts": false, "canWriteStreamEntries": false } }, "KnowledgeTreeDomain": { "type": "object", "properties": { "domainId": { "type": "string" }, "domainLabel": { "type": "string" }, "hasTree": { "type": "boolean" }, "artifactId": { "type": "string", "format": "uuid", "nullable": true }, "vertical": { "type": "string", "nullable": true }, "sections": { "type": "array", "items": { "type": "object" } }, "generatedAt": { "type": "string", "format": "date-time", "nullable": true }, "updatedAt": { "type": "string", "format": "date-time", "nullable": true } } }, "SearchRequest": { "type": "object", "required": [ "query", "companyId" ], "properties": { "query": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Search query text." }, "companyId": { "type": "string", "format": "uuid" }, "roomId": { "type": "string", "format": "uuid", "description": "Optional room to scope the search." }, "limit": { "type": "integer", "minimum": 1, "maximum": 50, "description": "Maximum number of results per category." }, "threshold": { "type": "number", "minimum": 0, "maximum": 1, "description": "Minimum similarity threshold (0-1)." }, "includeFirms": { "type": "boolean", "description": "Also search company/firm profiles alongside artifacts and conversations." } } }, "SearchResponse": { "type": "object", "properties": { "artifacts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "artifactType": { "type": "string" }, "contentPreview": { "type": "string" }, "similarity": { "type": "number" } } } }, "conversations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "summary": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "similarity": { "type": "number" } } } } } }, "ContactCompanyRole": { "type": "object", "required": [ "companyName", "companyId", "role", "contextType", "vertical", "stage" ], "properties": { "companyName": { "type": "string" }, "companyId": { "type": "string", "format": "uuid" }, "role": { "type": "string" }, "contextType": { "type": [ "string", "null" ] }, "vertical": { "type": [ "string", "null" ] }, "stage": { "type": [ "string", "null" ] } } }, "Contact": { "type": "object", "required": [ "id", "personId", "email", "name", "phone", "linkedinUrl", "avatarUrl", "profileId", "source", "tags", "createdAt", "updatedAt", "lastInteractionAt", "companyRoles", "companyName", "companyDomain", "accountId", "enriched", "investorType", "expertise", "location" ], "properties": { "id": { "type": "string", "format": "uuid" }, "personId": { "type": "string", "format": "uuid" }, "email": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "linkedinUrl": { "type": [ "string", "null" ] }, "avatarUrl": { "type": [ "string", "null" ] }, "profileId": { "type": [ "string", "null" ] }, "source": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "lastInteractionAt": { "type": [ "string", "null" ], "format": "date-time" }, "companyRoles": { "type": "array", "items": { "$ref": "#/components/schemas/ContactCompanyRole" } }, "companyName": { "type": [ "string", "null" ] }, "companyDomain": { "type": [ "string", "null" ] }, "accountId": { "type": [ "string", "null" ], "format": "uuid" }, "enriched": { "type": "boolean" }, "investorType": { "type": [ "string", "null" ] }, "expertise": { "type": "array", "items": { "type": "string" } }, "location": { "type": [ "string", "null" ] }, "networkId": { "type": [ "string", "null" ], "format": "uuid" }, "companyId": { "type": [ "string", "null" ], "format": "uuid" }, "checkSizeMin": { "type": [ "number", "null" ] }, "checkSizeMax": { "type": [ "number", "null" ] }, "checkSizeSweetSpot": { "type": [ "number", "null" ] }, "enrichmentData": { "type": [ "object", "null" ], "additionalProperties": true }, "enrichedAt": { "type": [ "string", "null" ], "format": "date-time" } } }, "MetricShareGrant": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "company_id": { "type": "string", "format": "uuid" }, "granted_by": { "type": "string", "format": "uuid", "nullable": true }, "recipient_company_id": { "type": "string", "format": "uuid", "nullable": true }, "recipient_user_id": { "type": "string", "format": "uuid", "nullable": true }, "scope": { "type": "array", "items": { "type": "string", "enum": [ "metrics", "context", "decisions" ] } }, "metric_ids": { "type": "array", "items": { "type": "string" } }, "include_historical": { "type": "boolean" }, "status": { "type": "string", "enum": [ "active", "revoked" ] }, "note": { "type": "string", "nullable": true }, "expires_at": { "type": "string", "format": "date-time", "nullable": true }, "revoked_at": { "type": "string", "format": "date-time", "nullable": true }, "revoked_by": { "type": "string", "format": "uuid", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "RoomListItem": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "label": { "type": "string", "description": "URL-safe slug (lowercase alphanumeric with hyphens)." }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "icon": { "type": "string", "nullable": true }, "visibility": { "type": "string", "enum": [ "private", "team", "shared" ] }, "created_by": { "type": "string", "format": "uuid", "nullable": true }, "created_at": { "type": "string", "format": "date-time", "nullable": true } } }, "RoomSummary": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "label": { "type": "string", "description": "URL-safe slug (lowercase alphanumeric with hyphens)." }, "name": { "type": "string" } } }, "SyncTarget": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "company_id": { "type": "string", "format": "uuid" }, "connection_id": { "type": "string", "format": "uuid" }, "owner": { "type": "string" }, "repo": { "type": "string" }, "branch": { "type": "string" }, "path": { "type": "string" }, "label": { "type": "string" }, "description": { "type": "string", "nullable": true }, "filter_patterns": { "type": "array", "items": { "type": "string" } }, "room_id": { "type": "string", "format": "uuid", "nullable": true }, "auto_sync": { "type": "boolean" }, "auto_sync_on": { "type": "array", "items": { "type": "string" } }, "provider": { "type": "string", "enum": [ "github", "gitlab" ] }, "provider_account_name": { "type": "string", "nullable": true }, "connection_status": { "type": "string", "enum": [ "active", "expired", "revoked" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "GithubTrackedIssue": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "company_id": { "type": "string", "format": "uuid", "nullable": true }, "room_id": { "type": "string", "format": "uuid", "nullable": true }, "issue_url": { "type": "string" }, "issue_number": { "type": "integer" }, "title": { "type": "string" }, "issue_type": { "type": "string", "enum": [ "epic", "feature", "task", "bug" ] }, "state": { "type": "string", "enum": [ "open", "closed" ] }, "decision_content": { "type": "string", "nullable": true }, "stream_entry_id": { "type": "string", "format": "uuid", "nullable": true }, "origin": { "type": "string", "enum": [ "cli", "browser", "webhook" ] }, "tracked_by": { "type": "string", "format": "uuid", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "SyncConnection": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "provider": { "type": "string", "enum": [ "github", "gitlab" ] }, "provider_account_name": { "type": "string", "nullable": true }, "scopes": { "type": "array", "items": { "type": "string" } }, "connected_at": { "type": "string", "format": "date-time" }, "last_used_at": { "type": "string", "format": "date-time", "nullable": true }, "status": { "type": "string", "enum": [ "active", "expired", "revoked" ] } } }, "SyncOperationSummary": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "operation_type": { "type": "string", "enum": [ "push", "pull", "preview" ] }, "status": { "type": "string", "enum": [ "pending", "running", "completed", "failed" ] }, "artifacts_count": { "type": "integer" }, "files_created_count": { "type": "integer" }, "files_updated_count": { "type": "integer" }, "files_deleted_count": { "type": "integer" }, "enrichment_applied": { "type": "boolean" }, "commit_sha": { "type": "string", "nullable": true }, "commit_url": { "type": "string", "nullable": true }, "commit_message": { "type": "string", "nullable": true }, "trigger_source": { "type": "string", "nullable": true }, "started_at": { "type": "string", "format": "date-time", "nullable": true }, "completed_at": { "type": "string", "format": "date-time", "nullable": true }, "error_message": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" } } }, "MetricPreferenceCardPage": { "type": "object", "required": [ "id", "title", "metricIds" ], "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "metricIds": { "type": "array", "items": { "type": "string" } } } }, "MetricPreferences": { "type": "object", "required": [ "vcCompanyId", "requestedMetrics", "tableColumns", "cardPages" ], "properties": { "id": { "type": "string", "format": "uuid" }, "vcCompanyId": { "type": "string", "format": "uuid" }, "requestedMetrics": { "type": "array", "items": { "type": "string" } }, "tableColumns": { "type": "array", "items": { "type": "string" } }, "cardPages": { "type": "array", "items": { "$ref": "#/components/schemas/MetricPreferenceCardPage" } }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "PipelineExistingAccount": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "domain": { "type": "string", "nullable": true }, "type": { "type": "string", "nullable": true }, "contextType": { "type": "string", "nullable": true, "enum": [ "startup", "vc", "pe", "lp", "advisory", "accelerator", "gov", "academic", "cvc", null ] }, "lifecycleState": { "type": "string", "nullable": true }, "firmName": { "type": "string", "nullable": true } } }, "PipelineExistingAccountsResponse": { "type": "object", "properties": { "accounts": { "type": "array", "items": { "$ref": "#/components/schemas/PipelineExistingAccount" } }, "count": { "type": "integer" }, "companyId": { "type": "string", "format": "uuid", "nullable": true }, "networkId": { "type": "string", "format": "uuid", "nullable": true }, "scope": { "type": "string", "enum": [ "company", "network" ] } } }, "PipelineSequenceMutationResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "company": { "$ref": "#/components/schemas/PipelineDealDetail" }, "sequence": { "$ref": "#/components/schemas/PipelineSequence" } } }, "PipelineDealMutationResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "company": { "$ref": "#/components/schemas/PipelineDealDetail" } } }, "PipelineImportResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "created": { "type": "integer" }, "skipped": { "type": "integer" }, "errors": { "type": "array", "items": { "type": "string" } }, "total": { "type": "integer" } } }, "PipelineEnrichFromUrlResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "source": { "type": "string", "enum": [ "firm_cache", "url_only", "live_enrichment" ] }, "normalizedUrl": { "type": "string" }, "domain": { "type": "string" }, "suggestedName": { "type": "string", "nullable": true }, "suggestedContextType": { "type": "string", "enum": [ "startup", "vc", "pe", "lp", "advisory", "accelerator", "gov", "academic", "cvc" ] }, "description": { "type": "string", "nullable": true }, "keyFacts": { "type": "array", "items": { "type": "string" } }, "executionTimeMs": { "type": "integer" } } }, "PipelineUploadResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "url": { "type": "string" }, "type": { "type": "string", "enum": [ "deck", "metrics" ] }, "metricsImportQueued": { "type": "boolean" } } }, "PipelineEnrichResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "queuedType": { "type": "string", "enum": [ "research", "due_diligence", "screening" ] }, "queuedPerspectives": { "type": "array", "items": { "type": "string" } } } }, "PipelinePromoteResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "alreadyPortfolio": { "type": "boolean" }, "company": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "type": { "type": "string" }, "lifecycle_state": { "type": "string", "nullable": true }, "investment_stage": { "type": "string", "nullable": true }, "investment_decision": { "type": "string", "nullable": true }, "updated_at": { "type": "string", "format": "date-time", "nullable": true } } } } }, "PipelineRoomResponse": { "type": "object", "properties": { "roomId": { "type": "string", "format": "uuid" } } }, "CollectRequest": { "type": "object", "required": [ "context", "source", "sink" ], "properties": { "context": { "type": "object", "required": [ "companyId" ], "properties": { "companyId": { "type": "string", "format": "uuid" }, "roomId": { "type": "string", "format": "uuid", "nullable": true }, "chatId": { "type": "string", "format": "uuid", "nullable": true }, "networkId": { "type": "string", "format": "uuid", "nullable": true }, "circleId": { "type": "string", "format": "uuid", "nullable": true } } }, "source": { "oneOf": [ { "type": "object", "required": [ "kind" ], "properties": { "kind": { "type": "string", "enum": [ "csv" ] }, "inline": { "type": "string" }, "storagePath": { "type": "string" }, "fileName": { "type": "string" } } }, { "type": "object", "required": [ "kind", "storagePath", "fileName", "mimeType", "fileSize" ], "properties": { "kind": { "type": "string", "enum": [ "uploaded-file" ] }, "storagePath": { "type": "string" }, "fileName": { "type": "string" }, "mimeType": { "type": "string" }, "fileSize": { "type": "integer", "minimum": 0 } } }, { "type": "object", "required": [ "kind", "documentId" ], "properties": { "kind": { "type": "string", "enum": [ "operalta-file" ] }, "documentId": { "type": "string", "format": "uuid" } } } ], "description": "Current public/CLI sources." }, "sink": { "oneOf": [ { "type": "object", "required": [ "kind" ], "properties": { "kind": { "type": "string", "enum": [ "document" ] }, "targetRoomId": { "type": "string", "format": "uuid" }, "documentType": { "type": "string" } } }, { "type": "object", "required": [ "kind" ], "properties": { "kind": { "type": "string", "enum": [ "list" ] }, "targetListId": { "type": "string", "format": "uuid" }, "createList": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" }, "icon": { "type": "string" }, "linkToRoomId": { "type": "string", "format": "uuid" }, "inferAttributes": { "type": "boolean" } } }, "columnMapping": { "type": "object", "additionalProperties": { "type": "string" } } } }, { "type": "object", "required": [ "kind", "ownerType", "ownerId" ], "properties": { "kind": { "type": "string", "enum": [ "contacts" ] }, "ownerType": { "type": "string", "enum": [ "company", "circle" ] }, "ownerId": { "type": "string", "format": "uuid" } } }, { "type": "object", "required": [ "kind" ], "properties": { "kind": { "type": "string", "enum": [ "accounts" ] }, "networkId": { "type": "string", "format": "uuid" } } }, { "type": "object", "required": [ "kind", "scope" ], "properties": { "kind": { "type": "string", "enum": [ "metrics" ] }, "scope": { "type": "string", "enum": [ "company_actuals", "account_metrics", "budget" ] } }, "description": "Declared but not implemented yet; returns 501." }, { "type": "object", "required": [ "kind", "chatId" ], "properties": { "kind": { "type": "string", "enum": [ "chat-attachment" ] }, "chatId": { "type": "string", "format": "uuid" }, "messageDraftId": { "type": "string", "format": "uuid" } }, "description": "Declared but not implemented yet; returns 501." } ] }, "options": { "type": "object", "properties": { "importBatchId": { "type": "string" }, "dryRun": { "type": "boolean" }, "asyncMode": { "type": "boolean", "description": "Currently refused with 422." } } } } }, "CollectResult": { "type": "object", "properties": { "success": { "type": "boolean" }, "sinkKind": { "type": "string", "enum": [ "document", "list", "contacts", "accounts", "metrics", "chat-attachment" ] }, "artifactIds": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "listId": { "type": "string", "format": "uuid" }, "documentId": { "type": "string", "format": "uuid" }, "importedCount": { "type": "integer" }, "skippedCount": { "type": "integer" }, "batchId": { "type": "string" }, "preview": { "type": "object", "properties": { "rows": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "columns": { "type": "array", "items": { "type": "string" } }, "notes": { "type": "array", "items": { "type": "string" } } } }, "warnings": { "type": "array", "items": { "type": "string" } }, "errors": { "type": "array", "items": { "type": "string" } } } }, "CompanyKnowledgeSearchResults": { "type": "object", "properties": { "artifacts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "type": { "type": "string" }, "content": { "type": "string", "nullable": true }, "snippet": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" } } } }, "documents": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "file_name": { "type": "string" }, "document_type": { "type": "string", "nullable": true }, "suggested_title": { "type": "string", "nullable": true }, "summary": { "type": "string", "nullable": true }, "snippet": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" } } } }, "streams": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "entry_type": { "type": "string" }, "content": { "type": "string", "nullable": true }, "snippet": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" } } } }, "totalCount": { "type": "integer" } } }, "CompanyKnowledgeReadResponse": { "type": "object", "properties": { "item": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "artifact", "document", "stream" ] }, "id": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "content": { "type": "string" }, "truncated": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "metadata": { "type": "object", "additionalProperties": true } } } } }, "FirmEnrichmentResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "firmId": { "type": "string", "format": "uuid", "nullable": true }, "domain": { "type": "string" }, "normalizedUrl": { "type": "string" }, "level": { "type": "string", "enum": [ "basic", "deep", "deeper" ] }, "enrichmentData": { "type": "object", "additionalProperties": true }, "contextMarkdown": { "type": "string", "nullable": true }, "metadata": { "type": "object", "additionalProperties": true } } } } }, "paths": { "/api/company/context": { "get": { "summary": "Get company context", "description": "Returns the company profile \u2014 name, industry, stage, team size, description, and other context fields. This is the core identity data of the company.", "operationId": "getCompanyContext", "tags": [ "Company" ], "parameters": [ { "$ref": "#/components/parameters/companyId" }, { "$ref": "#/components/parameters/XCompanyId" } ], "responses": { "200": { "description": "Company context", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyContext" } } } }, "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": "Company not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/company/metrics": { "get": { "summary": "Get company KPI metrics", "description": "Returns the latest KPI metrics from the newest actual company_metrics row. This is a live internal metrics endpoint, not a published snapshot surface.", "operationId": "getCompanyMetrics", "tags": [ "Company" ], "parameters": [ { "$ref": "#/components/parameters/companyId" }, { "$ref": "#/components/parameters/XCompanyId" } ], "responses": { "200": { "description": "Company metrics", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Metrics" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/company/structure": { "get": { "summary": "Get company structure", "description": "Returns the organizational structure as markdown or parsed JSON trees. Trees include: products, organization, and budgets.", "operationId": "getCompanyStructure", "tags": [ "Company" ], "parameters": [ { "$ref": "#/components/parameters/companyId" }, { "$ref": "#/components/parameters/XCompanyId" }, { "name": "tree_type", "in": "query", "schema": { "type": "string", "enum": [ "all", "products", "organization", "budgets" ], "default": "all" } }, { "name": "format", "in": "query", "schema": { "type": "string", "enum": [ "markdown", "json" ], "default": "markdown" } } ], "responses": { "200": { "description": "Company structure (markdown or JSON)", "content": { "text/markdown": { "schema": { "type": "string" } }, "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "summary": "Update company structure", "description": "Replaces the company structure markdown. The markdown must be valid structure format.", "operationId": "updateCompanyStructure", "tags": [ "Company" ], "parameters": [ { "$ref": "#/components/parameters/XCompanyId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "markdown" ], "properties": { "companyId": { "type": "string", "format": "uuid" }, "markdown": { "type": "string" } } } } } }, "responses": { "200": { "description": "Structure updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/company/structure/node": { "get": { "summary": "Get structure node context", "description": "Returns context for a specific node in the structure tree, optionally including related decisions, metrics, and stream entries.", "operationId": "getStructureNode", "tags": [ "Company" ], "parameters": [ { "$ref": "#/components/parameters/companyId" }, { "$ref": "#/components/parameters/XCompanyId" }, { "name": "node_id", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]+$" }, "description": "Slug identifier of the structure node." }, { "name": "include", "in": "query", "schema": { "type": "string", "default": "decisions" }, "description": "Comma-separated list of data to include: decisions, metrics, entries." } ], "responses": { "200": { "description": "Node context", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/streams/decisions": { "get": { "summary": "List strategic decisions", "description": "Returns recent strategic decisions extracted from the company's memory stream.", "operationId": "getDecisions", "tags": [ "Streams" ], "parameters": [ { "$ref": "#/components/parameters/companyId" }, { "$ref": "#/components/parameters/XCompanyId" }, { "name": "domain", "in": "query", "schema": { "type": "string" }, "description": "Filter by domain (e.g., product, growth, people, finance, operations)." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 20, "default": 5 } } ], "responses": { "200": { "description": "List of decisions", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Decision" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/streams/search": { "get": { "summary": "Search stream entries", "description": "Full-text search across stream entries. Returns a flat array of public stream-entry DTOs ranked by priority score.", "operationId": "searchStreams", "tags": [ "Streams" ], "parameters": [ { "$ref": "#/components/parameters/companyId" }, { "$ref": "#/components/parameters/XCompanyId" }, { "name": "query", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Search query string." }, { "name": "domain", "in": "query", "schema": { "type": "string" }, "description": "Restrict search to a specific domain." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 10 } } ], "responses": { "200": { "description": "Search results (flat array)", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/StreamEntry" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/streams/entries": { "get": { "summary": "List stream entries", "description": "Returns stream entries for a company, optionally filtered by type.", "operationId": "listStreamEntries", "tags": [ "Streams" ], "parameters": [ { "$ref": "#/components/parameters/companyId" }, { "$ref": "#/components/parameters/XCompanyId" }, { "name": "type", "in": "query", "schema": { "type": "string" }, "description": "Filter by entry type (for example decisions, hypotheses, experiments, blockers, wins, learnings)." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } } ], "responses": { "200": { "description": "Stream entries", "content": { "application/json": { "schema": { "type": "object", "properties": { "entries": { "type": "array", "items": { "$ref": "#/components/schemas/StreamEntry" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Create stream entry", "description": "Creates a new stream entry (decision, insight, milestone, or risk) in the company memory.", "operationId": "createStreamEntry", "tags": [ "Streams" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "companyId", "streamId", "title", "content" ], "properties": { "companyId": { "type": "string", "format": "uuid" }, "streamId": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "content": { "type": "string" }, "type": { "type": "string" }, "lifecycle": { "type": "string" }, "domain": { "type": "string" }, "reversibility": { "type": "string" }, "confidence": { "type": "string" } } } } } }, "responses": { "201": { "description": "Entry created", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "success": { "type": "boolean" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/artifacts": { "post": { "summary": "Create artifact", "description": "Creates a new artifact (document, analysis, deck, etc.) in the company workspace.", "operationId": "createArtifact", "tags": [ "Artifacts" ], "parameters": [ { "$ref": "#/components/parameters/XCompanyId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "title", "content" ], "properties": { "title": { "type": "string" }, "content": { "type": "string", "description": "Markdown content." }, "type": { "type": "string", "default": "general_draft" }, "description": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "file_path": { "type": "string" }, "origin_type": { "type": "string", "default": "cli" } } } } } }, "responses": { "201": { "description": "Artifact created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Artifact" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/artifacts/by-path": { "get": { "summary": "Find artifact by file path", "description": "Returns the latest non-deleted artifact matching a file path in the authenticated company context.", "operationId": "findArtifactByPath", "tags": [ "Artifacts" ], "parameters": [ { "$ref": "#/components/parameters/XCompanyId" }, { "name": "path", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Artifact file path to look up." } ], "responses": { "200": { "description": "Artifact lookup result", "content": { "application/json": { "schema": { "type": "object", "properties": { "artifact": { "anyOf": [ { "$ref": "#/components/schemas/Artifact" }, { "type": "null" } ] } } } } } }, "400": { "description": "Missing path parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/artifacts/sync": { "post": { "summary": "Create or update artifact by file path", "description": "Creates or updates an artifact using a CLI-style file path key inside the authenticated company context.", "operationId": "syncArtifactByPath", "tags": [ "Artifacts" ], "parameters": [ { "$ref": "#/components/parameters/XCompanyId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "file_path", "content" ], "properties": { "file_path": { "type": "string" }, "content": { "type": "string" }, "title": { "type": "string" }, "type": { "type": "string", "default": "general_draft" }, "tags": { "type": "array", "items": { "type": "string" } } } } } } }, "responses": { "200": { "description": "Artifact updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "artifact": { "$ref": "#/components/schemas/Artifact" }, "created": { "type": "boolean", "enum": [ false ] } } } } } }, "201": { "description": "Artifact created", "content": { "application/json": { "schema": { "type": "object", "properties": { "artifact": { "$ref": "#/components/schemas/Artifact" }, "created": { "type": "boolean", "enum": [ true ] } } } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/artifacts/generate": { "post": { "summary": "Generate artifact in background", "description": "Creates a placeholder artifact and dispatches background document generation. Use the returned artifactId with /api/artifacts/{id}/stream to watch live SSE chunks.", "operationId": "generateArtifact", "tags": [ "Artifacts" ], "parameters": [ { "$ref": "#/components/parameters/XCompanyId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "prompt" ], "properties": { "prompt": { "type": "string", "description": "User request to turn into a generated document artifact." }, "title": { "type": "string", "description": "Optional title override for the placeholder artifact." }, "type": { "type": "string", "default": "document_draft", "description": "Artifact type to persist." }, "conversationId": { "type": "string", "format": "uuid", "nullable": true, "description": "Optional conversation to link the generated artifact to." }, "webSearch": { "type": "boolean", "default": false, "description": "Whether live web research should augment generation." }, "thinkingBudget": { "type": "integer", "minimum": 0, "default": 0, "description": "Optional thinking budget in tokens for the background generation run." } } } } } }, "responses": { "202": { "description": "Background generation started", "content": { "application/json": { "schema": { "type": "object", "required": [ "runId", "artifactId", "status", "title", "type", "streamUrl" ], "properties": { "runId": { "type": "string", "format": "uuid" }, "artifactId": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "started" ] }, "title": { "type": "string" }, "type": { "type": "string" }, "streamUrl": { "type": "string", "description": "Relative SSE URL for live generation chunks." } } } } } }, "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": "Conversation not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Generation dispatch failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/artifacts/{id}": { "get": { "summary": "Get artifact", "description": "Fetches a single artifact by ID. When using Bearer token, pass X-Company-Id header.", "operationId": "getArtifact", "tags": [ "Artifacts" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/XCompanyId" } ], "responses": { "200": { "description": "Artifact", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Artifact" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "summary": "Update artifact", "description": "Updates an artifact's title, content, description, or tags.", "operationId": "patchArtifact", "tags": [ "Artifacts" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/XCompanyId" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string" }, "content": { "type": "string" }, "description": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } } } } } } }, "responses": { "200": { "description": "Updated artifact", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Artifact" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "summary": "Delete artifact", "description": "Soft-deletes an artifact. When using Bearer token, pass X-Company-Id header.", "operationId": "deleteArtifact", "tags": [ "Artifacts" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/XCompanyId" } ], "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/artifacts/{id}/stream": { "get": { "summary": "Stream artifact generation (SSE)", "description": "Opens a Server-Sent Events stream for a generating artifact. Emits chunk, complete, and error events while the background document job runs.", "operationId": "streamArtifactGeneration", "tags": [ "Artifacts" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Artifact ID to stream." }, { "$ref": "#/components/parameters/XCompanyId" } ], "responses": { "200": { "description": "SSE event stream", "content": { "text/event-stream": { "schema": { "type": "string", "description": "Server-Sent Events stream with artifact generation updates.", "example": "data: {\"type\":\"chunk\",\"artifactId\":\"uuid\",\"text\":\"# Memo\",\"accumulated\":\"# Memo\"}\n\ndata: {\"type\":\"complete\",\"artifactId\":\"uuid\",\"text\":\"# Memo\\n\\nFinal body\"}\n\n" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Artifact not found", "content": { "text/plain": { "schema": { "type": "string", "example": "Not found" } } } }, "409": { "description": "Artifact is not currently generating", "content": { "text/plain": { "schema": { "type": "string", "example": "Not generating" } } } } } } }, "/api/source-documents": { "get": { "summary": "List source documents", "description": "Dual-auth route that lists uploaded source documents for a company with simple offset pagination.", "operationId": "listSourceDocuments", "tags": [ "Documents" ], "security": [ { "BearerAuth": [] }, { "SessionCookie": [] } ], "parameters": [ { "name": "companyId", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 20, "minimum": 1 } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "default": 0, "minimum": 0 } } ], "responses": { "200": { "description": "Paginated source documents", "content": { "application/json": { "schema": { "type": "object", "required": [ "documents", "total", "limit", "offset" ], "properties": { "documents": { "type": "array", "items": { "type": "object", "required": [ "id", "fileName", "createdAt" ], "properties": { "id": { "type": "string", "format": "uuid" }, "fileName": { "type": "string" }, "mimeType": { "type": "string", "nullable": true }, "documentType": { "type": "string", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" } } } }, "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" } } } } } }, "400": { "description": "Missing companyId", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/uploads": { "post": { "summary": "Upload document or initialize signed upload", "description": "Unified document ingress endpoint. Supports direct multipart uploads for API/CLI use and JSON signed-upload initialization for browser flows.", "operationId": "uploadDocument", "tags": [ "Documents" ], "security": [ { "BearerAuth": [] }, { "SessionCookie": [] } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "file", "companyId" ], "properties": { "file": { "type": "string", "format": "binary" }, "companyId": { "type": "string", "format": "uuid" }, "origin": { "type": "string", "enum": [ "onboarding", "chat", "room", "api", "sync" ], "default": "api" }, "originId": { "type": "string", "format": "uuid", "nullable": true }, "targetRoomId": { "type": "string", "format": "uuid", "nullable": true }, "documentType": { "type": "string", "nullable": true } } } }, "application/json": { "schema": { "type": "object", "required": [ "fileName", "mimeType", "fileSize", "companyId", "origin" ], "properties": { "fileName": { "type": "string" }, "mimeType": { "type": "string" }, "fileSize": { "type": "integer", "minimum": 1 }, "fileHash": { "type": "string" }, "companyId": { "type": "string", "format": "uuid" }, "origin": { "type": "string", "enum": [ "onboarding", "chat", "room", "api", "sync" ] }, "originId": { "type": "string", "format": "uuid", "nullable": true }, "targetRoomId": { "type": "string", "format": "uuid", "nullable": true }, "documentType": { "type": "string", "nullable": true }, "sensitivity": { "type": "string", "enum": [ "public", "network", "internal", "restricted" ], "nullable": true } } } } } }, "responses": { "200": { "description": "Upload accepted or signed upload initialized", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "documentId", "extractUrl", "message" ], "properties": { "documentId": { "type": "string", "format": "uuid" }, "artifactId": { "type": "string", "format": "uuid", "nullable": true }, "extractUrl": { "type": "string" }, "message": { "type": "string" } } }, { "type": "object", "required": [ "documentId", "uploadUrl", "storagePath", "extractUrl", "message" ], "properties": { "documentId": { "type": "string", "format": "uuid" }, "uploadUrl": { "type": "string" }, "storagePath": { "type": "string" }, "extractUrl": { "type": "string" }, "message": { "type": "string" } } } ] } } } }, "400": { "description": "Invalid upload request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Upload failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/uploads/{documentId}/confirm": { "post": { "summary": "Confirm signed document upload", "description": "Dual-auth route that confirms a signed upload exists in storage and dispatches asynchronous document processing.", "operationId": "confirmDocumentUpload", "tags": [ "Documents" ], "security": [ { "BearerAuth": [] }, { "SessionCookie": [] } ], "parameters": [ { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Upload already completed", "content": { "application/json": { "schema": { "type": "object", "required": [ "documentId", "status", "extractUrl", "message" ], "properties": { "documentId": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "extractUrl": { "type": "string" }, "message": { "type": "string" } } } } } }, "202": { "description": "Processing started or already running", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "documentId", "eventId", "extractUrl", "message" ], "properties": { "documentId": { "type": "string", "format": "uuid" }, "eventId": { "type": "string" }, "extractUrl": { "type": "string" }, "message": { "type": "string" } } }, { "type": "object", "required": [ "documentId", "status", "extractUrl", "message" ], "properties": { "documentId": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "extractUrl": { "type": "string" }, "message": { "type": "string" } } } ] } } } }, "400": { "description": "Document not ready for confirmation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Document not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/extract/{documentId}": { "get": { "summary": "Stream document extraction (SSE)", "description": "Dual-auth route for TTFT extraction. Emits start, progress, chunk, complete, already_extracted, image_skipped, or error events.", "operationId": "streamDocumentExtraction", "tags": [ "Documents" ], "security": [ { "BearerAuth": [] }, { "SessionCookie": [] } ], "parameters": [ { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "mode", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "image-skip" ] }, "description": "Optional extraction mode override for image-only documents." } ], "responses": { "200": { "description": "SSE event stream", "content": { "text/event-stream": { "schema": { "type": "string", "example": "data: {\"type\":\"start\",\"documentId\":\"uuid\",\"extractionRunId\":\"uuid\"}\n\ndata: {\"type\":\"progress\",\"textLength\":5120,\"chunkIndex\":3}\n\ndata: {\"type\":\"chunk\",\"chunk\":\"Quarterly revenue reached ...\",\"format\":\"markdown\"}\n\ndata: {\"type\":\"complete\",\"textLength\":12842,\"chunkCount\":9}\n\n" } } } }, "401": { "description": "Unauthorized", "content": { "text/plain": { "schema": { "type": "string", "example": "Unauthorized" } } } }, "403": { "description": "Forbidden", "content": { "text/plain": { "schema": { "type": "string", "example": "Forbidden" } } } }, "404": { "description": "Document not found", "content": { "text/plain": { "schema": { "type": "string", "example": "Document not found" } } } } } } }, "/api/uploads/{documentId}": { "get": { "summary": "Get uploaded document status", "description": "Dual-auth route that returns processing status, progress, and public metadata for an uploaded document.", "operationId": "getDocumentStatus", "tags": [ "Documents" ], "security": [ { "BearerAuth": [] }, { "SessionCookie": [] } ], "parameters": [ { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Document status", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "file_name", "mime_type", "processing_status", "progress", "isComplete", "isFailed" ], "properties": { "id": { "type": "string", "format": "uuid" }, "file_name": { "type": "string" }, "mime_type": { "type": "string" }, "file_size": { "type": "integer", "nullable": true }, "origin": { "type": "string", "nullable": true }, "document_type": { "type": "string", "nullable": true }, "document_type_confidence": { "type": "number", "nullable": true }, "suggested_title": { "type": "string", "nullable": true }, "summary": { "type": "string", "nullable": true }, "taxonomy": { "type": "object", "nullable": true }, "sensitivity": { "type": "string", "nullable": true }, "processing_status": { "type": "string" }, "processing_error": { "type": "string", "nullable": true }, "processing_started_at": { "type": "string", "format": "date-time", "nullable": true }, "processing_completed_at": { "type": "string", "format": "date-time", "nullable": true }, "embedding_status": { "type": "string", "nullable": true }, "extraction_artifact_id": { "type": "string", "format": "uuid", "nullable": true }, "origin_id": { "type": "string", "format": "uuid", "nullable": true }, "version_number": { "type": "integer", "nullable": true }, "is_latest_version": { "type": "boolean", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "progress": { "type": "integer" }, "isComplete": { "type": "boolean" }, "isFailed": { "type": "boolean" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Document not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "summary": "Delete uploaded document", "description": "Dual-auth route that deletes the uploaded file and its source document record. Requires manage access to the document.", "operationId": "deleteDocument", "tags": [ "Documents" ], "security": [ { "BearerAuth": [] }, { "SessionCookie": [] } ], "parameters": [ { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Document deleted", "content": { "application/json": { "schema": { "type": "object", "required": [ "success" ], "properties": { "success": { "type": "boolean" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Document not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/uploads/{documentId}/file": { "get": { "summary": "Open uploaded document file", "description": "Dual-auth route that redirects to a short-lived signed file URL for an uploaded document.", "operationId": "openDocumentFile", "tags": [ "Documents" ], "security": [ { "BearerAuth": [] }, { "SessionCookie": [] } ], "parameters": [ { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "mode", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "json" ] }, "description": "Return signed file metadata as JSON instead of redirecting." } ], "responses": { "200": { "description": "Signed file metadata for API clients", "content": { "application/json": { "schema": { "type": "object", "required": [ "downloadUrl", "fileName" ], "properties": { "downloadUrl": { "type": "string" }, "fileName": { "type": "string" }, "mimeType": { "type": "string", "nullable": true }, "fileSize": { "type": "integer", "nullable": true } } } } } }, "307": { "description": "Redirects to signed storage URL" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Document not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/artifacts/search": { "get": { "summary": "Search artifacts", "description": "Full-text search across company artifacts. Returns final versions only (no duplicates).", "operationId": "searchArtifacts", "tags": [ "Artifacts" ], "parameters": [ { "$ref": "#/components/parameters/companyId" }, { "$ref": "#/components/parameters/XCompanyId" }, { "name": "q", "in": "query", "schema": { "type": "string" }, "description": "Search query string. Leave empty to list recent artifacts." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 25, "default": 10 } } ], "responses": { "200": { "description": "Search results", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/ArtifactSearchResult" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/artifacts/bulk-delete": { "post": { "summary": "Bulk delete artifacts", "description": "Soft-deletes multiple artifacts by ID and removes their room associations. Requires write scope.", "operationId": "bulkDeleteArtifacts", "tags": [ "Artifacts" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "artifactIds", "companyId" ], "properties": { "artifactIds": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 100 }, "companyId": { "type": "string", "format": "uuid" } } } } } }, "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "deleted": { "type": "integer" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden \u2014 write scope required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/artifacts/move": { "post": { "summary": "Move artifact between rooms", "description": "Browser-session route that moves the same artifact identity between two rooms. This changes room presence only and does not create a fork.", "operationId": "moveArtifactBetweenRooms", "tags": [ "Artifacts" ], "security": [ { "SessionCookie": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "artifact_id", "from_room_id", "to_room_id", "company_id" ], "properties": { "artifact_id": { "type": "string", "format": "uuid" }, "from_room_id": { "type": "string", "format": "uuid" }, "to_room_id": { "type": "string", "format": "uuid" }, "company_id": { "type": "string", "format": "uuid" } } } } } }, "responses": { "200": { "description": "Artifact moved", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "deduped" ], "properties": { "success": { "type": "boolean" }, "deduped": { "type": "boolean", "description": "True when the destination already had the same artifact identity and the move reused that room presence." } } } } } }, "400": { "description": "Invalid move payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Artifact or room presence not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Move failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/artifacts/copy": { "post": { "summary": "Copy artifact into another room", "description": "Browser-session route that copies an artifact into another room by creating a new fork. Product wording may say Copy; runtime semantics are fork + parentArtifactId.", "operationId": "copyArtifactToRoom", "tags": [ "Artifacts" ], "security": [ { "SessionCookie": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "artifact_id", "from_room_id", "to_room_id", "company_id" ], "properties": { "artifact_id": { "type": "string", "format": "uuid" }, "from_room_id": { "type": "string", "format": "uuid" }, "to_room_id": { "type": "string", "format": "uuid" }, "company_id": { "type": "string", "format": "uuid" } } } } } }, "responses": { "200": { "description": "Artifact fork created", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "artifactId", "artifactGroupId", "parentArtifactId" ], "properties": { "success": { "type": "boolean" }, "artifactId": { "type": "string", "format": "uuid" }, "artifactGroupId": { "type": "string", "format": "uuid" }, "parentArtifactId": { "type": "string", "format": "uuid" } } } } } }, "400": { "description": "Invalid copy payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Artifact or room presence not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Copy failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/rooms": { "get": { "summary": "List rooms", "description": "Returns all rooms for the company, ordered by creation date.", "operationId": "listRooms", "tags": [ "Rooms" ], "parameters": [ { "$ref": "#/components/parameters/companyId" }, { "$ref": "#/components/parameters/XCompanyId" } ], "responses": { "200": { "description": "Room list", "content": { "application/json": { "schema": { "type": "object", "properties": { "rooms": { "type": "array", "items": { "$ref": "#/components/schemas/RoomListItem" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Create room", "description": "Creates a new room (workspace). Optionally attaches a charter defining audience, objectives, and constraints. Requires write scope.", "operationId": "createRoom", "tags": [ "Rooms" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "companyId", "label", "name" ], "properties": { "companyId": { "type": "string", "format": "uuid" }, "label": { "type": "string", "pattern": "^[a-z0-9-]+$", "minLength": 2, "maxLength": 50, "description": "URL-safe slug." }, "name": { "type": "string", "minLength": 2, "maxLength": 100 }, "description": { "type": "string", "maxLength": 500 }, "icon": { "type": "string", "maxLength": 10 }, "visibility": { "type": "string", "enum": [ "private", "team", "shared" ], "default": "private" }, "charter": { "type": "object", "properties": { "audience": { "type": "array", "items": { "type": "string" } }, "objectives": { "type": "array", "items": { "type": "string" } }, "constraints": { "type": "array", "items": { "type": "string" } }, "data_sources": { "type": "array", "items": { "type": "string" } }, "policies": { "type": "array", "items": { "type": "string" } } } } } } } } }, "responses": { "201": { "description": "Room created", "content": { "application/json": { "schema": { "type": "object", "properties": { "room": { "$ref": "#/components/schemas/RoomSummary" } } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden \u2014 write scope required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/rooms/{roomId}/artifacts": { "get": { "summary": "List room artifacts", "description": "Returns room-visible artifacts linked to a room, with optional limit/offset pagination and charter-driven sensitivity filtering.", "operationId": "listRoomArtifacts", "tags": [ "Rooms" ], "parameters": [ { "name": "roomId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/companyId" }, { "$ref": "#/components/parameters/XCompanyId" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 500 }, "description": "Optional page size for room artifacts. Defaults to the route fallback when omitted." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 }, "description": "Optional row offset for room artifacts pagination." } ], "responses": { "200": { "description": "Room artifacts", "content": { "application/json": { "schema": { "type": "object", "properties": { "artifacts": { "type": "array", "items": { "$ref": "#/components/schemas/Artifact" } }, "pagination": { "type": "object", "properties": { "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" } } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Room not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Failed to load room charter policies or enforce artifact visibility rules", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Link document to room", "description": "Links a source document to a room by creating or reusing an artifact. Requires write scope.", "operationId": "linkDocumentToRoom", "tags": [ "Rooms" ], "parameters": [ { "name": "roomId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "companyId", "documentId" ], "properties": { "companyId": { "type": "string", "format": "uuid" }, "documentId": { "type": "string", "format": "uuid" } } } } } }, "responses": { "200": { "description": "Document linked (new or reused artifact)", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "artifactId": { "type": "string", "format": "uuid" }, "artifactGroupId": { "type": "string", "format": "uuid" }, "reused": { "type": "boolean" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden \u2014 write scope required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Room or document not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/rooms/{roomId}/artifacts/generate-preview-from-artifact": { "post": { "summary": "Generate readable room artifact preview", "description": "Dual-auth route that derives a markdown preview artifact from a non-markdown room artifact. The alias /api/rooms/{roomId}/artifacts/create-from-artifact points to the same implementation.", "operationId": "generateRoomArtifactPreview", "tags": [ "Rooms" ], "security": [ { "BearerAuth": [] }, { "SessionCookie": [] } ], "parameters": [ { "name": "roomId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "companyId", "sourceArtifactId" ], "properties": { "companyId": { "type": "string", "format": "uuid" }, "sourceArtifactId": { "type": "string", "format": "uuid" }, "title": { "type": "string", "nullable": true } } } } } }, "responses": { "200": { "description": "Preview artifact created", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "artifactId", "artifactGroupId" ], "properties": { "success": { "type": "boolean" }, "artifactId": { "type": "string", "format": "uuid" }, "artifactGroupId": { "type": "string", "format": "uuid" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Room or source artifact not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Artifact is already readable markdown", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/reports": { "get": { "summary": "List reports", "description": "Returns all saved reports (draft and published) for the company. Supports Bearer API keys and browser sessions. Bearer callers provide companyId or X-Company-Id.", "operationId": "listReports", "tags": [ "Reports" ], "parameters": [ { "$ref": "#/components/parameters/companyId" }, { "$ref": "#/components/parameters/XCompanyId" } ], "responses": { "200": { "description": "Report list", "content": { "application/json": { "schema": { "type": "object", "properties": { "reports": { "type": "array", "items": { "$ref": "#/components/schemas/ReportListItem" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Create draft report", "description": "Creates a draft report from a generated report JSON payload and markdown bundle. Supports Bearer callers with reports:write; Bearer callers can bind the company from the request body or X-Company-Id.", "operationId": "createReport", "tags": [ "Reports" ], "parameters": [ { "$ref": "#/components/parameters/XCompanyId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "companyId", "title", "templateId", "reportJson" ], "properties": { "companyId": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "templateId": { "type": "string" }, "markdownBundle": { "type": "object", "additionalProperties": true }, "reportJson": { "type": "object", "additionalProperties": true }, "dateRangeStart": { "type": "string", "format": "date", "nullable": true }, "dateRangeEnd": { "type": "string", "format": "date", "nullable": true }, "datePreset": { "type": "string", "nullable": true } } } } } }, "responses": { "200": { "description": "Draft report created", "content": { "application/json": { "schema": { "type": "object", "properties": { "report": { "$ref": "#/components/schemas/Report" } } } } } }, "400": { "description": "Missing required fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden \u2014 internal company access required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "summary": "Update a draft report variant", "description": "Updates a draft report variant and stores a report_versions snapshot before editing. Supports Bearer callers with reports:write; Bearer callers must pass X-Company-Id.", "operationId": "updateReport", "tags": [ "Reports" ], "parameters": [ { "$ref": "#/components/parameters/XCompanyId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "reportId", "editedMarkdown", "variant" ], "properties": { "reportId": { "type": "string", "format": "uuid" }, "editedMarkdown": { "type": "string" }, "variant": { "type": "string", "enum": [ "summary", "executive", "detailed" ] }, "changeDescription": { "type": "string", "nullable": true } } } } } }, "responses": { "200": { "description": "Draft report updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "report": { "$ref": "#/components/schemas/Report" }, "version": { "type": "integer" } } } } } }, "400": { "description": "Invalid edit payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden \u2014 internal company access required or report not editable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Report not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/reports/{id}": { "get": { "summary": "Get report", "description": "Returns a single report by ID. Supports Bearer API keys and browser sessions. Bearer callers pass X-Company-Id.", "operationId": "getReport", "tags": [ "Reports" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/XCompanyId" } ], "responses": { "200": { "description": "Report", "content": { "application/json": { "schema": { "type": "object", "properties": { "report": { "$ref": "#/components/schemas/Report" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden \u2014 internal company access required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "summary": "Delete report", "description": "Deletes a report. Requires write scope for Bearer auth.", "operationId": "deleteReport", "tags": [ "Reports" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/XCompanyId" } ], "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden \u2014 write scope required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/reports/{id}/autosave": { "post": { "summary": "Autosave a draft report", "description": "Saves draft edits without creating a formal version snapshot unless createVersion=true. Supports Bearer callers with reports:write; Bearer callers should pass X-Company-Id.", "operationId": "autosaveReport", "tags": [ "Reports" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/XCompanyId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "editedMarkdown", "variant" ], "properties": { "editedMarkdown": { "type": "string" }, "variant": { "type": "string", "enum": [ "summary", "executive", "detailed" ] }, "createVersion": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "Autosave completed", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "autosavedAt": { "type": "string", "format": "date-time" }, "versionCreated": { "type": "boolean" } } } } } }, "400": { "description": "Invalid autosave payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden \u2014 internal company access required or report not editable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Report not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/reports/{id}/metrics": { "get": { "summary": "Get frozen report metric snapshots", "description": "Returns the report_metric_snapshots attached to a report. This route is intentionally snapshot-only and never falls back to live company_metrics when snapshots are missing.", "operationId": "getReportMetrics", "tags": [ "Reports" ], "security": [ { "SessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Report metric snapshots", "content": { "application/json": { "schema": { "type": "object", "properties": { "metrics": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "report_id": { "type": "string", "format": "uuid" }, "metric_id": { "type": "string" }, "metric_source": { "type": "string", "enum": [ "datapack", "stream", "product" ], "nullable": true }, "company_id": { "type": "string", "format": "uuid", "nullable": true }, "stage": { "type": "string", "nullable": true }, "vertical": { "type": "string", "nullable": true }, "value": { "type": "number", "nullable": true }, "formatted_value": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "green", "yellow", "red", "na" ], "nullable": true }, "benchmark_target": { "type": "string", "nullable": true }, "previous_value": { "type": "number", "nullable": true }, "delta_percent": { "type": "number", "nullable": true }, "benchmark_percentile": { "type": "integer", "nullable": true }, "source_period_key": { "type": "string", "nullable": true }, "calculation_params": { "type": "object", "nullable": true, "additionalProperties": true }, "captured_at": { "type": "string", "format": "date-time", "nullable": true } } } }, "source": { "type": "string", "enum": [ "report_metric_snapshots" ] }, "missingSnapshots": { "type": "boolean" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Report not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Failed to fetch snapshots", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/reports/{id}/versions": { "get": { "summary": "List report versions", "description": "Returns the version history for a report, ordered by version_number descending. Supports Bearer callers with reports:read; Bearer callers should pass X-Company-Id.", "operationId": "listReportVersions", "tags": [ "Reports" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/XCompanyId" } ], "responses": { "200": { "description": "Report version history", "content": { "application/json": { "schema": { "type": "object", "properties": { "versions": { "type": "array", "items": { "$ref": "#/components/schemas/ReportVersion" } }, "total": { "type": "integer" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden \u2014 internal company access required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Report not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Restore a report version", "description": "Restores a previous report version into the current draft. Supports Bearer callers with reports:write; Bearer callers should pass X-Company-Id.", "operationId": "restoreReportVersion", "tags": [ "Reports" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/XCompanyId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "versionNumber" ], "properties": { "versionNumber": { "type": "integer" } } } } } }, "responses": { "200": { "description": "Report version restored", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "report": { "$ref": "#/components/schemas/Report" }, "restoredFromVersion": { "type": "integer" } } } } } }, "400": { "description": "Invalid restore request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden \u2014 internal company access required or report not editable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Report or version not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Stored version has invalid variant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/reports/{id}/publish": { "post": { "summary": "Publish report", "description": "Marks a draft report as published and queues report memorization. Public sharing is handled separately via /api/reports/share. Requires reports:write plus company admin or founder access.", "operationId": "publishReport", "tags": [ "Reports" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/XCompanyId" } ], "responses": { "200": { "description": "Report published", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "report": { "$ref": "#/components/schemas/Report" }, "memorizeQueued": { "type": "boolean" }, "memorizeJobId": { "type": "string", "nullable": true }, "warning": { "type": "string", "nullable": true } } } } } }, "400": { "description": "Already published", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden \u2014 admin/founder access required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/reports/{id}/send": { "post": { "summary": "Send a frozen report publication", "description": "Creates a frozen send record for a report. In audience mode it also queues delivery to the resolved recipients. Supports browser sessions and Bearer callers with reports:write.", "operationId": "sendReport", "tags": [ "Reports" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/XCompanyId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "audience": { "type": "object", "properties": { "users": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "circles": { "type": "array", "items": { "type": "string" } }, "networks": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "emails": { "type": "array", "items": { "type": "string", "format": "email" } } } }, "recipients": { "type": "array", "items": { "type": "string", "format": "email" } }, "note": { "type": "string" }, "correctsSendId": { "type": "string", "format": "uuid", "nullable": true }, "correctionReason": { "type": "string", "nullable": true }, "emailOptions": { "type": "object", "properties": { "layout": { "type": "string", "enum": [ "minimal", "standard", "detailed" ] }, "summaryType": { "type": "string", "enum": [ "summary", "executive" ] }, "showMetrics": { "type": "boolean" } } } } } } } }, "responses": { "200": { "description": "Report send created", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "sendId": { "type": "string", "format": "uuid" }, "shareUrl": { "type": "string", "format": "uri" }, "periodKey": { "type": "string" }, "periodLabel": { "type": "string" }, "versionNumber": { "type": "integer" }, "recipients": { "type": "array", "items": { "type": "string", "format": "email" } }, "recipientCount": { "type": "integer" }, "mode": { "type": "string", "enum": [ "audience", "legacy" ] }, "viewerPolicy": { "type": "object", "additionalProperties": true } } } } } }, "400": { "description": "Invalid send request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden \u2014 admin company access required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Report not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Report is already frozen or correction target conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/reports/share": { "post": { "summary": "Create or revoke a report public link", "description": "Creates, reuses, or revokes a public share link for a report. The report must already be published before a public link can be created. Supports browser sessions and Bearer callers with reports:write.", "operationId": "shareReport", "tags": [ "Reports" ], "parameters": [ { "$ref": "#/components/parameters/XCompanyId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string", "format": "uuid" }, "access": { "type": "string", "enum": [ "restricted", "anyone-view" ] }, "action": { "type": "string", "enum": [ "revoke" ] }, "expiresInDays": { "type": "integer", "nullable": true, "description": "Optional number of days before an anyone-view public link expires." } } } } } }, "responses": { "200": { "description": "Share link state", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "revoked": { "type": "boolean" }, "token": { "type": "string", "nullable": true }, "url": { "type": "string", "format": "uri" }, "viewerPolicy": { "type": "object", "additionalProperties": true } } } } } }, "400": { "description": "Invalid request or report not published", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden \u2014 admin company access required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Report not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Public link blocked by viewer policy", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/oauth/authorize": { "get": { "summary": "Start an OAuth PKCE authorization flow", "description": "Validates `client_id`, `redirect_uri`, PKCE parameters, and requested scopes, stores the request in a signed cookie, and redirects the browser to the consent screen.", "operationId": "oauthAuthorize", "tags": [ "Auth" ], "parameters": [ { "name": "client_id", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "redirect_uri", "in": "query", "required": true, "schema": { "type": "string", "format": "uri" } }, { "name": "response_type", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "code" ] } }, { "name": "code_challenge_method", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "S256" ] } }, { "name": "code_challenge", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "scope", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Space-delimited scope string. Defaults to `write`." }, { "name": "state", "in": "query", "required": true, "schema": { "type": "string", "minLength": 16 } } ], "responses": { "302": { "description": "Redirects the browser to the consent screen." }, "400": { "description": "Invalid OAuth request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "error_description": { "type": "string", "nullable": true } } } } } } } }, "post": { "summary": "Complete OAuth consent and create an authorization code redirect", "description": "Browser-session route. Reads the signed OAuth request cookie, verifies the logged-in user, enforces company access when needed, and returns a canonical `{ redirect_url }` payload for the CLI/browser callback.", "operationId": "oauthAuthorizeConsent", "tags": [ "Auth" ], "security": [ { "SessionCookie": [] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "company_id": { "type": "string", "format": "uuid", "description": "Required when the requested scopes are company-bound." }, "denied": { "type": "boolean", "description": "Set to true to deny consent and receive an access_denied redirect." } } } } } }, "responses": { "200": { "description": "Consent outcome redirect payload", "content": { "application/json": { "schema": { "type": "object", "properties": { "redirect_url": { "type": "string", "format": "uri" } } } } } }, "400": { "description": "Invalid OAuth request or missing company context", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "error_description": { "type": "string", "nullable": true } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden \u2014 company access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/cli/authorize": { "post": { "summary": "Issue a legacy CLI token", "description": "Browser-session route. Generates a legacy CLI token for compatibility checks, smoke tests, and direct token workflows. Prefer OAuth PKCE for the standard CLI login flow.", "operationId": "authorizeCliLegacyToken", "tags": [ "Auth" ], "security": [ { "SessionCookie": [] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "format": "uuid", "description": "Optional company to bind the issued token to. Requires internal company-wide access." }, "state": { "type": "string", "description": "Optional opaque client state for compatibility callers." } } } } } }, "responses": { "200": { "description": "Legacy CLI token issued", "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "object", "properties": { "accessToken": { "type": "string" }, "refreshToken": { "type": "string" }, "expiresAt": { "type": "integer", "description": "Unix timestamp in milliseconds." }, "userId": { "type": "string" }, "email": { "type": "string" }, "companyId": { "type": "string", "format": "uuid", "nullable": true }, "companyName": { "type": "string", "nullable": true }, "scope": { "type": "string", "description": "Canonical space-delimited scope string for the token." }, "scopes": { "type": "array", "items": { "type": "string" } } } } } } } } }, "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": "Forbidden \u2014 internal company-wide access required for company-scoped tokens", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "summary": "Validate a legacy CLI token", "description": "Bearer route. Validates a previously issued legacy CLI token and returns the canonical identity and scope DTO. Pass `?touch=false` to skip updating `last_used_at`.", "operationId": "validateCliLegacyToken", "tags": [ "Auth" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "touch", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "false" ] }, "description": "Set to `false` to validate without updating the token's `last_used_at` timestamp." } ], "responses": { "200": { "description": "Legacy token is valid", "content": { "application/json": { "schema": { "type": "object", "properties": { "valid": { "type": "boolean", "enum": [ true ] }, "userId": { "type": "string" }, "email": { "type": "string" }, "companyId": { "type": "string", "format": "uuid", "nullable": true }, "companyName": { "type": "string", "nullable": true }, "expiresAt": { "type": "integer", "description": "Unix timestamp in milliseconds." }, "scope": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } } } } } } }, "401": { "description": "Unauthorized or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "summary": "Revoke the current legacy CLI token", "description": "Bearer route. Revokes the presented legacy CLI token and returns a canonical success payload.", "operationId": "revokeCliLegacyToken", "tags": [ "Auth" ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Legacy token revoked", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "message": { "type": "string" } } } } } }, "401": { "description": "Missing authorization header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/oauth/token": { "post": { "summary": "OAuth token endpoint", "description": "Issues OAuth tokens for `authorization_code`, `refresh_token`, and `client_credentials` grants. The response follows RFC 6749 token response semantics and includes CORS headers.", "operationId": "oauthToken", "tags": [ "Auth" ], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "grant_type" ], "properties": { "grant_type": { "type": "string", "enum": [ "authorization_code", "refresh_token", "client_credentials" ] }, "code": { "type": "string" }, "code_verifier": { "type": "string" }, "client_id": { "type": "string" }, "client_secret": { "type": "string" }, "redirect_uri": { "type": "string", "format": "uri" }, "refresh_token": { "type": "string" }, "scope": { "type": "string", "description": "Optional narrower space-delimited scope string." } } } } } }, "responses": { "200": { "description": "OAuth token response", "content": { "application/json": { "schema": { "type": "object", "properties": { "access_token": { "type": "string" }, "token_type": { "type": "string", "enum": [ "Bearer" ] }, "expires_in": { "type": "integer" }, "scope": { "type": "string" }, "refresh_token": { "type": "string" } }, "required": [ "access_token", "token_type", "expires_in", "scope" ] } } } }, "400": { "description": "Invalid OAuth request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "error_description": { "type": "string", "nullable": true } } } } } }, "401": { "description": "Client authentication failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "error_description": { "type": "string", "nullable": true } } } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "error_description": { "type": "string", "nullable": true } } } } } } } } }, "/api/oauth/revoke": { "post": { "summary": "OAuth token revocation endpoint", "description": "RFC 7009 token revocation. Accepts access or refresh tokens and always returns HTTP 200 with an empty JSON object to avoid token disclosure.", "operationId": "oauthRevoke", "tags": [ "Auth" ], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "token": { "type": "string" }, "client_id": { "type": "string" }, "client_secret": { "type": "string" } }, "required": [ "token" ] } } } }, "responses": { "200": { "description": "Token revocation response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false } } } } } } }, "/api/cli/tokens": { "get": { "summary": "List API keys", "description": "Browser-session route. Returns all API keys for the authenticated user with canonical `label` + `scopes` fields and compatibility aliases for older clients.", "operationId": "listTokens", "tags": [ "Auth" ], "security": [ { "SessionCookie": [] } ], "responses": { "200": { "description": "Token list", "content": { "application/json": { "schema": { "type": "object", "properties": { "tokens": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "label": { "type": "string", "description": "Canonical human-readable label for the key." }, "user_agent": { "type": "string", "description": "Compatibility alias for `label`." }, "scope": { "type": "string", "description": "Raw space-delimited scope string stored with the key." }, "scopes": { "type": "array", "description": "Canonical normalized scope list for the key.", "items": { "type": "string" } }, "company_id": { "type": "string", "format": "uuid", "nullable": true }, "company_name": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": "string", "format": "date-time", "nullable": true }, "last_used_at": { "type": "string", "format": "date-time", "nullable": true } } } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Create API key", "description": "Browser-session route. Creates a new API key bound to the user and optionally a company. Returns the plaintext key once \u2014 store it securely.", "operationId": "createToken", "tags": [ "Auth" ], "security": [ { "SessionCookie": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "label": { "type": "string", "description": "Human-readable label for this key." }, "companyId": { "type": "string", "format": "uuid", "description": "Optional company to scope the key to." }, "expiresInDays": { "type": "integer", "description": "Number of days until expiration.", "default": 90 }, "scope": { "type": "string", "description": "Legacy or explicit scopes as a single space-delimited string. Defaults to `write`." }, "scopes": { "type": "array", "description": "Preferred explicit scope list. Equivalent to `scope` after normalization.", "items": { "type": "string" } } } } } } }, "responses": { "200": { "description": "Token created. The apiKey is shown only once.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "apiKey": { "type": "string", "description": "The plaintext API key. Shown only once." }, "token": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "label": { "type": "string" }, "user_agent": { "type": "string", "description": "Compatibility alias for `label`." }, "company_id": { "type": "string", "format": "uuid", "nullable": true }, "company_name": { "type": "string", "nullable": true }, "scope": { "type": "string", "description": "Raw space-delimited scope string stored with the key." }, "scopes": { "type": "array", "items": { "type": "string" } }, "created_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": "string", "format": "date-time" }, "last_used_at": { "type": "string", "format": "date-time", "nullable": true } } }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/cli/tokens/{id}": { "delete": { "summary": "Revoke API key", "description": "Browser-session route. Revokes an API key owned by the authenticated user.", "operationId": "revokeToken", "tags": [ "Auth" ], "security": [ { "SessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Token revoked", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "tokenId": { "type": "string", "format": "uuid" }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Token not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/portfolio/pipeline": { "get": { "summary": "List pipeline deals", "description": "Returns pipeline deals scoped to the authenticated portfolio context.", "operationId": "listPipelineDeals", "tags": [ "Pipeline" ], "parameters": [ { "name": "investment_stage", "in": "query", "schema": { "type": "string" }, "description": "Filter by stage (research, intro, diligence, term_sheet, closed, passed, portfolio)." }, { "name": "investment_decision", "in": "query", "schema": { "type": "string" }, "description": "Filter by decision (undecided, pass, invest, monitor, follow_on)." }, { "name": "account_type", "in": "query", "schema": { "type": "string" }, "description": "Filter by account type (startup, lp, advisor)." }, { "name": "context_type", "in": "query", "schema": { "type": "string" }, "description": "Filter by context type." }, { "name": "companyId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Company UUID for company-scoped pipeline access. Required for Bearer tokens unless the token is company-bound." }, { "$ref": "#/components/parameters/XCompanyId" }, { "name": "networkId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Optional legacy vc_portfolio network lane UUID for browser/session callers." }, { "name": "listId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Optional pipeline list rail UUID. When present, reads and writes are scoped to that rail." }, { "name": "c", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Optional company slug used by browser/session callers to resolve company scope." }, { "name": "scope", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "company", "network" ], "default": "company" }, "description": "Pipeline authority scope. Company scope is the default and the only Bearer-token mode." } ], "responses": { "200": { "description": "Pipeline deals", "content": { "application/json": { "schema": { "type": "object", "properties": { "companies": { "type": "array", "items": { "$ref": "#/components/schemas/PipelineDealListItem" } }, "lists": { "type": "array", "items": { "$ref": "#/components/schemas/PipelineList" } }, "networkId": { "type": "string", "format": "uuid", "nullable": true }, "companyId": { "type": "string", "format": "uuid", "nullable": true }, "metadata": { "type": "object", "additionalProperties": true } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No portfolio context found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Add pipeline deal", "description": "Adds a new company/deal to pipeline. Website can trigger enrichment.", "operationId": "addPipelineDeal", "tags": [ "Pipeline" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" }, "website": { "type": "string", "nullable": true }, "contextType": { "type": "string" }, "investmentStage": { "type": "string", "nullable": true }, "investmentDecision": { "type": "string", "nullable": true }, "investmentRationale": { "type": "string", "nullable": true }, "source": { "type": "string", "nullable": true } } } } } }, "responses": { "200": { "description": "Deal created", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "company": { "$ref": "#/components/schemas/PipelineDealDetail" }, "alreadyExists": { "type": "boolean" }, "placement": { "type": "object", "nullable": true, "properties": { "listId": { "type": "string", "format": "uuid", "nullable": true }, "listName": { "type": "string", "nullable": true } } } } } } } }, "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" } } } } }, "parameters": [ { "name": "companyId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Company UUID for company-scoped pipeline access. Required for Bearer tokens unless the token is company-bound." }, { "$ref": "#/components/parameters/XCompanyId" }, { "name": "networkId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Optional legacy vc_portfolio network lane UUID for browser/session callers." }, { "name": "listId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Optional pipeline list rail UUID. When present, reads and writes are scoped to that rail." }, { "name": "c", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Optional company slug used by browser/session callers to resolve company scope." }, { "name": "scope", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "company", "network" ], "default": "company" }, "description": "Pipeline authority scope. Company scope is the default and the only Bearer-token mode." } ] } }, "/api/portfolio/pipeline/{id}": { "get": { "summary": "Get pipeline deal", "description": "Get detailed information for one pipeline deal.", "operationId": "getPipelineDeal", "tags": [ "Pipeline" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "companyId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Company UUID for company-scoped pipeline access. Required for Bearer tokens unless the token is company-bound." }, { "$ref": "#/components/parameters/XCompanyId" }, { "name": "networkId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Optional legacy vc_portfolio network lane UUID for browser/session callers." }, { "name": "listId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Optional pipeline list rail UUID. When present, reads and writes are scoped to that rail." }, { "name": "c", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Optional company slug used by browser/session callers to resolve company scope." }, { "name": "scope", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "company", "network" ], "default": "company" }, "description": "Pipeline authority scope. Company scope is the default and the only Bearer-token mode." } ], "responses": { "200": { "description": "Deal detail", "content": { "application/json": { "schema": { "type": "object", "properties": { "account": { "$ref": "#/components/schemas/PipelineDealDetail" } } } } } }, "400": { "description": "Invalid account ID", "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" } } } } } }, "put": { "summary": "Update pipeline deal", "description": "Update stage, decision, rationale, list assignment, and basic company fields.", "operationId": "updatePipelineDeal", "tags": [ "Pipeline" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "companyId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Company UUID for company-scoped pipeline access. Required for Bearer tokens unless the token is company-bound." }, { "$ref": "#/components/parameters/XCompanyId" }, { "name": "networkId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Optional legacy vc_portfolio network lane UUID for browser/session callers." }, { "name": "listId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Optional pipeline list rail UUID. When present, reads and writes are scoped to that rail." }, { "name": "c", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Optional company slug used by browser/session callers to resolve company scope." }, { "name": "scope", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "company", "network" ], "default": "company" }, "description": "Pipeline authority scope. Company scope is the default and the only Bearer-token mode." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "website": { "type": "string", "nullable": true }, "contextType": { "type": "string" }, "investmentStage": { "type": "string", "nullable": true }, "investmentDecision": { "type": "string", "nullable": true }, "investmentRationale": { "type": "string", "nullable": true }, "listId": { "type": "string", "format": "uuid", "nullable": true } } } } } }, "responses": { "200": { "description": "Deal updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "company": { "$ref": "#/components/schemas/PipelineDealDetail" } } } } } }, "400": { "description": "Invalid request", "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": "Archive pipeline deal", "description": "Archives (soft-deletes) a pipeline deal.", "operationId": "archivePipelineDeal", "tags": [ "Pipeline" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "companyId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Company UUID for company-scoped pipeline access. Required for Bearer tokens unless the token is company-bound." }, { "$ref": "#/components/parameters/XCompanyId" }, { "name": "networkId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Optional legacy vc_portfolio network lane UUID for browser/session callers." }, { "name": "listId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Optional pipeline list rail UUID. When present, reads and writes are scoped to that rail." }, { "name": "c", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Optional company slug used by browser/session callers to resolve company scope." }, { "name": "scope", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "company", "network" ], "default": "company" }, "description": "Pipeline authority scope. Company scope is the default and the only Bearer-token mode." } ], "responses": { "200": { "description": "Deal archived", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "archivedId": { "type": "string", "format": "uuid" } } } } } }, "400": { "description": "Invalid account ID", "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/portfolio/pipeline/{id}/sequences/{sequenceId}": { "put": { "summary": "Update a pipeline sequence", "description": "Updates a pipeline sequence stage, owner, status, or notes. Stage transitions can be blocked by required tasks or stage-level review/gated controls.", "operationId": "updatePipelineSequence", "tags": [ "Pipeline" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "sequenceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "companyId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Company UUID for company-scoped pipeline access. Required for Bearer tokens unless the token is company-bound." }, { "$ref": "#/components/parameters/XCompanyId" }, { "name": "networkId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Optional legacy vc_portfolio network lane UUID for browser/session callers." }, { "name": "listId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Optional pipeline list rail UUID. When present, reads and writes are scoped to that rail." }, { "name": "c", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Optional company slug used by browser/session callers to resolve company scope." }, { "name": "scope", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "company", "network" ], "default": "company" }, "description": "Pipeline authority scope. Company scope is the default and the only Bearer-token mode." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "stage": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "completed" ] }, "ownerId": { "type": "string", "format": "uuid", "nullable": true }, "notes": { "type": "string", "nullable": true } } } } } }, "responses": { "200": { "description": "Sequence updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "company": { "$ref": "#/components/schemas/PipelineDealDetail" }, "sequence": { "$ref": "#/components/schemas/PipelineSequence" } } } } } }, "400": { "description": "Invalid request or stage transition", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Sequence or account not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Sequence progression blocked by required tasks or stage control", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "sequence_transition_required_tasks_incomplete", "sequence_transition_review_required", "sequence_transition_approval_required" ] }, "currentStage": { "type": "string" }, "targetStage": { "type": "string" }, "currentStageControl": { "type": "string", "enum": [ "light", "review", "gated" ] }, "disposition": { "type": "string", "nullable": true }, "openTaskKeys": { "type": "array", "items": { "type": "string" } }, "openTasks": { "type": "array", "items": { "$ref": "#/components/schemas/PipelineSequenceTask" } } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "BearerAuth": [] }, { "SessionCookie": [] } ] } }, "/api/portfolio/pipeline/{id}/sequences/{sequenceId}/approval-request": { "get": { "summary": "Read pending stage-transition approval request", "description": "Returns the current pending stage-transition approval request for a sequence, if one exists.", "operationId": "getPipelineSequenceApprovalRequest", "tags": [ "Pipeline" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "sequenceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "companyId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Company UUID for company-scoped pipeline access. Required for Bearer tokens unless the token is company-bound." }, { "$ref": "#/components/parameters/XCompanyId" }, { "name": "networkId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Optional legacy vc_portfolio network lane UUID for browser/session callers." }, { "name": "listId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Optional pipeline list rail UUID. When present, reads and writes are scoped to that rail." }, { "name": "c", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Optional company slug used by browser/session callers to resolve company scope." }, { "name": "scope", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "company", "network" ], "default": "company" }, "description": "Pipeline authority scope. Company scope is the default and the only Bearer-token mode." } ], "responses": { "200": { "description": "Pending stage-transition approval request or null", "content": { "application/json": { "schema": { "type": "object", "properties": { "request": { "allOf": [ { "$ref": "#/components/schemas/PipelinePendingStageTransitionApproval" } ], "nullable": true } } } } } }, "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": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Sequence or account not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "BearerAuth": [] }, { "SessionCookie": [] } ] }, "post": { "summary": "Request stage-transition approval", "description": "Creates a review or approval request for a gated stage transition when direct progression is blocked by stage control.", "operationId": "createPipelineSequenceApprovalRequest", "tags": [ "Pipeline" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "sequenceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "companyId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Company UUID for company-scoped pipeline access. Required for Bearer tokens unless the token is company-bound." }, { "$ref": "#/components/parameters/XCompanyId" }, { "name": "networkId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Optional legacy vc_portfolio network lane UUID for browser/session callers." }, { "name": "listId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Optional pipeline list rail UUID. When present, reads and writes are scoped to that rail." }, { "name": "c", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Optional company slug used by browser/session callers to resolve company scope." }, { "name": "scope", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "company", "network" ], "default": "company" }, "description": "Pipeline authority scope. Company scope is the default and the only Bearer-token mode." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "targetStage" ], "properties": { "targetStage": { "type": "string", "minLength": 1, "maxLength": 120 } } } } } }, "responses": { "200": { "description": "Approval request created", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "request": { "$ref": "#/components/schemas/PipelinePendingStageTransitionApproval" } } } } } }, "400": { "description": "Invalid request or stage does not require review", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Sequence or account not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Required tasks incomplete or a duplicate pending request already exists", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "BearerAuth": [] }, { "SessionCookie": [] } ] } }, "/api/portfolio/pipeline/{id}/sequences/{sequenceId}/switch-type": { "post": { "summary": "Switch workflow type for a pipeline sequence", "description": "Creates a new target workflow sequence and returns the updated deal detail when the switch can happen directly. If completing the source workflow requires approval, this route returns 409 `sequence_type_switch_approval_required` instead.", "operationId": "switchPipelineSequenceType", "tags": [ "Pipeline" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "sequenceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "companyId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Company UUID for company-scoped pipeline access. Required for Bearer tokens unless the token is company-bound." }, { "$ref": "#/components/parameters/XCompanyId" }, { "name": "networkId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Optional legacy vc_portfolio network lane UUID for browser/session callers." }, { "name": "listId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Optional pipeline list rail UUID. When present, reads and writes are scoped to that rail." }, { "name": "c", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Optional company slug used by browser/session callers to resolve company scope." }, { "name": "scope", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "company", "network" ], "default": "company" }, "description": "Pipeline authority scope. Company scope is the default and the only Bearer-token mode." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "targetSequenceType" ], "properties": { "targetSequenceType": { "type": "string", "enum": [ "fundraising", "sales", "partnerships", "user_activation" ] }, "targetStage": { "type": "string", "minLength": 1, "maxLength": 120 }, "ownerId": { "type": "string", "format": "uuid", "nullable": true }, "notes": { "type": "string", "nullable": true, "maxLength": 50000 }, "completeSource": { "type": "boolean", "default": true } } } } } }, "responses": { "200": { "description": "Workflow type switched", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PipelineSequenceMutationResponse" } } } }, "400": { "description": "Invalid request or target workflow is incompatible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Sequence or account not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Workflow switch requires approval because the source workflow must be completed first", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "sequence_type_switch_approval_required" ] } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "BearerAuth": [] }, { "SessionCookie": [] } ] } }, "/api/portfolio/pipeline/{id}/sequences/{sequenceId}/switch-type/approval-request": { "get": { "summary": "Read pending workflow type switch approval request", "description": "Returns the current pending workflow type switch approval request for a sequence, if one exists.", "operationId": "getPipelineSequenceTypeSwitchApprovalRequest", "tags": [ "Pipeline" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "sequenceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "companyId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Company UUID for company-scoped pipeline access. Required for Bearer tokens unless the token is company-bound." }, { "$ref": "#/components/parameters/XCompanyId" }, { "name": "networkId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Optional legacy vc_portfolio network lane UUID for browser/session callers." }, { "name": "listId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Optional pipeline list rail UUID. When present, reads and writes are scoped to that rail." }, { "name": "c", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Optional company slug used by browser/session callers to resolve company scope." }, { "name": "scope", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "company", "network" ], "default": "company" }, "description": "Pipeline authority scope. Company scope is the default and the only Bearer-token mode." } ], "responses": { "200": { "description": "Pending workflow switch approval request or null", "content": { "application/json": { "schema": { "type": "object", "properties": { "request": { "allOf": [ { "$ref": "#/components/schemas/PipelinePendingTypeSwitchApproval" } ], "nullable": true } } } } } }, "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": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Sequence or account not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "BearerAuth": [] }, { "SessionCookie": [] } ] }, "post": { "summary": "Request workflow type switch approval", "description": "Creates an approval request for a workflow type switch that must complete the source workflow before the new target workflow is created.", "operationId": "createPipelineSequenceTypeSwitchApprovalRequest", "tags": [ "Pipeline" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "sequenceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "companyId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Company UUID for company-scoped pipeline access. Required for Bearer tokens unless the token is company-bound." }, { "$ref": "#/components/parameters/XCompanyId" }, { "name": "networkId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Optional legacy vc_portfolio network lane UUID for browser/session callers." }, { "name": "listId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Optional pipeline list rail UUID. When present, reads and writes are scoped to that rail." }, { "name": "c", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Optional company slug used by browser/session callers to resolve company scope." }, { "name": "scope", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "company", "network" ], "default": "company" }, "description": "Pipeline authority scope. Company scope is the default and the only Bearer-token mode." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "targetSequenceType" ], "properties": { "targetSequenceType": { "type": "string", "enum": [ "fundraising", "sales", "partnerships", "user_activation" ] }, "targetStage": { "type": "string", "minLength": 1, "maxLength": 120 }, "ownerId": { "type": "string", "format": "uuid", "nullable": true }, "notes": { "type": "string", "nullable": true, "maxLength": 50000 }, "completeSource": { "type": "boolean", "enum": [ true ], "default": true } } } } } }, "responses": { "200": { "description": "Workflow switch approval request created", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "request": { "$ref": "#/components/schemas/PipelinePendingTypeSwitchApproval" } } } } } }, "400": { "description": "Invalid request or no eligible approver is available", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Sequence or account not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "A duplicate pending workflow switch request already exists", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "BearerAuth": [] }, { "SessionCookie": [] } ] } }, "/api/portfolio/pipeline/{id}/sequences/{sequenceId}/tasks": { "patch": { "summary": "Update a pipeline sequence task", "description": "Updates a required pipeline sequence task by taskId or taskKey.", "operationId": "updatePipelineSequenceTask", "tags": [ "Pipeline" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "sequenceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "companyId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Company UUID for company-scoped pipeline access. Required for Bearer tokens unless the token is company-bound." }, { "$ref": "#/components/parameters/XCompanyId" }, { "name": "networkId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Optional legacy vc_portfolio network lane UUID for browser/session callers." }, { "name": "listId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Optional pipeline list rail UUID. When present, reads and writes are scoped to that rail." }, { "name": "c", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Optional company slug used by browser/session callers to resolve company scope." }, { "name": "scope", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "company", "network" ], "default": "company" }, "description": "Pipeline authority scope. Company scope is the default and the only Bearer-token mode." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "status" ], "properties": { "taskId": { "type": "string", "format": "uuid" }, "taskKey": { "type": "string" }, "status": { "type": "string", "enum": [ "backlog", "open", "done", "passed", "postponed" ] } }, "anyOf": [ { "required": [ "taskId" ] }, { "required": [ "taskKey" ] } ] } } } }, "responses": { "200": { "description": "Sequence task updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "task": { "$ref": "#/components/schemas/PipelineSequenceTask" } } } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Sequence or task not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "BearerAuth": [] }, { "SessionCookie": [] } ] } }, "/api/portfolio/pipeline/{id}/metrics": { "get": { "summary": "Get pipeline deal metrics", "description": "Returns the account-level and linked company metric timeline for a pipeline deal.", "operationId": "getPipelineDealMetrics", "tags": [ "Pipeline" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "companyId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Company UUID for company-scoped pipeline access. Required for Bearer tokens unless the token is company-bound." }, { "$ref": "#/components/parameters/XCompanyId" }, { "name": "networkId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Optional legacy vc_portfolio network lane UUID for browser/session callers." }, { "name": "listId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Optional pipeline list rail UUID. When present, reads and writes are scoped to that rail." }, { "name": "c", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Optional company slug used by browser/session callers to resolve company scope." }, { "name": "scope", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "company", "network" ], "default": "company" }, "description": "Pipeline authority scope. Company scope is the default and the only Bearer-token mode." } ], "responses": { "200": { "description": "Pipeline metric timeline", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PipelineDealMetricsResponse" } } } }, "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" } } } } } }, "post": { "summary": "Add or update a pipeline deal metric", "description": "Upserts a metric observation for a pipeline deal and returns the active observation DTO.", "operationId": "addPipelineDealMetric", "tags": [ "Pipeline" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "companyId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Company UUID for company-scoped pipeline access. Required for Bearer tokens unless the token is company-bound." }, { "$ref": "#/components/parameters/XCompanyId" }, { "name": "networkId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Optional legacy vc_portfolio network lane UUID for browser/session callers." }, { "name": "listId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Optional pipeline list rail UUID. When present, reads and writes are scoped to that rail." }, { "name": "c", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Optional company slug used by browser/session callers to resolve company scope." }, { "name": "scope", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "company", "network" ], "default": "company" }, "description": "Pipeline authority scope. Company scope is the default and the only Bearer-token mode." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "metricId", "value", "periodKey", "periodType" ], "properties": { "metricId": { "type": "string" }, "value": { "type": "number" }, "periodKey": { "type": "string" }, "periodType": { "type": "string", "enum": [ "month", "quarter", "year" ] }, "source": { "type": "string", "enum": [ "manual", "vc_shared", "ai_inbox", "import", "integration", "founder_provided" ], "nullable": true }, "status": { "type": "string", "enum": [ "pending", "verified", "disputed", "rejected" ], "nullable": true }, "confidence": { "type": "number", "nullable": true }, "notes": { "type": "string", "nullable": true } } } } } }, "responses": { "200": { "description": "Metric saved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PipelineDealMetricMutationResponse" } } } }, "400": { "description": "Invalid request", "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 server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/portfolio/pipeline/lists": { "get": { "summary": "List pipeline lists", "description": "Returns named lists used to segment pipeline deals.", "operationId": "listPipelineLists", "tags": [ "Pipeline" ], "responses": { "200": { "description": "Pipeline lists", "content": { "application/json": { "schema": { "type": "object", "properties": { "lists": { "type": "array", "items": { "$ref": "#/components/schemas/PipelineList" } }, "communicationLane": { "allOf": [ { "$ref": "#/components/schemas/PipelineCommunicationLane" } ], "nullable": true }, "communicationLanes": { "type": "array", "items": { "$ref": "#/components/schemas/PipelineCommunicationLane" } } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "companyId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Company UUID for company-scoped pipeline access. Required for Bearer tokens unless the token is company-bound." }, { "$ref": "#/components/parameters/XCompanyId" }, { "name": "networkId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Optional legacy vc_portfolio network lane UUID for browser/session callers." }, { "name": "listId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Optional pipeline list rail UUID. When present, reads and writes are scoped to that rail." }, { "name": "c", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Optional company slug used by browser/session callers to resolve company scope." }, { "name": "scope", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "company", "network" ], "default": "company" }, "description": "Pipeline authority scope. Company scope is the default and the only Bearer-token mode." } ] }, "post": { "summary": "Create pipeline list", "description": "Creates a named pipeline list.", "operationId": "createPipelineList", "tags": [ "Pipeline" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 } } } } } }, "responses": { "201": { "description": "List created", "content": { "application/json": { "schema": { "type": "object", "properties": { "list": { "$ref": "#/components/schemas/PipelineList" } } } } } }, "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" } } } } }, "parameters": [ { "name": "companyId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Company UUID for company-scoped pipeline access. Required for Bearer tokens unless the token is company-bound." }, { "$ref": "#/components/parameters/XCompanyId" }, { "name": "networkId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Optional legacy vc_portfolio network lane UUID for browser/session callers." }, { "name": "listId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Optional pipeline list rail UUID. When present, reads and writes are scoped to that rail." }, { "name": "c", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Optional company slug used by browser/session callers to resolve company scope." }, { "name": "scope", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "company", "network" ], "default": "company" }, "description": "Pipeline authority scope. Company scope is the default and the only Bearer-token mode." } ] } }, "/api/council/invoke": { "post": { "summary": "Invoke Council compatibility wrapper", "description": "Starts a Council run through the canonical agent/run substrate and returns a run ID for polling.", "operationId": "invokeCouncil", "tags": [ "Agent" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "question" ], "properties": { "question": { "type": "string", "maxLength": 4000 }, "modelOverride": { "type": "string" } } } } } }, "responses": { "200": { "description": "Council run accepted", "content": { "application/json": { "schema": { "type": "object", "required": [ "runId", "status" ], "properties": { "runId": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "pending" ] } } } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Failed to prepare council run", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/council/result": { "get": { "summary": "Poll Council run result", "description": "Convenience poll endpoint that reshapes a canonical Council agent run into the public Council output shape.", "operationId": "getCouncilResult", "tags": [ "Agent" ], "parameters": [ { "name": "runId", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Pending, error, or completed council result", "content": { "application/json": { "schema": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "pending", "error", "complete" ] }, "error": { "type": "string" }, "answer": { "type": "string" }, "confidence": { "type": "number" }, "dissent": { "type": [ "string", "null" ] }, "perspectives": { "type": "array", "items": { "type": "object", "properties": { "agent": { "type": "string" }, "summary": { "type": "string" }, "score": { "type": "number" }, "model": { "type": "string" } } } }, "citations": { "type": "array", "items": { "type": "object" } }, "metadata": { "type": "object", "properties": { "tier": { "type": "string" }, "duration_ms": { "type": "number" }, "tokens_used": { "type": "number" }, "credits_used": { "type": "number" } } } } } } } }, "400": { "description": "runId is required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Run not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "not_found" ] } } } } } } } } }, "/api/panel/invoke": { "post": { "summary": "Invoke Panel compatibility wrapper", "description": "Starts a Panel run through the canonical agent/run substrate and returns a run ID for polling.", "operationId": "invokePanel", "tags": [ "Agent" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "question" ], "properties": { "question": { "type": "string", "maxLength": 4000 }, "modelOverride": { "type": "string" } } } } } }, "responses": { "200": { "description": "Panel run accepted", "content": { "application/json": { "schema": { "type": "object", "required": [ "runId", "status" ], "properties": { "runId": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "pending" ] } } } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Failed to prepare panel run", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/panel/result": { "get": { "summary": "Poll Panel run result", "description": "Convenience poll endpoint that reshapes a canonical Panel agent run into the public Panel output shape.", "operationId": "getPanelResult", "tags": [ "Agent" ], "parameters": [ { "name": "runId", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Pending, error, or completed panel result", "content": { "application/json": { "schema": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "pending", "error", "complete" ] }, "error": { "type": "string" }, "answer": { "type": "string" }, "confidence": { "type": "number" }, "conflicts": { "type": "string" }, "perspectives": { "type": "array", "items": { "type": "object", "properties": { "agent": { "type": "string" }, "summary": { "type": "string" }, "score": { "type": "number" }, "model": { "type": "string" } } } }, "metadata": { "type": "object", "properties": { "tier": { "type": "string" }, "duration_ms": { "type": "number" }, "tokens_used": { "type": "number" }, "credits_used": { "type": "number" } } } } } } } }, "400": { "description": "runId is required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Run not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "not_found" ] } } } } } } } } }, "/api/research-panel/invoke": { "post": { "summary": "Invoke Research Panel", "description": "Dispatches a research-panel run and returns a run ID for polling.", "operationId": "invokeResearchPanel", "tags": [ "Agent" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "topic" ], "properties": { "topic": { "type": "string", "maxLength": 4000 } } } } } }, "responses": { "200": { "description": "Research panel run accepted", "content": { "application/json": { "schema": { "type": "object", "required": [ "runId", "status" ], "properties": { "runId": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "pending" ] } } } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Failed to prepare or dispatch run", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/research-panel/result": { "get": { "summary": "Poll Research Panel result", "description": "Returns the normalized research-panel result shape for a previously started run.", "operationId": "getResearchPanelResult", "tags": [ "Agent" ], "parameters": [ { "name": "runId", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Pending, error, or completed research result", "content": { "application/json": { "schema": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "pending", "error", "complete" ] }, "error": { "type": "string" }, "summary": { "type": "string" }, "confidence": { "type": "string" }, "findings": { "type": "array", "items": { "type": "string" } }, "contradictions": { "type": "array", "items": { "type": "string" } }, "liabilityMode": { "type": "string", "enum": [ "standard", "analysis_only", "human_review_required" ] }, "requiresHumanReview": { "type": "boolean" }, "requiresCautionNote": { "type": "boolean" }, "liabilityNote": { "type": "string" }, "metadata": { "type": "object", "properties": { "tier": { "type": "string" }, "duration_ms": { "type": "number" }, "tokens_used": { "type": "number" }, "credits_used": { "type": "number" }, "models_used": { "type": "array", "items": { "type": "string" } } } } } } } } }, "400": { "description": "runId is required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Run not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "not_found" ] } } } } } } } } }, "/api/deep-research/invoke": { "post": { "summary": "Invoke Deep Research", "description": "Dispatches a deep-research run and returns a run ID for polling.", "operationId": "invokeDeepResearch", "tags": [ "Agent" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "query" ], "properties": { "query": { "type": "string", "maxLength": 4000 } } } } } }, "responses": { "200": { "description": "Deep research run accepted", "content": { "application/json": { "schema": { "type": "object", "required": [ "runId", "status" ], "properties": { "runId": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "pending" ] } } } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Failed to prepare or dispatch run", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/deep-research/result": { "get": { "summary": "Poll Deep Research result", "description": "Returns the normalized deep-research result shape for a previously started run.", "operationId": "getDeepResearchResult", "tags": [ "Agent" ], "parameters": [ { "name": "runId", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Pending, error, or completed deep research result", "content": { "application/json": { "schema": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "pending", "error", "complete" ] }, "error": { "type": "string" }, "summary": { "type": "string" }, "pagesScraped": { "type": "number" }, "sourcesFound": { "type": "number" }, "iterations": { "type": "number" }, "sources": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string" }, "url": { "type": "string" } } } }, "liabilityMode": { "type": "string", "enum": [ "standard", "analysis_only", "human_review_required" ] }, "requiresHumanReview": { "type": "boolean" }, "requiresCautionNote": { "type": "boolean" }, "liabilityNote": { "type": "string" }, "metadata": { "type": "object", "properties": { "tier": { "type": "string" }, "duration_ms": { "type": "number" }, "tokens_used": { "type": "number" }, "credits_used": { "type": "number" }, "models_used": { "type": "array", "items": { "type": "string" } } } } } } } } }, "400": { "description": "runId is required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Run not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "not_found" ] } } } } } } } } }, "/api/orchestrate/route": { "post": { "summary": "Route a question to the best subagent", "description": "Uses the orchestration router to choose between council, panel, research-panel, and deep-research before any run is started.", "operationId": "routeQuestion", "tags": [ "Agent" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "question" ], "properties": { "question": { "type": "string", "description": "Natural-language question to route.", "maxLength": 4000 }, "contextSummary": { "type": "string", "description": "Optional short company context summary to improve routing.", "maxLength": 400 } } } } } }, "responses": { "200": { "description": "Routing decision", "content": { "application/json": { "schema": { "type": "object", "required": [ "agent", "needsWebEnrichment", "contextSufficient", "reason" ], "properties": { "agent": { "type": "string", "enum": [ "council", "panel", "research-panel", "deep-research" ] }, "needsWebEnrichment": { "type": "boolean" }, "contextSufficient": { "type": "boolean" }, "reason": { "type": "string" } } } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/agent/runs": { "get": { "summary": "List recent top-level agent runs", "description": "Returns recent top-level canonical runs for the authenticated company context. Child runs remain nested under the parent status payload and are not returned as top-level list items.", "operationId": "listAgentRuns", "tags": [ "Agent" ], "parameters": [ { "$ref": "#/components/parameters/companyId" }, { "$ref": "#/components/parameters/XCompanyId" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 }, "description": "Maximum number of top-level runs to return." }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "pending", "running", "completed", "failed" ] }, "description": "Optional status filter." } ], "responses": { "200": { "description": "Recent top-level runs", "content": { "application/json": { "schema": { "type": "object", "required": [ "runs", "limit" ], "properties": { "runs": { "type": "array", "items": { "type": "object", "required": [ "runId", "status", "phase", "createdAt", "activeToolClasses", "canCreateArtifacts", "canWriteStreamEntries" ], "properties": { "runId": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "pending", "running", "completed", "failed" ] }, "phase": { "type": "string", "enum": [ "queued", "planning", "executing", "evaluating", "synthesizing", "finalizing", "complete", "error" ] }, "objective": { "type": "string", "nullable": true }, "skillTrigger": { "type": "string", "nullable": true }, "pattern": { "type": "string", "nullable": true }, "intent": { "type": "string", "nullable": true }, "metrics": { "type": "object", "nullable": true, "additionalProperties": true }, "error": { "type": "string", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "completedAt": { "type": "string", "format": "date-time", "nullable": true }, "parentRunId": { "type": "string", "format": "uuid", "nullable": true }, "role": { "type": "string", "nullable": true }, "target": { "type": "object", "nullable": true, "additionalProperties": true }, "budget": { "type": "object", "nullable": true, "additionalProperties": true }, "writePolicy": { "type": "string", "nullable": true }, "toolClasses": { "type": "array", "nullable": true, "items": { "type": "string", "enum": [ "read", "analyze", "write", "publish", "sync" ] } }, "riskClass": { "type": "string", "nullable": true, "enum": [ "standard", "financial_analysis", "sensitive_write", "external_publish" ] }, "childRunCount": { "type": "integer" }, "activeToolClasses": { "type": "array", "items": { "type": "string", "enum": [ "read", "analyze", "write", "publish", "sync" ] } }, "activeRiskClass": { "type": "string", "nullable": true, "enum": [ "standard", "financial_analysis", "sensitive_write", "external_publish" ] }, "canCreateArtifacts": { "type": "boolean", "description": "Whether the current runtime phase may currently persist artifact side effects." }, "canWriteStreamEntries": { "type": "boolean", "description": "Whether the current runtime phase may currently persist stream-entry side effects." } } } }, "limit": { "type": "integer" } }, "example": { "runs": [ { "runId": "uuid", "status": "completed", "phase": "synthesizing", "objective": "Write a strategic pricing memo", "skillTrigger": "@council", "pattern": "parallel", "intent": "generate", "metrics": { "totalTokens": 321, "childRunsSpawned": 2 }, "error": null, "createdAt": "2026-04-05T20:00:00.000Z", "completedAt": "2026-04-05T20:02:00.000Z", "parentRunId": null, "role": null, "target": { "type": "objective", "label": "pricing-memo" }, "budget": { "maxChildren": 4 }, "writePolicy": "artifact_allowed", "toolClasses": [ "read", "analyze", "write" ], "riskClass": "sensitive_write", "childRunCount": 2, "activeToolClasses": [], "activeRiskClass": null } ], "limit": 10 } } } } }, "400": { "description": "Invalid query", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/agent/run": { "post": { "summary": "Start agent orchestration run", "description": "Starts a new agent orchestration run. The agent will execute the given objective using the specified pattern and effort level. Returns a run ID for tracking progress via SSE or polling.", "operationId": "startAgentRun", "tags": [ "Agent" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentRunInput" } } } }, "responses": { "202": { "description": "Run accepted and started", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentRunResponse" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Company not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/agent/run/{runId}": { "get": { "summary": "Get run status and results", "description": "Returns the current status, output, metrics, and error information for an agent orchestration run.", "operationId": "getAgentRunStatus", "tags": [ "Agent" ], "parameters": [ { "name": "runId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID of the agent run." } ], "responses": { "200": { "description": "Run status and results", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentRunStatus" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Run not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/agent/run/{runId}/progress": { "get": { "summary": "Read or stream agent run progress", "description": "Reads cached progress events for an agent run, or opens a Server-Sent Events stream when `channel=true` is provided. Progress events include planning, worker/sub-agent execution, artifact activity, and terminal completion or error signals.", "operationId": "getAgentRunProgress", "tags": [ "Agent" ], "parameters": [ { "name": "runId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID of the agent run." }, { "name": "channel", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "When true, upgrades the route to an SSE stream via the realtime channel. Omit or set false to read the cached JSON event buffer." } ], "responses": { "200": { "description": "Cached progress events or SSE event stream", "content": { "application/json": { "schema": { "type": "object", "required": [ "runId", "phase", "events", "activeToolClasses", "canCreateArtifacts", "canWriteStreamEntries" ], "properties": { "runId": { "type": "string", "format": "uuid" }, "phase": { "type": "string", "enum": [ "queued", "planning", "executing", "evaluating", "synthesizing", "finalizing", "complete", "error" ] }, "events": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "activeToolClasses": { "type": "array", "items": { "type": "string", "enum": [ "read", "analyze", "write", "publish", "sync" ] } }, "activeRiskClass": { "type": "string", "nullable": true, "enum": [ "standard", "financial_analysis", "sensitive_write", "external_publish" ] }, "canCreateArtifacts": { "type": "boolean", "description": "Whether the current runtime phase may currently persist artifact side effects." }, "canWriteStreamEntries": { "type": "boolean", "description": "Whether the current runtime phase may currently persist stream-entry side effects." } }, "example": { "runId": "uuid", "phase": "planning", "events": [ { "type": "init", "runId": "uuid", "pattern": "parallel", "effort": "high", "intent": "research", "executionMode": "genesis-exploratory", "traceMode": "compact", "writePolicy": "artifact_allowed", "toolClasses": [ "read", "analyze", "write" ], "riskClass": "sensitive_write", "phase": "planning", "activeToolClasses": [], "activeRiskClass": null, "canCreateArtifacts": false, "canWriteStreamEntries": false }, { "type": "planning", "objective": "Analyze our expansion readiness", "workersPlanned": 4 }, { "type": "phase", "phase": "executing", "activeToolClasses": [ "read", "analyze" ], "activeRiskClass": "standard", "canCreateArtifacts": false, "canWriteStreamEntries": false }, { "type": "subagents_status", "planned": 4, "spawned": 0, "unspawned": 4, "queued": 4, "pending": 0, "running": 0, "completed": 0, "failed": 0, "maxConcurrentChildren": 2, "taskClasses": [ { "taskClass": "finance", "planned": 1, "spawned": 0, "unspawned": 1, "queued": 1, "pending": 0, "running": 0, "completed": 0, "failed": 0 }, { "taskClass": "growth", "planned": 3, "spawned": 0, "unspawned": 3, "queued": 3, "pending": 0, "running": 0, "completed": 0, "failed": 0 } ] }, { "type": "subagent_progress", "runId": "child-1", "role": "finance", "taskClass": "finance", "status": "running", "phase": "executing", "activeToolClasses": [ "read", "analyze" ], "activeRiskClass": "financial_analysis", "canCreateArtifacts": false, "canWriteStreamEntries": false } ], "activeToolClasses": [], "activeRiskClass": null, "canCreateArtifacts": false, "canWriteStreamEntries": false } } }, "text/event-stream": { "schema": { "type": "string", "description": "Server-Sent Events stream with progress updates.", "example": ": connected to progress stream\n\nevent: progress\ndata: {\"type\":\"init\",\"runId\":\"uuid\",\"pattern\":\"parallel\",\"effort\":\"high\",\"phase\":\"planning\",\"intent\":\"research\",\"executionMode\":\"genesis-exploratory\",\"traceMode\":\"compact\",\"writePolicy\":\"artifact_allowed\",\"toolClasses\":[\"read\",\"analyze\",\"write\"],\"riskClass\":\"sensitive_write\",\"activeToolClasses\":[],\"activeRiskClass\":null,\"canCreateArtifacts\":false,\"canWriteStreamEntries\":false}\n\nevent: progress\ndata: {\"type\":\"phase\",\"phase\":\"executing\",\"activeToolClasses\":[\"read\",\"analyze\"],\"activeRiskClass\":\"standard\",\"canCreateArtifacts\":false,\"canWriteStreamEntries\":false}\n\nevent: progress\ndata: {\"type\":\"subagents_status\",\"planned\":4,\"spawned\":0,\"unspawned\":4,\"queued\":4,\"pending\":0,\"running\":0,\"completed\":0,\"failed\":0,\"maxConcurrentChildren\":2,\"taskClasses\":[{\"taskClass\":\"finance\",\"planned\":1,\"spawned\":0,\"unspawned\":1,\"queued\":1,\"pending\":0,\"running\":0,\"completed\":0,\"failed\":0},{\"taskClass\":\"growth\",\"planned\":3,\"spawned\":0,\"unspawned\":3,\"queued\":3,\"pending\":0,\"running\":0,\"completed\":0,\"failed\":0}]}\n\nevent: progress\ndata: {\"type\":\"subagent_progress\",\"runId\":\"child-1\",\"role\":\"finance\",\"taskClass\":\"finance\",\"status\":\"running\",\"phase\":\"executing\",\"activeToolClasses\":[\"read\",\"analyze\"],\"activeRiskClass\":\"financial_analysis\",\"canCreateArtifacts\":false,\"canWriteStreamEntries\":false}\n\nevent: progress\ndata: {\"type\":\"complete\",\"metrics\":{\"totalTokens\":8500}}\n\nevent: done\ndata: {}\n" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Run not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/agent/run/{runId}/save": { "post": { "summary": "Save completed run output as artifact", "description": "Persists the text output of a completed canonical run as a generic artifact. The request accepts an optional title override; otherwise the route derives a title from the run objective.", "operationId": "saveAgentRun", "tags": [ "Agent" ], "parameters": [ { "name": "runId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID of the agent run." }, { "$ref": "#/components/parameters/companyId" }, { "$ref": "#/components/parameters/XCompanyId" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "maxLength": 160, "description": "Optional artifact title override." } } } } } }, "responses": { "200": { "description": "Saved artifact metadata", "content": { "application/json": { "schema": { "type": "object", "required": [ "artifactId", "artifactGroupId", "versionNumber", "annotationCount" ], "properties": { "artifactId": { "type": "string", "format": "uuid" }, "artifactGroupId": { "type": "string", "format": "uuid" }, "versionNumber": { "type": "integer" }, "annotationCount": { "type": "integer" } }, "example": { "artifactId": "uuid", "artifactGroupId": "uuid", "versionNumber": 1, "annotationCount": 1 } } } } }, "400": { "description": "Invalid input or run cannot be saved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Run not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/company/knowledge-trees": { "get": { "summary": "Get knowledge trees for all domains", "description": "Returns knowledge trees across all domains for a company. Each domain includes its tree structure, sections, and generation metadata.", "operationId": "getKnowledgeTrees", "tags": [ "Company" ], "parameters": [ { "$ref": "#/components/parameters/companyId" }, { "$ref": "#/components/parameters/XCompanyId" } ], "responses": { "200": { "description": "Knowledge trees for all domains", "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "format": "uuid" }, "domains": { "type": "array", "items": { "$ref": "#/components/schemas/KnowledgeTreeDomain" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/company/knowledge-trees/generate": { "post": { "summary": "Generate knowledge trees from conversations", "description": "Triggers an asynchronous knowledge tree generation process from the company's conversation history. Returns an event ID for tracking progress.", "operationId": "generateKnowledgeTrees", "tags": [ "Company" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "company_id" ], "properties": { "company_id": { "type": "string", "format": "uuid" } } } } } }, "responses": { "200": { "description": "Generation triggered", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "event_id": { "type": "string" }, "conversation_id": { "type": "string" }, "message": { "type": "string" } } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Company not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/search": { "post": { "summary": "Vector search across artifacts and conversations", "description": "Performs semantic vector search across company artifacts and conversations. Supports Bearer API keys and browser sessions. Provide companyId in the request body; Bearer callers may also send X-Company-Id.", "operationId": "vectorSearch", "tags": [ "Search" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchRequest" } } } }, "responses": { "200": { "description": "Search results", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchResponse" } } } }, "400": { "description": "Invalid input", "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" } } } }, "503": { "description": "Embedding service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "BearerAuth": [] }, { "SessionCookie": [] } ] } }, "/api/metrics/grants": { "get": { "summary": "List metric sharing grants", "description": "Returns metric sharing grants issued by the authenticated company, including active and revoked grants.", "operationId": "listMetricGrants", "tags": [ "Metrics" ], "parameters": [ { "$ref": "#/components/parameters/companyId" }, { "$ref": "#/components/parameters/XCompanyId" } ], "responses": { "200": { "description": "List of metric sharing grants", "content": { "application/json": { "schema": { "type": "object", "properties": { "grants": { "type": "array", "items": { "$ref": "#/components/schemas/MetricShareGrant" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "BearerAuth": [] }, { "SessionCookie": [] } ] }, "post": { "summary": "Create metric sharing grant", "description": "Creates a new metric sharing grant, allowing the recipient company to view the specified metric scopes.", "operationId": "createMetricGrant", "tags": [ "Metrics" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "companyId", "scope" ], "properties": { "companyId": { "type": "string", "format": "uuid" }, "scope": { "type": "array", "minItems": 1, "items": { "type": "string", "enum": [ "metrics", "context", "decisions" ] } }, "recipientCompanyId": { "type": "string", "format": "uuid" }, "recipientUserId": { "type": "string", "format": "uuid" }, "metricIds": { "type": "array", "items": { "type": "string" } }, "includeHistorical": { "type": "boolean", "default": false }, "expiresAt": { "type": "string", "format": "date-time" }, "note": { "type": "string", "maxLength": 500 } }, "description": "At least one of recipientCompanyId or recipientUserId must be provided." } } } }, "responses": { "201": { "description": "Grant created", "content": { "application/json": { "schema": { "type": "object", "properties": { "grant": { "$ref": "#/components/schemas/MetricShareGrant" } } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "BearerAuth": [] }, { "SessionCookie": [] } ] } }, "/api/metrics/grants/{id}/revoke": { "patch": { "summary": "Revoke a metric sharing grant", "description": "Revokes an active metric sharing grant, immediately stopping the recipient's access to the shared metrics. Requires company admin access in the authenticated company context.", "operationId": "revokeMetricGrant", "tags": [ "Metrics" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID of the grant to revoke." }, { "$ref": "#/components/parameters/companyId" }, { "$ref": "#/components/parameters/XCompanyId" } ], "responses": { "200": { "description": "Grant revoked", "content": { "application/json": { "schema": { "type": "object", "properties": { "grant": { "$ref": "#/components/schemas/MetricShareGrant" } } } } } }, "400": { "description": "Invalid grant id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Admin access required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Grant not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Grant already revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "BearerAuth": [] }, { "SessionCookie": [] } ] } }, "/api/reports/public/{slug}/{period}/{version}/{token}": { "get": { "summary": "Read a public frozen report", "description": "Returns a public frozen report publication by share URL. No account is required. Access is protected by the share token, enumeration protection, and rate limiting.", "operationId": "getPublicReport", "tags": [ "Reports" ], "security": [], "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Company slug embedded in the public share URL." }, { "name": "period", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Published period key for the shared report." }, { "name": "version", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^v\\d+$" }, "description": "Published version segment, for example v1 or v2." }, { "name": "token", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Opaque public share token." } ], "responses": { "200": { "description": "Public report", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "report": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "title": { "type": "string", "nullable": true }, "markdown": { "type": "string", "nullable": true }, "templateId": { "type": "string", "nullable": true }, "datePreset": { "type": "string", "nullable": true }, "dateRangeStart": { "type": "string", "nullable": true }, "dateRangeEnd": { "type": "string", "nullable": true }, "totalEntries": { "type": "integer", "nullable": true }, "createdAt": { "type": "string", "format": "date-time", "nullable": true }, "company": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "nullable": true }, "name": { "type": "string", "nullable": true }, "slug": { "type": "string", "nullable": true } } } } }, "send": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "sentAt": { "type": "string", "format": "date-time" }, "isCorrection": { "type": "boolean" }, "status": { "type": "string" }, "periodKey": { "type": "string" }, "versionNumber": { "type": "integer" }, "viewerPolicy": { "type": "object", "additionalProperties": true } } }, "meta": { "type": "object", "properties": { "periodLabel": { "type": "string" }, "isSuperseded": { "type": "boolean" }, "nextVersionUrl": { "type": "string", "nullable": true } } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited or temporarily blocked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/reports/public/typed/{type}/{slug}/{period}/{version}/{token}": { "get": { "summary": "Read a typed public frozen report", "description": "Returns a public frozen report publication by a template-aware share URL. No account is required. The typed prefix is validated against the report template and the response includes reportTypeLabel metadata.", "operationId": "getTypedPublicReport", "tags": [ "Reports" ], "security": [], "parameters": [ { "name": "type", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Typed URL prefix such as board-reports, monthly-updates, or lp-reports." }, { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Company slug embedded in the public share URL." }, { "name": "period", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Published period key for the shared report." }, { "name": "version", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^v\\d+$" }, "description": "Published version segment, for example v1 or v2." }, { "name": "token", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Opaque public share token." } ], "responses": { "200": { "description": "Typed public report", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "report": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "title": { "type": "string", "nullable": true }, "markdown": { "type": "string", "nullable": true }, "templateId": { "type": "string", "nullable": true }, "datePreset": { "type": "string", "nullable": true }, "dateRangeStart": { "type": "string", "nullable": true }, "dateRangeEnd": { "type": "string", "nullable": true }, "totalEntries": { "type": "integer", "nullable": true }, "createdAt": { "type": "string", "format": "date-time", "nullable": true }, "company": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "nullable": true }, "name": { "type": "string", "nullable": true }, "slug": { "type": "string", "nullable": true } } } } }, "send": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "sentAt": { "type": "string", "format": "date-time" }, "isCorrection": { "type": "boolean" }, "status": { "type": "string" }, "periodKey": { "type": "string" }, "versionNumber": { "type": "integer" }, "viewerPolicy": { "type": "object", "additionalProperties": true } } }, "meta": { "type": "object", "properties": { "periodLabel": { "type": "string" }, "reportTypeLabel": { "type": "string" }, "isSuperseded": { "type": "boolean" }, "nextVersionUrl": { "type": "string", "nullable": true } } } } } } } }, "404": { "description": "Invalid or expired share link", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/metrics/published/{companyId}": { "get": { "summary": "Read published metrics shared with you", "description": "Returns published report_metric_snapshots that a company has shared with the authenticated user or their company via active grants. Never returns live company_metrics actuals.", "operationId": "getPublishedMetrics", "tags": [ "Metrics" ], "parameters": [ { "name": "companyId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID of the company whose published metrics to read." }, { "name": "period", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}$" }, "description": "Optional published period key (YYYY-MM). When omitted, returns the latest allowed publication or historical set based on the grant." } ], "responses": { "200": { "description": "Published metrics", "content": { "application/json": { "schema": { "type": "object", "properties": { "grantId": { "type": "string", "format": "uuid" }, "scope": { "type": "array", "items": { "type": "string" } }, "expiresAt": { "type": "string", "format": "date-time", "nullable": true }, "mode": { "type": "string", "enum": [ "published_grant" ] }, "source": { "type": "string", "enum": [ "report_metric_snapshots", "none" ] }, "missingPublication": { "type": "boolean" }, "company": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "nullable": true }, "vertical": { "type": "string", "nullable": true }, "stage": { "type": "string", "nullable": true } } }, "metrics": { "type": "object", "properties": { "summary": { "type": "object", "additionalProperties": true }, "periods": { "type": "array", "items": { "type": "object", "properties": { "periodKey": { "type": "string" }, "periodType": { "type": "string" }, "reportId": { "type": "string", "format": "uuid" }, "versionNumber": { "type": "integer" }, "sentAt": { "type": "string", "format": "date-time" }, "data": { "type": "object", "additionalProperties": true } } } } } }, "publication": { "type": "object", "nullable": true, "properties": { "reportId": { "type": "string", "format": "uuid" }, "periodKey": { "type": "string", "nullable": true }, "versionNumber": { "type": "integer" }, "sentAt": { "type": "string", "format": "date-time" }, "shareToken": { "type": "string" }, "viewerPolicy": { "type": "object", "additionalProperties": true } } } } } } } }, "400": { "description": "Invalid companyId", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "No active published metrics grant for this company", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Company not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/company/initiatives": { "get": { "summary": "List company initiatives", "description": "Returns all initiatives for the company, including children, execution tasks, linked entity counts, and source entries.", "operationId": "listInitiatives", "tags": [ "Company" ], "parameters": [ { "$ref": "#/components/parameters/companyId" }, { "$ref": "#/components/parameters/XCompanyId" } ], "responses": { "200": { "description": "List of initiatives", "content": { "application/json": { "schema": { "type": "object", "properties": { "initiatives": { "type": "array", "items": { "$ref": "#/components/schemas/CompanyInitiative" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "BearerAuth": [] }, { "SessionCookie": [] } ] } }, "/api/company/initiatives/{id}/tasks": { "post": { "summary": "Create or upsert an initiative task", "description": "Creates a manual initiative task or upserts a suggested-action task for an initiative.", "operationId": "createInitiativeTask", "tags": [ "Company" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/companyId" }, { "$ref": "#/components/parameters/XCompanyId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "title" ], "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 200 }, "owner": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "backlog", "open", "done", "passed", "postponed" ] }, "sourceActionTitle": { "type": "string", "nullable": true } } } } } }, "responses": { "200": { "description": "Initiative task created or upserted", "content": { "application/json": { "schema": { "type": "object", "properties": { "task": { "$ref": "#/components/schemas/CompanyInitiativeTask" } } } } } }, "400": { "description": "Invalid task payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Initiative not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "BearerAuth": [] }, { "SessionCookie": [] } ] }, "patch": { "summary": "Update an initiative task status", "description": "Updates a persisted initiative task or materializes a suggested task from its virtual task id.", "operationId": "updateInitiativeTask", "tags": [ "Company" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/companyId" }, { "$ref": "#/components/parameters/XCompanyId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "taskId", "status" ], "properties": { "taskId": { "type": "string", "description": "Persisted initiative task UUID or virtual task id from GET /api/company/initiatives/:id." }, "status": { "type": "string", "enum": [ "backlog", "open", "done", "passed", "postponed" ] } } } } } }, "responses": { "200": { "description": "Initiative task updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "task": { "$ref": "#/components/schemas/CompanyInitiativeTask" } } } } } }, "400": { "description": "Invalid task payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Task not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "BearerAuth": [] }, { "SessionCookie": [] } ] } }, "/api/company/initiatives/{id}": { "get": { "summary": "Get company initiative detail", "description": "Returns one initiative with linked entities and firms-by-domain hydration using the company resolved by the authenticated request.", "operationId": "getInitiativeDetail", "tags": [ "Company" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Initiative detail", "content": { "application/json": { "schema": { "type": "object", "properties": { "initiative": { "$ref": "#/components/schemas/CompanyInitiative" }, "linkedEntities": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "firmsByDomain": { "type": "object", "additionalProperties": true } } } } } }, "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": "Initiative not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "BearerAuth": [] }, { "SessionCookie": [] } ] }, "patch": { "summary": "Update company initiative status", "description": "Updates an initiative status using the company resolved by the authenticated request.", "operationId": "updateInitiative", "tags": [ "Company" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "planned", "in_progress", "completed", "cancelled" ] } } } } } }, "responses": { "200": { "description": "Initiative updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } }, "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": "Initiative not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Initiative changed during guarded update", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "BearerAuth": [] }, { "SessionCookie": [] } ] } }, "/api/company/initiative-links": { "post": { "summary": "Link initiative to accounts/contacts", "description": "Creates a link between an initiative and one or more accounts or contacts.", "operationId": "createInitiativeLink", "tags": [ "Company" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "initiativeId" ], "properties": { "companyId": { "type": "string", "format": "uuid" }, "initiativeId": { "type": "string", "format": "uuid" }, "initiativeName": { "type": "string", "maxLength": 200, "nullable": true }, "leadAccountId": { "type": "string", "format": "uuid", "nullable": true }, "accountIds": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "contactIds": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "metadata": { "type": "object", "additionalProperties": true } } } } } }, "responses": { "200": { "description": "Link created", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "initiativeId": { "type": "string", "format": "uuid" }, "linksCreated": { "type": "integer" }, "linked": { "type": "object", "properties": { "leadAccountId": { "type": "string", "format": "uuid", "nullable": true }, "accountIds": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "contactIds": { "type": "array", "items": { "type": "string", "format": "uuid" } } } } } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "BearerAuth": [] }, { "SessionCookie": [] } ] }, "get": { "summary": "Get initiative linked entities", "description": "Returns all entities linked to a specific initiative.", "operationId": "getInitiativeLinks", "tags": [ "Company" ], "parameters": [ { "$ref": "#/components/parameters/companyId" }, { "$ref": "#/components/parameters/XCompanyId" }, { "name": "initiativeId", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID of the initiative." } ], "responses": { "200": { "description": "Linked entities", "content": { "application/json": { "schema": { "type": "object", "properties": { "initiativeId": { "type": "string", "format": "uuid" }, "initiative": { "type": "object", "properties": { "name": { "type": "string", "nullable": true } } }, "leadAccount": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "domain": { "type": "string", "nullable": true }, "type": { "type": "string" }, "stage": { "type": "string", "nullable": true }, "investment_stage": { "type": "string", "nullable": true } } }, "accounts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "domain": { "type": "string", "nullable": true }, "type": { "type": "string" }, "stage": { "type": "string", "nullable": true }, "investment_stage": { "type": "string", "nullable": true } } } }, "contacts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "account_id": { "type": "string", "format": "uuid", "nullable": true }, "name": { "type": "string", "nullable": true }, "email": { "type": "string", "nullable": true } } } }, "relationCount": { "type": "integer" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "BearerAuth": [] }, { "SessionCookie": [] } ] } }, "/api/lists": { "get": { "summary": "List custom lists", "description": "Returns custom lists for the authenticated session. Optionally scope to a company with the `companyId` query parameter; otherwise the first active network membership is used.", "operationId": "listCustomLists", "tags": [ "Lists" ], "security": [ { "SessionCookie": [] } ], "parameters": [ { "$ref": "#/components/parameters/companyId" } ], "responses": { "200": { "description": "Custom lists", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CustomListSummary" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No owner context found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Failed to load lists", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Create custom list", "description": "Creates a custom list in the authenticated owner context and returns the canonical public list DTO.", "operationId": "createCustomList", "tags": [ "Lists" ], "security": [ { "SessionCookie": [] } ], "parameters": [ { "$ref": "#/components/parameters/companyId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "maxLength": 200 }, "description": { "type": "string", "maxLength": 1000 }, "icon": { "type": "string" }, "color": { "type": "string" }, "entity_type": { "type": "string", "default": "custom" } } } } } }, "responses": { "201": { "description": "Custom list created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomListSummary" } } } }, "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": "No owner context found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Failed to create list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/lists/{listId}": { "get": { "summary": "Get custom list", "description": "Returns a single custom list with its attributes for the authenticated session.", "operationId": "getCustomList", "tags": [ "Lists" ], "security": [ { "SessionCookie": [] } ], "parameters": [ { "name": "listId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Custom list detail", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomListWithAttributes" } } } }, "400": { "description": "Invalid list ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "List not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "summary": "Update custom list", "description": "Updates a custom list and returns the canonical summary DTO.", "operationId": "updateCustomList", "tags": [ "Lists" ], "security": [ { "SessionCookie": [] } ], "parameters": [ { "name": "listId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 200 }, "description": { "type": "string", "maxLength": 1000, "nullable": true }, "icon": { "type": "string", "nullable": true }, "color": { "type": "string", "nullable": true }, "position": { "type": "integer" } } } } } }, "responses": { "200": { "description": "Custom list updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomListSummary" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Failed to update list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "summary": "Delete custom list", "description": "Deletes a custom list for the authenticated session.", "operationId": "deleteCustomList", "tags": [ "Lists" ], "security": [ { "SessionCookie": [] } ], "parameters": [ { "name": "listId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Custom list deleted" }, "400": { "description": "Invalid list ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Failed to delete list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/lists/{listId}/entries": { "get": { "summary": "List custom list entries", "description": "Returns entries for a custom list. Entries are returned as a flat array DTO used by the dashboard list views.", "operationId": "listCustomListEntries", "tags": [ "Lists" ], "security": [ { "SessionCookie": [] } ], "parameters": [ { "name": "listId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "archived", "in": "query", "required": false, "schema": { "type": "boolean" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 500 } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "List entries", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CustomListEntry" } } } } }, "400": { "description": "Invalid list ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Failed to load entries", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Create custom list entry", "description": "Creates a new entry at the end of a custom list and returns the canonical entry DTO.", "operationId": "createCustomListEntry", "tags": [ "Lists" ], "security": [ { "SessionCookie": [] } ], "parameters": [ { "name": "listId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "title" ], "properties": { "title": { "type": "string", "maxLength": 500 }, "values": { "type": "object", "additionalProperties": true }, "linked_entity_type": { "type": "string", "nullable": true }, "linked_entity_id": { "type": "string", "format": "uuid", "nullable": true } } } } } }, "responses": { "201": { "description": "List entry created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomListEntry" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Failed to create entry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "summary": "Update custom list entry", "description": "Updates a custom list entry. When `values` is provided, keys are merged with the existing entry payload.", "operationId": "updateCustomListEntry", "tags": [ "Lists" ], "security": [ { "SessionCookie": [] } ], "parameters": [ { "name": "listId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string", "format": "uuid" }, "title": { "type": "string", "maxLength": 500 }, "values": { "type": "object", "additionalProperties": true }, "position": { "type": "integer" }, "archived": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "List entry updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomListEntry" } } } }, "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": "Entry not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Failed to update entry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "summary": "Delete custom list entry", "description": "Deletes a custom list entry by `entryId` query parameter.", "operationId": "deleteCustomListEntry", "tags": [ "Lists" ], "security": [ { "SessionCookie": [] } ], "parameters": [ { "name": "listId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "entryId", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "List entry deleted" }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Failed to delete entry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/lists/{listId}/attributes": { "post": { "summary": "Create custom list attribute", "description": "Creates a new attribute (column) on a custom list and returns the canonical attribute DTO.", "operationId": "createCustomListAttribute", "tags": [ "Lists" ], "security": [ { "SessionCookie": [] } ], "parameters": [ { "name": "listId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "attribute_type" ], "properties": { "name": { "type": "string", "maxLength": 100 }, "attribute_type": { "type": "string", "enum": [ "text", "number", "currency", "date", "url", "email", "select", "multi_select", "status", "checkbox", "rating" ] }, "config": { "$ref": "#/components/schemas/ListAttributeConfig" }, "is_required": { "type": "boolean", "default": false }, "position": { "type": "integer" } } } } } }, "responses": { "201": { "description": "List attribute created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomListAttribute" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Attribute already exists", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Failed to create attribute", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "summary": "Update custom list attribute", "description": "Updates a custom list attribute and returns the canonical attribute DTO.", "operationId": "updateCustomListAttribute", "tags": [ "Lists" ], "security": [ { "SessionCookie": [] } ], "parameters": [ { "name": "listId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "maxLength": 100 }, "config": { "$ref": "#/components/schemas/ListAttributeConfig" }, "is_required": { "type": "boolean" }, "position": { "type": "integer" } } } } } }, "responses": { "200": { "description": "List attribute updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomListAttribute" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Failed to update attribute", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "summary": "Delete custom list attribute", "description": "Deletes a custom list attribute by `attributeId` query parameter.", "operationId": "deleteCustomListAttribute", "tags": [ "Lists" ], "security": [ { "SessionCookie": [] } ], "parameters": [ { "name": "listId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "attributeId", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "List attribute deleted" }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Failed to delete attribute", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/github/issues": { "post": { "summary": "Track GitHub issue", "description": "Creates a tracked GitHub issue link for a room and optional stream entry. Supports Bearer API keys and browser sessions.", "operationId": "trackGithubIssue", "tags": [ "GitHub" ], "security": [ { "BearerAuth": [] }, { "SessionCookie": [] } ], "parameters": [ { "$ref": "#/components/parameters/companyId" }, { "$ref": "#/components/parameters/XCompanyId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "room_id", "issue_url", "issue_number", "title", "issue_type" ], "properties": { "room_id": { "type": "string", "format": "uuid" }, "issue_url": { "type": "string" }, "issue_number": { "type": "integer" }, "title": { "type": "string" }, "issue_type": { "type": "string", "enum": [ "epic", "feature", "task", "bug" ] }, "decision_content": { "type": "string", "nullable": true }, "stream_entry_id": { "type": "string", "format": "uuid", "nullable": true } } } } } }, "responses": { "201": { "description": "Tracked issue created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GithubTrackedIssue" } } } }, "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": "Room not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Issue already tracked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/github/issues/{id}": { "patch": { "summary": "Update tracked GitHub issue", "description": "Updates a tracked GitHub issue state, title, or decision content. Supports Bearer API keys and browser sessions.", "operationId": "updateGithubTrackedIssue", "tags": [ "GitHub" ], "security": [ { "BearerAuth": [] }, { "SessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/companyId" }, { "$ref": "#/components/parameters/XCompanyId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "state": { "type": "string", "enum": [ "open", "closed" ] }, "title": { "type": "string" }, "decision_content": { "type": "string", "nullable": true } } } } } }, "responses": { "200": { "description": "Tracked issue updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GithubTrackedIssue" } } } }, "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": "Issue not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/cli/sync": { "post": { "summary": "Sync local file to knowledge base", "description": "Syncs a local file from the CLI to the Operalta knowledge base. Creates or updates stream entries based on file content.", "operationId": "cliSync", "tags": [ "CLI" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "filePath", "content", "fileType" ], "properties": { "filePath": { "type": "string", "description": "Path of the file on the local system." }, "content": { "type": "string", "description": "Full text content of the file." }, "fileType": { "type": "string", "description": "File type or extension (e.g., md, txt, json)." } } } } } }, "responses": { "200": { "description": "Sync result", "content": { "application/json": { "schema": { "type": "object", "properties": { "entriesCreated": { "type": "integer", "description": "Number of new entries created." }, "entriesUpdated": { "type": "integer", "description": "Number of existing entries updated." } } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/rooms/{roomId}": { "get": { "summary": "Get room", "description": "Returns details for a single room. Supports Bearer API keys and browser sessions. Unscoped Bearer tokens must send X-Company-Id.", "operationId": "getRoom", "tags": [ "Rooms" ], "security": [ { "BearerAuth": [] }, { "SessionCookie": [] } ], "parameters": [ { "name": "roomId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/XCompanyId" } ], "responses": { "200": { "description": "Room details", "content": { "application/json": { "schema": { "type": "object", "properties": { "room": { "$ref": "#/components/schemas/Room" } } } } } }, "400": { "description": "Missing company context for unscoped Bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Room not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/rooms/{roomId}/views": { "get": { "summary": "List room saved views", "description": "Returns saved views for a room, ordered by pinned state, position, and creation time.", "operationId": "listRoomSavedViews", "tags": [ "Rooms" ], "security": [ { "SessionCookie": [] } ], "parameters": [ { "name": "roomId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Saved views", "content": { "application/json": { "schema": { "type": "object", "properties": { "views": { "type": "array", "items": { "$ref": "#/components/schemas/SavedView" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Room access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Room not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Failed to fetch views", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Create room saved view", "description": "Creates a saved view for a room and returns the canonical saved-view DTO.", "operationId": "createRoomSavedView", "tags": [ "Rooms" ], "security": [ { "SessionCookie": [] } ], "parameters": [ { "name": "roomId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "filters" ], "properties": { "name": { "type": "string", "maxLength": 100 }, "description": { "type": "string", "maxLength": 500, "nullable": true }, "icon": { "type": "string", "maxLength": 50 }, "filters": { "$ref": "#/components/schemas/SavedViewFilters" }, "is_pinned": { "type": "boolean" } } } } } }, "responses": { "201": { "description": "Saved view created", "content": { "application/json": { "schema": { "type": "object", "properties": { "view": { "$ref": "#/components/schemas/SavedView" } } } } } }, "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": "Room access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Room not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Failed to create view", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/rooms/{roomId}/views/{viewId}": { "get": { "summary": "Get room saved view", "description": "Returns one saved view for a room.", "operationId": "getRoomSavedView", "tags": [ "Rooms" ], "security": [ { "SessionCookie": [] } ], "parameters": [ { "name": "roomId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "viewId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Saved view", "content": { "application/json": { "schema": { "type": "object", "properties": { "view": { "$ref": "#/components/schemas/SavedView" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Room access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "View not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "summary": "Update room saved view", "description": "Updates a saved view. Only the creator can modify a view.", "operationId": "updateRoomSavedView", "tags": [ "Rooms" ], "security": [ { "SessionCookie": [] } ], "parameters": [ { "name": "roomId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "viewId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 100 }, "description": { "type": "string", "maxLength": 500, "nullable": true }, "icon": { "type": "string", "maxLength": 50 }, "filters": { "$ref": "#/components/schemas/SavedViewFilters" }, "is_pinned": { "type": "boolean" }, "position": { "type": "integer", "minimum": 0 } } } } } }, "responses": { "200": { "description": "Saved view updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "view": { "$ref": "#/components/schemas/SavedView" } } } } } }, "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": "Not allowed to update this view", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "View not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Failed to update view", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "summary": "Delete room saved view", "description": "Deletes a saved view. Only the creator can delete a view.", "operationId": "deleteRoomSavedView", "tags": [ "Rooms" ], "security": [ { "SessionCookie": [] } ], "parameters": [ { "name": "roomId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "viewId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Saved view deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Not allowed to delete this view", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "View not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Failed to delete view", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/rooms/{roomId}/github-issues": { "get": { "summary": "List room GitHub issues", "description": "Returns tracked GitHub issues linked to a room. Supports Bearer API keys and browser sessions.", "operationId": "listRoomGithubIssues", "tags": [ "Rooms" ], "security": [ { "BearerAuth": [] }, { "SessionCookie": [] } ], "parameters": [ { "name": "roomId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/companyId" }, { "$ref": "#/components/parameters/XCompanyId" }, { "name": "state", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "open", "closed", "all" ] } }, { "name": "type", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "epic", "feature", "task", "bug" ] } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200 } } ], "responses": { "200": { "description": "Tracked room GitHub issues", "content": { "application/json": { "schema": { "type": "object", "properties": { "issues": { "type": "array", "items": { "$ref": "#/components/schemas/GithubTrackedIssue" } }, "total": { "type": "integer" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Room not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/contacts": { "get": { "summary": "List contacts", "description": "Returns contacts for the requested owner. Bearer API keys support `owner_type=company`; `owner_type=network` remains a browser-session flow.", "operationId": "listContacts", "tags": [ "Contacts" ], "parameters": [ { "name": "owner_type", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "company", "network" ] }, "description": "Owner scope. Bearer callers should use `company`." }, { "name": "owner_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Company UUID or network UUID matching `owner_type`." }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Optional full-text search query." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Contacts list", "content": { "application/json": { "schema": { "type": "object", "required": [ "contacts", "total", "hasMore" ], "properties": { "contacts": { "type": "array", "items": { "$ref": "#/components/schemas/Contact" } }, "total": { "type": "integer" }, "hasMore": { "type": "boolean" } } } } } }, "400": { "description": "Missing or invalid owner parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "BearerAuth": [] }, { "SessionCookie": [] } ] }, "post": { "summary": "Create contact", "description": "Creates a contact for the requested owner. Bearer API keys support `owner_type=company`; `owner_type=network` remains a browser-session flow.", "operationId": "createContact", "tags": [ "Contacts" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "owner_type", "owner_id" ], "properties": { "owner_type": { "type": "string", "enum": [ "company", "network" ] }, "owner_id": { "type": "string", "format": "uuid" }, "email": { "type": "string" }, "name": { "type": "string" }, "phone": { "type": "string" }, "linkedin_url": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "source": { "type": "string" }, "company_name": { "type": "string" }, "website_domain": { "type": "string" } }, "description": "At least one of `email` or `linkedin_url` must be provided. Bearer callers should use `owner_type=company`." } } } }, "responses": { "200": { "description": "Contact created or reused", "content": { "application/json": { "schema": { "type": "object", "required": [ "contact" ], "properties": { "contact": { "$ref": "#/components/schemas/Contact" }, "existed": { "type": "boolean" } } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Duplicate contact in the same owner scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "BearerAuth": [] }, { "SessionCookie": [] } ] } }, "/api/rooms/{roomId}/streams": { "get": { "summary": "List room stream entries", "description": "Returns stream entries linked to artifacts in a room. Supports Bearer API keys and browser sessions.", "operationId": "listRoomStreams", "tags": [ "Rooms" ], "security": [ { "BearerAuth": [] }, { "SessionCookie": [] } ], "parameters": [ { "name": "roomId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/companyId" }, { "$ref": "#/components/parameters/XCompanyId" }, { "name": "since", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200 } }, { "name": "types", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Comma-separated stream entry types." } ], "responses": { "200": { "description": "Room stream entries", "content": { "application/json": { "schema": { "type": "object", "properties": { "entries": { "type": "array", "items": { "$ref": "#/components/schemas/StreamEntry" } }, "total": { "type": "integer" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Room not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/metrics/preferences": { "get": { "summary": "Read VC metric display preferences", "description": "Browser-session route that returns the saved metric display preferences for a VC company. When no row exists yet, the server returns the canonical default preferences.", "operationId": "getMetricPreferences", "tags": [ "Metrics" ], "parameters": [ { "name": "vcCompanyId", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID of the VC company whose display preferences to read." } ], "responses": { "200": { "description": "Metric preferences", "content": { "application/json": { "schema": { "type": "object", "required": [ "preferences" ], "properties": { "preferences": { "$ref": "#/components/schemas/MetricPreferences" } } } } } }, "400": { "description": "vcCompanyId is required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authenticated browser session required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "SessionCookie": [] } ] }, "post": { "summary": "Create or update VC metric display preferences", "description": "Browser-session route that upserts the saved metric display preferences for a VC company and returns the canonical response envelope.", "operationId": "upsertMetricPreferences", "tags": [ "Metrics" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "vcCompanyId" ], "properties": { "vcCompanyId": { "type": "string", "format": "uuid" }, "requestedMetrics": { "type": "array", "items": { "type": "string" } }, "tableColumns": { "type": "array", "items": { "type": "string" } }, "cardPages": { "type": "array", "items": { "$ref": "#/components/schemas/MetricPreferenceCardPage" } } } } } } }, "responses": { "200": { "description": "Metric preferences saved", "content": { "application/json": { "schema": { "type": "object", "required": [ "preferences" ], "properties": { "preferences": { "$ref": "#/components/schemas/MetricPreferences" } } } } } }, "400": { "description": "Invalid payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authenticated browser session required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "SessionCookie": [] } ] } }, "/api/company/initiatives/refresh": { "post": { "summary": "Queue initiatives refresh", "description": "Queues background re-analysis/sync for company initiatives. Requires internal company access and decisions:write for Bearer callers.", "operationId": "refreshCompanyInitiatives", "tags": [ "Company" ], "parameters": [ { "$ref": "#/components/parameters/companyId" }, { "$ref": "#/components/parameters/XCompanyId" } ], "responses": { "200": { "description": "Initiatives refresh queued", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "eventId": { "type": "string", "nullable": true } } } } } }, "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" } } } }, "500": { "description": "Failed to queue initiatives refresh", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "BearerAuth": [] }, { "SessionCookie": [] } ] } }, "/api/collect": { "post": { "summary": "Collect source data into an Operalta sink", "description": "Unified JSON-only source-to-sink import route used by browser, CLI, and MCP. Binary files must be staged through /api/uploads first and referenced as uploaded-file. Current implemented public sinks are document, list, contacts, and accounts; metrics and chat-attachment are declared but return 501 until implemented.", "operationId": "collect", "tags": [ "Collect" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectRequest" } } } }, "responses": { "200": { "description": "Collect result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectResult" } } } }, "400": { "description": "Invalid collect request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Sink returned validation errors", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectResult" } } } }, "500": { "description": "Collect failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "501": { "description": "Sink not implemented", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "BearerAuth": [] }, { "SessionCookie": [] } ] } }, "/api/company/knowledge/search": { "get": { "summary": "Search internal company knowledge", "description": "Searches company artifacts, source documents, and stream entries according to the caller scopes. Bearer callers need at least one of artifacts:read, documents:read, or decisions:read.", "operationId": "searchCompanyKnowledge", "tags": [ "Company" ], "parameters": [ { "name": "query", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Search query." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 25, "default": 10 }, "description": "Max results per surface." }, { "$ref": "#/components/parameters/companyId" }, { "$ref": "#/components/parameters/XCompanyId" } ], "responses": { "200": { "description": "Knowledge search results", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyKnowledgeSearchResults" } } } }, "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": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "BearerAuth": [] }, { "SessionCookie": [] } ] } }, "/api/company/knowledge/read": { "get": { "summary": "Read one internal knowledge item", "description": "Reads one artifact, source document, or stream entry by id. Bearer callers need artifacts:read, documents:read, or decisions:read respectively.", "operationId": "readCompanyKnowledgeItem", "tags": [ "Company" ], "parameters": [ { "name": "kind", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "artifact", "document", "stream" ] }, "description": "Knowledge item kind." }, { "name": "id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Knowledge item UUID." }, { "name": "maxChars", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 500, "maximum": 20000, "default": 8000 }, "description": "Maximum returned content characters." }, { "$ref": "#/components/parameters/companyId" }, { "$ref": "#/components/parameters/XCompanyId" } ], "responses": { "200": { "description": "Knowledge item", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyKnowledgeReadResponse" } } } }, "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": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Knowledge item not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "BearerAuth": [] }, { "SessionCookie": [] } ] } }, "/api/enrichment/firm": { "post": { "summary": "Run firm enrichment", "description": "Runs site crawl and structured profile enrichment for a firm URL. Used by MCP/CLI firm enrichment tooling. Requires a write-capable token or session.", "operationId": "enrichFirm", "tags": [ "Enrichment" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string" }, "contextType": { "type": "string", "enum": [ "startup", "vc", "pe", "lp", "advisory", "accelerator", "gov", "academic", "cvc" ], "default": "startup" }, "level": { "type": "string", "enum": [ "basic", "deep", "deeper" ], "default": "deep" }, "name": { "type": "string", "maxLength": 200 }, "persist": { "type": "boolean", "default": true } } } } } }, "responses": { "200": { "description": "Firm enrichment result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FirmEnrichmentResponse" } } } }, "400": { "description": "Invalid request or URL", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Enrichment failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Enrichment provider failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "BearerAuth": [] }, { "SessionCookie": [] } ] } }, "/api/portfolio/pipeline/{id}/sequences": { "post": { "summary": "Create a pipeline sequence", "description": "Creates a new active sequence for a pipeline account. Only one active sequence per type is allowed.", "operationId": "createPipelineSequence", "tags": [ "Pipeline" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "companyId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Company UUID for company-scoped pipeline access. Required for Bearer tokens unless the token is company-bound." }, { "$ref": "#/components/parameters/XCompanyId" }, { "name": "networkId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Optional legacy vc_portfolio network lane UUID for browser/session callers." }, { "name": "listId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Optional pipeline list rail UUID. When present, reads and writes are scoped to that rail." }, { "name": "c", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Optional company slug used by browser/session callers to resolve company scope." }, { "name": "scope", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "company", "network" ], "default": "company" }, "description": "Pipeline authority scope. Company scope is the default and the only Bearer-token mode." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "sequenceType" ], "properties": { "sequenceType": { "type": "string", "enum": [ "fundraising", "investor_relations", "sales", "partnership", "hiring", "general" ] }, "stage": { "type": "string", "maxLength": 120 }, "ownerId": { "type": "string", "format": "uuid", "nullable": true }, "notes": { "type": "string", "maxLength": 50000, "nullable": true } } } } } }, "responses": { "200": { "description": "Pipeline sequence created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PipelineSequenceMutationResponse" } } } }, "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": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "BearerAuth": [] }, { "SessionCookie": [] } ] } }, "/api/portfolio/pipeline/existing": { "get": { "summary": "List existing accounts eligible for pipeline intake", "description": "Lists active workspace accounts that are not already tracked as pipeline or portfolio records.", "operationId": "listExistingPipelineAccounts", "tags": [ "Pipeline" ], "parameters": [ { "name": "companyId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Company UUID for company-scoped pipeline access. Required for Bearer tokens unless the token is company-bound." }, { "$ref": "#/components/parameters/XCompanyId" }, { "name": "networkId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Optional legacy vc_portfolio network lane UUID for browser/session callers." }, { "name": "listId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Optional pipeline list rail UUID. When present, reads and writes are scoped to that rail." }, { "name": "c", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Optional company slug used by browser/session callers to resolve company scope." }, { "name": "scope", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "company", "network" ], "default": "company" }, "description": "Pipeline authority scope. Company scope is the default and the only Bearer-token mode." }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Optional account name/domain search term." } ], "responses": { "200": { "description": "Existing accounts", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PipelineExistingAccountsResponse" } } } }, "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": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "BearerAuth": [] }, { "SessionCookie": [] } ] }, "post": { "summary": "Add an existing account to pipeline", "description": "Moves an existing workspace account into the pipeline or portfolio lifecycle and initializes its fundraising sequence.", "operationId": "addExistingPipelineAccount", "tags": [ "Pipeline" ], "parameters": [ { "name": "companyId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Company UUID for company-scoped pipeline access. Required for Bearer tokens unless the token is company-bound." }, { "$ref": "#/components/parameters/XCompanyId" }, { "name": "networkId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Optional legacy vc_portfolio network lane UUID for browser/session callers." }, { "name": "listId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Optional pipeline list rail UUID. When present, reads and writes are scoped to that rail." }, { "name": "c", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Optional company slug used by browser/session callers to resolve company scope." }, { "name": "scope", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "company", "network" ], "default": "company" }, "description": "Pipeline authority scope. Company scope is the default and the only Bearer-token mode." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "accountId", "investmentStage" ], "properties": { "accountId": { "type": "string", "format": "uuid" }, "investmentStage": { "type": "string", "enum": [ "research", "intro", "diligence", "term_sheet", "closed", "passed", "portfolio" ] } } } } } }, "responses": { "200": { "description": "Existing account added to pipeline", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PipelineDealMutationResponse" } } } }, "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": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "BearerAuth": [] }, { "SessionCookie": [] } ] } }, "/api/portfolio/pipeline/enrich-from-url": { "post": { "summary": "Preview pipeline enrichment from URL", "description": "Normalizes a URL, reuses cached firm enrichment when available, or runs live enrichment to suggest name/context/facts before pipeline intake.", "operationId": "enrichPipelineFromUrl", "tags": [ "Pipeline" ], "parameters": [ { "name": "companyId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Company UUID for company-scoped pipeline access. Required for Bearer tokens unless the token is company-bound." }, { "$ref": "#/components/parameters/XCompanyId" }, { "name": "networkId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Optional legacy vc_portfolio network lane UUID for browser/session callers." }, { "name": "listId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Optional pipeline list rail UUID. When present, reads and writes are scoped to that rail." }, { "name": "c", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Optional company slug used by browser/session callers to resolve company scope." }, { "name": "scope", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "company", "network" ], "default": "company" }, "description": "Pipeline authority scope. Company scope is the default and the only Bearer-token mode." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string" }, "contextType": { "type": "string", "enum": [ "startup", "vc", "pe", "lp", "advisory", "accelerator", "gov", "academic", "cvc" ], "default": "startup" } } } } } }, "responses": { "200": { "description": "Pipeline URL enrichment preview", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PipelineEnrichFromUrlResponse" } } } }, "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": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "BearerAuth": [] }, { "SessionCookie": [] } ] } }, "/api/portfolio/pipeline/{id}/upload": { "post": { "summary": "Attach pipeline deck or metrics file", "description": "Links an already-uploaded source document or uploads a legacy file directly into the pipeline deck/metrics slot. Metrics uploads queue background account metric import when possible.", "operationId": "uploadPipelineMaterial", "tags": [ "Pipeline" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "companyId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Company UUID for company-scoped pipeline access. Required for Bearer tokens unless the token is company-bound." }, { "$ref": "#/components/parameters/XCompanyId" }, { "name": "networkId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Optional legacy vc_portfolio network lane UUID for browser/session callers." }, { "name": "listId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Optional pipeline list rail UUID. When present, reads and writes are scoped to that rail." }, { "name": "c", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Optional company slug used by browser/session callers to resolve company scope." }, { "name": "scope", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "company", "network" ], "default": "company" }, "description": "Pipeline authority scope. Company scope is the default and the only Bearer-token mode." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "documentId", "type" ], "properties": { "documentId": { "type": "string", "format": "uuid" }, "type": { "type": "string", "enum": [ "deck", "metrics" ] } } } }, "multipart/form-data": { "schema": { "type": "object", "required": [ "file", "type" ], "properties": { "file": { "type": "string", "format": "binary" }, "type": { "type": "string", "enum": [ "deck", "metrics" ] } } } } } }, "responses": { "200": { "description": "Pipeline material attached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PipelineUploadResponse" } } } }, "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": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "BearerAuth": [] }, { "SessionCookie": [] } ] } }, "/api/portfolio/pipeline/{id}/enrich": { "post": { "summary": "Queue pipeline account enrichment", "description": "Queues research, due diligence, or screening enrichment for a pipeline account.", "operationId": "enrichPipelineAccount", "tags": [ "Pipeline" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "companyId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Company UUID for company-scoped pipeline access. Required for Bearer tokens unless the token is company-bound." }, { "$ref": "#/components/parameters/XCompanyId" }, { "name": "networkId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Optional legacy vc_portfolio network lane UUID for browser/session callers." }, { "name": "listId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Optional pipeline list rail UUID. When present, reads and writes are scoped to that rail." }, { "name": "c", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Optional company slug used by browser/session callers to resolve company scope." }, { "name": "scope", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "company", "network" ], "default": "company" }, "description": "Pipeline authority scope. Company scope is the default and the only Bearer-token mode." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "research", "due_diligence", "screening" ] } } } } } }, "responses": { "200": { "description": "Pipeline enrichment queued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PipelineEnrichResponse" } } } }, "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": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "BearerAuth": [] }, { "SessionCookie": [] } ] } }, "/api/portfolio/pipeline/{id}/promote": { "post": { "summary": "Promote pipeline startup to portfolio", "description": "Promotes a tracked startup from pipeline lifecycle to portfolio lifecycle and syncs portfolio list membership.", "operationId": "promotePipelineDeal", "tags": [ "Pipeline" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "companyId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Company UUID for company-scoped pipeline access. Required for Bearer tokens unless the token is company-bound." }, { "$ref": "#/components/parameters/XCompanyId" }, { "name": "networkId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Optional legacy vc_portfolio network lane UUID for browser/session callers." }, { "name": "listId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Optional pipeline list rail UUID. When present, reads and writes are scoped to that rail." }, { "name": "c", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Optional company slug used by browser/session callers to resolve company scope." }, { "name": "scope", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "company", "network" ], "default": "company" }, "description": "Pipeline authority scope. Company scope is the default and the only Bearer-token mode." } ], "responses": { "200": { "description": "Pipeline deal promoted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PipelinePromoteResponse" } } } }, "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": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "BearerAuth": [] }, { "SessionCookie": [] } ] } }, "/api/portfolio/pipeline/{id}/room": { "post": { "summary": "Get or create pipeline dossier room", "description": "Returns the deterministic private dossier room for a pipeline account, creating it if needed.", "operationId": "getOrCreatePipelineRoom", "tags": [ "Pipeline" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "companyId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Company UUID for company-scoped pipeline access. Required for Bearer tokens unless the token is company-bound." }, { "$ref": "#/components/parameters/XCompanyId" }, { "name": "networkId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Optional legacy vc_portfolio network lane UUID for browser/session callers." }, { "name": "listId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Optional pipeline list rail UUID. When present, reads and writes are scoped to that rail." }, { "name": "c", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Optional company slug used by browser/session callers to resolve company scope." }, { "name": "scope", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "company", "network" ], "default": "company" }, "description": "Pipeline authority scope. Company scope is the default and the only Bearer-token mode." } ], "responses": { "200": { "description": "Pipeline dossier room", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PipelineRoomResponse" } } } }, "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": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "BearerAuth": [] }, { "SessionCookie": [] } ] } } }, "tags": [] }