{ "openapi": "3.1.0", "info": { "title": "Ultralayer API", "version": "V0", "description": "# Ultralayer API V0: Beta\n\n## Authentication\nAll endpoints require valid Bearer Authentication. Get your API key at https://console.ultralayer.ai\n" }, "servers": [ { "url": "https://api.ultralayer.ai", "description": "Ultralayer Production Server" } ], "paths": { "/v0/search/semantic_search": { "post": { "tags": [ "Search" ], "summary": "Semantic Search", "description": "Perform a semantic search over all indexed document chunks using a query string. Returns the top-k most relevant chunks based on cosine similarity of embeddings, with optional filters for timestamp, keywords, tags, and minimum rating.", "operationId": "semantic_search", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SemanticSearchParams" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/SemanticSearchResult" }, "type": "array", "title": "Response Semantic Search" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/v0/search/semantic_search_multi": { "post": { "tags": [ "Search" ], "summary": "Semantic Search Multi", "description": "Perform semantic search across multiple queries in one request. Results are flattened, deduplicated, and returned in a single ranked list. Benefits (vs just making multiple semantic_search calls): 1. simpler client implementation, 2. smarter strategies for deduplication and ranking, 3. cheaper as duplicates arent charged.", "operationId": "semantic_search_multi", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SemanticSearchMultiParams" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/SemanticSearchResult" }, "type": "array", "title": "Response Semantic Search Multi" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/v0/search/identify_stakeholders": { "post": { "tags": [ "Search" ], "summary": "Identify Stakeholders", "description": "Identify key stakeholders relevant to a given query, with optional context and instructions to guide the identification process.", "operationId": "identify_stakeholders", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StakeholderIdentificationParams" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StakeholderIdentificationResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/v0/search/search_developments": { "post": { "tags": [ "Search" ], "summary": "Search Developments", "description": "Search for developments semantically (or not). Various filters available: timestamp, development type, stakeholder impact, and more.", "operationId": "search_developments", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DevelopmentSearchParams" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/DevelopmentFromDB" }, "type": "array", "title": "Response Search Developments" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/v0/search/retrieve_development": { "post": { "tags": [ "Search" ], "summary": "Retrieve Development", "description": "Retrieve a specific development by its ID.", "operationId": "retrieve_development", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetrieveDevelopmentParams" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/DevelopmentFromDB" }, { "type": "null" } ], "title": "Response Retrieve Development" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/v0/search/retrieve_event_developments": { "post": { "tags": [ "Search" ], "summary": "Retrieve Event Developments", "description": "Retrieve all developments associated with a known event_id. Filters for timestamp and occurrence are available. Track and understand the full event lifecycle through its developments.", "operationId": "retrieve_event_developments", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetrieveEventDevelopmentsParams" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/EventWithDevelopments" }, { "type": "null" } ], "title": "Response Retrieve Event Developments" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/v0/search/search_events": { "post": { "tags": [ "Search" ], "summary": "Search Events", "description": "Search for events semantically (or not). Various filters available: timestamp, occurrence, event type and more.", "operationId": "search_events", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventSearchParams" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/EventFromDB" }, "type": "array", "title": "Response Search Events" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/v0/webhook/create_webhook": { "post": { "tags": [ "Webhook" ], "summary": "Create Webhook", "description": "Create a webhook that periodically calls a specified endpoint with given arguments and sends the results to a designated URL.", "operationId": "create_webhook", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookInstructions" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookCreationResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/v0/webhook/get_webhooks": { "get": { "tags": [ "Webhook" ], "summary": "Get Webhooks", "description": "Retrieve a list of all webhooks associated with the authenticated user.", "operationId": "get_webhooks", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/WebhookRecord" }, "type": "array", "title": "Response Get Webhooks" } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/v0/webhook/deactivate_webhook": { "post": { "tags": [ "Webhook" ], "summary": "Deactivate Webhook", "description": "Deactivate a webhook by setting its status to 'paused'.", "operationId": "deactivate_webhook", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookId" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "string", "title": "Response Deactivate Webhook" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/v0/webhook/activate_webhook": { "post": { "tags": [ "Webhook" ], "summary": "Activate Webhook", "description": "Activate a webhook by setting its status to 'active'.", "operationId": "activate_webhook", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookId" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "string", "title": "Response Activate Webhook" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/v0/webhook/delete_webhook": { "post": { "tags": [ "Webhook" ], "summary": "Delete Webhook", "description": "Permanently delete a webhook from the database.", "operationId": "delete_webhook", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookId" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "string", "title": "Response Delete Webhook" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/v0/webhook/execute_webhook": { "post": { "tags": [ "Webhook" ], "summary": "Execute Webhook.", "description": "Execute a webhook to test functionality.", "operationId": "execute_webhook", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookId" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "boolean", "title": "Response Execute Webhook" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/v0/mcp": { "post": { "tags": [ "MCP" ], "summary": "MCP Server (V0)", "description": "### This endpoint serves the remote Model Context Protocol (MCP) server for Ultralayer V0.\n### Tools\n- **semantic_search**: Perform a semantic search over all indexed document chunks using a query string. Returns the top-k most relevant chunks based on cosine similarity of embeddings, with optional filters for timestamp, keywords, tags, and minimum rating.\n- **semantic_search_multi**: Perform semantic search across multiple queries in one request. Results are flattened, deduplicated, and returned in a single ranked list. Benefits (vs just making multiple semantic_search calls): 1. simpler client implementation, 2. smarter strategies for deduplication and ranking, 3. cheaper as duplicates arent charged.\n- **identify_stakeholders**: Identify key stakeholders relevant to a given query, with optional context and instructions to guide the identification process.\n- **search_developments**: Search for developments semantically (or not). Various filters available: timestamp, development type, stakeholder impact, and more.\n- **retrieve_development**: Retrieve a specific development by its ID.\n- **retrieve_event_developments**: Retrieve all developments associated with a known event_id. Filters for timestamp and occurrence are available. Track and understand the full event lifecycle through its developments.\n- **search_events**: Search for events semantically (or not). Various filters available: timestamp, occurrence, event type and more.\n- **create_webhook**: Create a webhook that periodically calls a specified endpoint with given arguments and sends the results to a designated URL.\n- **get_webhooks**: Retrieve a list of all webhooks associated with the authenticated user.\n- **deactivate_webhook**: Deactivate a webhook by setting its status to 'paused'.\n- **activate_webhook**: Activate a webhook by setting its status to 'active'.\n- **execute_webhook**: Execute a webhook to test functionality.", "operationId": "v0_mcp", "responses": { "200": { "description": "MCP Protocol Stream", "content": { "application/json": {} } } } } } }, "components": { "schemas": { "DevelopmentFromDB": { "properties": { "development_id": { "type": "integer", "title": "Development Id", "description": "Logical identifier for the development across updates." }, "timestamp": { "type": "integer", "title": "Timestamp", "description": "Canonical backtest system timestamp of this development version." }, "source_timestamp": { "type": "integer", "title": "Source Timestamp", "description": "Most recent timestamp of any source used for the development." }, "occurrence_timestamp": { "type": "integer", "title": "Occurrence Timestamp", "description": "Actual (estimate of) real world time that the development took place." }, "occurrence_timestamp_confidence_score": { "type": "number", "title": "Occurrence Timestamp Confidence Score", "description": "Confidence score in estimate of occurrence_timestamp." }, "name": { "type": "string", "title": "Name", "description": "Name of the development." }, "description": { "type": "string", "title": "Description", "description": "Description of the development." }, "development_type": { "type": "string", "title": "Development Type", "description": "Type of the development." }, "occurrence_status": { "type": "string", "title": "Occurrence Status", "description": "Status of the real world occurrence." }, "rationale": { "type": "string", "title": "Rationale", "description": "Explanation for all decisions made." }, "stakeholders": { "items": { "$ref": "#/components/schemas/StakeholderImpact" }, "type": "array", "title": "Stakeholders", "description": "List of involved stakeholders and their impacts." }, "importance_score": { "type": "number", "title": "Importance Score", "description": "LLM heuristic of general development importance." }, "surprise_score": { "type": "number", "title": "Surprise Score", "description": "LLM heuristic of how surprising the development is to the market." }, "confidence_score": { "type": "number", "title": "Confidence Score", "description": "LLM heuristic of its confidence in everything it presents." }, "events": { "items": { "$ref": "#/components/schemas/EventSummary" }, "type": "array", "title": "Events", "description": "List of events this development is associated with, resolved to their most recent known state." }, "sources": { "items": { "$ref": "#/components/schemas/SourceWithQuotes" }, "type": "array", "title": "Sources", "description": "List of sources used for this development." } }, "type": "object", "required": [ "development_id", "timestamp", "source_timestamp", "occurrence_timestamp", "occurrence_timestamp_confidence_score", "name", "description", "development_type", "occurrence_status", "rationale", "stakeholders", "importance_score", "surprise_score", "confidence_score", "events", "sources" ], "title": "DevelopmentFromDB", "description": "A development as returned from the database.\nAlways represents the latest known version of the development at or before the requested end_timestamp." }, "DevelopmentSearchParams": { "properties": { "query": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Query", "description": "Semantic search query. If None, retrieves all developments matching the filters." }, "start_timestamp": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Start Timestamp", "description": "Filter for results >= this integer unix timestamp. None means realtime mode." }, "end_timestamp": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "End Timestamp", "description": "Filter for results <= this integer unix timestamp. None means realtime mode." }, "start_occurrence_timestamp": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Start Occurrence Timestamp", "description": "Filter for occurrence_timestamp >= this integer unix timestamp. None means no limit." }, "end_occurrence_timestamp": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "End Occurrence Timestamp", "description": "Filter for occurrence_timestamp <= this integer unix timestamp. None means no limit." }, "development_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Development Type", "description": "Filter by development type." }, "stakeholder_symbol": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Stakeholder Symbol", "description": "Filter by stakeholder symbol." }, "min_impact_score": { "anyOf": [ { "type": "number", "maximum": 1.0, "minimum": -1.0 }, { "type": "null" } ], "title": "Min Impact Score", "description": "Minimum impact score filter in [-1, 1]. If both min and max are provided, matching is directional OR (impact >= min OR impact <= max)." }, "max_impact_score": { "anyOf": [ { "type": "number", "maximum": 1.0, "minimum": -1.0 }, { "type": "null" } ], "title": "Max Impact Score", "description": "Maximum impact score filter in [-1, 1]. If both min and max are provided, matching is directional OR (impact >= min OR impact <= max)." }, "min_importance_score": { "anyOf": [ { "type": "number", "maximum": 1.0, "minimum": 0.0 }, { "type": "null" } ], "title": "Min Importance Score", "description": "Minimum importance score in [0, 1]." }, "min_surprise_score": { "anyOf": [ { "type": "number", "maximum": 1.0, "minimum": 0.0 }, { "type": "null" } ], "title": "Min Surprise Score", "description": "Minimum surprise score in [0, 1]." }, "min_confidence_score": { "anyOf": [ { "type": "number", "maximum": 1.0, "minimum": 0.0 }, { "type": "null" } ], "title": "Min Confidence Score", "description": "Minimum confidence score in [0, 1]." }, "limit": { "type": "integer", "maximum": 200.0, "minimum": 1.0, "title": "Limit", "description": "Maximum number of results to return.", "default": 10 } }, "type": "object", "title": "DevelopmentSearchParams" }, "DevelopmentSummary": { "properties": { "development_id": { "type": "integer", "title": "Development Id", "description": "Logical identifier for the development across updates." }, "timestamp": { "type": "integer", "title": "Timestamp", "description": "Canonical backtest system timestamp of this development version." }, "occurrence_timestamp": { "type": "integer", "title": "Occurrence Timestamp", "description": "Actual (estimate of) real world time that the development took place." }, "occurrence_timestamp_confidence_score": { "type": "number", "title": "Occurrence Timestamp Confidence Score", "description": "Confidence score in estimate of occurrence_timestamp." }, "name": { "type": "string", "title": "Name", "description": "Name of the development." }, "description": { "type": "string", "title": "Description", "description": "Description of the development." }, "development_type": { "type": "string", "title": "Development Type", "description": "Type of the development." }, "occurrence_status": { "type": "string", "title": "Occurrence Status", "description": "Status of the real world occurrence." }, "importance_score": { "type": "number", "title": "Importance Score", "description": "LLM heuristic of general development importance." }, "surprise_score": { "type": "number", "title": "Surprise Score", "description": "LLM heuristic of how surprising the development is to the market." }, "confidence_score": { "type": "number", "title": "Confidence Score", "description": "LLM heuristic of its confidence in everything it presents." }, "event_ids": { "items": { "type": "integer" }, "type": "array", "title": "Event Ids", "description": "Raw list of event IDs this development is associated with." } }, "type": "object", "required": [ "development_id", "timestamp", "occurrence_timestamp", "occurrence_timestamp_confidence_score", "name", "description", "development_type", "occurrence_status", "importance_score", "surprise_score", "confidence_score", "event_ids" ], "title": "DevelopmentSummary", "description": "Lightweight development summary embedded within an EventFromDB response.\nOmits heavy fields (rationale, stakeholders, sources) that are not strictly needed\nto understand what a development is in the context of scanning events." }, "EventFromDB": { "properties": { "event_id": { "type": "integer", "title": "Event Id", "description": "Logical identifier for the event." }, "name": { "type": "string", "title": "Name", "description": "Name of the event." }, "description": { "type": "string", "title": "Description", "description": "Description of the event." }, "event_type": { "type": "string", "title": "Event Type", "description": "Type of the event." }, "recent_developments": { "items": { "$ref": "#/components/schemas/DevelopmentSummary" }, "type": "array", "title": "Recent Developments", "description": "Most recent developments for this event (count controlled by developments_per_event param), ordered by occurrence_timestamp descending." } }, "type": "object", "required": [ "event_id", "name", "description", "event_type", "recent_developments" ], "title": "EventFromDB", "description": "Response model for search_events.\nEach event includes a condensed list of its most recent developments for quick scanning.\nFull developments can be retrieved via retrieve_event_developments." }, "EventSearchParams": { "properties": { "query": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Query", "description": "Semantic search query over event descriptions. If None, returns events ordered by recency of event creation." }, "start_timestamp": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Start Timestamp", "description": "Filter for events with development activity >= this unix timestamp." }, "end_timestamp": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "End Timestamp", "description": "Filter for events with development activity <= this unix timestamp. None means realtime mode." }, "event_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Event Type", "description": "Filter by event type." }, "limit": { "type": "integer", "maximum": 50.0, "minimum": 1.0, "title": "Limit", "description": "Maximum number of events to return.", "default": 10 }, "developments_per_event": { "type": "integer", "maximum": 10.0, "minimum": 0.0, "title": "Developments Per Event", "description": "Number of most recent developments to embed per event result, ordered by occurrence_timestamp descending.", "default": 3 }, "include_future_developments": { "type": "boolean", "title": "Include Future Developments", "description": "Whether to include developments whose occurrence_timestamp is in the future (relative to end_timestamp, or current time if end_timestamp is None) in the embedded per-event development list. Set to False to restrict to already-occurred developments.", "default": true } }, "type": "object", "title": "EventSearchParams", "description": "Parameters for semantically searching events.\nWhen timestamps are provided, only events with development activity within that window\nare considered \u2014 ensuring the user sees events that are actually relevant to the time period." }, "EventSummary": { "properties": { "event_id": { "type": "integer", "title": "Event Id", "description": "Logical identifier for the event across updates." }, "name": { "type": "string", "title": "Name", "description": "Name of the event." }, "description": { "type": "string", "title": "Description", "description": "Description of the event." }, "event_type": { "type": "string", "title": "Event Type", "description": "Type of the event." } }, "type": "object", "required": [ "event_id", "name", "description", "event_type" ], "title": "EventSummary", "description": "Lightweight event summary embedded within a DevelopmentFromDB response.\nProvides enough context for the user to understand what event a development belongs to\nwithout requiring a separate event lookup." }, "EventWithDevelopments": { "properties": { "event_id": { "type": "integer", "title": "Event Id", "description": "Logical identifier for the event." }, "name": { "type": "string", "title": "Name", "description": "Name of the event." }, "description": { "type": "string", "title": "Description", "description": "Description of the event." }, "event_type": { "type": "string", "title": "Event Type", "description": "Type of the event." }, "developments": { "items": { "$ref": "#/components/schemas/DevelopmentFromDB" }, "type": "array", "title": "Developments", "description": "Developments associated with this event, ordered by occurrence_timestamp descending (real-world timeline)." } }, "type": "object", "required": [ "event_id", "name", "description", "event_type", "developments" ], "title": "EventWithDevelopments", "description": "Response model for retrieve_event_developments.\nWraps full event details with its associated developments." }, "Factor": { "properties": { "name": { "type": "string", "title": "Name", "description": "Unique snake_case primary key for the factor. Name must be entirely self contained and describe the situation unambiguously. Name should be consistent and reusable across separate calls." }, "description": { "type": "string", "title": "Description", "description": "What the factor represents. This will be embedded for semantic retrieval, so write it as a clean, general definition." }, "factor_scale": { "type": "string", "enum": [ "BINARY", "CATEGORICAL", "CONTINUOUS", "SIGNED_CONTINUOUS" ], "title": "Factor Scale", "description": "Scale of factor." }, "rubric": { "type": "string", "title": "Rubric", "description": "Mandatory scoring rubric for consistency. Keep it short but explicit. This should ensure absolute consistency globally across separate calls." }, "allowed_values": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Allowed Values", "description": "Only for CATEGORICAL: enum of allowed category strings." } }, "type": "object", "required": [ "name", "description", "factor_scale", "rubric" ], "title": "Factor", "description": "Factor for comparing stakeholders." }, "FactorAssessment": { "properties": { "rationale": { "type": "string", "title": "Rationale", "description": "A brief explanation of the reasoning behind the assessment for this stakeholder given the factor." }, "value": { "anyOf": [ { "type": "boolean" }, { "type": "number" }, { "type": "string" } ], "title": "Value", "description": "Assessed value (type depends on factor_type). 1. BINARY -> bool; 2. CONTINUOUS -> float in [0,1]; 3. SIGNED_CONTINUOUS -> float in [-1,1]; 4. CATEGORICAL -> str in allowed_values." }, "sources": { "items": { "$ref": "#/components/schemas/Source" }, "type": "array", "minItems": 1, "title": "Sources", "description": "List of sources that support this factor assessment." } }, "type": "object", "required": [ "rationale", "value", "sources" ], "title": "FactorAssessment", "description": "Factor assessment information with relevant sources" }, "FactorMatrixRow": { "properties": { "factor": { "$ref": "#/components/schemas/Factor", "description": "Factor definition." }, "stakeholder_assessments": { "additionalProperties": { "$ref": "#/components/schemas/FactorAssessment" }, "type": "object", "title": "Stakeholder Assessments", "description": "Map: stakeholder symbol -> assessment object for this factor." } }, "type": "object", "required": [ "factor", "stakeholder_assessments" ], "title": "FactorMatrixRow", "description": "A row in the factor matrix, containing assessments for all stakeholders for a single factor." }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" }, "RetrieveDevelopmentParams": { "properties": { "development_id": { "type": "integer", "title": "Development Id", "description": "The ID of the development to retrieve." }, "end_timestamp": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "End Timestamp", "description": "Filter for results <= this integer unix timestamp. None means realtime mode." } }, "type": "object", "required": [ "development_id" ], "title": "RetrieveDevelopmentParams" }, "RetrieveEventDevelopmentsParams": { "properties": { "event_id": { "type": "integer", "title": "Event Id", "description": "The event_id to retrieve developments for." }, "start_timestamp": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Start Timestamp", "description": "Filter developments with timestamp >= this unix timestamp. None means no lower bound." }, "end_timestamp": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "End Timestamp", "description": "Filter developments with timestamp <= this unix timestamp. None means realtime mode." }, "limit": { "type": "integer", "maximum": 100.0, "minimum": 1.0, "title": "Limit", "description": "Maximum number of developments to return, ordered by occurrence_timestamp descending.", "default": 20 }, "include_future_developments": { "type": "boolean", "title": "Include Future Developments", "description": "Whether to include developments whose occurrence_timestamp is in the future (relative to end_timestamp, or current time if end_timestamp is None). Set to False to restrict results to developments that have already occurred.", "default": true } }, "type": "object", "required": [ "event_id" ], "title": "RetrieveEventDevelopmentsParams", "description": "Parameters for retrieving all developments associated with a known event_id.\nPrimarily used to: poll for new developments on a tracked event, or gather\nbackground context for a development whose event_ids are already known." }, "SemanticSearchMultiParams": { "properties": { "queries": { "items": { "type": "string" }, "type": "array", "maxItems": 50, "minItems": 2, "title": "Queries", "description": "List of semantic search queries.", "examples": [ [ "Apple iPhone demand outlook", "Apple services revenue growth", "Apple CEO guidance" ] ] }, "total_top_k": { "type": "integer", "maximum": 500.0, "minimum": 1.0, "title": "Total Top K", "description": "Best-effort target number of results to return after flattening and deduplication.", "default": 100 }, "start_timestamp": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Start Timestamp", "description": "filter for results >= this integer unix timestamp.", "examples": [ null, 1735689600 ] }, "end_timestamp": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "End Timestamp", "description": "filter for results <= this integer unix timestamp.", "examples": [ null, 1767225600 ] }, "minimum_cosine_similarity": { "type": "number", "maximum": 1.0, "minimum": 0.0, "title": "Minimum Cosine Similarity", "description": "filters results for cosine similarity >= this value.", "default": 0.0, "examples": [ 0.0, 0.75 ] }, "keywords": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Keywords", "description": "List of exact match keywords. If provided, returns results containing at least one.", "examples": [ [ "Apple", "Microsoft" ] ] }, "tags": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Tags", "description": "List of tags to filter by. If provided, returns results containing all specified tags.", "examples": [ [ "NEWS" ] ] }, "minimum_rating": { "anyOf": [ { "type": "number", "maximum": 1.0, "minimum": 0.0 }, { "type": "null" } ], "title": "Minimum Rating", "description": "filters results for quality rating >= this value.", "default": 0.4, "examples": [ 0.0, 0.4, 0.75 ] }, "strategy": { "type": "string", "enum": [ "cosine_similarity", "round_robin", "rank_sum" ], "title": "Strategy", "description": "Ranking strategy for consolidating results across queries. Final output is always ordered by cosine_similarity. - 'cosine_similarity': rank purely by cosine similarity. - 'round_robin': interleave results from each query in a round-robin fashion to promote diversity across queries. - 'rank_sum': assign a score to each chunk based on its rank in each query's results and sum these scores across queries, promotes duplicates.", "default": "round_robin" } }, "type": "object", "required": [ "queries" ], "title": "SemanticSearchMultiParams" }, "SemanticSearchParams": { "properties": { "query": { "type": "string", "title": "Query", "description": "The semantic search query string.", "examples": [ "machine learning trends" ] }, "start_timestamp": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Start Timestamp", "description": "filter for results >= this integer unix timestamp.", "examples": [ null, 1735689600 ] }, "end_timestamp": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "End Timestamp", "description": "filter for results <= this integer unix timestamp.", "examples": [ null, 1767225600 ] }, "top_k": { "type": "integer", "maximum": 100.0, "minimum": 1.0, "title": "Top K", "description": "Number of results to return.", "default": 10, "examples": [ 10, 25, 50 ] }, "minimum_cosine_similarity": { "type": "number", "maximum": 1.0, "minimum": 0.0, "title": "Minimum Cosine Similarity", "description": "filters results for cosine similarity >= this value.", "default": 0.0, "examples": [ 0.0, 0.75 ] }, "keywords": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Keywords", "description": "List of exact match keywords. If provided, returns results containing at least one.", "examples": [ [ "Apple", "Microsoft" ] ] }, "tags": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Tags", "description": "List of tags to filter by. If provided, returns results containing all specified tags.", "examples": [ [ "NEWS" ] ] }, "minimum_rating": { "anyOf": [ { "type": "number", "maximum": 1.0, "minimum": 0.0 }, { "type": "null" } ], "title": "Minimum Rating", "description": "filters results for quality rating >= this value.", "default": 0.4, "examples": [ 0.0, 0.4, 0.75 ] } }, "type": "object", "required": [ "query" ], "title": "SemanticSearchParams" }, "SemanticSearchResult": { "properties": { "cosine_similarity": { "type": "number", "title": "Cosine Similarity", "description": "Cosine similarity score between the query and the chunk embedding." }, "id": { "type": "integer", "title": "Id", "description": "Unique identifier for the chunk." }, "timestamp": { "type": "integer", "title": "Timestamp", "description": "Unix timestamp of the source document." }, "document_id": { "type": "integer", "title": "Document Id", "description": "Identifier of the source document." }, "tags": { "items": { "type": "string" }, "type": "array", "title": "Tags", "description": "List of tags associated with the chunk." }, "title": { "type": "string", "title": "Title", "description": "Title of the source document." }, "content": { "type": "string", "title": "Content", "description": "Content of the chunk." }, "named_entities": { "items": { "type": "string" }, "type": "array", "title": "Named Entities", "description": "List of named entities extracted from the chunk." }, "rating": { "type": "number", "title": "Rating", "description": "Quality rating of the chunk between 0.0 and 1.0." }, "source": { "$ref": "#/components/schemas/Source", "description": "Source information." } }, "type": "object", "required": [ "cosine_similarity", "id", "timestamp", "document_id", "tags", "title", "content", "named_entities", "rating", "source" ], "title": "SemanticSearchResult" }, "Source": { "properties": { "source_timestamp": { "type": "integer", "title": "Source Timestamp", "description": "Timestamp of the source item (unix epoch)." }, "source_table": { "type": "string", "title": "Source Table", "description": "Table (Type) of the source item (e.g., 'news', 'earnings_calls', 'press_releases', etc.)" }, "source_id": { "type": "integer", "title": "Source Id", "description": "'id' of the source item" }, "source_metadata": { "$ref": "#/components/schemas/SourceMetadata", "description": "Additional metadata about the source item." } }, "type": "object", "required": [ "source_timestamp", "source_table", "source_id", "source_metadata" ], "title": "Source", "description": "Full source information to be returned to end user." }, "SourceMetadata": { "properties": { "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Url", "description": "URL of the source material, if applicable." }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Title", "description": "Title of the source material, if applicable." }, "publisher": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Publisher", "description": "Publisher of the source material, if applicable." } }, "type": "object", "title": "SourceMetadata", "description": "Additional metadata about the source item, this is stuff that can change depending on the type of source" }, "SourceWithQuotes": { "properties": { "source_timestamp": { "type": "integer", "title": "Source Timestamp", "description": "Timestamp of the source item (unix epoch)." }, "source_table": { "type": "string", "title": "Source Table", "description": "Table (Type) of the source item (e.g., 'news', 'earnings_calls', 'press_releases', etc.)" }, "source_id": { "type": "integer", "title": "Source Id", "description": "'id' of the source item" }, "source_metadata": { "$ref": "#/components/schemas/SourceMetadata", "description": "Additional metadata about the source item." }, "quotes": { "items": { "type": "string" }, "type": "array", "minItems": 1, "title": "Quotes", "description": "List of EXACT quotes from the source material." } }, "type": "object", "required": [ "source_timestamp", "source_table", "source_id", "source_metadata", "quotes" ], "title": "SourceWithQuotes", "description": "Source information with relevant quotes" }, "StakeholderBase": { "properties": { "name": { "type": "string", "title": "Name", "description": "Name of the stakeholder" }, "stakeholder_type": { "type": "string", "const": "PUBLIC_COMPANY", "title": "Stakeholder Type", "description": "The type of stakeholder. ONLY the following are allowed: [PUBLIC_COMPANY]." }, "symbol": { "type": "string", "title": "Symbol", "description": "Ticker symbol of the stakeholder" } }, "type": "object", "required": [ "name", "stakeholder_type", "symbol" ], "title": "StakeholderBase", "description": "Stakeholder information" }, "StakeholderIdentificationParams": { "properties": { "query": { "type": "string", "title": "Query", "description": "The query / subject for which to identify stakeholders for." }, "context": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Context", "description": "Optional additional context to help identify stakeholders." }, "instructions": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Instructions", "description": "Optional additional instructions to guide stakeholder identification." }, "start_timestamp": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Start Timestamp", "description": "Optional start timestamp (unix epoch) to consider for time-sensitive queries." }, "end_timestamp": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "End Timestamp", "description": "Optional end timestamp (unix epoch) to consider for time-sensitive queries." } }, "type": "object", "required": [ "query" ], "title": "StakeholderIdentificationParams" }, "StakeholderIdentificationResponse": { "properties": { "stakeholder_impacts": { "items": { "$ref": "#/components/schemas/StakeholderImpact" }, "type": "array", "minItems": 0, "title": "Stakeholder Impacts", "description": "List of identified stakeholders with their impact details." }, "factor_matrix": { "items": { "$ref": "#/components/schemas/FactorMatrixRow" }, "type": "array", "minItems": 0, "title": "Factor Matrix", "description": "Factor matrix providing scoring for each stakeholder across defined factors." } }, "type": "object", "required": [ "stakeholder_impacts", "factor_matrix" ], "title": "StakeholderIdentificationResponse", "description": "Response model for stakeholder identification" }, "StakeholderImpact": { "properties": { "stakeholder": { "$ref": "#/components/schemas/StakeholderBase", "description": "The stakeholder being identified." }, "impact_score": { "type": "number", "maximum": 1.0, "minimum": -1.0, "title": "Impact Score", "description": "Impact score (-1.0 to 1.0) indicating the estimated magnitude and direction of the impact on the stakeholder." }, "confidence_score": { "type": "number", "maximum": 1.0, "minimum": 0.0, "title": "Confidence Score", "description": "Confidence score (0.0 to 1.0) indicating level of certainty in the stakeholder being materially impacted." }, "rationale": { "type": "string", "title": "Rationale", "description": "A brief explanation of why this stakeholder is relevant to the query" }, "sources_with_quotes": { "items": { "$ref": "#/components/schemas/SourceWithQuotes" }, "type": "array", "minItems": 1, "title": "Sources With Quotes", "description": "List of sources (with quotes) that support the identification of this stakeholder." } }, "type": "object", "required": [ "stakeholder", "impact_score", "confidence_score", "rationale", "sources_with_quotes" ], "title": "StakeholderImpact", "description": "Stakeholder impact information with relevant sources" }, "ValidationError": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" }, "WebhookCreationResponse": { "properties": { "message": { "type": "string", "title": "Message", "description": "Confirmation message indicating successful creation of the webhook." }, "webhook_id": { "type": "integer", "title": "Webhook Id", "description": "The unique identifier of the created webhook." }, "sample_data": { "title": "Sample Data", "description": "A sample of the data that will be sent to the webhook receiver URL upon execution." } }, "type": "object", "required": [ "message", "webhook_id", "sample_data" ], "title": "WebhookCreationResponse" }, "WebhookId": { "properties": { "webhook_id": { "type": "integer", "title": "Webhook Id", "description": "The ID of the webhook." } }, "type": "object", "required": [ "webhook_id" ], "title": "WebhookId" }, "WebhookInstructions": { "properties": { "path": { "type": "string", "const": "/v0/search/semantic_search", "title": "Path", "description": "The path of the desired endpoint.", "examples": [ "/v0/search/semantic_search" ] }, "arguments": { "additionalProperties": true, "type": "object", "title": "Arguments", "description": "A dictionary of arguments to call the endpoint with. *Note*: Do not include 'start_timestamp' or 'end_timestamp' as these are handled by the webhook.", "examples": [ { "minimum_cosine_similarity": 0.7, "query": "example query" } ] }, "interval": { "type": "integer", "minimum": 5.0, "title": "Interval", "description": "The interval (in minutes) at which the webhook will check the endpoint. Must be a multiple of 5.", "examples": [ 15 ] }, "receiver_url": { "type": "string", "title": "Receiver Url", "description": "The URL to which the webhook payloads will be sent.", "examples": [ "https://example.com/webhook_receiver" ] }, "receiver_headers": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Receiver Headers", "description": "Optional headers to include in the webhook requests to your url.", "examples": [ { "Authorization": "Bearer your_token_here" } ] } }, "type": "object", "required": [ "path", "arguments", "interval", "receiver_url" ], "title": "WebhookInstructions" }, "WebhookRecord": { "properties": { "webhook_id": { "type": "integer", "title": "Webhook Id", "description": "Unique identifier for the webhook." }, "status": { "type": "string", "enum": [ "active", "paused" ], "title": "Status", "description": "Current status of the webhook either 'active' or 'paused'." }, "instructions": { "additionalProperties": true, "type": "object", "title": "Instructions", "description": "User defined webhook configuration." }, "created_at": { "type": "string", "title": "Created At", "description": "Timestamp indicating when the webhook was created." } }, "type": "object", "required": [ "webhook_id", "status", "instructions", "created_at" ], "title": "WebhookRecord" } }, "securitySchemes": { "HTTPBearer": { "type": "http", "scheme": "bearer" } } } }