Search

Endpointhttps://api.ultralayer.ai

Semantic Search

POST

https://api.ultralayer.ai

/v0/search/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.

Semantic Search › Request Body

query

string · required

The semantic search query string.

Example: machine learning trends

filter for results >= this integer unix timestamp.

Example: null

filter for results <= this integer unix timestamp.

Example: null

top_k

integer · min: 1 · max: 100

Number of results to return.

Example: 10

Default: 10

minimum_cosine_similarity

number · min: 0 · max: 1

filters results for cosine similarity >= this value.

Example: 0

Default: 0

List of exact match keywords. If provided, returns results containing at least one.

Example: ["Apple","Microsoft"]

List of tags to filter by. If provided, returns results containing all specified tags.

Example: ["NEWS"]

filters results for quality rating >= this value.

Example: 0

Default: 0.4

Semantic Search › Responses

Successful Response

object[]

cosine_similarity

number · required

Cosine similarity score between the query and the chunk embedding.

id

integer · required

Unique identifier for the chunk.

timestamp

integer · required

Unix timestamp of the source document.

document_id

integer · required

Identifier of the source document.

tags

string[] · required

List of tags associated with the chunk.

title

string · required

Title of the source document.

content

string · required

Content of the chunk.

named_entities

string[] · required

List of named entities extracted from the chunk.

rating

number · required

Quality rating of the chunk between 0.0 and 1.0.

object · required

Source information.

POST/v0/search/semantic_search

curl --request POST \
  --url https://api.ultralayer.ai/v0/search/semantic_search \
  --header 'Content-Type: application/json' \
  --data '
{
  "query": "machine learning trends",
  "start_timestamp": null,
  "end_timestamp": null,
  "top_k": 10,
  "minimum_cosine_similarity": 0,
  "keywords": [
    "Apple",
    "Microsoft"
  ],
  "tags": [
    "NEWS"
  ],
  "minimum_rating": 0.4
}
'

shell

Example Request Body

{
  "query": "machine learning trends",
  "start_timestamp": null,
  "end_timestamp": null,
  "top_k": 10,
  "minimum_cosine_similarity": 0,
  "keywords": [
    "Apple",
    "Microsoft"
  ],
  "tags": [
    "NEWS"
  ],
  "minimum_rating": 0.4
}

json

Example Responses

[
  {
    "cosine_similarity": 0,
    "id": 0,
    "timestamp": 0,
    "document_id": 0,
    "tags": [
      "string"
    ],
    "title": "title",
    "content": "content",
    "named_entities": [
      "string"
    ],
    "rating": 0,
    "source": {
      "source_timestamp": 0,
      "source_table": "source_table",
      "source_id": 0,
      "source_metadata": {
        "url": "string",
        "title": "string",
        "publisher": "string"
      }
    }
  }
]

json

application/json

Semantic Search Multi

POST

https://api.ultralayer.ai

/v0/search/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.

Semantic Search Multi › Request Body

queries

string[] · minItems: 2 · maxItems: 50 · required

List of semantic search queries.

Example: ["Apple iPhone demand outlook","Apple services revenue growth","Apple CEO guidance"]

total_top_k

integer · min: 1 · max: 500

Best-effort target number of results to return after flattening and deduplication.

Default: 100

filter for results >= this integer unix timestamp.

Example: null

filter for results <= this integer unix timestamp.

Example: null

minimum_cosine_similarity

number · min: 0 · max: 1

filters results for cosine similarity >= this value.

Example: 0

Default: 0

List of exact match keywords. If provided, returns results containing at least one.

Example: ["Apple","Microsoft"]

List of tags to filter by. If provided, returns results containing all specified tags.

Example: ["NEWS"]

filters results for quality rating >= this value.

Example: 0

Default: 0.4

strategy

string · enum

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.

Enum values:

cosine_similarity

round_robin

rank_sum

Default: round_robin

Semantic Search Multi › Responses

Successful Response

object[]

cosine_similarity

number · required

Cosine similarity score between the query and the chunk embedding.

id

integer · required

Unique identifier for the chunk.

timestamp

integer · required

Unix timestamp of the source document.

document_id

integer · required

Identifier of the source document.

tags

string[] · required

List of tags associated with the chunk.

title

string · required

Title of the source document.

content

string · required

Content of the chunk.

named_entities

string[] · required

List of named entities extracted from the chunk.

rating

number · required

Quality rating of the chunk between 0.0 and 1.0.

object · required

Source information.

POST/v0/search/semantic_search_multi

