{ "openapi": "3.0.1", "info": { "title": "LinqAlpha API", "description": "Linq helps finance professionals make informed decisions using Retrieval-Augmented Generation (RAG)-enhanced answers. By leveraging cutting-edge Large Language Models (LLM) and supplementary technology, Linq provides the most optimized responses based on your queries.", "version": "1.0.0", "license": { "name": "MIT" } }, "servers": [ { "url": "https://api.linqalpha.com" } ], "security": [ { "ApiKeyAuth": [] } ], "tags": [ { "name": "Search", "description": "Search and generate responses" }, { "name": "Data", "description": "Data retrieval and mapping" }, { "name": "Feedback", "description": "Conversation feedback" }, { "name": "RMS", "description": "Research Management System" }, { "name": "Source Management", "description": "Source batch and file management" }, { "name": "MCP", "description": "LinqAlpha MCP — Financial data tools for AI assistants via Model Context Protocol" }, { "name": "Connectors", "description": "Customer Connectors — customer-owned MCP connector management" }, { "name": "Briefing", "description": "Briefing Agent — automated market briefings with scheduling and delivery" }, { "name": "Status", "description": "Sync status — check organization, document, and container sync progress" } ], "paths": { "/v1/organizations": { "post": { "summary": "Create Organization", "description": "Creates a new organization with the specified parameters.\n\n**Note**: This feature is available to a limited set of users only. Access requires a separate onboarding process, which will be provided upon request. For more information, please contact us at [support@linqalpha.com](mailto:support@linqalpha.com)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOrganizationRequest" }, "example": { "id": "organization_001", "name": "Example Investment Fund", "s3_path": "s3://example-bucket/organization_001/" } } } }, "responses": { "200": { "description": "Organization created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOrganizationResponse" }, "example": { "organization_id": "123e4567-e89b-12d3-a456-426614174000", "error": null } } } }, "400": { "description": "Bad Request - Invalid request parameters or incorrect format.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" }, "example": { "error": { "code": "ORGANIZATION_ID_MISSING", "msg": "organization id is required", "message": "organization id is required" }, "payload": null } } } }, "401": { "description": "Unauthorized - Invalid API key or authentication credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" }, "example": { "error": { "code": "API_KEY_MISSING", "msg": "header does not contain api key", "message": "header does not contain api key" }, "payload": null } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" }, "example": { "error": { "code": "SERVER_ERROR", "message": "An unexpected error occurred on the server." }, "payload": null } } } } }, "tags": [ "RMS" ] } }, "/v1/source_batches": { "post": { "summary": "Create Source Batch", "description": "Creates a new source batch container for organizing and managing related document sources. A source batch acts as a logical grouping that must be created before uploading any sources. The returned `source_batch_id` is required when creating sources and can be used to reference all contained sources in chat or search requests.\n\n**Workflow:**\n1. Create a source batch (this endpoint)\n2. Upload sources to the batch using the returned `source_batch_id`\n3. Use the `source_batch_id` in chat/search API requests to access all sources in the batch", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSourceBatchRequest" }, "example": { "name": "Q4_Financial_Reports", "description": "Financial documents for Q4 2024 analysis" } } } }, "responses": { "200": { "description": "Source batch created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSourceBatchResponse" }, "example": { "source_batch_id": "123e4567-e89b-12d3-a456-426614174000" } } } }, "400": { "description": "Bad request - invalid parameters" }, "401": { "description": "Unauthorized - invalid or missing API key" } }, "tags": [ "Source Management" ] } }, "/v1/sources/upload_url": { "post": { "summary": "Get Upload URL", "description": "Returns a presigned S3 PUT URL for direct file upload. Lets clients upload files without managing AWS credentials or staging buckets — the server signs a single-use URL bound to a server-generated S3 object key, the client PUTs the file body to that URL, then registers the upload via `POST /v1/sources` with the returned `file_key`.\n\n**Why this exists:** `POST /v1/sources` requires a `file_key` for an object that already exists in our backing storage. Customers without their own staging bucket use this endpoint to obtain an upload URL pointed at the canonical destination directly, eliminating any client-side AWS setup.\n\n**Important — Content-Type binding:** The presigned URL is signed with `Content-Type` baked into the signature. The client **MUST** send a matching `Content-Type` header on the PUT request, otherwise S3 rejects with HTTP 403 (`SignatureDoesNotMatch`). The expected value is returned in the `content_type` field of this response — pass it back as the `Content-Type` header on your PUT.\n\n**Workflow:**\n1. Create a source batch via `POST /v1/source_batches` (returns `source_batch_id`)\n2. Call this endpoint with `name`, `source_type`, `source_batch_id` (returns `upload_url`, `file_key`, `content_type`, `expires_in`)\n3. PUT the file to `upload_url` with `Content-Type: ` header\n4. Register the source via `POST /v1/sources` with `file_key` from step 2\n5. Poll `GET /v1/sources/{source_id}` until `status: \"success\"`\n6. Reference `source_batch_id` in chat/search requests\n\n**Constraints:**\n- Supported `source_type`: `pdf`, `docx`, `xlsx`, `pptx`, `doc`, `txt`\n- Maximum file size enforced at registration step: 20MB\n- Maximum 10 active sources (status: `processing` or `success`) per source_batch — `failed`/`deleted` sources do not count toward the limit (enforced when generating the URL)\n- URL expires after 10 minutes (`expires_in: 600`)\n- File is validated at registration time (`POST /v1/sources`); a wrong-content upload will be accepted by S3 but rejected when registering", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadUrlRequest" }, "example": { "name": "Q4_Revenue_Report.pdf", "source_type": "pdf", "source_batch_id": "123e4567-e89b-12d3-a456-426614174000" } } } }, "responses": { "200": { "description": "Presigned upload URL generated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadUrlResponse" }, "example": { "upload_url": "https://linq-vertex-documents.s3.amazonaws.com/uploads/1715000000000_a1b2c3d4_Q4_Revenue_Report.pdf/original.pdf?X-Amz-Algorithm=...&X-Amz-Signature=...", "file_key": "uploads/1715000000000_a1b2c3d4_Q4_Revenue_Report.pdf/original.pdf", "content_type": "application/pdf", "expires_in": 600 } } } }, "400": { "description": "Bad request — invalid `source_type` or missing required fields" }, "401": { "description": "Unauthorized — invalid or missing API key" }, "404": { "description": "Source batch not found or not accessible to the caller" }, "422": { "description": "Source batch already contains the maximum number of sources (10)" } }, "tags": [ "Source Management" ] } }, "/v1/sources": { "post": { "summary": "Create Source", "description": "Registers a previously-uploaded file as a document source under a source batch and queues it for asynchronous parsing. Once `status: \"success\"`, the source is searchable in chat/search conversations that reference its `source_batch_id`.\n\n**Important Notes:**\n- **Prerequisite:** A source batch must be created first using `POST /v1/source_batches`\n- **The file must already be in S3** before calling this endpoint. Two ways to get it there:\n - **Recommended:** call `POST /v1/sources/upload_url` to obtain a presigned PUT URL, upload the file directly via that URL, then pass the returned `file_key` here. No client-side AWS setup required.\n - **Alternative:** if you already have your own S3 staging bucket integrated with us, upload there and pass the resulting `file_key`.\n- **Processing:** Sources are queued for asynchronous processing. Use `GET /v1/sources/{source_id}` to poll the processing status before using in conversations.\n- **File Requirements:**\n - Supported formats: PDF, DOCX, XLSX, DOC, TXT, PPTX\n - Maximum size: 20MB per file\n - Maximum files per batch: 10 files\n- **Usage in Conversations:**\n - Reference sources via `source_batch_id` in chat/search API requests\n - All sources in a batch are accessible when the batch is referenced\n - Sources remain available for reuse within conversations that reference their batch\n\n**Workflow (presigned-URL path):**\n1. `POST /v1/source_batches` → `source_batch_id`\n2. `POST /v1/sources/upload_url` → `upload_url`, `file_key`, `content_type`\n3. PUT the file body to `upload_url` with header `Content-Type: `\n4. `POST /v1/sources` (this endpoint) with `file_key` from step 2\n5. Poll `GET /v1/sources/{source_id}` until `status: \"success\"`\n6. Reference `source_batch_id` in chat/search requests", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSourceRequest" }, "example": { "source_batch_id": "123e4567-e89b-12d3-a456-426614174000", "name": "Q4_Revenue_Report.pdf", "file_key": "uploaded_sources/2024/q4/revenue_report.pdf" } } } }, "responses": { "200": { "description": "Source created and queued for processing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSourceResponse" }, "example": { "source_id": "456e7890-e89b-12d3-a456-426614174001", "size": 2048576, "status": "processing" } } } }, "400": { "description": "Bad request - invalid file format, size exceeded, or invalid source_batch_id" }, "401": { "description": "Unauthorized - invalid or missing API key" }, "404": { "description": "Source batch not found" } }, "tags": [ "Source Management" ] } }, "/v1/sources/{source_id}": { "get": { "summary": "Get Source Status", "description": "Retrieves the current processing status of an uploaded source. Use this endpoint to poll source readiness before including it in chat or search requests.\n\n**Status Values:**\n- `processing`: Source is being parsed and indexed (typically takes 10-60 seconds depending on file size)\n- `success`: Source is ready for use in conversations\n- `failed`: Processing failed (check file format, size, or content validity)\n\n**Best Practice:** Poll this endpoint with exponential backoff until status is `success` before initiating chat/search requests.", "parameters": [ { "name": "source_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The unique identifier (UUID) of the source returned from POST /v1/sources", "example": "456e7890-e89b-12d3-a456-426614174001" } ], "responses": { "200": { "description": "Source status retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetSourceResponse" }, "examples": { "processing": { "summary": "Source is being processed", "value": { "source_id": "456e7890-e89b-12d3-a456-426614174001", "status": "processing" } }, "success": { "summary": "Source is ready", "value": { "source_id": "456e7890-e89b-12d3-a456-426614174001", "status": "success" } }, "failed": { "summary": "Processing failed", "value": { "source_id": "456e7890-e89b-12d3-a456-426614174001", "status": "failed", "error": "Unsupported file format or corrupted file" } } } } } }, "401": { "description": "Unauthorized - invalid or missing API key" }, "404": { "description": "Source not found" } }, "tags": [ "Source Management" ] } }, "/v1/rms_chat": { "post": { "summary": "RMS Chat (SSE - Stream)", "description": "Generate a response using the RMS (Research Management System) with streaming server-sent events. This endpoint provides enhanced search capabilities with organization-specific data and customizable document types.\n\n**Note**: This feature is available to a limited set of users only. Access requires a separate onboarding process, which will be provided upon request. For more information, please contact us at [support@linqalpha.com](mailto:support@linqalpha.com)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RmsChatRequest" }, "example": { "organization_id": "123e4567-e89b-12d3-a456-426614174000", "conversation_id": "987e6543-e21b-32d3-c654-426614174999", "user_id": "123e4567-e89b-12d3-a456-426614174000", "user_email": "john.doe@example.com", "user_name": "John Doe", "query": "What are the latest insights on AAPL performance?", "search_types": [ "rms", "external" ], "external_types": [ "transcript", "filing", "news", "ir_slide" ], "rms_types": [ "emailnotes", "generalnotes" ], "stock_ids": [ "BBG001S5N8V8" ], "per_event_size": 0, "per_event_sleep_time": 0.01, "source_batch_id": "123e4567-e89b-12d3-a456-426614174000", "fiscal_period": { "start_time": { "year": 2023, "quarter": 1 }, "end_time": { "year": 2024, "quarter": 3 } } } } } }, "responses": { "200": { "description": "SSE stream response with RMS search results", "content": { "text/event-stream": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ConversationEvent" }, { "$ref": "#/components/schemas/DialogueIdEvent" }, { "$ref": "#/components/schemas/ThinkEvent" }, { "$ref": "#/components/schemas/SubQuestionsEvent" }, { "$ref": "#/components/schemas/StatusEvent" }, { "$ref": "#/components/schemas/DialogueIdEvent" }, { "$ref": "#/components/schemas/SearchResultsEvent" }, { "$ref": "#/components/schemas/AnswerEvent" } ], "discriminator": { "propertyName": "event_name", "mapping": { "conversation": "#/components/schemas/ConversationEvent", "dialogue_id": "#/components/schemas/DialogueIdEvent", "think": "#/components/schemas/ThinkEvent", "sub_questions": "#/components/schemas/SubQuestionsEvent", "status": "#/components/schemas/StatusEvent", "search_results": "#/components/schemas/SearchResultsEvent", "answer": "#/components/schemas/AnswerEvent" } } }, "examples": { "conversation_created": { "summary": "1) Conversation Created", "description": "Created conversation ID", "value": { "event_name": "conversation", "data": { "conversation_id": "123e4567-e89b-12d3-a456-426614174000" } } }, "dialogue_id_event": { "summary": "2) Dialogue ID", "description": "Dialogue ID for stream control/stop", "value": { "event_name": "dialogue_id", "data": { "dialogue_id": "987e6543-e21b-32d3-c654-426614174999" } } }, "think_event": { "summary": "3) Think", "description": "Model's planning/reasoning piece (streaming)", "value": { "event_name": "think", "data": { "think_piece": "" } } }, "sub_questions_event": { "summary": "4) Sub Questions", "description": "Sub-question generation result", "value": { "event_name": "sub_questions", "data": { "sub_questions": [ "What are the key points of AAPL's recent performance?", "What is the summary of the Brokerage Research?" ] } } }, "search_results_event": { "summary": "5) Search Results ID", "description": "Provide chat_message_id for reference lookup", "value": { "event_name": "search_results", "data": { "chat_message_id": "123e4567-e89b-12d3-a456-426614174000" } } }, "answer_event": { "summary": "6) Answer", "description": "Final answer piece (streaming)", "value": { "event_name": "answer", "data": { "answer_piece": "Based on the latest research..." } } }, "status_finish": { "summary": "7) Status Finish", "description": "Stream end", "value": { "event_name": "status", "data": { "status": "finish" } } } } } } }, "400": { "description": "Bad Request - Invalid request parameters or incorrect format.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" }, "example": { "error": { "code": "CREATE_CONV_FAIL", "message": "RMS conversation could not be created." }, "payload": null } } } }, "401": { "description": "Unauthorized - Invalid authentication credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" }, "example": { "error": { "code": "API_KEY_MISSING", "msg": "header does not contain api key", "message": "header does not contain api key" }, "payload": null } } } }, "403": { "description": "Forbidden - No permission to access this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" }, "example": { "error": { "code": "FORBIDDEN", "message": "Access denied: insufficient permissions." }, "payload": null } } } }, "404": { "description": "Not Found - The requested resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "message": "The requested resource was not found." }, "payload": null } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" }, "example": { "error": { "code": "SERVER_ERROR", "message": "An unexpected error occurred on the server." }, "payload": null } } } } }, "tags": [ "RMS" ] } }, "/v1/rms_deep_research": { "post": { "summary": "RMS Deep Research", "description": "Generate a response using the RMS (Research Management System) with deep research capabilities. This endpoint provides enhanced search capabilities with organization-specific data and customizable document types.\n\n**Note**:This feature is available to a limited set of users only. Access requires a separate onboarding process, which will be provided upon request. For more information, please contact us at [support@linqalpha.com](mailto:support@linqalpha.com)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RmsChatRequest" }, "example": { "organization_id": "123e4567-e89b-12d3-a456-426614174000", "conversation_id": "987e6543-e21b-32d3-c654-426614174999", "user_id": "123e4567-e89b-12d3-a456-426614174000", "user_email": "john.doe@example.com", "user_name": "John Doe", "query": "What are the latest insights on AAPL performance?", "search_types": [ "rms", "external" ], "external_types": [ "transcript", "filing", "news", "ir_slide" ], "rms_types": [ "emailnotes", "generalnotes" ], "document_ids": [ "123e4567-e89b-12d3-a456-426614174000" ], "container_ids": [ "123e4567-e89b-12d3-a456-426614174000" ], "stock_ids": [ "BBG001S5N8V8" ], "per_event_size": 0, "per_event_sleep_time": 0.01, "upload_period": { "start_time": { "year": 2023, "month": 1, "day": 1 }, "end_time": { "year": 2024, "month": 12, "day": 31 } }, "fiscal_period": { "start_time": { "year": 2023, "quarter": 1 }, "end_time": { "year": 2024, "quarter": 3 } } } } } }, "responses": { "200": { "description": "SSE stream of research events. Each event is sent as `data: {json}\\n\\n`", "content": { "text/event-stream": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ConversationEvent" }, { "$ref": "#/components/schemas/ChatMessageEvent" }, { "$ref": "#/components/schemas/StatusEvent" }, { "$ref": "#/components/schemas/KeepAliveEvent" }, { "$ref": "#/components/schemas/DialogueIdEvent" }, { "$ref": "#/components/schemas/ResearchProgressEvent" }, { "$ref": "#/components/schemas/RoundEvent" }, { "$ref": "#/components/schemas/ThinkEvent" }, { "$ref": "#/components/schemas/ToolCallEvent" }, { "$ref": "#/components/schemas/ToolResponseEvent" }, { "$ref": "#/components/schemas/SearchResultsEvent" }, { "$ref": "#/components/schemas/AnswerEvent" } ], "discriminator": { "propertyName": "event_name", "mapping": { "conversation": "#/components/schemas/ConversationEvent", "chat_message": "#/components/schemas/ChatMessageEvent", "status": "#/components/schemas/StatusEvent", "keep_alive": "#/components/schemas/KeepAliveEvent", "dialogue_id": "#/components/schemas/DialogueIdEvent", "research_progress": "#/components/schemas/ResearchProgressEvent", "round": "#/components/schemas/RoundEvent", "think": "#/components/schemas/ThinkEvent", "tool_call": "#/components/schemas/ToolCallEvent", "tool_response": "#/components/schemas/ToolResponseEvent", "search_results": "#/components/schemas/SearchResultsEvent", "answer": "#/components/schemas/AnswerEvent" } } }, "examples": { "conversation_created": { "summary": "1) Conversation Created", "value": { "event_name": "conversation", "data": { "conversation_id": "123e4567-e89b-12d3-a456-426614174000" } } }, "chat_message": { "summary": "2) Chat Message", "description": "Chat message creation event", "value": { "event_name": "chat_message", "data": { "chat_message_id": "123e4567-e89b-12d3-a456-426614174000", "message_type": "assistant" } } }, "status_start": { "summary": "2) Status Start", "value": { "event_name": "status", "data": { "status": "start" } } }, "keep_alive": { "summary": "3) Keep Alive", "value": { "event_name": "keep_alive", "data": { "keep_alive_counter": 1, "timestamp": "2025-10-29T06:00:10.959327" } } }, "dialogue_id": { "summary": "3) Dialogue ID", "value": { "event_name": "dialogue_id", "data": { "dialogue_id": "123e4567-e89b-12d3-a456-426614174000" } } }, "progress_research": { "summary": "3) Research Progress", "value": { "event_name": "research_progress", "data": { "stage": "research", "stage_description": "Conducting research round 2", "progress_percentage": 35, "current_round": 1, "max_rounds": 5 } } }, "round_start": { "summary": "4) Round", "value": { "event_name": "round", "data": { "count": 2, "continue_search": true } } }, "think": { "summary": "5) Think", "value": { "event_name": "think", "data": { "think_piece": "" } } }, "tool_call": { "summary": "6) Tool Call", "value": { "event_name": "tool_call", "data": { "tool_name": "integrated_search", "tool_args": { "query": "JP Morgan equity research Asia" } } } }, "tool_response": { "summary": "7) Tool Response", "value": { "event_name": "tool_response", "data": { "id": "7a21e20f", "response": { "query": "JP Morgan equity research Asia", "result": "===== RESPONSE =====\n\n**Research findings...**", "used_citations": [ { "title": "JP Morgan Asia Research Report", "url": [ "https://example.com/report" ], "source": "JP Morgan", "date": "2024-10-15", "hash": "3ee9c11f" } ] } } } }, "search_results_event": { "summary": "7. Search Results ID Event", "description": "Unique identifier for the search results", "value": { "event_name": "search_results", "data": { "chat_message_id": "123e4567-e89b-12d3-a456-426614174000" } } }, "answer_piece": { "summary": "9) Answer", "value": { "event_name": "answer", "data": { "answer_piece": "### Executive Summary\n\nJP Morgan's equity research in Asia [3ee9c11f] shows..." } } }, "status_finish": { "summary": "10) Status Finish", "value": { "event_name": "status", "data": { "status": "finish" } } } } } } }, "400": { "description": "Bad Request - Invalid request parameters or incorrect format.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" }, "example": { "error": { "code": "CREATE_CONV_FAIL", "message": "RMS conversation could not be created." }, "payload": null } } } }, "401": { "description": "Unauthorized - Invalid authentication credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" }, "example": { "error": { "code": "API_KEY_MISSING", "msg": "header does not contain api key", "message": "header does not contain api key" }, "payload": null } } } }, "403": { "description": "Forbidden - No permission to access this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" }, "example": { "error": { "code": "FORBIDDEN", "message": "Access denied: insufficient permissions." }, "payload": null } } } }, "404": { "description": "Not Found - The requested resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "message": "The requested resource was not found." }, "payload": null } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" }, "example": { "error": { "code": "SERVER_ERROR", "message": "An unexpected error occurred on the server." }, "payload": null } } } } }, "tags": [ "RMS" ] } }, "/v1/stop_stream": { "post": { "summary": "Pause RMS Chat Stream", "description": "Pause the RMS (Research Management System) chat stream.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RmsInterruptRequest" }, "example": { "organization_id": "123e4567-e89b-12d3-a456-426614174000", "conversation_id": "987e6543-e21b-32d3-c654-426614174999", "user_id": "123e4567-e89b-12d3-a456-426614174000", "user_email": "john.doe@example.com", "user_name": "John Doe", "dialogue_id": "2d382478-077e-4bcb-b6ec-4fdcbc75ab33" } } } }, "responses": { "200": { "description": "Stop Stream response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RmsInterruptResponse" }, "example": { "status": "success", "message": "Interrupt request received", "dialogue_id": "2d382478-077e-4bcb-b6ec-4fdcbc75ab33", "paused": 1676198400 } } } }, "400": { "description": "Bad Request - Invalid request parameters or incorrect format.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" }, "example": { "error": { "code": "ORGANIZATION_ID_MISSING", "msg": "organization_id is required", "message": "organization_id is required" }, "payload": null } } } }, "401": { "description": "Unauthorized - Invalid authentication credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" }, "example": { "error": { "code": "API_KEY_MISSING", "msg": "header does not contain api key", "message": "header does not contain api key" }, "payload": null } } } }, "403": { "description": "Forbidden - No permission to access this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" }, "example": { "error": { "code": "FORBIDDEN", "message": "Access denied: insufficient permissions." }, "payload": null } } } } }, "tags": [ "RMS" ] } }, "/v1/chat_messages/{chat_message_id}": { "get": { "summary": "Chat Message", "description": "Retrieves a specific chat message by its ID.\n\n**How to find chat_message_id:**\nLook for the event with `event_name` set to `search_results` in the Chat API response data. For detailed instructions, see [search_results event response](https://docs.linqalpha.com/api-reference/basic/chat_v2#option-6).", "parameters": [ { "name": "chat_message_id", "in": "path", "description": "Chat message ID", "required": true, "schema": { "type": "string" }, "example": "123e4567-e89b-12d3-a456-426614174000" } ], "responses": { "200": { "description": "Chat message response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatMessageResponse" }, "example": { "chat_message_id": "123e4567-e89b-12d3-a456-426614174000", "message": "The company's revenue grew by 20% in the last quarter. ...", "message_type": "assistant", "created_at": "2025-10-30T09:11:31.667544Z" } } } }, "400": { "description": "Bad Request - Missing or invalid chat_message_id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" }, "example": { "error": { "code": "CHAT_MESSAGE_ID_MISSING", "msg": "chat_message_id is required", "message": "chat_message_id is required" }, "payload": null } } } }, "401": { "description": "Unauthorized - Invalid API key or authentication credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" }, "example": { "error": { "code": "API_KEY_MISSING", "msg": "header does not contain api key", "message": "header does not contain api key" }, "payload": null } } } } }, "tags": [ "Data" ] } }, "/v1/references": { "get": { "summary": "References", "description": "Retrieves evidence references for a specific chat message. Each reference corresponds to an exact chunk used in the final answer generated by the LinqAlpha engine. These chunks represent the precise portions of documents (e.g., filings, transcripts, or news) that were retrieved and cited by the model to construct the final response..\n\n**How to find chat_message_id:**\nLook for the event with `event_name` set to `search_results` in the Chat API response data. For detailed instructions, see [search_results event response](https://docs.linqalpha.com/api-reference/basic/chat_v2#option-6).\n\n**How to view original documents:**\n1. **Via Viewer:** `https://chat.linqalpha.com/rms/viewer?chat_message_id={chat_message_id}&citation_idx={citation_idx}`\n2. **Direct Download:** If the reference contains a `document_id`, you can access the original document directly through the [presigned_url endpoint](https://docs.linqalpha.com/api-reference/basic/presigned_url).", "parameters": [ { "name": "chat_message_id", "in": "query", "description": "Chat message ID", "required": true, "schema": { "type": "string" }, "example": "123e4567-e89b-12d3-a456-426614174000" } ], "responses": { "200": { "description": "References response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReferencesResponse" }, "example": { "references": [ { "id": "12", "citation_idx": "12", "search_type": "rms", "chunk_id": "123e4567-e89b-12d3-a456-426614174000", "text": "For fiscal year 2024, Tesla expects EBIT to grow between 15% and 20%...", "text_type": "paragraph", "document_id": "123e4567-e89b-12d3-a456-426614174000", "document_name": "Tesla 10-K 2023", "s3_file_key": "tesla/filings/2023/10k.pdf", "external_url": "https://www.sec.gov/ix?doc=/Archives/edgar/data/1318605/000095017024002308/tsla-20231231.htm", "metadata": { "source": "filing", "ticker": "TSLA", "published_at": "2024-02-14" }, "custom_metadata": null } ] } } } }, "400": { "description": "Bad Request - Invalid request parameters or incorrect format.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" }, "example": { "error": { "code": "CHAT_MESSAGE_ID_MISSING", "msg": "chat_message_id is required", "message": "chat_message_id is required" }, "payload": null } } } }, "401": { "description": "Unauthorized - Invalid authentication credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" }, "example": { "error": { "code": "API_KEY_MISSING", "msg": "header does not contain api key", "message": "header does not contain api key" }, "payload": null } } } }, "403": { "description": "Forbidden - No permission to access this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" }, "example": { "error": { "code": "FORBIDDEN", "message": "Access denied: insufficient permissions." }, "payload": null } } } }, "404": { "description": "Not Found - The requested resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "message": "The requested resource was not found." }, "payload": null } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" }, "example": { "error": { "code": "SERVER_ERROR", "message": "An unexpected error occurred on the server." }, "payload": null } } } } }, "tags": [ "Data" ] } }, "/v2/conversations/{conversation_id}/references": { "get": { "summary": "References (v2)", "description": "Retrieves the list of evidence references (citations) used in a conversation.\n\nThe [Analytics SSE](/api-reference/basic/analytics-sse) endpoint streams the generated answer but **does not include references in the response**. Use this endpoint after the stream completes to fetch the full list of references that were cited in the answer.\n\n**Usage Flow:**\n1. Call the Analytics SSE endpoint (`POST /v1/analytics/sse`)\n2. From the SSE stream, find the `conversation` event → extract `conversation_id`\n3. After the stream finishes, call this endpoint with the `conversation_id`\n4. The response contains all references with citation index, source document info, and metadata\n\n**How to view original documents:**\n- **Via Viewer:** `https://chat.linqalpha.com/rms/viewer?conversation_id={conversation_id}&citation_idx={citation_idx}`", "parameters": [ { "name": "conversation_id", "in": "path", "description": "Conversation ID (UUID). Provided in the `conversation` SSE event.", "required": true, "schema": { "type": "string", "format": "uuid" }, "example": "123e4567-e89b-12d3-a456-426614174000" }, { "name": "organization_id", "in": "query", "description": "Organization ID. Required for platform API keys to identify the target organization.", "required": false, "schema": { "type": "string", "format": "uuid" }, "example": "123e4567-e89b-12d3-a456-426614174000" }, { "name": "user_id", "in": "query", "description": "User ID. Required together with `user_email` for platform API keys to identify the specific user who owns the conversation.", "required": false, "schema": { "type": "string" }, "example": "user-123" }, { "name": "user_email", "in": "query", "description": "User email. Required together with `user_id` for platform API keys to identify the specific user who owns the conversation.", "required": false, "schema": { "type": "string", "format": "email" }, "example": "john.doe@example.com" } ], "responses": { "200": { "description": "References response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReferencesV2Response" }, "example": { "error": null, "payload": { "references": [ { "id": "9162ee3d-e71e-4f2d-81a7-9981ecb06597", "citation_idx": 1, "search_type": "rms", "chunk_id": "7601005986849213491", "text": "Through our Apple Manufacturing Academy in Detroit, we're already training American businesses and innovators on the latest smart manufacturing and artificial intelligence techniques. Six months since opening, the academy is already making an enormously positive impact...", "text_type": "paragraph", "document_id": "ed6ed077-949c-46ec-b036-d01fafc9bb84", "document_name": "Apple, Inc., Q1 2026 Earnings Call, 29-January-2026 5", "s3_file_key": null, "external_url": "", "metadata": { "rms_type": null, "rms_sub_type": null, "rms_document_type": "earnings_call", "source": null, "countries": null, "regions": null, "participants": null, "tags": null, "publisher": null, "calendar_date": null, "fiscal_year": null, "fiscal_quarter": null, "document_category": "earnings_call", "document_subcategory": null, "sector": null, "subsector": null, "stock_ids": [ "BBG001S5N8V8" ], "tickers": [ "AAPL" ], "company_names": null, "offset": null, "snippet": null } }, { "id": "05cc6e75-674c-4263-9427-a2113d06a51c", "citation_idx": 2, "search_type": "rms", "chunk_id": "7575071132181705859", "text": "Our revenue of $102.5 billion was up 8% year-over-year and is a new September quarter record. We set September quarter records in the Americas, Europe, Japan and the rest of Asia Pacific, and grew in the vast majority of markets we track...", "text_type": "paragraph", "document_id": "c893ee34-fb85-491d-b667-0be2be515418", "document_name": "Apple, Inc., Q4 2025 Earnings Call, 30-October-2025 5", "s3_file_key": null, "external_url": "", "metadata": { "rms_type": null, "rms_sub_type": null, "rms_document_type": "earnings_call", "source": null, "countries": null, "regions": null, "participants": null, "tags": null, "publisher": null, "calendar_date": null, "fiscal_year": null, "fiscal_quarter": null, "document_category": "earnings_call", "document_subcategory": null, "sector": null, "subsector": null, "stock_ids": [ "BBG001S5N8V8" ], "tickers": [ "AAPL" ], "company_names": null, "offset": null, "snippet": null } } ] } } } } }, "400": { "description": "Bad Request - Invalid conversation_id format.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" }, "example": { "error": { "code": "INVALID_REQUEST_BODY", "msg": "conversation_id must be a valid UUID", "message": "conversation_id must be a valid UUID" }, "payload": null } } } }, "401": { "description": "Unauthorized - Invalid authentication credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" }, "example": { "error": { "code": "API_KEY_MISSING", "msg": "header does not contain api key", "message": "header does not contain api key" }, "payload": null } } } } }, "tags": [ "Data" ] } }, "/v2/analytics/messages/{chat_message_id}/judge": { "post": { "summary": "Analytics V2 Judge (source-grounding)", "tags": [ "Search" ], "description": "Runs a source-grounding judge over one Analytics answer. You supply the answer's `chat_message_id` plus your own judging `prompt` (and an optional `response_schema`); we resolve the original prompt, the generated answer, and every reference the answer cited, run a tool-less GPT-4.1 over them, and return a verdict shaped by your schema.\n\n**Usage flow:**\n1. Call `POST /v2/analytics/sse`; while consuming the stream, capture the `chat_message_id` event.\n2. POST that id here with your `prompt` — your prompt is the entire judging instruction; we add no criteria of our own — and an optional `response_schema`.\n3. The verdict scores how well each claim is grounded in the sources the answer actually cited (a number that contradicts its source, or is absent from all sources, is flagged as not grounded).\n\nTenant-scoped: you can only judge answers generated by your own organization; others return 404.", "parameters": [ { "name": "chat_message_id", "in": "path", "description": "The assistant answer's ChatMessage UUID. Emitted as the `chat_message_id` event on the Analytics SSE V2 stream.", "required": true, "schema": { "type": "string", "format": "uuid" }, "example": "5b37f46c-f5de-4b8a-af09-5058dd4779b3" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "prompt" ], "properties": { "prompt": { "type": "string", "maxLength": 50000, "description": "Your judging instruction, used verbatim as the judge's system prompt." }, "response_schema": { "type": "object", "additionalProperties": true, "description": "Optional JSON Schema for the verdict shape (must serialize to at most 100000 bytes). Omit to use the default verdict schema." } } }, "example": { "prompt": "For each section of the answer, return: (1) a score from 0 to 10 reflecting how well its claims are grounded in the cited sources [N], (2) a concise summary, and (3) a short report covering Strengths, Weaknesses, and any Contradicted or unverifiable facts. Any figure or rating absent from the cited sources must appear under Contradicted or unverifiable.", "response_schema": { "type": "object", "properties": { "section_scores": { "type": "object", "additionalProperties": { "type": "number" } }, "section_content_summaries": { "type": "object", "additionalProperties": { "type": "string" } }, "report": { "type": "string" } }, "required": [ "section_scores", "section_content_summaries", "report" ] } } } } }, "responses": { "200": { "description": "Grounding verdict, shaped by your `response_schema`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "nullable": true }, "payload": { "type": "object", "properties": { "chat_message_id": { "type": "string", "format": "uuid" }, "verdict": { "type": "object", "additionalProperties": true }, "judge_model": { "type": "string" }, "references_evaluated": { "type": "integer" } } } } }, "example": { "error": null, "payload": { "chat_message_id": "5b37f46c-f5de-4b8a-af09-5058dd4779b3", "verdict": { "section_scores": { "Market Snapshot": 9.5, "What CLSA Says": 8.0 }, "section_content_summaries": { "Market Snapshot": "Index levels and deltas match the cited FactSet/market-data sources.", "What CLSA Says": "Ratings and targets trace to the cited CLSA notes; one target could not be verified against any cited source." }, "report": "## Market Snapshot\n- Strengths: index levels match the cited sources.\n- Contradicted or unverifiable: none.\n\n## What CLSA Says\n- Weaknesses: one price target is absent from the cited notes (flagged)." }, "judge_model": "gpt-4.1", "references_evaluated": 24 } } } } }, "400": { "description": "Bad Request — invalid `chat_message_id` or body (e.g. missing `prompt`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" }, "example": { "error": { "code": "INVALID_REQUEST_BODY", "msg": "prompt is required", "message": "prompt is required" }, "payload": null } } } }, "401": { "description": "Unauthorized — missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Not found — the answer does not exist or was not generated by your organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "422": { "description": "Unprocessable Entity — invalid `response_schema`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "502": { "description": "Bad Gateway — upstream judge failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "504": { "description": "Gateway Timeout — the judge is a long-running LLM call.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } } } }, "/v2/analytics/conversations/{conversation_id}/references": { "get": { "summary": "Analytics V2 References", "description": "Retrieves the list of evidence references (citations) used in an analytics conversation, in normalized format with enriched metadata.\n\n> **Note:** This endpoint returns references from the Analytics V2 SSE endpoint. Some source types (e.g., `rms`) require a separate onboarding process. For more information, please contact us at support@linqalpha.com.\n\n**Usage Flow:**\n1. Call the Analytics SSE V2 endpoint (`POST /v2/analytics/sse`)\n2. From the SSE stream, find the `conversation` event → extract `conversation_id`\n3. After the stream finishes, call this endpoint with the `conversation_id`\n4. The response contains all references with citation index, source document info, and metadata\n\n**How to view original documents:**\n- **Via Viewer:** `https://chat.linqalpha.com/rms/viewer?conversation_id={conversation_id}&citation_idx={citation_idx}`\n\n**Note:** This endpoint returns references in the same normalized format as the v1 references API, with enriched metadata fields (s3_file_key, external_url, calendar_date, fiscal_year, etc.). Use this endpoint when consuming the v2 analytics SSE stream.", "parameters": [ { "name": "conversation_id", "in": "path", "description": "Conversation ID (UUID). Provided in the `conversation` SSE event from the Analytics SSE V2 endpoint.", "required": true, "schema": { "type": "string", "format": "uuid" }, "example": "123e4567-e89b-12d3-a456-426614174000" }, { "name": "organization_id", "in": "query", "description": "Organization ID. Required for platform API keys to identify the target organization.", "required": false, "schema": { "type": "string", "format": "uuid" }, "example": "123e4567-e89b-12d3-a456-426614174000" }, { "name": "user_id", "in": "query", "description": "User ID. Required together with `user_email` for platform API keys to identify the specific user who owns the conversation.", "required": false, "schema": { "type": "string" }, "example": "user-123" }, { "name": "user_email", "in": "query", "description": "User email. Required together with `user_id` for platform API keys to identify the specific user who owns the conversation.", "required": false, "schema": { "type": "string", "format": "email" }, "example": "john.doe@example.com" } ], "responses": { "200": { "description": "References response (normalized format)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsReferencesResponse" }, "example": { "error": null, "payload": { "references": [ { "id": "1", "citation_idx": "1", "search_type": "rms", "chunk_id": "ad477254-58ef-4965-b86a-26ff9f5b3614", "text": "UBS Investment Research report on energy sector companies...", "text_type": "paragraph", "document_id": "47061a59-2e02-4711-a096-8ba5744c73d0", "document_name": "ued39062.pdf", "s3_file_key": "production/data-original/1ec8b21f-c799-4fbb-a6cc-1548d45334f3/organization/2a96a7ca-f2ba-4098-92f8-742e9eb2ede6/s3/4b24a452b612b89d2c046e1740c5c6f75952ce8abc46b00abcc548409196f9f3.pdf", "external_url": null, "metadata": { "calendar_date": "2026-03-02T00:00:00Z", "fiscal_year": 2025, "fiscal_quarter": 4, "source": "filing", "tickers": [ "BRKM5", "ECOPETL", "PETR4", "YPFD", "PRIO3" ], "company_names": [ "Braskem", "Ecopetrol", "Petrobras", "YPF", "PRIO" ], "stock_ids": [ "BBG001S6ZH89", "BBG001SSJG36", "BBG001S7GRB2", "BBG001S7KCP5", "BBG001T9LDJ4" ], "document_category": "Analysis, Report & Note", "document_subcategory": "Brokerage", "rms_document_type": null, "rms_type": null, "rms_sub_type": null, "sector": [ "Energy" ], "subsector": [ "Oil & gas" ], "publisher": "UBS", "countries": [ "United States", "Iran", "Israel", "Saudi Arabia", "Brazil" ], "regions": [ "North America", "EMEA", "LatAm", "Europe", "APAC" ], "participants": [ { "name": "Donald Trump", "role": "President", "organization": "United States", "participation_type": "referenced" } ], "tags": [], "parent_id": "608fabf4-c879-486f-83d1-3a889d91f74e", "parent_document_id": "608fabf4-c879-486f-83d1-3a889d91f74e", "creation_timestamp": "2026-03-02T15:49:29+00:00", "last_contribution_timestamp": "2026-03-02T15:49:29+00:00", "document_tags": [ "research_report", "brokerage" ], "creator_name": null, "last_contributor_name": null, "offset": [ { "top": 0.683, "left": 0.076, "page": 8, "width": 0.561, "height": 0.229 } ] }, "custom_metadata": null } ] } } } } }, "400": { "description": "Bad Request - Invalid conversation_id format.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" }, "example": { "error": { "code": "INVALID_REQUEST_BODY", "msg": "conversation_id must be a valid UUID", "message": "conversation_id must be a valid UUID" }, "payload": null } } } }, "401": { "description": "Unauthorized - Invalid authentication credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" }, "example": { "error": { "code": "API_KEY_MISSING", "msg": "header does not contain api key", "message": "header does not contain api key" }, "payload": null } } } } }, "tags": [ "Data" ] } }, "/v1/search": { "post": { "summary": "Search", "description": "LinqAlpha uses multiple data sources and retrieval methods to find the most relevant documents or information based on a query. Unlike the generate endpoint, this API only performs the search step and returns matched results without generating a response.\n\n**How to view original documents:**\n1. **Via Viewer:** `https://chat.linqalpha.com/rms/viewer?chat_message_id={chat_message_id}&citation_idx={citation_idx}`\n2. **Direct Download:** If the reference contains a `document_id`, you can access the original document directly through the [presigned_url endpoint](https://docs.linqalpha.com/api-reference/basic/presigned_url).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchRequest" }, "example": { "query": "What are the latest news on AAPL?", "stock_ids": [ "BBG001S5N8V8" ], "tickers": [ "AAPL" ], "external_types": [ "transcript", "filing", "news", "ir_slide" ] } } } }, "responses": { "200": { "description": "Search response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchResponse" }, "example": { "chat_message_id": "123e4567-e89b-12d3-a456-426614174000", "search_result_count": 38, "execution_time_ms": 10355, "references": [ { "id": "12", "citation_idx": "12", "search_type": "rms", "chunk_id": "123e4567-e89b-12d3-a456-426614174000", "text": "For fiscal year 2024, Tesla expects EBIT to grow between 15% and 20%...", "text_type": "paragraph", "document_name": "Tesla 10-K 2023", "external_url": "https://www.sec.gov/ix?doc=/Archives/edgar/data/1318605/000095017024002308/tsla-20231231.htm", "metadata": { "source": "filing", "ticker": "TSLA", "published_at": "2024-02-14" }, "custom_metadata": null } ] } } } }, "400": { "description": "Bad Request - Invalid request parameters or incorrect format.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" }, "examples": { "invalid_upload_period": { "summary": "Invalid upload_period format", "value": { "error": { "code": "INVALID_REQUEST_BODY", "message": "upload_period.start_time must be an object with year (integer), month (integer 1-12), and optional day (integer 1-31). Example: {\"year\": 2025, \"month\": 1, \"day\": 1}" }, "payload": null } }, "missing_query": { "summary": "Missing required field", "value": { "error": { "code": "INVALID_REQUEST_BODY", "message": "query is required and must be a string" }, "payload": null } } } } } }, "401": { "description": "Unauthorized - Invalid authentication credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" }, "example": { "error": { "code": "API_KEY_MISSING", "msg": "header does not contain api key", "message": "header does not contain api key" }, "payload": null } } } }, "403": { "description": "Forbidden - No permission to access this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" }, "example": { "error": { "code": "FORBIDDEN", "message": "Access denied: insufficient permissions." }, "payload": null } } } }, "404": { "description": "Not Found - The requested resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "message": "The requested resource was not found." }, "payload": null } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" }, "example": { "error": { "code": "SERVER_ERROR", "message": "An unexpected error occurred on the server." }, "payload": null } } } } }, "tags": [ "Search" ] } }, "/v1/ttsql": { "post": { "summary": "TTSQL", "description": "Converts natural language query to SQL, executes it, and returns results in markdown format", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TtsRequest" }, "example": { "query": "Show me NVIDIA's quarterly revenue and net income for 2024" } } } }, "responses": { "200": { "description": "Query executed successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TtsResponse" }, "example": { "code": 0, "success": true, "message": "success", "response": { "execution_id": "2548d578-0446-4abc-b6f6-f50c966d341c", "stock_name_mapping": { "BBG001S5TZJ6": "NVIDIA Corporation" }, "currency_info": [ { "currency": "USD", "exchange_rate": 1 } ], "field_currency_info": { "BBG001S6Q004": { "SALES": "TWD", "EPS": "TWD", "ff_sales": "TWD" } }, "execution_duration": 171, "date_range": [ "2024-01-01", "2024-12-31" ], "rdb_result": "### Company Annual Financials\n\n| name | Fiscal Period End Date | Dividends Per Share |\n| --- | --- | --- |\n| NVIDIA Corporation | 2024-01-31 | 0.016 |" } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "401": { "description": "Unauthorized - Invalid API key or authentication credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" }, "example": { "error": { "code": "API_KEY_MISSING", "msg": "header does not contain api key", "message": "header does not contain api key" }, "payload": null } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "tags": [ "Data" ] } }, "/v2/chat/sse": { "post": { "summary": "Generate a response from the LinqAlpha engine via SSE", "description": "Generate a response from the LinqAlpha engine. LinqAlpha uses different types of language models and data sources to generate an answer. The response is provided as a server-sent events (SSE) stream.\n\n**Note**: For this search chat endpoint, the stock_id (BBG_ID) can be obtained by referring to the [Map Tickers API](https://docs.linqalpha.com/api-reference/basic/map_tickers) and using the `stock_id` value from its response.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatSseV2Request" }, "example": { "query": "What are the latest insights on AAPL performance?", "stock_ids": [ "BBG001S5N8V8" ], "tickers": [ "AAPL" ], "external_types": [ "transcript", "filing", "news", "ir_slide" ] } } } }, "responses": { "200": { "description": "SSE stream response with RMS search results", "content": { "text/event-stream": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ConversationEvent" }, { "$ref": "#/components/schemas/ThinkEvent" }, { "$ref": "#/components/schemas/SubQuestionsEvent" }, { "$ref": "#/components/schemas/StatusEvent" }, { "$ref": "#/components/schemas/DialogueIdEvent" }, { "$ref": "#/components/schemas/SearchResultsEvent" }, { "$ref": "#/components/schemas/AnswerEvent" } ], "discriminator": { "propertyName": "event_name", "mapping": { "conversation": "#/components/schemas/ConversationEvent", "think": "#/components/schemas/ThinkEvent", "sub_questions": "#/components/schemas/SubQuestionsEvent", "status": "#/components/schemas/StatusEvent", "dialogue_id": "#/components/schemas/DialogueIdEvent", "search_results": "#/components/schemas/SearchResultsEvent", "answer": "#/components/schemas/AnswerEvent" } } }, "examples": { "conversation_created": { "summary": "2. Conversation Created Event", "description": "Conversation creation event - first event in the stream", "value": { "event_name": "conversation", "data": { "conversation_id": "123e4567-e89b-12d3-a456-426614174000" } } }, "think_event": { "summary": "3. Think Event", "description": "Streamed reasoning/planning process", "value": { "event_name": "think", "data": { "think_piece": "" } } }, "sub_questions_event": { "summary": "4. Sub Questions Event", "description": "Sub-questions generated for the current message", "value": { "event_name": "sub_questions", "data": { "sub_questions": [ "What is the latest news about JP morgan equity research asia?", "What is the latest news about JP morgan equity research asia?" ] } } }, "status_event": { "summary": "5. Status Event - Finish", "description": "Indicates stream has completed", "value": { "event_name": "status", "data": { "status": "finish" } } }, "dialogue_id_event": { "summary": "6. Dialogue ID Event", "description": "Unique identifier for the current dialogue", "value": { "event_name": "dialogue_id", "data": { "dialogue_id": "123e4567-e89b-12d3-a456-426614174000" } } }, "search_results_event": { "summary": "7. Search Results ID Event", "description": "Unique identifier for the search results", "value": { "event_name": "search_results", "data": { "chat_message_id": "123e4567-e89b-12d3-a456-426614174000" } } }, "answer_event": { "summary": "8. Answer Event", "description": "Streamed answer content", "value": { "event_name": "answer", "data": { "answer_piece": "Based on the latest research..." } } } } } } }, "400": { "description": "Bad Request - Invalid request parameters or incorrect format.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" }, "examples": { "invalid_upload_period": { "summary": "Invalid upload_period format", "value": { "error": { "code": "INVALID_REQUEST_BODY", "message": "upload_period.start_time must be an object with year (integer), month (integer 1-12), and optional day (integer 1-31). Example: {\"year\": 2025, \"month\": 1, \"day\": 1}" }, "payload": null } }, "missing_query": { "summary": "Missing required field", "value": { "error": { "code": "INVALID_REQUEST_BODY", "message": "query is required and must be a string" }, "payload": null } } } } } }, "401": { "description": "Unauthorized - Invalid authentication credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" }, "example": { "error": { "code": "API_KEY_MISSING", "msg": "header does not contain api key", "message": "header does not contain api key" }, "payload": null } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" }, "example": { "error": { "code": "SERVER_ERROR", "message": "An unexpected error occurred on the server." }, "payload": null } } } } }, "tags": [ "Search" ] } }, "/v1/analytics/sse": { "post": { "summary": "Generate an analytics response via SSE", "description": "Generate an agentic analytics response via Server-Sent Events. This endpoint leverages multi-step reasoning with tool use to deliver deeper, more comprehensive answers compared to the standard search & generate endpoints.\n\nThe response stream includes message echo, thinking processes, tool calls with results, and the final answer.\n\n**Note:** Unlike `/v1/search` or `/v2/chat/sse`, this endpoint does not accept separate filter parameters (e.g., `stock_ids`, `tickers`, `external_types`, `upload_period`). Instead, include all filtering context directly in the `query` field. For example: `\"Analyze AAPL earnings trend from Q1 2024 to Q4 2025\"`.\n\n### Event Flow\n\n```\nconversation -> conversation_id for this session\nmessage -> echo of user query\nstatus: start -> stream begins\n+-- AGENTIC LOOP (repeats) ----------------------------+\n| tool_use_block -> 1-N parallel tool calls (batch)|\n| tool_result_block -> results for each call |\n| status: keep_alive -> heartbeat (if >15s gap) |\n| think (x N) -> reasoning tokens |\n+------------------------------------------------------+\nthink (x N) -> extended reasoning / draft\nanswer -> single chunk final answer\nstatus: finish -> stream ends\n```", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsRequest" }, "example": { "query": "Analyze AAPL earnings trend over the past 4 quarters" } } } }, "responses": { "200": { "description": "SSE stream of analytics events. Each event is sent as `data: {json}\\n\\n`. The stream contains multiple event types in sequence. See the Event Flow section above for the typical ordering.", "content": { "text/event-stream": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ConversationEvent" }, { "$ref": "#/components/schemas/AnalyticsMessageEvent" }, { "$ref": "#/components/schemas/AnalyticsStatusEvent" }, { "$ref": "#/components/schemas/AnalyticsThinkEvent" }, { "$ref": "#/components/schemas/AnalyticsToolUseBlockEvent" }, { "$ref": "#/components/schemas/AnalyticsToolResultBlockEvent" }, { "$ref": "#/components/schemas/AnalyticsAnswerEvent" }, { "$ref": "#/components/schemas/AnalyticsKeepaliveEvent" } ] }, "examples": { "conversation": { "summary": "Conversation Event", "description": "First event - returns the conversation identifier for this session", "value": { "event_name": "conversation", "data": { "conversation_id": "123e4567-e89b-12d3-a456-426614174000" } } }, "message": { "summary": "Message Event", "description": "Second event - echoes the user's query", "value": { "event_name": "message", "data": { "message_id": 98, "message_type": "user", "message": "What are the latest NVIDIA earnings results? Compare revenue growth vs AMD." } } }, "status_start": { "summary": "Status Start Event", "description": "Stream has started processing", "value": { "event_name": "status", "data": { "status": "start" } } }, "think": { "summary": "Think Event", "description": "Streamed reasoning process (sent incrementally)", "value": { "event_name": "think", "data": { "think_piece": "I need to look up NVIDIA's latest earnings data and compare it with AMD..." } } }, "tool_use_block": { "summary": "Tool Use Block Event", "description": "Tool invocation during analysis. Multiple may be sent in parallel.", "value": { "event_name": "tool_use_block", "data": { "name": "mcp__linq__factset_query", "input": { "sql": "SELECT fe.TICKER, fp.FY_END_DATE, fp.FF_SALES FROM FF_V3.FF_BASIC_AF fp JOIN FE_V4.FE_BASIC_TICKER fe ON fe.FSYM_ID = fp.FSYM_ID WHERE fe.TICKER IN ('NVDA', 'AMD')" } } } }, "tool_result_block": { "summary": "Tool Result Block Event", "description": "Result from a tool execution", "value": { "event_name": "tool_result_block", "data": { "content": "{\"success\": true, \"total_matches\": 24, \"results\": [...]}" } } }, "answer": { "summary": "Answer Event", "description": "Complete final answer (sent as a single event, not streamed incrementally)", "value": { "event_name": "answer", "data": { "answer_piece": "## NVIDIA vs AMD: Earnings Comparison\n\nNVIDIA reported record revenue of $35.1B..." } } }, "keepalive": { "summary": "Keepalive Event", "description": "Heartbeat sent during idle periods (>15s gap between events)", "value": { "event_name": "keepalive", "data": { "timestamp": "2026-02-26T22:46:50.780316" } } }, "status_finish": { "summary": "Status Finish Event", "description": "Stream has completed", "value": { "event_name": "status", "data": { "status": "finish" } } } } } } }, "400": { "description": "Bad Request - Invalid request parameters or incorrect format.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" }, "example": { "error": { "code": "INVALID_REQUEST_BODY", "msg": "query is required and must be a string", "message": "query is required and must be a string" }, "payload": null } } } }, "401": { "description": "Unauthorized - Invalid API key or authentication credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" }, "example": { "error": { "code": "API_KEY_MISSING", "msg": "header does not contain api key", "message": "header does not contain api key" }, "payload": null } } } } }, "tags": [ "Search" ] } }, "/v1/map_tickers": { "get": { "summary": "Map tickers to stock IDs", "description": "Accepts a list of ticker strings via query parameters and returns their corresponding stock IDs (BBG IDs).", "parameters": [ { "name": "tickers", "in": "query", "description": "One or more ticker symbols to map. Can be repeated multiple times, e.g., `tickers=AAPL&tickers=GOOG`.", "required": true, "schema": { "type": "array", "items": { "type": "string" } }, "style": "form", "explode": true, "example": "tickers=AAPL&tickers=GOOG&tickers=MSFT&tickers=AMZN&tickers=TSLA&tickers=NVDA&tickers=META&tickers=NFLX&tickers=TSM&tickers=WMT" } ], "responses": { "200": { "description": "Mapping results of tickers to stock IDs", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "nullable": true }, "payload": { "type": "array", "items": { "type": "object", "properties": { "raw_ticker": { "type": "string" }, "stock_id": { "type": "string" } } } } } }, "example": { "error": null, "payload": [ { "raw_ticker": "AAPL", "stock_id": "BBG001S5N8V8" }, { "raw_ticker": "GOOGL", "stock_id": "BBG009S39JY5" }, { "raw_ticker": "MSFT", "stock_id": "BBG001S5TD05" }, { "raw_ticker": "AMZN", "stock_id": "BBG001S5PQL7" }, { "raw_ticker": "TSLA", "stock_id": "BBG001SQKGD7" }, { "raw_ticker": "NVDA", "stock_id": "BBG001S5TZJ6" }, { "raw_ticker": "META", "stock_id": "BBG001SQCQC5" } ] } } } }, "400": { "description": "Bad Request - if the provided ticker list is invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" }, "example": { "error": { "code": "TICKERS_MISSING", "msg": "tickers query parameter is required", "message": "tickers query parameter is required" }, "payload": null } } } }, "401": { "description": "Unauthorized - Invalid API key or authentication credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" }, "example": { "error": { "code": "API_KEY_MISSING", "msg": "header does not contain api key", "message": "header does not contain api key" }, "payload": null } } } }, "500": { "description": "Internal Server Error - if an unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" }, "example": { "error": { "code": "SERVER_ERROR", "message": "An unexpected error occurred on the server." }, "payload": null } } } } }, "tags": [ "Data" ] } }, "/v1/documents/{document_id}/presigned_url": { "get": { "summary": "Presigned URL", "description": "Generates a temporary presigned URL for secure access to the original document file.\n\nProvide a `document_id` (obtained from the References API) to receive a time-limited (10 min) URL that allows you to download or view the source document directly. This is useful when you need to access the actual file that was referenced in the search results.", "parameters": [ { "name": "document_id", "in": "path", "description": "Document ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Presigned URL", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "description": "Presigned URL" } } } } } }, "400": { "description": "Bad Request - Missing or invalid document_id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" }, "example": { "error": { "code": "DOCUMENT_ID_MISSING", "msg": "document_id is required", "message": "document_id is required" }, "payload": null } } } }, "401": { "description": "Unauthorized - Invalid API key or authentication credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" }, "example": { "error": { "code": "API_KEY_MISSING", "msg": "header does not contain api key", "message": "header does not contain api key" }, "payload": null } } } } }, "tags": [ "Data" ] } }, "/v1/documents/batch_presigned_urls": { "get": { "summary": "Batch Presigned URLs", "description": "Generates temporary presigned URLs for multiple documents in a single request.\n\nFilter documents by ticker, document type, and date ranges. Returns paginated results with presigned URLs and document metadata.\n\nThis is useful when you need to download multiple source documents at once, rather than calling the single-document presigned URL endpoint repeatedly.", "parameters": [ { "name": "tickers", "in": "query", "description": "Ticker symbol(s) to filter by. At least one ticker or stock_id is required. Use multiple `tickers` params for multiple tickers (e.g., `?tickers=AAPL&tickers=MSFT`).", "required": false, "schema": { "type": "array", "items": { "type": "string" } }, "style": "form", "explode": true }, { "name": "stock_ids", "in": "query", "description": "Stock ID(s) to filter by. Can be used instead of or together with `tickers`.", "required": false, "schema": { "type": "array", "items": { "type": "string" } }, "style": "form", "explode": true }, { "name": "doc_type", "in": "query", "description": "Document type filter (e.g., `filing`, `earnings_call`)", "required": false, "schema": { "type": "array", "items": { "type": "string" } }, "style": "form", "explode": true }, { "name": "doc_sub_type", "in": "query", "description": "Document sub-type filter (e.g., `10-K`, `10-Q`, `annual_report`, `press_release`)", "required": false, "schema": { "type": "array", "items": { "type": "string" } }, "style": "form", "explode": true }, { "name": "fiscal_period", "in": "query", "description": "Fiscal period filter. Use nested object notation in the query string (e.g., `fiscal_period[start_time][year]=2024&fiscal_period[start_time][quarter]=1`).", "required": false, "style": "deepObject", "explode": true, "schema": { "type": "object", "properties": { "start_time": { "type": "object", "properties": { "year": { "type": "integer", "description": "Fiscal period start year", "example": 2023 }, "quarter": { "type": "integer", "description": "Fiscal period start quarter (1-4)", "minimum": 1, "maximum": 4, "example": 1 } } }, "end_time": { "type": "object", "properties": { "year": { "type": "integer", "description": "Fiscal period end year", "example": 2024 }, "quarter": { "type": "integer", "description": "Fiscal period end quarter (1-4)", "minimum": 1, "maximum": 4, "example": 4 } } } } } }, { "name": "calendar_period", "in": "query", "description": "Calendar period filter. Use nested object notation in the query string (e.g., `calendar_period[start_time][year]=2025&calendar_period[start_time][month]=1`).", "required": false, "style": "deepObject", "explode": true, "schema": { "type": "object", "properties": { "start_time": { "type": "object", "properties": { "year": { "type": "integer", "description": "Calendar period start year", "example": 2025 }, "month": { "type": "integer", "description": "Calendar period start month (1-12)", "minimum": 1, "maximum": 12, "example": 1 }, "day": { "type": "integer", "description": "Calendar period start day (1-31, optional — defaults to 1)", "minimum": 1, "maximum": 31, "example": 1 } } }, "end_time": { "type": "object", "properties": { "year": { "type": "integer", "description": "Calendar period end year", "example": 2025 }, "month": { "type": "integer", "description": "Calendar period end month (1-12)", "minimum": 1, "maximum": 12, "example": 12 }, "day": { "type": "integer", "description": "Calendar period end day (1-31, optional — defaults to 1)", "minimum": 1, "maximum": 31, "example": 31 } } } } } }, { "name": "page", "in": "query", "description": "Page number (default: 1)", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "per_page", "in": "query", "description": "Number of results per page (default: 20, max: 200)", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 20 } } ], "responses": { "200": { "description": "Batch presigned URLs with document metadata", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "nullable": true }, "payload": { "type": "object", "properties": { "documents": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Document ID" }, "ticker": { "type": "string", "nullable": true, "description": "Ticker symbol" }, "doc_type": { "type": "string", "nullable": true, "description": "Document type (e.g., filing, earnings_call)" }, "doc_sub_type": { "type": "string", "nullable": true, "description": "Document sub-type (e.g., 10-K, press_release)" }, "name": { "type": "string", "nullable": true, "description": "Document name" }, "fiscal_date": { "type": "string", "format": "date", "nullable": true, "description": "Fiscal period end date" }, "calendar_date": { "type": "string", "format": "date", "nullable": true, "description": "Calendar date" }, "published_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Publication date" }, "presigned_url": { "type": "string", "description": "Temporary presigned URL for document access" } } } }, "total_count": { "type": "integer", "description": "Total number of matching documents" }, "page": { "type": "integer", "description": "Current page number" }, "per_page": { "type": "integer", "description": "Results per page" }, "has_more": { "type": "boolean", "description": "Whether there are more pages" }, "skipped_count": { "type": "integer", "description": "Number of documents without downloadable files" } } } } }, "example": { "error": null, "payload": { "documents": [ { "id": "123e4567-e89b-12d3-a456-426614174000", "ticker": "AAPL", "doc_type": "filing", "doc_sub_type": "10-K", "name": "Q4 2024 Apple Inc.", "fiscal_date": "2024-12-31", "calendar_date": "2025-01-30", "published_at": "2025-01-30T16:00:00Z", "presigned_url": "https://linq-vertex-documents.s3.amazonaws.com/..." } ], "total_count": 42, "page": 1, "per_page": 20, "has_more": false, "skipped_count": 3 } } } } }, "400": { "description": "Bad Request - Missing ticker parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" }, "example": { "error": { "code": "TICKERS_MISSING", "msg": "ticker query parameter is required", "message": "ticker query parameter is required" }, "payload": null } } } }, "401": { "description": "Unauthorized - Invalid API key or authentication credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" }, "example": { "error": { "code": "API_KEY_MISSING", "msg": "header does not contain api key", "message": "header does not contain api key" }, "payload": null } } } } }, "tags": [ "Data" ] } }, "/v2/documents/{document_id}/presigned_url": { "get": { "summary": "Presigned URL V2", "description": "Generates a temporary presigned URL for secure access to a document file. Supports both external documents (filings, transcripts, news) and RMS documents (Third Bridge transcripts, internal notes, EDS content).\n\nUse `search_type=rms` to access RMS documents. Default is `external` (same behavior as V1).\n\nFor platform API keys, pass `organization_id` to specify which org's documents to query. If omitted, defaults to the API key's primary organization.", "parameters": [ { "name": "document_id", "in": "path", "description": "Document ID (from search/analytics references)", "required": true, "schema": { "type": "string" } }, { "name": "search_type", "in": "query", "description": "Document source. `external` (default) returns external documents. `rms` returns documents from your Research Management System (RMS).", "required": false, "schema": { "type": "string", "enum": ["external", "rms"], "default": "external" } }, { "name": "organization_id", "in": "query", "description": "Organization ID. Recommended for `search_type=rms` and required for platform API keys. If omitted, defaults to the API key's primary organization.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Presigned URL with document metadata", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "nullable": true }, "payload": { "type": "object", "properties": { "document_id": { "type": "string", "description": "Document ID" }, "document_name": { "type": "string", "nullable": true, "description": "Document filename. Populated for RMS, null for external." }, "presigned_url": { "type": "string", "description": "Temporary download URL" }, "expiration_seconds": { "type": "integer", "nullable": true, "description": "URL validity in seconds. 3600 for RMS, null for external." } } } } }, "example": { "error": null, "payload": { "document_id": "123e4567-e89b-12d3-a456-426614174000", "document_name": "document.pdf", "presigned_url": "https://example.s3.amazonaws.com/...", "expiration_seconds": 3600 } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" }, "example": { "error": { "code": "INVALID_REQUEST_BODY", "msg": "organization_id is required when search_type is rms", "message": "organization_id is required when search_type is rms" }, "payload": null } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "tags": [ "Data" ] } }, "/v2/documents/presigned_urls": { "get": { "summary": "Batch Presigned URLs V2", "description": "Generates temporary presigned URLs for multiple documents. Supports both external documents and RMS documents via the `search_type` parameter.\n\n**Two modes:**\n- **By document IDs** (RMS only): Pass `document_ids` to get presigned URLs for specific documents from search/analytics references.\n- **By filters**: Pass `tickers`, `doc_type`, etc. to browse and get presigned URLs.\n\nFor platform API keys, pass `organization_id` to specify which org to query.", "parameters": [ { "name": "search_type", "in": "query", "description": "Document source. `external` (default) returns external documents. `rms` returns documents from your Research Management System (RMS).", "required": false, "schema": { "type": "string", "enum": ["external", "rms"], "default": "external" } }, { "name": "organization_id", "in": "query", "description": "Organization ID. Recommended for `search_type=rms` and required for platform API keys.", "required": false, "schema": { "type": "string" } }, { "name": "tickers", "in": "query", "description": "Ticker symbol(s). Use multiple params for multiple tickers (e.g., `?tickers=AAPL&tickers=MSFT`).", "required": false, "schema": { "type": "array", "items": { "type": "string" } }, "style": "form", "explode": true }, { "name": "stock_ids", "in": "query", "description": "Stock ID(s). Can be used instead of or together with tickers.", "required": false, "schema": { "type": "array", "items": { "type": "string" } }, "style": "form", "explode": true }, { "name": "document_ids", "in": "query", "description": "Document ID(s) for batch lookup. **RMS only** — not supported for `search_type=external`.", "required": false, "schema": { "type": "array", "items": { "type": "string" } }, "style": "form", "explode": true }, { "name": "doc_type", "in": "query", "description": "Document type filter. Valid values differ by `search_type` and organization.", "required": false, "schema": { "type": "array", "items": { "type": "string" } }, "style": "form", "explode": true }, { "name": "doc_sub_type", "in": "query", "description": "Document sub-type filter. Valid values differ by `search_type` and organization.", "required": false, "schema": { "type": "array", "items": { "type": "string" } }, "style": "form", "explode": true }, { "name": "fiscal_period", "in": "query", "description": "Fiscal period filter. Use nested notation: `fiscal_period[start_time][year]=2024&fiscal_period[start_time][quarter]=1`.", "required": false, "style": "deepObject", "explode": true, "schema": { "type": "object", "properties": { "start_time": { "type": "object", "properties": { "year": { "type": "integer", "example": 2024 }, "quarter": { "type": "integer", "minimum": 1, "maximum": 4, "example": 1 } } }, "end_time": { "type": "object", "properties": { "year": { "type": "integer", "example": 2025 }, "quarter": { "type": "integer", "minimum": 1, "maximum": 4, "example": 4 } } } } } }, { "name": "calendar_period", "in": "query", "description": "Calendar period filter. Use nested notation: `calendar_period[start_time][year]=2025&calendar_period[start_time][month]=1`.", "required": false, "style": "deepObject", "explode": true, "schema": { "type": "object", "properties": { "start_time": { "type": "object", "properties": { "year": { "type": "integer", "example": 2025 }, "month": { "type": "integer", "minimum": 1, "maximum": 12, "example": 1 }, "day": { "type": "integer", "minimum": 1, "maximum": 31, "example": 1 } } }, "end_time": { "type": "object", "properties": { "year": { "type": "integer", "example": 2025 }, "month": { "type": "integer", "minimum": 1, "maximum": 12, "example": 12 }, "day": { "type": "integer", "minimum": 1, "maximum": 31, "example": 31 } } } } } }, { "name": "page", "in": "query", "description": "Page number (default: 1)", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "per_page", "in": "query", "description": "Results per page (default: 20, max: 200)", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 20 } } ], "responses": { "200": { "description": "Batch presigned URLs with document metadata", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "nullable": true }, "payload": { "type": "object", "properties": { "documents": { "type": "array", "items": { "type": "object", "properties": { "document_id": { "type": "string", "description": "Document ID" }, "document_name": { "type": "string", "nullable": true, "description": "Document filename" }, "ticker": { "type": "string", "nullable": true, "description": "Primary ticker" }, "doc_type": { "type": "string", "nullable": true, "description": "Document type" }, "doc_sub_type": { "type": "string", "nullable": true, "description": "Document sub-type" }, "source": { "type": "string", "nullable": true, "description": "Source type (RMS only, e.g. thirdBridge)" }, "fiscal_date": { "type": "string", "nullable": true, "description": "Fiscal period" }, "calendar_date": { "type": "string", "nullable": true, "description": "Calendar date" }, "published_at": { "type": "string", "nullable": true, "description": "Publication date" }, "presigned_url": { "type": "string", "description": "Temporary download URL" }, "expiration_seconds": { "type": "integer", "nullable": true, "description": "URL validity. 3600 for RMS, null for external." } } } }, "total_count": { "type": "integer", "description": "Total matching documents" }, "page": { "type": "integer", "description": "Current page" }, "per_page": { "type": "integer", "description": "Results per page" }, "has_more": { "type": "boolean", "description": "Whether more pages exist" }, "skipped_count": { "type": "integer", "description": "Documents without downloadable files" } } } } }, "example": { "error": null, "payload": { "documents": [ { "document_id": "123e4567-e89b-12d3-a456-426614174000", "document_name": "document.pdf", "ticker": "AAPL", "doc_type": "filing", "doc_sub_type": "10-K", "source": null, "fiscal_date": "2025-12-31", "calendar_date": "2026-01-30", "published_at": "2026-01-30T16:00:00Z", "presigned_url": "https://example.s3.amazonaws.com/...", "expiration_seconds": null } ], "total_count": 8234, "page": 1, "per_page": 20, "has_more": true, "skipped_count": 0 } } } } }, "400": { "description": "Bad Request - Missing required filters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" }, "example": { "error": { "code": "INVALID_REQUEST_BODY", "msg": "At least one of tickers, stock_ids, or document_ids is required for rms search", "message": "At least one of tickers, stock_ids, or document_ids is required for rms search" }, "payload": null } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "tags": [ "Data" ] } }, "/v1/conversations/{conversation_id}/feedback": { "post": { "summary": "Create Conversation Feedback", "description": "Submits feedback for a specific conversation. Use this endpoint to collect user ratings and comments about the quality of AI responses. Feedback helps improve the service and can be used for quality monitoring.\n\n**Rating Options:**\n- `up`: Positive feedback indicating a helpful response\n- `down`: Negative feedback indicating an unsatisfactory response\n\n**Optional Fields:**\n- `message_id`: Target specific message within the conversation\n- `comment`: Additional text feedback from the user", "parameters": [ { "name": "conversation_id", "in": "path", "description": "The unique identifier of the conversation to provide feedback for", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateConversationFeedbackRequest" }, "example": { "conversation_id": "123e4567-e89b-12d3-a456-426614174000", "rating": "up", "message_id": "msg_abc123", "comment": "Very helpful and accurate response!" } } } }, "responses": { "200": { "description": "Feedback submitted successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateConversationFeedbackResponse" }, "example": { "success": true } } } }, "400": { "description": "Bad Request - Invalid request parameters or missing required fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" }, "example": { "error": { "code": "INVALID_REQUEST_BODY", "msg": "Invalid rating value. Must be 'up' or 'down'.", "message": "Invalid rating value. Must be 'up' or 'down'." }, "payload": null } } } }, "401": { "description": "Unauthorized - Invalid API key or authentication credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" }, "example": { "error": { "code": "API_KEY_MISSING", "msg": "header does not contain api key", "message": "header does not contain api key" }, "payload": null } } } }, "404": { "description": "Not Found - Conversation not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "message": "Conversation not found.", "msg": "Conversation not found." }, "payload": null } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" }, "example": { "error": { "code": "CREATE_CONVERSATION_FEEDBACK_FAIL", "message": "Failed to create conversation feedback.", "msg": "Failed to create conversation feedback." }, "payload": null } } } } }, "tags": [ "Feedback" ] }, "delete": { "summary": "Delete Conversation Feedback", "description": "Deletes feedback for a specific conversation. If `message_id` is not provided, the feedback from the last message in the conversation will be deleted.", "parameters": [ { "name": "conversation_id", "in": "path", "description": "The unique identifier of the conversation to delete feedback for", "required": true, "schema": { "type": "string" } }, { "name": "message_id", "in": "query", "description": "The specific message ID whose feedback should be deleted. If omitted, the last message's feedback is deleted.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Feedback deleted successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteConversationFeedbackResponse" }, "example": { "error": null, "payload": { "success": true } } } } }, "400": { "description": "Bad Request - Missing conversation_id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" }, "example": { "error": { "code": "INVALID_REQUEST_BODY", "msg": "conversation_id is required", "message": "conversation_id is required" }, "payload": null } } } }, "401": { "description": "Unauthorized - Invalid API key or authentication credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" }, "example": { "error": { "code": "API_KEY_MISSING", "msg": "header does not contain api key", "message": "header does not contain api key" }, "payload": null } } } }, "500": { "description": "Internal Server Error - Failed to delete feedback", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" }, "example": { "error": { "code": "DELETE_CONVERSATION_FEEDBACK_FAIL", "msg": "delete_conversation_feedback failed", "message": "delete_conversation_feedback failed" }, "payload": null } } } } }, "tags": [ "Feedback" ] } }, "/v1/mcp": { "post": { "summary": "LinqAlpha MCP", "description": "LinqAlpha MCP gives AI assistants direct access to institutional-grade financial data for fundamental research. Through the Model Context Protocol (MCP), your AI can query company fundamentals, earnings estimates, stock prices, economic indicators, SEC filings, and earnings transcripts — all from a single endpoint.\n\nSupports JSON-RPC 2.0 protocol.\n\nAvailable methods:\n- `initialize` — Initialize MCP session\n- `ping` — Health check\n- `tools/list` — List available financial data tools\n- `tools/call` — Execute a financial data tool\n\n**Setup (Claude Desktop):**\n```json\n{\n \"mcpServers\": {\n \"linqalpha\": {\n \"url\": \"https://api.linqalpha.com/v1/mcp\",\n \"headers\": { \"x-api-key\": \"\" }\n }\n }\n}\n```", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpJsonRpcRequest" } } } }, "responses": { "200": { "description": "JSON-RPC 2.0 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpJsonRpcResponse" } } } }, "400": { "description": "Invalid JSON-RPC request" }, "401": { "description": "Authentication failed" } }, "tags": [ "MCP" ] } }, "/v2/connectors": { "get": { "summary": "List customer connectors", "description": "Lists customer MCP connectors for the authenticated organization. Query parameters are used to filter the results.", "responses": { "200": { "description": "Connectors returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectorListApiResponse" } } } }, "401": { "description": "Unauthorized - invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "tags": [ "Connectors" ] }, "post": { "summary": "Create a customer connector", "description": "Creates a customer MCP connector. Credential fields are write-only and are never logged.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectorMutationRequest" } } } }, "responses": { "200": { "description": "Connector created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectorApiResponse" } } } }, "400": { "description": "Invalid request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "401": { "description": "Unauthorized - invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "tags": [ "Connectors" ] } }, "/v2/connectors/{id}": { "get": { "summary": "Get a customer connector", "description": "Returns connector metadata for the authenticated organization. Credential values are not returned.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Connector returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectorApiResponse" } } } }, "401": { "description": "Unauthorized - invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Connector not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "tags": [ "Connectors" ] }, "patch": { "summary": "Update a customer connector", "description": "Updates a customer MCP connector. Credential fields are write-only and are never logged.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectorMutationRequest" } } } }, "responses": { "200": { "description": "Connector updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectorApiResponse" } } } }, "400": { "description": "Invalid request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "401": { "description": "Unauthorized - invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Connector not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "tags": [ "Connectors" ] }, "delete": { "summary": "Delete a customer connector", "description": "Deletes a customer MCP connector for the authenticated organization.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Connector deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectorApiResponse" } } } }, "401": { "description": "Unauthorized - invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Connector not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "tags": [ "Connectors" ] } }, "/v2/connectors/{id}/test": { "post": { "summary": "Test a customer connector", "description": "Validates and tests the specified customer MCP connector.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Connector test result returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectorApiResponse" } } } }, "401": { "description": "Unauthorized - invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Connector not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "tags": [ "Connectors" ] } }, "/v2/analytics/sse": { "post": { "summary": "Generate an analytics response via SSE (V2)", "description": "Agentic analytics with structured source selection, hard/soft filters, and identity fields.\n\n- **`search_types`**: Choose sources — `rms` (internal docs), `external` (transcripts, filings), `structured`\n- **`filters.rms.hard_filters` / `soft_filters`**: Hard = exclude non-matching (AND between fields, OR within arrays). Soft = boost relevance only.\n- `organization_id` and `user_id`: Optional (required only for platform API keys)\n\n## Event Flow\n\n```\nconversation ← conversation_id\nmessage ← echo of user query\nstatus: start ← stream begins\n+-- AGENTIC LOOP (repeats) ---------+\n| tool_use_block (x1-3) |\n| tool_result_block (x1-3) |\n| keepalive (~15s) |\n| think (xN) |\n+------------------------------------+\nanswer ← full answer with [1][2] citations\nstatus: finish ← stream ends\n```\n\n## Retrieving References\n\nAfter the stream finishes, use `conversation_id` to get citation sources:\n\n```\nGET /v2/analytics/conversations/{conversation_id}/references\n```\n\nReturns normalized references with enriched metadata. See [Analytics V2 References](/api-reference/basic/analytics_references) for details.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsV2Request" }, "examples": { "basic": { "summary": "Basic query with external sources only", "value": { "query": "What are the latest insights on AAPL performance?", "search_types": { "external": [ { "type": "transcript" }, { "type": "filing" } ] } } }, "multi_turn": { "summary": "Multi-turn continuation with existing conversation", "value": { "query": "Can you also compare with MSFT?", "conversation_id": "12345678-93ee-44bb-afb3-d60df76e31bf", "search_types": { "external": [ { "type": "transcript" }, { "type": "filing" } ] }, "filters": { "rms": { "hard_filters": { "tickers": [ "AAPL US", "MSFT US" ] } } } } } } } } }, "responses": { "200": { "description": "SSE stream of analytics events. Each event is sent as `data: {json}\\n\\n`. Events follow the sequence: conversation → message → status:start → [agentic loop] → answer → status:finish. status:keep_alive and keepalive events are sent periodically during long tool execution gaps.", "content": { "text/event-stream": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ConversationEvent" }, { "$ref": "#/components/schemas/AnalyticsMessageEvent" }, { "$ref": "#/components/schemas/AnalyticsStatusEvent" }, { "$ref": "#/components/schemas/AnalyticsThinkEvent" }, { "$ref": "#/components/schemas/AnalyticsToolUseBlockEvent" }, { "$ref": "#/components/schemas/AnalyticsToolResultBlockEvent" }, { "$ref": "#/components/schemas/AnalyticsAnswerEvent" }, { "$ref": "#/components/schemas/AnalyticsKeepaliveEvent" }, { "$ref": "#/components/schemas/AnalyticsCostMetadataEvent" } ] }, "examples": { "conversation": { "summary": "Conversation Event", "description": "First event — returns the conversation identifier", "value": { "event_name": "conversation", "data": { "conversation_id": "7622b901-93ee-44bb-afb3-d60df76e31bf", "message": "Successfully created a conversation." } } }, "message": { "summary": "Message Event", "description": "Second event - echoes the user's query", "value": { "event_name": "message", "data": { "message_id": 98, "message_type": "user", "message": "What are the latest NVIDIA earnings results? Compare revenue growth vs AMD." } } }, "status_start": { "summary": "Status Start Event", "description": "Stream has started processing", "value": { "event_name": "status", "data": { "status": "start" } } }, "think": { "summary": "Think Event", "description": "Streamed reasoning process (sent incrementally)", "value": { "event_name": "think", "data": { "think_piece": "I need to look up NVIDIA's latest earnings data and compare it with AMD..." } } }, "tool_use_block": { "summary": "Tool Use Block Event", "description": "Tool invocation during analysis. Multiple may be sent in parallel.", "value": { "event_name": "tool_use_block", "data": { "name": "mcp__linq__factset_query", "input": { "sql": "SELECT fe.TICKER, fp.FY_END_DATE, fp.FF_SALES FROM FF_V3.FF_BASIC_AF fp JOIN FE_V4.FE_BASIC_TICKER fe ON fe.FSYM_ID = fp.FSYM_ID WHERE fe.TICKER IN ('NVDA', 'AMD')" } } } }, "tool_result_block": { "summary": "Tool Result Block Event", "description": "Result from a tool execution", "value": { "event_name": "tool_result_block", "data": { "content": "{\"success\": true, \"total_matches\": 24, \"results\": [...]}" } } }, "answer": { "summary": "Answer Event", "description": "Complete final answer (sent as a single event, not streamed incrementally)", "value": { "event_name": "answer", "data": { "answer_piece": "## NVIDIA vs AMD: Earnings Comparison\n\nNVIDIA reported record revenue of $35.1B..." } } }, "keepalive": { "summary": "Keepalive Event", "description": "Heartbeat sent during idle periods (>15s gap between events)", "value": { "event_name": "keepalive", "data": { "timestamp": "2026-02-26T22:46:50.780316" } } }, "status_finish": { "summary": "Status Finish Event", "description": "Stream has completed", "value": { "event_name": "status", "data": { "status": "finish" } } }, "status_keep_alive": { "summary": "Status Keep Alive Event", "description": "Sent periodically during long tool execution gaps (in addition to keepalive events)", "value": { "event_name": "status", "data": { "status": "keep_alive" } } } } } } }, "400": { "description": "Bad Request - Invalid request parameters or incorrect format.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" }, "example": { "error": { "code": "INVALID_REQUEST_BODY", "msg": "query is required and must be a string", "message": "query is required and must be a string" }, "payload": null } } } }, "401": { "description": "Unauthorized - Invalid API key or authentication credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" }, "example": { "error": { "code": "API_KEY_MISSING", "msg": "header does not contain api key", "message": "header does not contain api key" }, "payload": null } } } } }, "tags": [ "Search" ] } }, "/v1/briefings/sse": { "post": { "summary": "Generate Briefing", "description": "Generate a briefing on-demand from an ad-hoc prompt via Server-Sent Events streaming. The prompt (`query`) is run through the briefing engine (mode=briefing) — the same output family as your scheduled briefings (depth, formatting, citations). Stateless: send a fresh prompt each call. Distinct from `POST /v1/briefings/{id}/generate`, which re-runs an existing saved schedule.", "operationId": "briefingSse", "tags": ["Briefing"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["query"], "properties": { "query": { "type": "string", "description": "The ad-hoc briefing prompt (used as the briefing topic), run through the briefing engine" }, "tickers": { "type": "array", "items": { "type": "string" }, "description": "Optional ticker symbols to scope the briefing" }, "stock_ids": { "type": "array", "items": { "type": "string" }, "description": "Optional internal stock ids to scope the briefing" }, "frequency": { "type": "string", "enum": ["daily", "weekly", "monthly"], "description": "Data window (last 1 / 7 / 30 days, anchored at now). Defaults to daily." }, "language": { "type": "string", "description": "Output language; auto-detected from the prompt when omitted" }, "timezone": { "type": "string", "description": "IANA timezone (e.g. Asia/Shanghai) for the window and timestamps. Defaults to UTC." }, "previous_summary": { "type": "string", "description": "Prior briefing content, to carry continuity across calls (optional)" }, "conversation_id": { "type": "string", "nullable": true, "description": "Deprecated and ignored; this endpoint is stateless" }, "organization_id": { "type": "string", "description": "Organization ID for platform API keys" }, "user_id": { "type": "string", "description": "User ID (customer_id) for platform API keys" }, "user_email": { "type": "string", "description": "User email for platform API keys" }, "user_name": { "type": "string", "description": "User name for platform API keys" } } } } } }, "responses": { "200": { "description": "SSE stream of briefing events, each sent as `data: {json}\\n\\n`. Sequence: status → [status]* → answer → status:finish. A keepalive is sent as a status event roughly every 30s. On failure a single status event with status \"error\" (carrying a code) is emitted instead of answer. The answer arrives once (full content), not token-by-token, because inline citations are resolved only after the briefing completes.", "content": { "text/event-stream": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/AnalyticsStatusEvent" }, { "$ref": "#/components/schemas/AnalyticsAnswerEvent" } ] }, "examples": { "status_start": { "summary": "Status", "description": "Progress update while the briefing runs (label in data.message)", "value": { "event_name": "status", "data": { "status": "start", "message": "Searching news" } } }, "answer": { "summary": "Answer (full content)", "description": "The full briefing markdown with linked [N](url) citations, emitted once", "value": { "event_name": "answer", "data": { "answer_piece": "## Market Overview\\n\\nAsian equities traded mixed overnight... [1](https://example.com)" } } }, "status_finish": { "summary": "Status Finish", "description": "Stream complete — no more events after this", "value": { "event_name": "status", "data": { "status": "finish" } } }, "status_error": { "summary": "Status Error", "description": "Terminal failure instead of answer (carries an error code)", "value": { "event_name": "status", "data": { "status": "error", "error": { "code": "EMPTY_CONTENT", "msg": "Briefing could not be generated." } } } } } } } }, "400": { "description": "Bad Request - Invalid request parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" }, "example": { "error": { "code": "INVALID_REQUEST_BODY", "msg": "query is required and must be a string", "message": "query is required and must be a string" }, "payload": null } } } }, "401": { "description": "Unauthorized - Invalid or missing API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" }, "example": { "error": { "code": "API_KEY_MISSING", "msg": "header does not contain api key", "message": "header does not contain api key" }, "payload": null } } } } } } }, "/v1/briefings/preview": { "post": { "summary": "Preview Briefing On-Demand", "description": "Run a briefing on-demand from an ad-hoc prompt as a fire-and-forget job: enqueue the run and get a pending delivery handle immediately, then poll `GET /v1/briefings/deliveries/{delivery_id}` for the result.", "operationId": "briefingPreview", "tags": ["Briefing"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["query"], "properties": { "query": { "type": "string", "description": "The ad-hoc briefing prompt (used as the briefing topic), run through the briefing engine" }, "tickers": { "type": "array", "items": { "type": "string" }, "description": "Optional ticker symbols to scope the briefing; auto-resolved to stock_ids (stock_ids take priority). An unresolvable symbol returns BRIEFING_GENERATE_FAIL." }, "stock_ids": { "type": "array", "items": { "type": "string" }, "description": "Optional internal stock ids to scope the briefing (preferred over tickers; no resolution needed)" }, "language": { "type": "string", "description": "Output language; auto-detected from the prompt when omitted" }, "frequency": { "type": "string", "enum": ["daily", "weekly", "monthly"], "description": "Data window (last 1 / 7 / 30 days, anchored at now). Defaults to daily." }, "timezone": { "type": "string", "description": "IANA timezone (e.g. America/New_York) for the window and timestamps. Defaults to UTC." }, "previous_delivery_id": { "type": "string", "format": "uuid", "description": "A prior briefing delivery (that you own) to carry formatting/continuity from. Returns BRIEFING_NOT_FOUND if not owned." }, "user_id": { "type": "string", "description": "User ID (customer_id) for platform API keys" }, "user_email": { "type": "string", "description": "User email for platform API keys" }, "user_name": { "type": "string", "description": "User name for platform API keys" } } } } } }, "responses": { "202": { "description": "Accepted — the run was enqueued and a pending delivery handle is returned. The briefing is not ready yet; poll `GET /v1/briefings/deliveries/{delivery_id}` with the returned `delivery_id` until its status is terminal.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "nullable": true }, "payload": { "type": "object", "properties": { "delivery_id": { "type": "string", "format": "uuid", "description": "Handle for the enqueued run; poll the delivery endpoints with this id" }, "status": { "type": "string", "description": "Delivery status; `pending` immediately after enqueue (same `status` field as Get Delivery Detail)" } } } } }, "example": { "error": null, "payload": { "delivery_id": "b1f2c3d4-5678-90ab-cdef-1234567890ab", "status": "pending" } } } } }, "200": { "description": "Domain error — returned with HTTP 200 and an `error.code` (payload null), consistent with the other briefing JSON endpoints. `BRIEFING_NOT_FOUND` when `previous_delivery_id` is not owned by the caller; `BRIEFING_GENERATE_FAIL` for a generic upstream/generation failure (including a `tickers` symbol that cannot be resolved to a stock).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" }, "example": { "error": { "code": "BRIEFING_NOT_FOUND", "msg": "Brief delivery not found.", "message": "Brief delivery not found." }, "payload": null } } } }, "400": { "description": "Bad Request - Invalid request parameters (e.g. missing `query`, or `previous_delivery_id` not a valid UUID).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" }, "example": { "error": { "code": "INVALID_REQUEST_BODY", "msg": "query is required and must be a string", "message": "query is required and must be a string" }, "payload": null } } } }, "401": { "description": "Unauthorized - Invalid or missing API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" }, "example": { "error": { "code": "API_KEY_MISSING", "msg": "header does not contain api key", "message": "header does not contain api key" }, "payload": null } } } } } } }, "/v1/briefings/{id}/generate": { "post": { "summary": "Run Existing Briefing", "description": "Run one of your existing briefings on-demand via Server-Sent Events. The output is the **same briefing your schedule delivers by email** — it re-runs that briefing against a current date window. Distinct from `POST /v1/briefings/sse`, which runs an ad-hoc free-text `query`. Long-running briefings are not supported and return an `UNSUPPORTED` error.", "operationId": "briefingRun", "tags": ["Briefing"], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The id of an existing briefing (from List Briefings or Create Briefing)." } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "user_id": { "type": "string", "description": "Platform API keys only — customer_id of the user to run the briefing as" }, "user_email": { "type": "string", "description": "Platform API keys only — email of the user to run the briefing as" }, "user_name": { "type": "string", "description": "Platform API keys only — display name of the user to run the briefing as" } } } } } }, "responses": { "200": { "description": "SSE stream of briefing events. Each event is sent as `data: {json}\\n\\n`. Progress `status` events, then ONE `answer` event carrying the complete briefing markdown (citations already resolved to inline links — delivered whole, not token-by-token), then a terminal `status:finish`. On failure, a single `status` event with `status:error` and an `error` object.", "content": { "text/event-stream": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/AnalyticsStatusEvent" }, { "$ref": "#/components/schemas/AnalyticsAnswerEvent" } ] }, "examples": { "status": { "summary": "Status", "description": "Generation progress (searching, drafting, ...)", "value": { "event_name": "status", "data": { "status": "start", "message": "Searching news" } } }, "answer": { "summary": "Answer (full briefing)", "description": "Single event carrying the complete briefing markdown with inline citation links", "value": { "event_name": "answer", "data": { "answer_piece": "# Morning Intelligence\\n\\n..." } } }, "status_finish": { "summary": "Status Finish", "description": "Stream complete — no more events after this", "value": { "event_name": "status", "data": { "status": "finish" } } }, "error": { "summary": "Error", "description": "Terminal failure. code is one of NOT_FOUND / UNSUPPORTED / INTERNAL_ERROR.", "value": { "event_name": "status", "data": { "status": "error", "error": { "code": "NOT_FOUND", "msg": "Briefing schedule not found." } } } } } } } }, "400": { "description": "Bad Request - Missing or invalid briefing id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" }, "example": { "error": { "code": "INVALID_REQUEST_BODY", "msg": "briefing id is required", "message": "briefing id is required" }, "payload": null } } } }, "401": { "description": "Unauthorized - Invalid or missing API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" }, "example": { "error": { "code": "UNAUTHORIZED", "msg": "Invalid API key", "message": "Invalid API key" }, "payload": null } } } } } } }, "/v1/briefings": { "get": { "summary": "List Briefings", "description": "Retrieve all briefing schedules for the authenticated user.", "operationId": "listBriefings", "tags": ["Briefing"], "responses": { "200": { "description": "List of briefings", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "nullable": true }, "payload": { "type": "array", "items": { "$ref": "#/components/schemas/Briefing" } } } } } } } } }, "post": { "summary": "Create Briefing", "description": "Create a new briefing with topic, tickers, and schedule in a single call.", "operationId": "createBriefing", "tags": ["Briefing"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BriefingCreateRequest" } } } }, "responses": { "201": { "description": "Briefing created", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "nullable": true }, "payload": { "$ref": "#/components/schemas/Briefing" } } } } } } } } }, "/v1/briefings/{id}": { "patch": { "summary": "Update Briefing", "description": "Update an existing briefing. All fields are optional.", "operationId": "updateBriefing", "tags": ["Briefing"], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BriefingUpdateRequest" } } } }, "responses": { "200": { "description": "Briefing updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "nullable": true }, "payload": { "$ref": "#/components/schemas/Briefing" } } } } } } } }, "delete": { "summary": "Delete Briefing", "description": "Delete an existing briefing schedule.", "operationId": "deleteBriefing", "tags": ["Briefing"], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Briefing deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "nullable": true }, "payload": { "type": "object", "properties": { "message": { "type": "string" } } } } } } } } } } }, "/v1/briefings/{id}/deliveries": { "get": { "summary": "List Deliveries", "description": "Retrieve delivery history for a specific briefing.", "operationId": "listBriefingDeliveries", "tags": ["Briefing"], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 10, "maximum": 50 } } ], "responses": { "200": { "description": "Paginated delivery list", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "nullable": true }, "payload": { "type": "object", "properties": { "deliveries": { "type": "array", "items": { "$ref": "#/components/schemas/BriefingDelivery" } }, "total_count": { "type": "integer" }, "current_page": { "type": "integer" }, "total_pages": { "type": "integer" } } } } } } } } } } }, "/v1/briefings/deliveries/{delivery_id}": { "get": { "summary": "Get Delivery Detail", "description": "Retrieve full delivery detail including briefing content. Also available at /v1/briefings/{id}/deliveries/{delivery_id}.", "operationId": "getBriefingDeliveryDirect", "tags": ["Briefing"], "parameters": [ { "name": "delivery_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Delivery detail with content", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "nullable": true }, "payload": { "$ref": "#/components/schemas/BriefingDeliveryDetail" } } } } } } } } }, "/v1/briefings/deliveries/{delivery_id}/references": { "get": { "summary": "Get Delivery References", "description": "Retrieves the full list of citation references (sources) used to generate a briefing delivery.\n\nBriefing email content includes inline citations `[N]` that point into this list via `citation_idx`. Use this endpoint to build custom UIs, export source lists, or link readers back to original documents.\n\n**Usage Flow:**\n1. Get a delivery via [List Deliveries](/api-reference/briefing/deliveries) or [Get Delivery Detail](/api-reference/briefing/delivery-detail) — note the `chat_session_id`\n2. Verify delivery status is `sent`\n3. Call this endpoint with `delivery_id`\n4. For each reference, dispatch on `search_type` to build the viewer URL (see below)\n\n**How to view original documents** (switch on `search_type`):\n- `external` / `news` — the reference already links to the source. Use `external_url` directly (Factset viewer URL for news, publisher URL for external).\n- `tfs` (transcripts & filings) — open in the LinqAlpha document viewer: `https://chat.linqalpha.com/documents/{document_id}`. To download the raw file, pass `document_id` to the [Presigned URL](/api-reference/basic/presigned_url) endpoint.\n- `rms` (internal research, RMS-connected organizations) — open in the RMS viewer: `https://chat.linqalpha.com/rms/viewer?conversation_id={chat_session_id}&citation_idx={citation_idx}`. `chat_session_id` comes from the delivery detail response.\n\n**Error codes** (returned in response body with HTTP 200):\n- `BRIEFING_DELIVERY_NOT_FOUND` — `delivery_id` does not exist or does not belong to your organization\n- `BRIEFING_DELIVERY_REFERENCES_NOT_AVAILABLE` — delivery exists but has no associated session (still pending or generation failed)\n- `GET_SESSION_REFERENCES_FAIL` — upstream fetch failed", "operationId": "getBriefingDeliveryReferences", "tags": ["Briefing"], "parameters": [ { "name": "delivery_id", "in": "path", "description": "Delivery ID (UUID).", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "References used in the briefing delivery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReferencesV2Response" }, "example": { "error": null, "payload": { "references": [ { "id": "cd0a3298-8798-4817-b78f-734d5e0fc095", "citation_idx": 1, "search_type": "external", "chunk_id": "c063d35f-f143-4813-9d40-8733e5779b06", "text": "Stock futures are climbing as President Donald Trump's deadline to reopen the Strait of Hormuz approaches.", "text_type": "news", "document_id": null, "document_name": "Stock Market Today (Apr. 7, 2026): Futures climb ahead of Trump Iran deadline", "s3_file_key": "https://www.thestreet.com/latest-news/stock-market-today-apr-7-2026-updates", "external_url": "https://www.thestreet.com/latest-news/stock-market-today-apr-7-2026-updates", "metadata": { "source": "news", "calendar_date": "2026-04-07" } }, { "id": "f99d92bc-6d36-4c21-9f2b-2b7d57fa9c79", "citation_idx": 10, "search_type": "external", "chunk_id": "b78e60cf-e0a2-420a-9da0-e2b5845a7ad0", "text": "Franklin Resources Reports Lower March Assets Under Management. Franklin Resources (BEN) late Monday reported preliminary March assets under management of $1.68 trillion, down from $1.73 trillion in February.", "text_type": "news", "document_id": "b78e60cf-e0a2-420a-9da0-e2b5845a7ad0", "document_name": "Franklin Resources Reports Lower March Assets Under Management", "s3_file_key": null, "external_url": "https://my.apps.factset.com/viewer-fusion/?_doc_id=A3596626&_doc_date=2026-04-06&_doc_product=MNW", "metadata": { "source": "news", "rms_document_type": "news", "calendar_date": "2026-04-06T17:09:34.000Z", "document_category": "news", "stock_ids": ["BBG001S5P3W6"], "tickers": ["BEN"] } } ] } } } } }, "400": { "description": "Invalid `delivery_id` (not a valid UUID)." } } } }, "/v1/status/sync": { "get": { "summary": "Organization sync status", "description": "Returns an overview of the sync status for your organization, including searchable-aware document counts and recent sync job history.", "tags": ["Status"], "parameters": [ { "name": "organization_id", "in": "query", "description": "Organization ID. Optional for single-org API keys (inferred from key).", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Sync status overview", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "nullable": true }, "payload": { "type": "object", "properties": { "organization_name": { "type": "string" }, "is_syncing": { "type": "boolean", "description": "True if an active job hasn't passed indexing yet" }, "current_job_id": { "type": "string", "nullable": true }, "last_sync_time": { "type": "string", "nullable": true, "description": "ISO 8601" }, "total_items": { "type": "integer" }, "synced_items": { "type": "integer", "description": "Searchable documents (includes docs with failed base status but past indexing)" }, "failed_items": { "type": "integer" }, "recent_syncs": { "type": "array", "items": { "type": "object", "properties": { "started_at": { "type": "string" }, "completed_at": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": ["pending", "running", "complete"] } } } } } } } }, "example": { "error": null, "payload": { "organization_name": "Acme Research", "is_syncing": false, "current_job_id": null, "last_sync_time": "2026-04-08T03:01:01", "total_items": 10017, "synced_items": 10010, "failed_items": 7, "recent_syncs": [ { "started_at": "2026-04-08T02:00:39", "completed_at": "2026-04-08T03:01:01", "status": "complete" }, { "started_at": "2026-04-07T02:00:20", "completed_at": "2026-04-07T03:11:17", "status": "complete" } ] } } } } } } } }, "/v1/status/documents": { "get": { "summary": "Document sync status", "description": "Returns per-document sync status. At least one filter (path, name, or document_ids) is required.", "tags": ["Status"], "parameters": [ { "name": "organization_id", "in": "query", "description": "Organization ID. Optional for single-org API keys.", "required": false, "schema": { "type": "string" } }, { "name": "document_ids", "in": "query", "description": "Comma-separated document IDs.", "required": false, "schema": { "type": "string" }, "example": "doc-id-1,doc-id-2" }, { "name": "path", "in": "query", "description": "Filter by path prefix.", "required": false, "schema": { "type": "string" } }, { "name": "name", "in": "query", "description": "Filter by document name (partial, case-insensitive).", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Document status list", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "nullable": true }, "payload": { "type": "array", "items": { "type": "object", "properties": { "document_id": { "type": "string" }, "document_name": { "type": "string" }, "status": { "type": "string", "description": "Display status: Synced, Syncing, Syncing Failed, Deleting, Deleting Failed" }, "extraction_status": { "type": "string", "enum": ["pending", "completed", "failed"] }, "last_synced_at": { "type": "string", "nullable": true }, "summary": { "type": "string", "nullable": true, "description": "LLM-generated document summary" } } } } } }, "example": { "error": null, "payload": [ { "document_id": "40aef76a-bb93-4f3c-9f4f-9119f38d85bf", "document_name": "Q1 Earnings Report.pdf", "status": "Synced", "extraction_status": "completed", "last_synced_at": "2026-04-08T02:38:15", "summary": "Q1 2026 earnings report showing 15% YoY revenue growth..." }, { "document_id": "7fe4d59f-1097-466d-a7fe-a60e8fe58c46", "document_name": "Old Report.pdf", "status": "Syncing Failed", "extraction_status": "pending", "last_synced_at": null, "summary": null } ] } } } } } } }, "/v1/status/containers": { "get": { "summary": "Container sync status", "description": "Returns per-container sync status with direct children IDs. At least one filter (path, name, or container_ids) is required.", "tags": ["Status"], "parameters": [ { "name": "organization_id", "in": "query", "description": "Organization ID. Optional for single-org API keys.", "required": false, "schema": { "type": "string" } }, { "name": "container_ids", "in": "query", "description": "Comma-separated container IDs.", "required": false, "schema": { "type": "string" }, "example": "container-id-1,container-id-2" }, { "name": "path", "in": "query", "description": "Filter by path prefix.", "required": false, "schema": { "type": "string" } }, { "name": "name", "in": "query", "description": "Filter by container name (partial, case-insensitive).", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Container status list", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "nullable": true }, "payload": { "type": "array", "items": { "type": "object", "properties": { "container_id": { "type": "string" }, "container_name": { "type": "string" }, "container_type": { "type": "string", "nullable": true }, "status": { "type": "string" }, "last_synced_at": { "type": "string", "nullable": true }, "child_document_ids": { "type": "array", "items": { "type": "string" } }, "child_container_ids": { "type": "array", "items": { "type": "string" } } } } } } }, "example": { "error": null, "payload": [ { "container_id": "001e4e05-d690-4f0b-9ebd-3e58b91e5d6c", "container_name": "Q1 2026 Earnings", "container_type": "note", "status": "Synced", "last_synced_at": "2026-04-08T02:04:56", "child_document_ids": ["doc-001", "doc-002"], "child_container_ids": ["17fc814d-7d47-4f92-ac82-c970b45955fb"] } ] } } } } } } }, "/v2/vault/presigned_url": { "post": { "tags": [ "Vault" ], "summary": "Vault — Get Upload URL", "description": "Step 1 of the Vault upload flow. Returns a single-use presigned upload (PUT) URL. Upload the file directly to that URL, then register it via POST /v2/vault/confirm.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VaultPresignedUrlRequest" }, "example": { "file_name": "Q4_report.pdf", "content_type": "application/pdf", "workspace": "personal" } } } }, "responses": { "200": { "description": "Presigned upload URL generated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VaultPresignedUrlResponse" }, "example": { "presigned_url": "https:///.../.pdf?...", "file_key": "development/data-original/.pdf", "document_id": "3a5b47d5-124e-4052-9fa6-0647ddcb1d97", "expiration_seconds": 600 } } } }, "400": { "description": "Bad request — missing/invalid fields" }, "401": { "description": "Unauthorized — invalid or missing API key" } } } }, "/v2/vault/confirm": { "post": { "tags": [ "Vault" ], "summary": "Vault — Confirm Upload", "description": "Step 3 of the Vault upload flow. Registers the uploaded file in RMS and triggers async ingestion (parse → chunk → embed → index), returning immediately with the rms_document_id. Poll GET /v2/vault/status for processing status / readiness.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VaultConfirmRequest" }, "example": { "document_id": "3a5b47d5-124e-4052-9fa6-0647ddcb1d97", "file_key": "development/data-original/.pdf", "file_name": "Q4_report.pdf", "content_type": "application/pdf", "workspace": "personal" } } } }, "responses": { "200": { "description": "Upload confirmed / registered", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VaultConfirmResponse" }, "example": { "rms_document_id": "eeb72343-d883-41a3-a58c-533184bbb9fd" } } } }, "400": { "description": "Bad request — missing/invalid fields" }, "401": { "description": "Unauthorized — invalid or missing API key" }, "500": { "description": "Upstream error — e.g. the uploaded file does not exist yet" } } } }, "/v2/vault/status": { "get": { "tags": [ "Vault" ], "summary": "Vault — Document Status", "description": "Returns the processing status for one or more vault documents. Poll after confirm until status is `Synced` (complete and searchable).", "parameters": [ { "name": "rms_document_ids", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Comma-separated list of rms_document_id values (the rms_document_id returned by confirm — NOT the presign document_id). Max 100.", "example": "eeb72343-d883-41a3-a58c-533184bbb9fd,3a0e9e69-191f-471a-94fd-97505c762ad3" }, { "name": "organization_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Organization ID (optional)." }, { "name": "user_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "User id (optional)." }, { "name": "user_email", "in": "query", "required": false, "schema": { "type": "string", "format": "email" }, "description": "User email (optional)." }, { "name": "user_name", "in": "query", "required": false, "schema": { "type": "string" }, "description": "User name (optional)." } ], "responses": { "200": { "description": "Per-document status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VaultStatusResponse" }, "example": { "statuses": [ { "rms_document_id": "eeb72343-d883-41a3-a58c-533184bbb9fd", "name": "Q4_report.pdf", "status": "Synced", "fail_code": null } ] } } } }, "400": { "description": "Bad request — rms_document_ids required" }, "401": { "description": "Unauthorized — invalid or missing API key" } } } } }, "components": { "schemas": { "CreateOrganizationRequest": { "type": "object", "properties": { "id": { "type": "string", "description": "Your organization ID", "example": "org_001" }, "name": { "type": "string", "description": "Organization's name", "example": "Example Investment Organization" }, "s3_path": { "type": "string", "description": "S3 path for organization data (optional)", "example": "s3://example-bucket/organization_001/" } }, "required": [ "id", "name" ] }, "CreateOrganizationResponse": { "type": "object", "properties": { "organization_id": { "type": "string", "format": "uuid", "description": "Organization's UUID", "example": "123e4567-e89b-12d3-a456-426614174000" }, "error": { "type": "string", "nullable": true, "description": "Error message if creation failed", "example": null } }, "required": [ "organization_id" ] }, "ChatMessageResponse": { "type": "object", "properties": { "chat_message_id": { "type": "string", "format": "uuid", "description": "Chat message ID" }, "message": { "type": "string", "description": "Chat message" }, "message_type": { "type": "string", "description": "Chat message type", "enum": [ "assistant", "user", "think" ], "example": "assistant" }, "created_at": { "type": "string", "description": "Chat message created at", "example": "2025-10-30T09:11:31.667544Z" } } }, "SearchRequest": { "type": "object", "properties": { "query": { "type": "string", "description": "A search query", "example": "What are the latest updates on AAPL?" }, "stock_ids": { "type": "array", "items": { "type": "string" }, "description": "Bloomberg stock IDs (optional)", "example": [ "BBG001S5N8V8" ] }, "tickers": { "type": "array", "items": { "type": "string" }, "description": "Ticker symbols (optional)", "example": [ "AAPL" ] }, "external_types": { "type": "array", "items": { "type": "string" }, "description": "External document types (optional, defaults to [\"transcript\", \"filing\", \"news\", \"ir_slide\"])", "default": [ "transcript", "filing", "news", "ir_slide" ], "example": [ "transcript", "filing", "news", "ir_slide" ] }, "top_k": { "type": "number", "description": "Specifies the number of top search results to return.\nIf the value exceeds 50, it will be capped at 50\nThe number of returned results will be less than or equal to the specified top_k value.\nResults are sorted by relevancy in descending order (from highest to lowest).", "example": 50 }, "upload_period": { "type": "object", "description": "Filter documents by upload date range. At least one of start_time or end_time must be provided.", "properties": { "start_time": { "$ref": "#/components/schemas/DateFilter" }, "end_time": { "$ref": "#/components/schemas/DateFilter" } }, "example": { "start_time": { "year": 2025, "month": 1, "day": 1 }, "end_time": { "year": 2026, "month": 1, "day": 17 } } }, "search_types": { "type": "array", "items": { "type": "string", "enum": [ "rms", "external", "all" ] }, "description": "Types of search to perform", "example": [ "rms", "external" ] }, "rms_types": { "type": "array", "items": { "type": "string" }, "description": "Filter by RMS document type. Only applies when `search_types` includes `rms`.", "nullable": true }, "rms_sub_types": { "type": "array", "items": { "type": "string" }, "description": "Filter by RMS document subtype within `rms_types`.", "nullable": true } }, "required": [ "query" ] }, "SearchResponse": { "type": "object", "properties": { "chat_message_id": { "type": "string", "format": "uuid", "description": "Chat message ID" }, "search_result_count": { "type": "number", "description": "Search result count" }, "execution_time_ms": { "type": "number", "description": "Execution time in milliseconds" }, "references": { "type": "array", "items": { "type": "object", "properties": { "citation_idx": { "type": "string", "description": "Citation index" }, "chunk_id": { "type": "string", "description": "Chunk ID" }, "document_id": { "type": "string", "description": "Document ID" }, "text": { "type": "string", "description": "Text" }, "text_type": { "type": "string", "description": "Text type" }, "document_name": { "type": "string", "description": "Document name" }, "external_url": { "type": "string", "description": "External URL" }, "metadata": { "$ref": "#/components/schemas/ReferenceMetadata" }, "custom_metadata": { "$ref": "#/components/schemas/CustomMetadata" } }, "required": [ "citation_idx", "chunk_id", "text", "text_type", "document_name", "external_url", "metadata" ] }, "description": "References" } }, "required": [ "chat_message_id" ] }, "TtsRequest": { "type": "object", "required": [ "query" ], "properties": { "query": { "type": "string", "description": "Natural language query to be converted to SQL", "example": "Show me NVIDIA's quarterly revenue and net income for 2024" } } }, "TtsResponse": { "type": "object", "required": [ "code", "success", "message", "response" ], "properties": { "code": { "type": "integer", "description": "Response code (0 for success)", "example": 0 }, "success": { "type": "boolean", "description": "Indicates whether the request was successful", "example": true }, "message": { "type": "string", "description": "Response message", "example": "success" }, "response": { "$ref": "#/components/schemas/TtsQueryResult" } } }, "TtsQueryResult": { "type": "object", "required": [ "execution_id", "rdb_result" ], "properties": { "execution_id": { "type": "string", "format": "uuid", "description": "Unique identifier for the query execution", "example": "2548d578-0446-4abc-b6f6-f50c966d341c" }, "stock_name_mapping": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Mapping of stock IDs to company names", "example": { "BBG001S5TZJ6": "NVIDIA Corporation" } }, "currency_info": { "type": "array", "items": { "$ref": "#/components/schemas/CurrencyInfo" }, "description": "Currency information for each stock" }, "field_currency_info": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Currency information for each field", "example": { "BBG001S6Q004": { "SALES": "TWD", "EPS": "TWD", "ff_sales": "TWD" } } }, "execution_duration": { "type": "number", "description": "Execution duration in milliseconds" }, "date_range": { "type": "array", "items": { "type": "string", "format": "date" }, "minItems": 2, "maxItems": 2, "description": "Date range for the query [start_date, end_date]", "example": [ "2024-01-01", "2024-12-31" ] }, "rdb_result": { "type": "string", "description": "Query results formatted as markdown tables", "example": "### Company Annual Financials\n\n| name | Fiscal Period End Date | Dividends Per Share |\n| --- | --- | --- |\n| NVIDIA Corporation | 2024-01-31 | 0.016 |" }, "earnings_schedule": { "type": "array", "items": { "$ref": "#/components/schemas/EarningsScheduleEvent" }, "description": "Prior/upcoming earnings-call schedule events for the resolved companies, returned when the query asks for earnings-call dates (e.g. \"When does Apple next report?\"). Returned only for organizations entitled to earnings-call schedule retrieval; omitted entirely for all other organizations." }, "earnings_schedule_truncated": { "type": "boolean", "description": "True when an unbounded universe scan (\"which companies report this week?\") was capped by a load/window limit, so the returned list is partial. Always false for company-specific queries. Present only alongside earnings_schedule." } } }, "EarningsScheduleEvent": { "type": "object", "required": [ "stock_id", "stock_name", "event_datetime", "direction", "is_estimated" ], "properties": { "stock_id": { "type": "string", "description": "Bloomberg Global ID of the company", "example": "BBG001S5N8V8" }, "stock_name": { "type": "string", "description": "Company name", "example": "Apple Inc." }, "event_datetime": { "type": "string", "description": "Earnings-call / release datetime (ISO 8601)", "example": "2026-07-30T00:00:00" }, "direction": { "type": "string", "enum": [ "prior", "upcoming" ], "description": "Whether the event is in the past (prior) or future (upcoming) relative to now" }, "is_estimated": { "type": "boolean", "description": "True when the date is a vendor projection rather than a confirmed/announced date. Always false for prior events; only ever true for upcoming events.", "example": true }, "fiscal_date": { "type": "string", "format": "date", "nullable": true, "description": "Fiscal period the event reports on", "example": "2026-09-30" }, "link": { "type": "string", "nullable": true, "description": "Webcast link, if available" }, "event_description": { "type": "string", "nullable": true, "description": "Human-readable event description", "example": "Q3 2026 Earnings Release (Projected)" } } }, "CurrencyInfo": { "type": "object", "required": [ "currency", "exchange_rate" ], "properties": { "currency": { "type": "string", "description": "Currency code (ISO 4217)", "example": "USD" }, "exchange_rate": { "type": "number", "description": "Exchange rate to base currency", "example": 1 } } }, "ChatSseV2Request": { "type": "object", "properties": { "query": { "type": "string", "description": "A search query", "example": "What are the latest updates on AAPL?" }, "conversation_id": { "type": "string", "format": "uuid", "description": "Conversation id (optional)\n\nEvery user-initiated chat is grouped under a conversation. A conversation contains one or more messages generated either by the user or LinqAlpha. Use the conversation_id to track the context of previous interactions.", "example": "123e4567-e89b-12d3-a456-426614174000" }, "stock_ids": { "type": "array", "items": { "type": "string" }, "description": "Bloomberg stock IDs (optional)", "example": [ "BBG001S5N8V8" ] }, "tickers": { "type": "array", "items": { "type": "string" }, "description": "Ticker symbols (optional)", "example": [ "AAPL" ] }, "external_types": { "type": "array", "items": { "type": "string" }, "description": "External document types (optional, defaults to [\"transcript\", \"filing\", \"news\", \"ir_slide\"])", "default": [ "transcript", "filing", "news", "ir_slide" ], "example": [ "transcript", "filing", "news", "ir_slide" ] }, "top_k": { "type": "number", "description": "Specifies the number of top search results to return.\nIf the value exceeds 50, it will be capped at 50\nThe number of returned results will be less than or equal to the specified top_k value.\nResults are sorted by relevancy in descending order (from highest to lowest).", "example": 50 }, "upload_period": { "type": "object", "description": "Filter documents by upload date range. At least one of start_time or end_time must be provided.", "properties": { "start_time": { "$ref": "#/components/schemas/DateFilter" }, "end_time": { "$ref": "#/components/schemas/DateFilter" } }, "example": { "start_time": { "year": 2025, "month": 1, "day": 1 }, "end_time": { "year": 2026, "month": 1, "day": 17 } } } }, "required": [ "query" ] }, "RmsChatRequest": { "type": "object", "properties": { "organization_id": { "type": "string", "format": "uuid", "description": "Organization ID", "example": "123e4567-e89b-12d3-a456-426614174000" }, "conversation_id": { "type": "string", "format": "uuid", "description": "Conversation ID for multi-turn interactions (optional)", "example": "987e6543-e21b-32d3-c654-426614174999" }, "source_batch_id": { "type": "string", "format": "uuid", "description": "Source batch ID", "example": "123e4567-e89b-12d3-a456-426614174000" }, "source_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Optional array of specific source IDs to search within. If provided, only these sources will be searched. If omitted, all sources belonging to the `source_batch_id` will be searched. Requires `source_batch_id` to be specified, and all IDs must exist within that batch.", "example": [ "123e4567-e89b-12d3-a456-426614174000", "223e4567-e89b-12d3-a456-426614174001" ] }, "user_id": { "type": "string", "description": "User ID", "example": "123e4567-e89b-12d3-a456-426614174000" }, "user_email": { "type": "string", "description": "User email", "example": "john.doe@example.com" }, "user_name": { "type": "string", "description": "User name", "example": "John Doe" }, "container_ids": { "type": "array", "items": { "type": "string" }, "description": "Container IDs to search within (optional)", "example": [ "container_id1", "container_id2" ] }, "document_ids": { "type": "array", "items": { "type": "string" }, "description": "Document IDs to search within (optional)", "example": [ "document_id1", "document_id2" ] }, "query": { "type": "string", "description": "Search query", "example": "What are the latest insights on AAPL performance?" }, "search_types": { "type": "array", "items": { "type": "string", "enum": [ "rms", "external", "all" ] }, "description": "Types of search to perform", "example": [ "rms", "external" ] }, "client_api_url": { "type": "string", "description": "Client API URL", "example": "https://api.example.com", "nullable": true }, "per_event_size": { "type": "number", "description": "Number of kb size to return per event. When set to 0, search_results will not be returned via stream, only chat_message_id will be returned. You can retrieve search_results using the chat_message_id through the references API. Setting to 0 is recommended for stream stability.", "default": 0, "example": 0 }, "per_event_sleep_time": { "type": "number", "description": "Sleep time per event", "default": 0.01, "example": 0.01 }, "rms_types": { "type": "array", "items": { "type": "string" }, "description": "RMS document types (customizable)", "example": [ "emailnotes", "generalnotes", "templatednotes", "custom-data", "structured-data" ] }, "rms_sub_types": { "type": "object", "description": "RMS sub-types mapping (optional)", "example": { "template_note": [ "template_note1", "template_note2" ] } }, "external_types": { "type": "array", "items": { "type": "string", "enum": [ "transcript", "filing", "news", "ir_slide", "structured_data" ] }, "description": "External document types (optional, defaults to [\"transcript\", \"filing\", \"news\", \"ir_slide\"])", "default": [ "transcript", "filing", "news", "ir_slide" ], "example": [ "transcript", "filing", "news", "ir_slide" ] }, "stock_ids": { "type": "array", "items": { "type": "string" }, "description": "Bloomberg stock IDs (optional)", "example": [ "BBG001S5N8V8" ] }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Search tags (optional)", "example": [ "tech", "earnings" ] }, "upload_period": { "type": "object", "properties": { "start_time": { "$ref": "#/components/schemas/DateFilter" }, "end_time": { "$ref": "#/components/schemas/DateFilter" } }, "description": "Filter documents by upload date range. At least one of start_time or end_time must be provided." }, "fiscal_period": { "type": "object", "properties": { "start_time": { "$ref": "#/components/schemas/FiscalPeriodFilter" }, "end_time": { "$ref": "#/components/schemas/FiscalPeriodFilter" } }, "description": "Fiscal period filter (optional)", "example": { "start_time": { "year": 2023, "quarter": 1 }, "end_time": { "year": 2024, "quarter": 3 } } }, "agentic": { "type": "boolean", "description": "Whether to use agentic search", "example": true }, "prerelease": { "type": "object", "description": "Prerelease filters (optional)", "example": { "stream_t2s_table": true } }, "custom_filters": { "type": "object", "description": "Custom filters (optional)", "example": { "your_own_field": "value" } } }, "required": [ "organization_id", "user_id", "user_email", "user_name", "query", "search_types" ] }, "CreateSourceBatchRequest": { "type": "object", "properties": { "user_id": { "type": "string", "description": "User ID", "example": "123e4567-e89b-12d3-a456-426614174000" }, "organization_id": { "type": "string", "format": "uuid", "description": "Organization ID", "example": "123e4567-e89b-12d3-a456-426614174000" }, "user_email": { "type": "string", "description": "User email", "example": "john.doe@example.com" }, "user_name": { "type": "string", "description": "User name", "example": "John Doe" }, "name": { "type": "string", "description": "Descriptive name for the source batch (e.g., project name, document category)", "minLength": 1, "maxLength": 255, "example": "Q4_Financial_Reports" }, "description": { "type": "string", "description": "Optional detailed description of the source batch purpose and contents", "maxLength": 1000, "example": "Financial documents including revenue reports, expense summaries, and forecasts for Q4 2024" } }, "required": [ "name" ] }, "CreateSourceBatchResponse": { "type": "object", "properties": { "source_batch_id": { "type": "string", "format": "uuid", "description": "Unique identifier for the created source batch. Use this ID when uploading sources and referencing the batch in chat/search requests.", "example": "123e4567-e89b-12d3-a456-426614174000" } }, "required": [ "source_batch_id" ] }, "CreateSourceRequest": { "type": "object", "properties": { "user_id": { "type": "string", "description": "User ID", "example": "123e4567-e89b-12d3-a456-426614174000" }, "organization_id": { "type": "string", "format": "uuid", "description": "Organization ID", "example": "123e4567-e89b-12d3-a456-426614174000" }, "user_email": { "type": "string", "description": "User email", "example": "john.doe@example.com" }, "user_name": { "type": "string", "description": "User name", "example": "John Doe" }, "source_batch_id": { "type": "string", "format": "uuid", "description": "ID of the source batch to add this source to. The batch must be created first via POST /v1/source_batches.", "example": "123e4567-e89b-12d3-a456-426614174000" }, "name": { "type": "string", "description": "Display name for the source, typically the original filename. Must not include a file extension.", "example": "Q4_Revenue_Report" }, "file_key": { "type": "string", "description": "S3 object key path where the file is stored. The file must be accessible to the API service and meet format/size requirements (PDF, DOCX, XLSX, DOC, TXT, PPTX; max 20MB).", "example": "uploaded_sources/2024/q4/revenue_report.pdf" } }, "required": [ "source_batch_id", "name", "file_key" ] }, "CreateSourceResponse": { "type": "object", "properties": { "source_id": { "type": "string", "format": "uuid", "description": "Unique identifier for the created source. Use this ID to poll processing status via GET /v1/sources/{source_id}.", "example": "456e7890-e89b-12d3-a456-426614174001" }, "size": { "type": "integer", "description": "File size in bytes", "minimum": 0, "example": 2048576 }, "status": { "type": "string", "description": "Initial processing status (typically 'processing' when first created)", "enum": [ "processing", "success", "failed" ], "example": "processing" } }, "required": [ "source_id", "size" ] }, "GetSourceResponse": { "type": "object", "properties": { "source_id": { "type": "string", "format": "uuid", "description": "Source identifier", "example": "456e7890-e89b-12d3-a456-426614174001" }, "status": { "type": "string", "description": "Current processing status:\n- `processing`: File is being parsed and indexed\n- `success`: Source is ready for use in conversations\n- `failed`: Processing failed, source cannot be used", "enum": [ "processing", "success", "failed" ], "example": "success" }, "error": { "type": "string", "description": "Error message if status is 'failed' (optional)", "example": "File format not supported" } }, "required": [ "source_id", "status" ] }, "UploadUrlRequest": { "type": "object", "properties": { "name": { "type": "string", "description": "Display name for the source, typically the original filename. Used to construct the S3 object key.", "example": "Q4_Revenue_Report.pdf" }, "source_type": { "type": "string", "description": "File extension. Determines the expected `Content-Type` baked into the presigned URL signature.", "enum": [ "pdf", "docx", "xlsx", "pptx", "doc", "txt" ], "example": "pdf" }, "source_batch_id": { "type": "string", "format": "uuid", "description": "Source batch the upload will be registered under. Must be created first via `POST /v1/source_batches`. Per-batch source limit (10) is enforced here.", "example": "123e4567-e89b-12d3-a456-426614174000" } }, "required": [ "name", "source_type", "source_batch_id" ] }, "UploadUrlResponse": { "type": "object", "properties": { "upload_url": { "type": "string", "format": "uri", "description": "Presigned S3 PUT URL. Single-use, signed with the `content_type` value below. Send the file body via `PUT ` with header `Content-Type: `.", "example": "https://linq-vertex-documents.s3.amazonaws.com/uploads/1715000000000_a1b2c3d4_Q4_Revenue_Report.pdf/original.pdf?X-Amz-Algorithm=...&X-Amz-Signature=..." }, "file_key": { "type": "string", "description": "Server-generated object key. Pass this as `file_key` in the subsequent `POST /v1/sources` call to register the uploaded file.", "example": "uploads/1715000000000_a1b2c3d4_Q4_Revenue_Report.pdf/original.pdf" }, "content_type": { "type": "string", "description": "Content-Type baked into the presigned URL signature. Client MUST send this exact value as the `Content-Type` header on the PUT, otherwise S3 rejects with HTTP 403 (`SignatureDoesNotMatch`).", "example": "application/pdf" }, "expires_in": { "type": "integer", "description": "Seconds until `upload_url` expires. After this, request a new URL.", "example": 600 } }, "required": [ "upload_url", "file_key", "content_type", "expires_in" ] }, "RmsInterruptRequest": { "type": "object", "properties": { "organization_id": { "type": "string", "format": "uuid", "description": "Organization ID" }, "user_id": { "type": "string", "description": "User ID" }, "user_email": { "type": "string", "description": "User email" }, "user_name": { "type": "string", "description": "User name" }, "conversation_id": { "type": "string", "format": "uuid", "description": "Conversation ID" }, "dialogue_id": { "type": "string", "format": "uuid", "description": "Dialogue ID" } }, "required": [ "conversation_id", "dialogue_id" ] }, "DateFilter": { "type": "object", "description": "Date filter with year, month, and optional day", "properties": { "year": { "type": "integer", "description": "Year (e.g., 2025)", "example": 2025 }, "month": { "type": "integer", "description": "Month (1-12)", "minimum": 1, "maximum": 12, "example": 1 }, "day": { "type": "integer", "description": "Day of month (1-31, optional)", "minimum": 1, "maximum": 31, "example": 15 } }, "required": [ "year", "month" ] }, "FiscalPeriodFilter": { "type": "object", "properties": { "year": { "type": "integer", "example": 2024 }, "quarter": { "type": "integer", "minimum": 1, "maximum": 4, "example": 3 } }, "required": [ "year", "quarter" ] }, "ReferencesResponse": { "type": "object", "properties": { "references": { "type": "array", "items": { "$ref": "#/components/schemas/RMSReference" }, "description": "References" } }, "required": [ "references" ] }, "AnalyticsReferencesResponse": { "type": "object", "description": "Wrapper for analytics references response (normalized format). The payload contains a list of references with enriched metadata.", "properties": { "error": { "type": "object", "nullable": true, "description": "Error object. Null on success." }, "payload": { "type": "object", "nullable": true, "properties": { "references": { "type": "array", "items": { "type": "object", "description": "Reference in normalized format with enriched metadata", "properties": { "id": { "type": "string", "description": "Citation index as string (e.g., \"1\")" }, "citation_idx": { "type": "string", "description": "Citation index as string" }, "search_type": { "type": "string", "enum": [ "rms", "external" ], "description": "Source type" }, "chunk_id": { "type": "string", "description": "Chunk identifier" }, "text": { "type": "string", "description": "Reference text content" }, "text_type": { "type": "string", "enum": [ "paragraph", "table", "image", "news" ], "description": "Content type" }, "document_id": { "type": "string", "description": "Source document ID" }, "document_name": { "type": "string", "description": "Document title" }, "s3_file_key": { "type": "string", "nullable": true, "description": "S3 file path for document download" }, "external_url": { "type": "string", "nullable": true, "description": "External URL for the document" }, "metadata": { "type": "object", "description": "Enriched metadata with financial and document classification fields", "properties": { "calendar_date": { "type": "string", "nullable": true, "description": "Publication or event date" }, "fiscal_year": { "type": "integer", "nullable": true }, "fiscal_quarter": { "type": "integer", "nullable": true }, "source": { "type": "string", "nullable": true }, "tickers": { "type": "array", "items": { "type": "string" }, "nullable": true }, "company_names": { "type": "array", "items": { "type": "string" }, "nullable": true }, "stock_ids": { "type": "array", "items": { "type": "string" }, "nullable": true }, "document_category": { "type": "string", "nullable": true }, "document_subcategory": { "type": "string", "nullable": true }, "rms_document_type": { "type": "string", "nullable": true }, "rms_type": { "type": "string", "nullable": true }, "rms_sub_type": { "type": "string", "nullable": true }, "sector": { "type": "array", "items": { "type": "string" }, "nullable": true }, "subsector": { "type": "array", "items": { "type": "string" }, "nullable": true }, "publisher": { "type": "string", "nullable": true }, "countries": { "type": "array", "items": { "type": "string" }, "nullable": true }, "regions": { "type": "array", "items": { "type": "string" }, "nullable": true }, "participants": { "type": "array", "nullable": true }, "tags": { "type": "array", "items": { "type": "string" }, "nullable": true }, "offset": { "type": "array", "nullable": true }, "parent_id": { "type": "string", "nullable": true, "description": "Parent document ID" }, "parent_document_id": { "type": "string", "nullable": true, "description": "Parent document ID (same as parent_id)" }, "creation_timestamp": { "type": "string", "nullable": true, "description": "Document creation timestamp (ISO 8601)" }, "last_contribution_timestamp": { "type": "string", "nullable": true, "description": "Last modification timestamp (ISO 8601)" }, "document_tags": { "type": "array", "items": { "type": "string" }, "nullable": true, "description": "Document classification tags (e.g. research_report, brokerage)" }, "creator_name": { "type": "string", "nullable": true, "description": "Document creator name" }, "last_contributor_name": { "type": "string", "nullable": true, "description": "Last contributor name" } } }, "custom_metadata": { "type": "object", "nullable": true, "description": "Additional custom metadata" } } } } } } } }, "ReferencesV2Response": { "type": "object", "properties": { "references": { "type": "array", "items": { "$ref": "#/components/schemas/ReferenceV2" }, "description": "List of references associated with the conversation" } }, "required": [ "references" ] }, "ReferenceV2": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Reference ID" }, "citation_idx": { "type": "integer", "description": "Citation index number" }, "search_type": { "type": "string", "description": "Type of search that produced this reference (e.g., \"rms\")" }, "chunk_id": { "type": "string", "description": "Chunk identifier" }, "text": { "type": "string", "description": "Reference text content" }, "text_type": { "type": "string", "description": "Type of text (e.g., \"paragraph\")" }, "document_id": { "type": "string", "format": "uuid", "description": "Document ID. Use with presigned_url endpoint for direct download." }, "document_name": { "type": "string", "description": "Document name" }, "s3_file_key": { "type": "string", "nullable": true, "description": "S3 file key (may be null)" }, "external_url": { "type": "string", "description": "External URL for the document" }, "metadata": { "$ref": "#/components/schemas/ReferenceMetadataV2" } }, "required": [ "id", "citation_idx", "search_type", "chunk_id", "text", "text_type", "document_id", "document_name", "s3_file_key", "external_url", "metadata" ] }, "ReferenceMetadataV2": { "type": "object", "properties": { "rms_type": { "type": "string", "nullable": true }, "rms_sub_type": { "type": "string", "nullable": true }, "rms_document_type": { "type": "string", "nullable": true, "description": "Document type (e.g., \"earnings_call\", \"filing\")" }, "source": { "type": "string", "nullable": true }, "countries": { "type": "array", "items": { "type": "string" }, "nullable": true }, "regions": { "type": "array", "items": { "type": "string" }, "nullable": true }, "participants": { "type": "array", "items": { "type": "string" }, "nullable": true }, "tags": { "type": "array", "items": { "type": "string" }, "nullable": true }, "publisher": { "type": "string", "nullable": true }, "calendar_date": { "type": "string", "nullable": true }, "fiscal_year": { "type": "string", "nullable": true }, "fiscal_quarter": { "type": "string", "nullable": true }, "document_category": { "type": "string", "nullable": true, "description": "Document category (e.g., \"earnings_call\")" }, "document_subcategory": { "type": "string", "nullable": true }, "sector": { "type": "string", "nullable": true }, "subsector": { "type": "string", "nullable": true }, "stock_ids": { "type": "array", "items": { "type": "string" }, "nullable": true, "description": "Bloomberg Global Identifiers (e.g., [\"BBG001S5N8V8\"])" }, "tickers": { "type": "array", "items": { "type": "string" }, "nullable": true, "description": "Ticker symbols (e.g., [\"AAPL\"])" }, "company_names": { "type": "array", "items": { "type": "string" }, "nullable": true }, "offset": { "type": "integer", "nullable": true }, "snippet": { "type": "string", "nullable": true } } }, "AnalyticsRequest": { "type": "object", "properties": { "query": { "type": "string", "description": "The analytics query to process. Include ticker symbols, date ranges, and any other filtering context directly in the query text (e.g., \"Compare MSFT and GOOG revenue growth from 2023 to 2025\")." }, "conversation_id": { "type": "string", "nullable": true, "description": "Existing conversation ID to continue a multi-turn conversation. Omit or set to null for a new conversation." }, "organization_id": { "type": "string", "format": "uuid", "description": "Organization ID. Required for platform API keys to identify the target organization.", "example": "123e4567-e89b-12d3-a456-426614174000" }, "user_id": { "type": "string", "description": "User ID. Required together with `user_email` for platform API keys to identify the specific user.", "example": "user-123" }, "user_email": { "type": "string", "format": "email", "description": "User email. Required together with `user_id` for platform API keys to identify the specific user.", "example": "john.doe@example.com" } }, "required": [ "query" ] }, "ConversationEvent": { "description": "Conversation event", "allOf": [ { "$ref": "#/components/schemas/ChatSseEvent" }, { "properties": { "event_name": { "enum": [ "conversation" ] }, "data": { "type": "object", "required": [ "conversation_id" ], "properties": { "conversation_id": { "type": "string", "description": "Unique conversation identifier. Use for multi-turn continuation and References API." }, "message": { "type": "string", "description": "Status message (e.g., 'Successfully created a conversation.')" } }, "description": "Event-specific data payload" } } } ] }, "DialogueIdEvent": { "type": "object", "description": "Dialogue id streaming event", "allOf": [ { "$ref": "#/components/schemas/ChatSseEvent" }, { "properties": { "event_name": { "enum": [ "dialogue_id" ] }, "data": { "type": "object", "required": [ "dialogue_id" ], "properties": { "dialogue_id": { "type": "string", "description": "A unique identifier (UUID) that represents a specific dialogue or message exchange within a chat session. This ID is provided as an event during the chat process, appearing in the stream before any think events.\n\nThe dialogue_id serves to uniquely identify individual dialogue instances within a chat session, enabling precise control over message streaming and interruption. Here, a dialogue is defined as a single question and answer pair - so a single chat_session is composed of a sequence of dialogues.\n\nUnlike using only the chat_session_id, the dialogue_id prevents race conditions that could occur when multiple windows or instances interact with the same chat session simultaneously. " } } } } } ] }, "ChatMessageEvent": { "type": "object", "description": "Chat message event", "allOf": [ { "$ref": "#/components/schemas/ChatSseEvent" }, { "properties": { "event_name": { "enum": [ "chat_message" ] }, "data": { "type": "object", "required": [ "chat_message_id", "message_type" ] } } } ] }, "StatusEvent": { "description": "Stream status event (start/finish)", "allOf": [ { "$ref": "#/components/schemas/BaseSseEvent" }, { "properties": { "event_name": { "enum": [ "status" ] }, "data": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "start", "finish" ], "description": "Stream status indicator" } } } } } ] }, "ThinkEvent": { "description": "Thinking/reasoning process stream", "allOf": [ { "$ref": "#/components/schemas/BaseSseEvent" }, { "properties": { "event_name": { "enum": [ "think" ] }, "data": { "type": "object", "required": [ "think_piece" ], "properties": { "think_piece": { "type": "string", "description": "A piece of the thinking/reasoning process (streamed incrementally)", "example": "" } } } } } ] }, "SubQuestionsEvent": { "description": "Sub-questions event", "allOf": [ { "$ref": "#/components/schemas/BaseSseEvent" }, { "properties": { "event_name": { "enum": [ "sub_questions" ] }, "data": { "type": "object", "required": [ "sub_questions" ], "properties": { "sub_questions": { "type": "array", "description": "Sub-questions", "items": { "type": "string", "description": "Sub-question" } } } } } } ] }, "SearchResultsEvent": { "description": "Search result id streaming event", "allOf": [ { "$ref": "#/components/schemas/ChatSseEvent" }, { "properties": { "event_name": { "enum": [ "search_results" ] }, "data": { "type": "object", "required": [ "chat_message_id" ], "properties": { "chat_message_id": { "type": "string", "description": "Chat message id (You can retrieve search_results using the chat_message_id through the references API.)" } } } } } ] }, "AnswerEvent": { "description": "Final answer streaming event", "allOf": [ { "$ref": "#/components/schemas/BaseSseEvent" }, { "properties": { "event_name": { "enum": [ "answer" ] }, "data": { "type": "object", "required": [ "answer_piece" ], "properties": { "answer_piece": { "type": "string", "description": "A piece of the final answer (streamed incrementally). Citations are embedded as [hash] format.", "example": "### Executive Summary" } } } } } ] }, "RMSReference": { "type": "object", "properties": { "id": { "type": "string", "description": "Reference citation index (will be deprecated in the future)", "example": "123e4567-e89b-12d3-a456-426614174000" }, "citation_idx": { "type": "string", "description": "Reference citation index", "example": "123e4567-e89b-12d3-a456-426614174000" }, "search_type": { "type": "string", "enum": [ "rms", "external" ], "description": "Type of search used", "example": "rms" }, "chunk_id": { "type": "string", "format": "uuid", "description": "ID of the chunk this reference belongs to" }, "text": { "type": "string", "description": "Exact text content of the matching chunk retrieved during search and used in the final answer. This is the precise segment of the source document that the model cited as evidence." }, "text_type": { "type": "string", "enum": [ "paragraph", "table", "image", "news" ], "description": "Type of text content" }, "document_id": { "type": "string", "format": "uuid", "description": "Document ID that this reference points to" }, "document_name": { "type": "string", "description": "Human-readable document name" }, "s3_file_key": { "type": "string", "description": "S3 file path for the document" }, "external_url": { "type": "string", "description": "External S3 URL to access the document" }, "metadata": { "$ref": "#/components/schemas/ReferenceMetadata" }, "custom_metadata": { "$ref": "#/components/schemas/CustomMetadata" } }, "required": [ "id", "citation_idx", "search_type", "chunk_id", "text", "text_type", "document_name", "external_url", "metadata" ] }, "CreateConversationFeedbackRequest": { "type": "object", "properties": { "organization_id": { "type": "string", "description": "Organization ID (optional, inferred from API key if not provided)", "example": "org_001" }, "user_id": { "type": "string", "description": "User ID submitting the feedback (optional)", "example": "user_123" }, "user_email": { "type": "string", "description": "User email (optional)", "example": "user@example.com" }, "user_name": { "type": "string", "description": "User name (optional)", "example": "John Doe" }, "conversation_id": { "type": "string", "description": "The unique identifier of the conversation", "example": "123e4567-e89b-12d3-a456-426614174000" }, "rating": { "type": "string", "enum": [ "up", "down" ], "description": "Feedback rating: 'up' for positive, 'down' for negative", "example": "up" }, "message_id": { "type": "string", "description": "Specific message ID to provide feedback on (optional)", "example": "msg_abc123" }, "comment": { "type": "string", "description": "Additional text comment from the user (optional)", "example": "Very helpful and accurate response!" } }, "required": [ "conversation_id", "rating" ] }, "CreateConversationFeedbackResponse": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Indicates whether the feedback was successfully submitted", "example": true } }, "required": [ "success" ] }, "DeleteConversationFeedbackResponse": { "type": "object", "properties": { "error": { "nullable": true, "description": "Error object, null on success" }, "payload": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Indicates whether the feedback was successfully deleted", "example": true } }, "required": [ "success" ] } } }, "ApiError": { "type": "object", "properties": { "code": { "type": "string", "description": "Error code indicating the type of error. Common codes:\n- Authentication: `API_KEY_MISSING`, `INVALID_API_KEY`\n- Validation: `INVALID_REQUEST_BODY`, `ORGANIZATION_ID_MISSING`, `TICKERS_MISSING`, `CHAT_MESSAGE_ID_MISSING`, `DOCUMENT_ID_MISSING`\n- Service: `SEARCH_FAIL`, `TTS_FAIL`, `CREATE_CONV_FAIL`, `GET_STOCK_FAIL`, `CREATE_MSG_FAIL`, `ALPHA_COMP_FAIL`, `GET_REF_FAIL`\n- Connectors: `CONNECTOR_LIST_FAIL`, `CONNECTOR_NOT_FOUND`, `CONNECTOR_CREATE_FAIL`, `CONNECTOR_UPDATE_FAIL`, `CONNECTOR_DELETE_FAIL`, `CONNECTOR_TEST_FAIL`\n- Not Found: `NOT_FOUND`", "example": "INVALID_REQUEST_BODY" }, "msg": { "type": "string", "description": "Error message (deprecated, use `message` instead)", "example": "query is required and must be a string" }, "message": { "type": "string", "description": "Error message providing more details about the error", "example": "query is required and must be a string" } }, "required": [ "code" ] }, "RmsInterruptResponse": { "type": "object", "properties": { "status": { "type": "string", "description": "Response status", "example": "success" }, "message": { "type": "string", "description": "Response message", "example": "Interrupt request received" }, "dialogue_id": { "type": "string", "description": "Dialogue ID", "example": "2d382478-077e-4bcb-b6ec-4fdcbc75ab33" }, "paused": { "type": "integer", "description": "Pause timestamp (Unix epoch)", "example": 1676198400 } } }, "ChatSseEvent": { "type": "object", "description": "Base structure for all Chat SSE events", "required": [ "event_name", "data" ], "properties": { "event_name": { "type": "string", "enum": [ "conversation", "status", "think", "sub_questions", "dialogue_id", "search_results", "answer" ] }, "data": { "type": "object", "description": "Event-specific data payload" } } }, "ApiErrorResponse": { "type": "object", "description": "Standard error response wrapper", "properties": { "error": { "$ref": "#/components/schemas/ApiError" }, "payload": { "description": "Always null for error responses", "nullable": true } }, "required": [ "error", "payload" ] }, "ReferenceMetadata": { "type": "object", "description": "Additional metadata information", "properties": { "source": { "type": "string", "nullable": true, "example": "news" }, "rms_type": { "type": "string", "enum": [ "emailnotes", "generalnotes", "templatednotes", "custom-data", "structured-data", "public_transcript", "private_transcript" ], "nullable": true }, "rms_sub_type": { "type": "string", "nullable": true }, "rms_document_type": { "type": "string", "enum": [ "note", "attachment" ], "nullable": true }, "parent_id": { "type": "string", "nullable": true }, "parent_document_id": { "type": "string", "nullable": true }, "countries": { "type": "array", "items": { "type": "string" }, "nullable": true }, "regions": { "type": "array", "items": { "type": "string" }, "nullable": true }, "participants": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "organization": { "type": "string" }, "role": { "type": "string", "nullable": true }, "participant_type": { "type": "string", "enum": [ "author", "analyst", "attendee", "mentioned", "others" ], "nullable": true } } }, "nullable": true }, "tags": { "type": "array", "items": { "type": "string" }, "nullable": true }, "publisher": { "type": "string", "nullable": true }, "calendar_date": { "type": "string", "format": "date-time", "nullable": true }, "creation_timestamp": { "type": "string", "nullable": true }, "last_contribution_timestamp": { "type": "string", "nullable": true }, "creator_name": { "type": "string", "description": "Name of the user who created the document", "nullable": true }, "last_contributor_name": { "type": "string", "description": "Name of the user who last contributed to the document", "nullable": true }, "fiscal_year": { "type": "integer", "nullable": true }, "fiscal_quarter": { "type": "string", "nullable": true }, "document_category": { "type": "string", "enum": [ "internal", "brokerage", "expert_network", "corporate_data", "external", "earnings_call", "filing" ], "nullable": true }, "document_subcategory": { "type": "string", "enum": [ "calls", "model", "analysis", "report", "filings", "ir_slide", "factsheet", "email", "earning", "slides", "10-K", "10-Q", "6-K", "8-K", "DEF 14A", "20-F", "annual_results", "interim_results", "annual_report", "interim_report", "offerings", "others" ], "nullable": true }, "document_tags": { "type": "array", "items": { "type": "string" }, "nullable": true }, "sector": { "type": "array", "items": { "type": "string", "enum": [ "Basic Materials", "Consumer Cyclicals", "Consumer Staples", "Energy", "Financial Services", "Healthcare", "Industrials", "Technology", "Transportation", "Telecom Services", "Utilities" ] }, "nullable": true }, "subsector": { "type": "array", "items": { "type": "string", "enum": [ "Agriculture", "Chemicals", "Metals & Mining", "Paper & Forest", "Steel", "Automobiles", "Branded Consumer Goods", "Business Services", "Consumer Cyclicals", "Consumer Durables", "Education", "Entertainment & Leisure", "Gaming", "Housing", "Lodging", "Media", "Restaurants & Pubs", "Retail", "Textile", "Apparel & Footwear", "Travel", "Beverages", "Consumer Products", "Food", "Tobacco", "Clean Energy", "Energy", "Gas", "Oil", "Oil Services", "Banks", "Brokers & Asset Managers", "Capital Markets", "Diversified Financials", "Insurance", "Real Estate", "Specialty Finance", "Biotechnology", "Healthcare Services", "Life Sciences", "Medical Technology", "Pharmaceuticals", "Aerospace & Defense", "Capital Goods", "Construction", "Electrical Equipment", "Environmental Services", "Machinery", "Machinery & Diversified Industrials", "Multi-Industry", "Packaging", "Communications Technology", "Hardware", "Info Services", "Integrated Electricals", "Internet", "IT Services", "IT Supply Chain", "Semiconductors", "Software", "Technology", "Air Freight", "Airlines", "Airports", "Infrastructure", "Logistics", "Railroads", "Shipping", "Trucking", "Communication Services", "Satellite", "Telecom Wireless", "Towers", "Diversified", "MLPs", "Power", "Utilities", "Water" ] }, "nullable": true }, "stock_ids": { "type": "array", "items": { "type": "string" }, "nullable": true }, "tickers": { "type": "array", "items": { "type": "string" }, "nullable": true }, "company_names": { "type": "array", "items": { "type": "string" }, "nullable": true }, "offset": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "top": { "type": "number" }, "left": { "type": "number" }, "width": { "type": "number" }, "height": { "type": "number" }, "page": { "type": "integer" } } } }, "blocks": { "type": "array", "items": { "type": "integer" }, "nullable": true, "description": "Transcript block indices for this chunk." } } }, "CustomMetadata": { "type": "object", "nullable": true, "description": "User-defined metadata. This field may contain additional structured data based on the document type and user configuration.", "properties": { "edgar_metadata": { "type": "object", "description": "SEC EDGAR filing metadata. This field is only available for SEC filing documents and is provided upon request. Not all users will have access to this data. Contact support@linqalpha.com to enable EDGAR metadata for your organization.", "properties": { "public_url": { "type": "string", "format": "uri", "description": "Public EDGAR URL to the source filing document on the SEC website", "example": "https://www.sec.gov/Archives/edgar/data/1045810/000104581023000227/nvda-20231029.htm" }, "accession_number": { "type": "string", "description": "SEC accession number uniquely identifying the filing. Format: XXXXXXXXXX-XX-XXXXXX", "example": "0001045810-23-000227", "pattern": "^\\d{10}-\\d{2}-\\d{6}$" }, "filing_values": { "type": "object", "description": "Additional SEC filing identifiers", "properties": { "film_number": { "type": "string", "description": "SEC film number assigned to the filing", "example": "231428716" }, "sec_file_number": { "type": "string", "description": "SEC file number for the registrant", "example": "000-23985" } } } }, "required": [ "public_url", "accession_number" ] } } }, "McpJsonRpcRequest": { "type": "object", "required": [ "jsonrpc", "method" ], "properties": { "jsonrpc": { "type": "string", "enum": [ "2.0" ], "description": "JSON-RPC version" }, "method": { "type": "string", "enum": [ "initialize", "ping", "notifications/initialized", "tools/list", "tools/call" ], "description": "MCP method to invoke" }, "id": { "type": "integer", "description": "Request identifier" }, "params": { "type": "object", "description": "Method-specific parameters. For tools/call: { name: string, arguments: object }" } } }, "McpJsonRpcResponse": { "type": "object", "properties": { "jsonrpc": { "type": "string", "enum": [ "2.0" ] }, "id": { "type": "integer", "nullable": true, "description": "Request identifier (null for error responses)" }, "result": { "type": "object", "description": "Method result (present on success)" }, "error": { "type": "object", "properties": { "code": { "type": "integer", "description": "JSON-RPC error code" }, "message": { "type": "string", "description": "Error message" } }, "description": "Error object (present on failure)" } } }, "AnalyticsSseEvent": { "type": "object", "description": "Base structure for all Analytics SSE events", "required": [ "event_name", "data" ], "properties": { "event_name": { "type": "string", "enum": [ "message", "status", "think", "tool_use_block", "tool_result_block", "answer", "keepalive" ], "description": "Type of event in the analytics stream" }, "data": { "type": "object", "description": "Event-specific data payload" } } }, "AnalyticsMessageEvent": { "description": "User message echo event. Second event in the stream (after conversation), echoing the user's query.", "allOf": [ { "$ref": "#/components/schemas/AnalyticsSseEvent" }, { "properties": { "event_name": { "enum": [ "message" ] }, "data": { "type": "object", "required": [ "message_id", "message_type", "message" ], "properties": { "message_id": { "type": "integer", "description": "Unique message identifier" }, "message_type": { "type": "string", "enum": [ "user", "assistant" ], "description": "Type of message" }, "message": { "type": "string", "description": "The message content" } } } } } ] }, "AnalyticsStatusEvent": { "description": "Stream status event indicating start, finish, or keep_alive of the analytics stream.", "allOf": [ { "$ref": "#/components/schemas/AnalyticsSseEvent" }, { "properties": { "event_name": { "enum": [ "status" ] }, "data": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "start", "finish", "keep_alive" ], "description": "Stream lifecycle status. 'keep_alive' is sent periodically during long tool execution gaps." } } } } } ] }, "AnalyticsThinkEvent": { "description": "Thinking/reasoning process stream. Sent as the model reasons through the problem.", "allOf": [ { "$ref": "#/components/schemas/AnalyticsSseEvent" }, { "properties": { "event_name": { "enum": [ "think" ] }, "data": { "type": "object", "required": [ "think_piece" ], "properties": { "think_piece": { "type": "string", "description": "A piece of the thinking/reasoning process (streamed incrementally)" } } } } } ] }, "AnalyticsToolUseBlockEvent": { "description": "Tool invocation event. Indicates a tool is being called during analysis. Multiple tool_use_block events may be sent in parallel batches.", "allOf": [ { "$ref": "#/components/schemas/AnalyticsSseEvent" }, { "properties": { "event_name": { "enum": [ "tool_use_block" ] }, "data": { "type": "object", "required": [ "name", "input" ], "properties": { "name": { "type": "string", "description": "Name of the tool being called (e.g., mcp__linq__manticore_sql, mcp__linq__factset_query)", "example": "mcp__linq__manticore_sql" }, "input": { "type": "object", "description": "Input arguments passed to the tool. Structure varies by tool.", "additionalProperties": true } } } } } ] }, "AnalyticsToolResultBlockEvent": { "description": "Tool execution result event. Contains the output from a tool call.", "allOf": [ { "$ref": "#/components/schemas/AnalyticsSseEvent" }, { "properties": { "event_name": { "enum": [ "tool_result_block" ] }, "data": { "type": "object", "required": [ "content" ], "properties": { "content": { "type": "string", "description": "JSON-encoded result from the tool execution" } } } } } ] }, "AnalyticsAnswerEvent": { "description": "Final answer event. Contains the complete answer in a single event (not streamed incrementally).", "allOf": [ { "$ref": "#/components/schemas/AnalyticsSseEvent" }, { "properties": { "event_name": { "enum": [ "answer" ] }, "data": { "type": "object", "required": [ "answer_piece" ], "properties": { "answer_piece": { "type": "string", "description": "The complete final answer content. Unlike other SSE endpoints, analytics sends the full answer in a single event rather than streaming it incrementally." } } } } } ] }, "AnalyticsKeepaliveEvent": { "description": "Heartbeat event sent periodically (every ~15s during idle periods) to keep the connection alive.", "allOf": [ { "$ref": "#/components/schemas/AnalyticsSseEvent" }, { "properties": { "event_name": { "enum": [ "keepalive" ] }, "data": { "type": "object", "required": [ "timestamp" ], "properties": { "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of the keepalive event", "example": "2026-02-26T22:46:50.780316" } } } } } ] }, "AnalyticsV2Request": { "type": "object", "properties": { "organization_id": { "type": "string", "format": "uuid", "description": "Organization ID" }, "user_id": { "type": "string", "format": "uuid", "description": "User ID" }, "user_email": { "type": "string", "format": "email", "description": "User email" }, "user_name": { "type": "string", "description": "User name" }, "query": { "type": "string", "description": "The analytics query to process.", "example": "What are the latest insights on AAPL earnings?" }, "conversation_id": { "type": "string", "nullable": true, "description": "Existing conversation ID for multi-turn continuation. Omit or null for new conversation." }, "search_types": { "type": "object", "nullable": true, "description": "Structured source selection. Controls which document sources to query. Omitting a category means don't search it.", "properties": { "rms": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "workspace": { "type": "string", "enum": [ "personal", "organization" ], "description": "Workspace scope" }, "source": { "type": "string", "nullable": true, "description": "Source type for this RMS selection. For Vault-uploaded documents (referenced by their rms_document_id in document_ids), you MUST set source to \"vault\". If omitted, the documents are searched generically: they are not retrieved for direct file citation, the answer's [N] markers won't resolve, and GET /v2/analytics/conversations/{id}/references returns an empty list." }, "type": { "type": "string", "nullable": true }, "subtypes": { "type": "array", "items": { "type": "string" }, "nullable": true }, "container_ids": { "type": "array", "items": { "type": "string" }, "nullable": true }, "document_ids": { "type": "array", "items": { "type": "string" }, "nullable": true } }, "required": [ "workspace" ] } }, "external": { "type": "array", "nullable": true, "description": "Third-party sources", "items": { "type": "object", "properties": { "type": { "type": "string" }, "subtypes": { "type": "array", "items": { "type": "string" }, "nullable": true }, "document_ids": { "type": "array", "items": { "type": "string" }, "nullable": true } }, "required": [ "type" ] } }, "structured": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "type": { "type": "string" } }, "required": [ "type" ] } } } }, "filters": { "type": "object", "nullable": true, "description": "Metadata filters. Hard filters exclude non-matching documents (AND between fields, OR within arrays). Soft filters boost relevance without excluding.", "properties": { "rms": { "type": "object", "nullable": true, "properties": { "hard_filters": { "type": "object", "nullable": true, "description": "Strict metadata constraints for internal sources. AND between fields, OR within arrays." }, "soft_filters": { "type": "object", "nullable": true, "description": "Preferred but not required metadata for internal sources. Boosts relevance." } } }, "external": { "type": "object", "nullable": true, "properties": { "soft_filters": { "type": "object", "nullable": true, "description": "Preferred metadata for external sources. No hard filters on external by design." } } } } }, "connectors": { "type": "array", "nullable": true, "description": "Customer MCP connectors to enable for this analytics request.", "items": { "type": "object", "additionalProperties": true, "properties": { "name": { "type": "string", "description": "Connector name" }, "tool_filter": { "type": "array", "nullable": true, "items": { "type": "string" }, "description": "Optional tool allow-list for this connector" } }, "required": [ "name" ] } }, "disabled_connectors": { "type": "array", "nullable": true, "description": "Connector names to disable for this analytics request.", "items": { "type": "string" } } }, "required": [ "query" ] }, "ConnectorMutationRequest": { "type": "object", "description": "Customer connector create/update body. Any additional fields you include are preserved and forwarded with the request.", "additionalProperties": true, "properties": { "name": { "type": "string", "description": "Connector name" }, "credentials": { "type": "object", "description": "Write-only credential payload.", "additionalProperties": true, "properties": { "headers": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Write-only HTTP headers used by the connector upstream. Values are not returned by read endpoints." } } } } }, "ConnectorProxyPayload": { "type": "object", "description": "Opaque connector payload. Credential values are write-only and are not returned.", "additionalProperties": true }, "ConnectorApiResponse": { "type": "object", "properties": { "error": { "nullable": true, "oneOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "payload": { "$ref": "#/components/schemas/ConnectorProxyPayload" } }, "required": [ "error", "payload" ] }, "ConnectorListApiResponse": { "type": "object", "description": "List response — the payload is an array of connectors.", "properties": { "error": { "nullable": true, "oneOf": [ { "$ref": "#/components/schemas/ApiError" } ] }, "payload": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/ConnectorProxyPayload" } } }, "required": [ "error", "payload" ] }, "Briefing": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string", "nullable": true }, "topic": { "type": "string" }, "tickers": { "type": "array", "items": { "type": "string" } }, "language": { "type": "string", "nullable": true }, "scheduled_time": { "type": "string", "description": "Time in h:mm AM/PM format, echoing the value provided on create/update (e.g. '9:00 AM')" }, "timezone": { "type": "string", "description": "IANA timezone" }, "frequency": { "type": "string", "enum": ["daily", "weekly", "monthly"] }, "scheduled_day_of_week": { "type": "integer", "nullable": true }, "scheduled_day_of_month": { "type": "integer", "nullable": true }, "next_delivery_at": { "type": "string", "nullable": true }, "is_active": { "type": "boolean" }, "source_type": { "type": "string" }, "attach_pdf": { "type": "boolean" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } } }, "BriefingCreateRequest": { "type": "object", "required": ["topic", "scheduled_time", "timezone"], "properties": { "topic": { "type": "string", "description": "Briefing instructions/topic" }, "stock_ids": { "type": "array", "items": { "type": "string" }, "description": "Internal stock UUIDs (preferred). Use /v1/map_tickers to convert ticker symbols." }, "tickers": { "type": "array", "items": { "type": "string" }, "description": "Ticker symbols (e.g. AAPL, 9988.HK). Auto-resolved to stock_ids." }, "language": { "type": "string", "nullable": true, "enum": ["English", "Spanish", "French", "German", "Italian", "Portuguese", "Dutch", "Hindi", "Japanese", "Chinese", "Finnish", "Korean", "Polish", "Russian", "Turkish", "Ukrainian", "Vietnamese"], "description": "Output language (null = auto-detect)" }, "scheduled_time": { "type": "string", "description": "Time in h:mm AM/PM format. Examples: '9:00 AM', '3:30 PM'" }, "timezone": { "type": "string", "description": "IANA timezone identifier (e.g. America/New_York, Asia/Seoul, Europe/London)" }, "frequency": { "type": "string", "enum": ["daily", "weekly", "monthly"], "default": "daily" }, "scheduled_day_of_week": { "type": "integer", "minimum": 0, "maximum": 6, "description": "Day of week for weekly frequency (0=Sun, 1=Mon, ..., 6=Sat)" }, "scheduled_day_of_month": { "type": "integer", "minimum": 1, "maximum": 31, "description": "Day of month for monthly frequency" }, "title": { "type": "string", "description": "Custom briefing title (auto-generated if omitted)" }, "source_type": { "type": "string", "enum": ["tfs_only", "rms_only", "both"], "default": "tfs_only", "description": "Data source: tfs_only (news+filings), rms_only (uploaded documents), both" }, "attach_pdf": { "type": "boolean", "default": false, "description": "Attach briefing as PDF to delivery email" }, "is_active": { "type": "boolean", "default": true, "description": "Enable/disable the schedule" }, "rms_sources": { "type": "array", "items": { "type": "object", "properties": { "source": { "type": "string" }, "workspace": { "type": "string" } } }, "description": "RMS source configurations for storage-based briefing" }, "watchlist_group_id": { "type": "string", "description": "Link to watchlist group for dynamic ticker sync" }, "use_custom_email_title": { "type": "boolean", "default": false, "description": "Use briefing title as fixed email subject" }, "organization_id": { "type": "string", "description": "Platform (EDS) keys only: org UUID under the key's platform. Ignored by org-bound keys." }, "user_id": { "type": "string", "description": "Platform (EDS) keys only: the target user's customer_id (your external user id, not a UUID). Ignored by org-bound keys." }, "user_email": { "type": "string", "description": "Platform (EDS) keys only: the target user's email (used to find or create the user). Ignored by org-bound keys." }, "user_name": { "type": "string", "description": "Platform (EDS) keys only: optional display name (used only when creating the user)." } } }, "BriefingUpdateRequest": { "type": "object", "description": "All fields are optional. Only include fields you want to change.", "properties": { "topic": { "type": "string", "description": "Briefing instructions/topic" }, "stock_ids": { "type": "array", "items": { "type": "string" }, "description": "Internal stock UUIDs (preferred)" }, "tickers": { "type": "array", "items": { "type": "string" }, "description": "Ticker symbols (auto-resolved)" }, "language": { "type": "string", "nullable": true, "enum": ["English", "Spanish", "French", "German", "Italian", "Portuguese", "Dutch", "Hindi", "Japanese", "Chinese", "Finnish", "Korean", "Polish", "Russian", "Turkish", "Ukrainian", "Vietnamese"], "description": "Output language (null = auto-detect)" }, "scheduled_time": { "type": "string", "description": "h:mm AM/PM format (e.g. '9:00 AM')" }, "timezone": { "type": "string", "description": "IANA timezone (e.g. Asia/Seoul)" }, "frequency": { "type": "string", "enum": ["daily", "weekly", "monthly"] }, "scheduled_day_of_week": { "type": "integer", "nullable": true, "minimum": 0, "maximum": 6, "description": "0=Sun, 6=Sat" }, "scheduled_day_of_month": { "type": "integer", "nullable": true, "minimum": 1, "maximum": 31 }, "title": { "type": "string", "nullable": true, "description": "Custom briefing title" }, "source_type": { "type": "string", "enum": ["tfs_only", "rms_only", "both"] }, "attach_pdf": { "type": "boolean" }, "is_active": { "type": "boolean", "description": "Enable/disable the schedule" }, "rms_sources": { "type": "array", "items": { "type": "object", "properties": { "source": { "type": "string" }, "workspace": { "type": "string" } } }, "description": "RMS source configurations" }, "watchlist_group_id": { "type": "string", "nullable": true, "description": "Watchlist group ID to link for dynamic ticker sync. Note: unlinking by sending null is not currently supported." }, "use_custom_email_title": { "type": "boolean", "description": "Use title as fixed email subject" }, "organization_id": { "type": "string", "description": "Platform (EDS) keys only: org UUID under the key's platform. Ignored by org-bound keys." }, "user_id": { "type": "string", "description": "Platform (EDS) keys only: the target user's customer_id (your external user id, not a UUID). Ignored by org-bound keys." }, "user_email": { "type": "string", "description": "Platform (EDS) keys only: the target user's email. Ignored by org-bound keys." }, "user_name": { "type": "string", "description": "Platform (EDS) keys only: optional display name (used only when creating the user)." } } }, "BriefingDelivery": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": ["pending", "sent", "failed", "resynced", "skipped"], "description": "Delivery status" }, "delivered_at": { "type": "string", "nullable": true }, "scheduled_at": { "type": "string", "nullable": true }, "email_title": { "type": "string", "nullable": true }, "tickers": { "type": "array", "items": { "type": "string" } }, "frequency": { "type": "string", "nullable": true }, "created_at": { "type": "string" } } }, "BriefingDeliveryDetail": { "type": "object", "properties": { "id": { "type": "string", "description": "Delivery ID" }, "status": { "type": "string", "enum": ["pending", "sent", "failed", "resynced", "skipped"], "description": "Delivery status" }, "delivered_at": { "type": "string", "nullable": true, "description": "ISO 8601 timestamp when delivered" }, "scheduled_at": { "type": "string", "nullable": true, "description": "ISO 8601 timestamp when scheduled" }, "email_title": { "type": "string", "nullable": true, "description": "Email subject line" }, "tickers": { "type": "array", "items": { "type": "string" }, "description": "Ticker symbols included" }, "frequency": { "type": "string", "nullable": true, "enum": ["daily", "weekly", "monthly"], "description": "Schedule frequency" }, "content": { "type": "string", "nullable": true, "description": "Full briefing content. Markdown for most briefings; may be HTML for certain briefing types." }, "chat_session_id": { "type": "string", "nullable": true, "description": "Chat session ID from this delivery's generation (informational; the on-demand endpoints do not accept it as input)." }, "created_at": { "type": "string", "description": "ISO 8601 creation timestamp" } } }, "BaseSseEvent": { "type": "object", "description": "Base structure for SSE events", "required": [ "event_name", "data" ], "properties": { "event_name": { "type": "string", "enum": [ "status", "research_progress", "round", "think", "sub_questions", "tool_call", "tool_response", "search_results", "answer" ], "description": "Type of SSE event" }, "data": { "type": "object", "description": "Event-specific data payload" } } }, "KeepAliveEvent": { "description": "Keep alive event", "allOf": [ { "$ref": "#/components/schemas/BaseSseEvent" }, { "properties": { "event_name": { "enum": [ "keep_alive" ] }, "data": { "type": "object", "required": [ "keep_alive_counter", "timestamp" ], "properties": { "keep_alive_counter": { "type": "integer", "description": "Counter for keep alive messages" }, "timestamp": { "type": "string", "description": "Timestamp of the keep alive message" } } } } } ] }, "ResearchProgressEvent": { "description": "Research progress tracking event (5-100%)", "allOf": [ { "$ref": "#/components/schemas/BaseSseEvent" }, { "properties": { "event_name": { "enum": [ "research_progress" ] }, "data": { "type": "object", "required": [ "stage", "stage_description", "progress_percentage" ], "properties": { "stage": { "type": "string", "enum": [ "initialization", "research", "finalizing", "complete" ], "description": "Current research stage:\n- initialization (5-10%): Environment setup and structure generation\n- research (15-85%): Multi-round research phase\n- finalizing (90%): Final preparation\n- complete (100%): Research done, content generation starting" }, "stage_description": { "type": "string", "description": "Human-readable description of current stage", "example": "Conducting research round 3" }, "progress_percentage": { "type": "number", "minimum": 0, "maximum": 100, "description": "Overall progress percentage (0-100)" }, "current_round": { "type": "integer", "nullable": true, "description": "Current research round (0-indexed, null if not in research stage)", "example": 2 }, "max_rounds": { "type": "integer", "nullable": true, "description": "Maximum number of research rounds (null if not in research stage)", "example": 5 } } } } } ] }, "RoundEvent": { "description": "Research round start/end marker", "allOf": [ { "$ref": "#/components/schemas/BaseSseEvent" }, { "properties": { "event_name": { "enum": [ "round" ] }, "data": { "type": "object", "required": [ "count", "continue_search" ], "properties": { "count": { "type": "integer", "description": "Current round number (0-indexed)" }, "continue_search": { "type": "boolean", "description": "Whether to continue searching in next round" } } } } } ] }, "ToolCallEvent": { "description": "Tool invocation event", "allOf": [ { "$ref": "#/components/schemas/BaseSseEvent" }, { "properties": { "event_name": { "enum": [ "tool_call" ] }, "data": { "type": "object", "required": [ "tool_name", "tool_args" ], "properties": { "tool_name": { "type": "string", "description": "Name of the tool being called", "example": "integrated_search" }, "tool_args": { "type": "object", "description": "Arguments passed to the tool", "properties": { "query": { "type": "string", "description": "Search query", "example": "JP Morgan equity research Asia" } } } } } } } ] }, "ToolResponseEvent": { "description": "Tool response event with search results", "allOf": [ { "$ref": "#/components/schemas/BaseSseEvent" }, { "properties": { "event_name": { "enum": [ "tool_response" ] }, "data": { "type": "object", "required": [ "id", "response" ], "properties": { "id": { "type": "string", "description": "Unique identifier for the tool response", "example": "7a21e20f" }, "response": { "type": "object", "required": [ "query", "result" ], "properties": { "query": { "type": "string", "description": "The query that was executed" }, "result": { "type": "string", "description": "The search result content" }, "used_citations": { "type": "array", "description": "Citations used in the response", "items": { "$ref": "#/components/schemas/DeepResearchCitation" } } } } } } } } ] }, "DeepResearchCitation": { "type": "object", "description": "Citation information for a source", "properties": { "title": { "type": "string", "description": "Title of the cited source" }, "url": { "type": "array", "items": { "type": "string" }, "description": "URL(s) of the source" }, "source": { "type": "string", "description": "Source name or publication" }, "date": { "type": "string", "description": "Publication date (if available)" }, "hash": { "type": "string", "description": "Unique hash identifier for the citation", "example": "3ee9c11f" } } }, "VaultPresignedUrlRequest": { "type": "object", "required": [ "file_name", "content_type" ], "properties": { "file_name": { "type": "string", "description": "Original file name (with extension).", "example": "Q4_report.pdf" }, "content_type": { "type": "string", "description": "MIME type of the file.", "example": "application/pdf" }, "workspace": { "type": "string", "enum": [ "personal", "organization" ], "default": "personal", "description": "Vault scope the document is uploaded into. Must match between presigned_url and confirm. Note: the analytics SSE search must use the same workspace to retrieve the document." }, "organization_id": { "type": "string", "format": "uuid", "description": "Organization ID (optional)." }, "user_id": { "type": "string", "format": "uuid", "description": "User id (optional)." }, "user_email": { "type": "string", "format": "email", "description": "User email (optional)." }, "user_name": { "type": "string", "description": "User name (optional)." } } }, "VaultPresignedUrlResponse": { "type": "object", "properties": { "presigned_url": { "type": "string", "format": "uri", "description": "Single-use presigned upload (PUT) URL. Upload the file body via PUT with header Content-Type matching the request content_type." }, "file_key": { "type": "string", "description": "Server-generated file key. Pass back to POST /v2/vault/confirm." }, "document_id": { "type": "string", "description": "Document id for this upload. Pass back to confirm." }, "expiration_seconds": { "type": "integer", "example": 600 } } }, "VaultConfirmRequest": { "type": "object", "required": [ "document_id", "file_key", "file_name", "content_type" ], "properties": { "document_id": { "type": "string", "description": "From the presigned_url response." }, "file_key": { "type": "string", "description": "From the presigned_url response." }, "file_name": { "type": "string", "description": "Original filename including the extension. The server resolves the file type from this extension first, so it must be correct.", "example": "Q4_report.pdf" }, "content_type": { "type": "string", "description": "Canonical MIME type for the file. Must match the value sent to presigned_url and the upload PUT Content-Type header. If the content_type does not match the file, the document is not processed. See the content_type table on this page for the value per file type.", "example": "application/pdf" }, "workspace": { "type": "string", "enum": [ "personal", "organization" ], "default": "personal" }, "organization_id": { "type": "string", "format": "uuid", "description": "Organization ID (optional)." }, "user_id": { "type": "string", "format": "uuid", "description": "User id (optional)." }, "user_email": { "type": "string", "format": "email", "description": "User email (optional)." }, "user_name": { "type": "string", "description": "User name (optional)." } } }, "VaultConfirmResponse": { "type": "object", "properties": { "rms_document_id": { "type": "string", "nullable": true, "description": "RMS document id; null when the upload deduplicated into an existing document. Use it to poll GET /v2/vault/status." } } }, "VaultDocumentStatus": { "type": "object", "properties": { "rms_document_id": { "type": "string", "nullable": true }, "name": { "type": "string" }, "status": { "type": "string", "nullable": true, "description": "Processing status. Poll until `Synced` (complete and searchable). See the status values table on this page." }, "fail_code": { "type": "string", "nullable": true, "description": "Deterministic terminal-failure code (e.g. `PASSWORD_PROTECTED`, `FILE_SIZE_EXCEEDED`, `CONVERSION_FAILED`). Branch on this instead of parsing `status` text; `null` unless the document terminally failed." } } }, "VaultStatusResponse": { "type": "object", "properties": { "statuses": { "type": "array", "items": { "$ref": "#/components/schemas/VaultDocumentStatus" } } } } }, "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-KEY" } } } }