curl --request POST \
  --url https://api.ultralayer.ai/v0/search/semantic_search_multi \
  --header 'Content-Type: application/json' \
  --data '
{
  "queries": [
    "Apple iPhone demand outlook",
    "Apple services revenue growth",
    "Apple CEO guidance"
  ],
  "total_top_k": 100,
  "start_timestamp": null,
  "end_timestamp": null,
  "minimum_cosine_similarity": 0,
  "keywords": [
    "Apple",
    "Microsoft"
  ],
  "tags": [
    "NEWS"
  ],
  "minimum_rating": 0.4,
  "strategy": "round_robin"
}
'

shell

Example Request Body

{
  "queries": [
    "Apple iPhone demand outlook",
    "Apple services revenue growth",
    "Apple CEO guidance"
  ],
  "total_top_k": 100,
  "start_timestamp": null,
  "end_timestamp": null,
  "minimum_cosine_similarity": 0,
  "keywords": [
    "Apple",
    "Microsoft"
  ],
  "tags": [
    "NEWS"
  ],
  "minimum_rating": 0.4,
  "strategy": "round_robin"
}

json

Example Responses

[
  {
    "cosine_similarity": 0,
    "id": 0,
    "timestamp": 0,
    "document_id": 0,
    "tags": [
      "string"
    ],
    "title": "title",
    "content": "content",
    "named_entities": [
      "string"
    ],
    "rating": 0,
    "source": {
      "source_timestamp": 0,
      "source_table": "source_table",
      "source_id": 0,
      "source_metadata": {
        "url": "string",
        "title": "string",
        "publisher": "string"
      }
    }
  }
]

json

application/json

Identify Stakeholders

POST

https://api.ultralayer.ai

/v0/search/identify_stakeholders

Identify key stakeholders relevant to a given query, with optional context and instructions to guide the identification process.

Identify Stakeholders › Request Body

query

string · required

The query / subject for which to identify stakeholders for.

Optional additional context to help identify stakeholders.

Optional additional instructions to guide stakeholder identification.

Optional start timestamp (unix epoch) to consider for time-sensitive queries.

Optional end timestamp (unix epoch) to consider for time-sensitive queries.

Identify Stakeholders › Responses

Successful Response

Response model for stakeholder identification

object[] · minItems: 0 · required

List of identified stakeholders with their impact details.

object[] · minItems: 0 · required

Factor matrix providing scoring for each stakeholder across defined factors.

POST/v0/search/identify_stakeholders

curl --request POST \
  --url https://api.ultralayer.ai/v0/search/identify_stakeholders \
  --header 'Content-Type: application/json' \
  --data '
{
  "query": "query",
  "context": "string",
  "instructions": "string",
  "start_timestamp": 0,
  "end_timestamp": 0
}
'

shell

Example Request Body

{
  "query": "query",
  "context": "string",
  "instructions": "string",
  "start_timestamp": 0,
  "end_timestamp": 0
}

json

Example Responses

{
  "stakeholder_impacts": [
    {
      "stakeholder": {
        "name": "name",
        "stakeholder_type": "PUBLIC_COMPANY",
        "symbol": "symbol"
      },
      "impact_score": 0,
      "confidence_score": 0,
      "rationale": "rationale",
      "sources_with_quotes": [
        {
          "source_timestamp": 0,
          "source_table": "source_table",
          "source_id": 0,
          "source_metadata": {
            "url": "string",
            "title": "string",
            "publisher": "string"
          },
          "quotes": [
            "string"
          ]
        }
      ]
    }
  ],
  "factor_matrix": [
    {
      "factor": {
        "name": "name",
        "description": "description",
        "factor_scale": "BINARY",
        "rubric": "rubric",
        "allowed_values": [
          "string"
        ]
      },
      "stakeholder_assessments": {
        "key": {
          "rationale": "rationale",
          "value": true,
          "sources": [
            {
              "source_timestamp": 0,
              "source_table": "source_table",
              "source_id": 0,
              "source_metadata": {
                "url": "string",
                "title": "string",
                "publisher": "string"
              }
            }
          ]
        }
      }
    }
  ]
}

json

application/json

Search Developments

POST

https://api.ultralayer.ai

/v0/search/search_developments

Search for developments semantically (or not). Various filters available: timestamp, development type, stakeholder impact, and more.

Search Developments › Request Body

Semantic search query. If None, retrieves all developments matching the filters.

Filter for results >= this integer unix timestamp. None means realtime mode.

Filter for results <= this integer unix timestamp. None means realtime mode.

Filter for occurrence_timestamp >= this integer unix timestamp. None means no limit.

Filter for occurrence_timestamp <= this integer unix timestamp. None means no limit.

Filter by development type.

Filter by stakeholder symbol.

Minimum impact score filter in [-1, 1]. If both min and max are provided, matching is directional OR (impact >= min OR impact <= max).

Maximum impact score filter in [-1, 1]. If both min and max are provided, matching is directional OR (impact >= min OR impact <= max).

Minimum importance score in [0, 1].

Minimum surprise score in [0, 1].

Minimum confidence score in [0, 1].

limit

integer · min: 1 · max: 200

Maximum number of results to return.

Default: 10

Search Developments › Responses

Successful Response

object[]

A development as returned from the database. Always represents the latest known version of the development at or before the requested end_timestamp.

development_id

integer · required

Logical identifier for the development across updates.

timestamp

integer · required

Canonical backtest system timestamp of this development version.

source_timestamp

integer · required

Most recent timestamp of any source used for the development.

occurrence_timestamp

integer · required

Actual (estimate of) real world time that the development took place.

occurrence_timestamp_confidence_score

number · required

Confidence score in estimate of occurrence_timestamp.

name

string · required

Name of the development.

description

string · required

Description of the development.

development_type

string · required

Type of the development.

occurrence_status

string · required

Status of the real world occurrence.

rationale

string · required

Explanation for all decisions made.

object[] · required

List of involved stakeholders and their impacts.

importance_score

number · required

LLM heuristic of general development importance.

surprise_score

number · required

LLM heuristic of how surprising the development is to the market.

confidence_score

number · required

LLM heuristic of its confidence in everything it presents.

object[] · required

List of events this development is associated with, resolved to their most recent known state.

object[] · required

List of sources used for this development.

POST/v0/search/search_developments

curl --request POST \
  --url https://api.ultralayer.ai/v0/search/search_developments \
  --header 'Content-Type: application/json' \
  --data '
{
  "query": "string",
  "start_timestamp": 0,
  "end_timestamp": 0,
  "start_occurrence_timestamp": 0,
  "end_occurrence_timestamp": 0,
  "development_type": "string",
  "stakeholder_symbol": "string",
  "min_impact_score": 0,
  "max_impact_score": 0,
  "min_importance_score": 0,
  "min_surprise_score": 0,
  "min_confidence_score": 0,
  "limit": 10
}
'

shell

Example Request Body

{
  "query": "string",
  "start_timestamp": 0,
  "end_timestamp": 0,
  "start_occurrence_timestamp": 0,
  "end_occurrence_timestamp": 0,
  "development_type": "string",
  "stakeholder_symbol": "string",
  "min_impact_score": 0,
  "max_impact_score": 0,
  "min_importance_score": 0,
  "min_surprise_score": 0,
  "min_confidence_score": 0,
  "limit": 10
}

json

Example Responses

[
  {
    "development_id": 0,
    "timestamp": 0,
    "source_timestamp": 0,
    "occurrence_timestamp": 0,
    "occurrence_timestamp_confidence_score": 0,
    "name": "name",
    "description": "description",
    "development_type": "development_type",
    "occurrence_status": "occurrence_status",
    "rationale": "rationale",
    "stakeholders": [
      {
        "stakeholder": {
          "name": "name",
          "stakeholder_type": "PUBLIC_COMPANY",
          "symbol": "symbol"
        },
        "impact_score": 0,
        "confidence_score": 0,
        "rationale": "rationale",
        "sources_with_quotes": [
          {
            "source_timestamp": 0,
            "source_table": "source_table",
            "source_id": 0,
            "source_metadata": {
              "url": "string",
              "title": "string",
              "publisher": "string"
            },
            "quotes": [
              "string"
            ]
          }
        ]
      }
    ],
    "importance_score": 0,
    "surprise_score": 0,
    "confidence_score": 0,
    "events": [
      {
        "event_id": 0,
        "name": "name",
        "description": "description",
        "event_type": "event_type"
      }
    ],
    "sources": [
      {
        "source_timestamp": 0,
        "source_table": "source_table",
        "source_id": 0,
        "source_metadata": {
          "url": "string",
          "title": "string",
          "publisher": "string"
        },
        "quotes": [
          "string"
        ]
      }
    ]
  }
]

json

application/json

Retrieve Development

POST

https://api.ultralayer.ai

/v0/search/retrieve_development

Retrieve a specific development by its ID.

Retrieve Development › Request Body

development_id

integer · required

The ID of the development to retrieve.

Filter for results <= this integer unix timestamp. None means realtime mode.

Retrieve Development › Responses

Successful Response

anyOf

At least one variant must match. Multiple variants may match simultaneously.

Decision Table

Variant	Matching Criteria
	type = object · requires: development_id, timestamp, source_timestamp +13 more
	type = null

Properties for DevelopmentFromDB:

A development as returned from the database. Always represents the latest known version of the development at or before the requested end_timestamp.

development_id

integer · required

Logical identifier for the development across updates.

timestamp

integer · required

Canonical backtest system timestamp of this development version.

source_timestamp

integer · required

Most recent timestamp of any source used for the development.

occurrence_timestamp

integer · required

Actual (estimate of) real world time that the development took place.

occurrence_timestamp_confidence_score

number · required

Confidence score in estimate of occurrence_timestamp.

name

string · required

Name of the development.

description

string · required

Description of the development.

development_type

string · required

Type of the development.

occurrence_status

string · required

Status of the real world occurrence.

rationale

string · required

Explanation for all decisions made.

object[] · required

List of involved stakeholders and their impacts.

importance_score

number · required

LLM heuristic of general development importance.

surprise_score

number · required

LLM heuristic of how surprising the development is to the market.

confidence_score

number · required

LLM heuristic of its confidence in everything it presents.

object[] · required

List of events this development is associated with, resolved to their most recent known state.

object[] · required

List of sources used for this development.

POST/v0/search/retrieve_development

curl --request POST \
  --url https://api.ultralayer.ai/v0/search/retrieve_development \
  --header 'Content-Type: application/json' \
  --data '
{
  "development_id": 0,
  "end_timestamp": 0
}
'

shell

Example Request Body

{
  "development_id": 0,
  "end_timestamp": 0
}

json

Example Responses

{
  "development_id": 0,
  "timestamp": 0,
  "source_timestamp": 0,
  "occurrence_timestamp": 0,
  "occurrence_timestamp_confidence_score": 0,
  "name": "name",
  "description": "description",
  "development_type": "development_type",
  "occurrence_status": "occurrence_status",
  "rationale": "rationale",
  "stakeholders": [
    {
      "stakeholder": {
        "name": "name",
        "stakeholder_type": "PUBLIC_COMPANY",
        "symbol": "symbol"
      },
      "impact_score": 0,
      "confidence_score": 0,
      "rationale": "rationale",
      "sources_with_quotes": [
        {
          "source_timestamp": 0,
          "source_table": "source_table",
          "source_id": 0,
          "source_metadata": {
            "url": "string",
            "title": "string",
            "publisher": "string"
          },
          "quotes": [
            "string"
          ]
        }
      ]
    }
  ],
  "importance_score": 0,
  "surprise_score": 0,
  "confidence_score": 0,
  "events": [
    {
      "event_id": 0,
      "name": "name",
      "description": "description",
      "event_type": "event_type"
    }
  ],
  "sources": [
    {
      "source_timestamp": 0,
      "source_table": "source_table",
      "source_id": 0,
      "source_metadata": {
        "url": "string",
        "title": "string",
        "publisher": "string"
      },
      "quotes": [
        "string"
      ]
    }
  ]
}

json

application/json

Retrieve Event Developments

POST

https://api.ultralayer.ai

/v0/search/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.

Retrieve Event Developments › Request Body

Parameters for retrieving all developments associated with a known event_id. Primarily used to: poll for new developments on a tracked event, or gather background context for a development whose event_ids are already known.

event_id

integer · required

The event_id to retrieve developments for.

Filter developments with timestamp >= this unix timestamp. None means no lower bound.

Filter developments with timestamp <= this unix timestamp. None means realtime mode.

limit

integer · min: 1 · max: 100

Maximum number of developments to return, ordered by occurrence_timestamp descending.

Default: 20

include_future_developments

boolean

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

Retrieve Event Developments › Responses

Successful Response

anyOf

At least one variant must match. Multiple variants may match simultaneously.

Decision Table

Variant	Matching Criteria
	type = object · requires: event_id, name, description +2 more
	type = null

Properties for EventWithDevelopments:

Response model for retrieve_event_developments. Wraps full event details with its associated developments.

event_id

integer · required

Logical identifier for the event.

name

string · required

Name of the event.

description

string · required

Description of the event.

event_type

string · required

Type of the event.

object[] · required

Developments associated with this event, ordered by occurrence_timestamp descending (real-world timeline).

POST/v0/search/retrieve_event_developments

curl --request POST \
  --url https://api.ultralayer.ai/v0/search/retrieve_event_developments \
  --header 'Content-Type: application/json' \
  --data '
{
  "event_id": 0,
  "start_timestamp": 0,
  "end_timestamp": 0,
  "limit": 20,
  "include_future_developments": true
}
'

shell

Example Request Body

{
  "event_id": 0,
  "start_timestamp": 0,
  "end_timestamp": 0,
  "limit": 20,
  "include_future_developments": true
}

json

Example Responses

{
  "event_id": 0,
  "name": "name",
  "description": "description",
  "event_type": "event_type",
  "developments": [
    {
      "development_id": 0,
      "timestamp": 0,
      "source_timestamp": 0,
      "occurrence_timestamp": 0,
      "occurrence_timestamp_confidence_score": 0,
      "name": "name",
      "description": "description",
      "development_type": "development_type",
      "occurrence_status": "occurrence_status",
      "rationale": "rationale",
      "stakeholders": [
        {
          "stakeholder": {
            "name": "name",
            "stakeholder_type": "PUBLIC_COMPANY",
            "symbol": "symbol"
          },
          "impact_score": 0,
          "confidence_score": 0,
          "rationale": "rationale",
          "sources_with_quotes": [
            {
              "source_timestamp": 0,
              "source_table": "source_table",
              "source_id": 0,
              "source_metadata": {
                "url": "string",
                "title": "string",
                "publisher": "string"
              },
              "quotes": [
                "string"
              ]
            }
          ]
        }
      ],
      "importance_score": 0,
      "surprise_score": 0,
      "confidence_score": 0,
      "events": [
        {
          "event_id": 0,
          "name": "name",
          "description": "description",
          "event_type": "event_type"
        }
      ],
      "sources": [
        {
          "source_timestamp": 0,
          "source_table": "source_table",
          "source_id": 0,
          "source_metadata": {
            "url": "string",
            "title": "string",
            "publisher": "string"
          },
          "quotes": [
            "string"
          ]
        }
      ]
    }
  ]
}

json

application/json

Search Events

POST

https://api.ultralayer.ai

/v0/search/search_events

Search for events semantically (or not). Various filters available: timestamp, occurrence, event type and more.

Search Events › Request Body

Parameters for semantically searching events. When timestamps are provided, only events with development activity within that window are considered — ensuring the user sees events that are actually relevant to the time period.

Semantic search query over event descriptions. If None, returns events ordered by recency of event creation.

Filter for events with development activity >= this unix timestamp.

Filter for events with development activity <= this unix timestamp. None means realtime mode.

Filter by event type.

limit

integer · min: 1 · max: 50

Maximum number of events to return.

Default: 10

developments_per_event

integer · min: 0 · max: 10

Number of most recent developments to embed per event result, ordered by occurrence_timestamp descending.

Default: 3

include_future_developments

boolean

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

Search Events › Responses

Successful Response

object[]

Response model for search_events. Each event includes a condensed list of its most recent developments for quick scanning. Full developments can be retrieved via retrieve_event_developments.

event_id

integer · required

Logical identifier for the event.

name

string · required

Name of the event.

description

string · required

Description of the event.

event_type

string · required

Type of the event.

object[] · required

Most recent developments for this event (count controlled by developments_per_event param), ordered by occurrence_timestamp descending.

POST/v0/search/search_events

curl --request POST \
  --url https://api.ultralayer.ai/v0/search/search_events \
  --header 'Content-Type: application/json' \
  --data '
{
  "query": "string",
  "start_timestamp": 0,
  "end_timestamp": 0,
  "event_type": "string",
  "limit": 10,
  "developments_per_event": 3,
  "include_future_developments": true
}
'

shell

Example Request Body

{
  "query": "string",
  "start_timestamp": 0,
  "end_timestamp": 0,
  "event_type": "string",
  "limit": 10,
  "developments_per_event": 3,
  "include_future_developments": true
}

json

Example Responses

[
  {
    "event_id": 0,
    "name": "name",
    "description": "description",
    "event_type": "event_type",
    "recent_developments": [
      {
        "development_id": 0,
        "timestamp": 0,
        "occurrence_timestamp": 0,
        "occurrence_timestamp_confidence_score": 0,
        "name": "name",
        "description": "description",
        "development_type": "development_type",
        "occurrence_status": "occurrence_status",
        "importance_score": 0,
        "surprise_score": 0,
        "confidence_score": 0,
        "event_ids": [
          0
        ]
      }
    ]
  }
]

json

application/json

Webhook