Schemas | Ultralayer Docs

AlertAttempt

Cheap, always-written record of one execution: 'we ran the alert and this is what happened'. Carries no payload and no per-receiver results (those live only on deliveries).

end_timestamp

string · date-time · required

End of the query window used (== the start the next run dedups against).

execution_finished_at

string · date-time · required

When this execution finished.

outcome

string · enum · required

Terminal state of this execution.

Enum values:

no_data

below_threshold

endpoint_error

delivered

delivery_partial

delivery_failed

item_count

integer · required

Items found in the window (0 on no_data / endpoint_error).

AlertDelivery

Record of an execution that delivered to at least one receiver. Includes the payload that was sent.

end_timestamp

string · date-time · required

End of the query window used.

delivered_at

string · date-time · required

Latest successful per-receiver delivery time.

object · required

The envelope that was delivered ({name, response}).

object[] · required

Per-receiver delivery outcomes.

AlertId

alert_id

integer · required

AlertInstructions

path

string · enum · required

Endpoint the alert polls.

Enum values:

/v0/search/list_wire

/v0/search/semantic_search

/v0/search/search_developments

/v0/search/retrieve_event_developments

/v0/search/search_events

/v0/filings/list_guidance

/v0/filings/list_changes

/v0/filings/list_guidance_outcomes

Example: /v0/search/list_wire

object · required

Endpoint arguments, dont provide system timestamps.

Example: {"entities":["Apple Inc."],"max_entity_sentiment":-0.3,"min_entity_sentiment":0.3,"novelty":["new","update","correction"]}

interval_minutes

integer · min: 5 · required

Poll interval; multiple of 5.

Example: 15

array · minItems: 1 · maxItems: 2 · required

1-2 unique targets.

Unique label; auto-generated if omitted

Example: apple_wire_sentiment

Defaults to interval_minutes

threshold

integer · min: 1

Items required to fire.

Default: 1

AlertRecord

alert_id

integer · required

Unique identifier for the alert.

name

string · required

Human label for the alert.

status

string · enum · required

Current status of the alert.

Enum values:

active

paused

path

string · enum · required

The endpoint the alert polls.

Enum values:

/v0/search/list_wire

/v0/search/semantic_search

/v0/search/search_developments

/v0/search/retrieve_event_developments

/v0/search/search_events

/v0/filings/list_guidance

/v0/filings/list_changes

/v0/filings/list_guidance_outcomes

object · required

The endpoint arguments.

interval_minutes

integer · required

How often the alert checks the endpoint, in minutes.

lookback_minutes

integer · required

Rolling lookback window, in minutes.

threshold

integer · required

Minimum item count before the alert fires.

array · required

The configured delivery targets.

required

end_timestamp of the last successful delivery, or null.

object[] · required

Recent execution attempts (no payload).

object[] · required

Recent deliveries (includes payload).

created_at

string · date-time · required

When the alert was created.

ChangeListParams

System timestamp; Inclusive ISO 8601

System timestamp; Inclusive ISO 8601; null=realtime

limit

integer · min: 1 · max: 100

Default: 10

Match any.

Example: ["NVDA","AAPL"]

Match any.

min_materiality_score

number · min: 0 · max: 1

0-.2 reword; .2-.4 weak; .4-.6 mod; .6-.8 high; .8-1 must-read

Default: 0.4

sort

string · enum

timestamp: newest first; materiality: highest materiality_score first.

Enum values:

timestamp

materiality

Default: timestamp

detail

string · enum

essential:finding; standard:citable; full:all.

Enum values:

full

standard

essential

Default: full

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

string · date-time · required

Canonical backtest system timestamp of this development version.

source_timestamp

string · date-time · required

Most recent timestamp of any source used for the development.

occurrence_timestamp

string · date-time · 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.

DevelopmentSearchParams

System timestamp; Inclusive ISO 8601

System timestamp; Inclusive ISO 8601; null=realtime

Real-world occurrence timestamp; Inclusive ISO 8601

Match any.

Example: ["NVDA","AAPL"]

+-.5+ strong; 0..+-.5 weak; 0 neutral; both: >=min OR <=max

0-.2 noise; .2-.4 minor; .4-.6 expected/mod; .6-.8 material; .8-1 critical

0-.2 known; .2-.4 expected; .4-.6 modest; .6-.8 notable; .8-1 shock

<.2 unreliable; .4-.6 incomplete; .6+ strong; .8+ explicit

limit

integer · min: 1 · max: 20

Default: 5

detail

string · enum

essential:minimal; standard:scored+citable; full:all.

Enum values:

full

standard

essential

Default: full

DevelopmentSummary

Lightweight development summary embedded within an EventFromDB response. Omits heavy fields (rationale, stakeholders, sources) that are not strictly needed to understand what a development is in the context of scanning events.

development_id

integer · required

Logical identifier for the development across updates.

timestamp

string · date-time · required

Canonical backtest system timestamp of this development version.

occurrence_timestamp

string · date-time · 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.

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.

event_ids

integer[] · required

Raw list of event IDs this development is associated with.

DisclosureChange

One evidenced qualitative change between consecutive earnings releases.

symbol

string · required

Listing symbol of the filer.

required

Filer name.

required

SEC CIK of the filer.

timestamp

string · date-time · required

System timestamp of this change.

source_timestamp

string · date-time · required

When the current release became public.

fiscal_year

integer · required

Filer fiscal year of the current release's completed period.

required

Filer fiscal quarter of the current release; null for a full-year report.

prior_fiscal_year

integer · required

Filer fiscal year of the prior release's completed period.

required

Filer fiscal quarter of the prior release; null for a full-year report.

change_kind

string · enum · required

added, removed, or modified.

Enum values:

added

removed

modified

change_category

string · required

Kind of disclosure that changed.

summary

string · required

One sentence stating what changed.

required

Evidencing sentence in the current release. Null on a removal.

required

Evidencing sentence in the prior release. Null on an addition.

materiality_score

number · required

0-.2 reword; .2-.4 weak; .4-.6 mod; .6-.8 high; .8-1 must-read

impact

string · enum · required

Which way the change moves a reader's view of the company.

Enum values:

positive

negative

neutral

object · required

Current release.

object · required

Prior release.

EmailReceiver

type

string · const · required

Const value: email

EntityCoMention

Entity frequently co-mentioned with the target on recent high-relevance wire items.

entity_id

integer · required

Entity id of the co-mentioned entity.

canonical_name

string · required

Entity name of the co-mentioned entity.

share

number · min: 0 · max: 1 · required

Fraction of the co-mention sample wire items that also mention this entity at primary or significant relevance.

EntityDataPackage

Realtime context package for one Ultralayer entity.

timestamp

string · date-time · required

Canonical system timestamp when this package was assembled.

object · required

Resolved entity identity.

object[] · required

Most recent non-duplicate wire items where this entity is primary or significant.

object[] · required

Calendar-day bars (oldest first). Empty days are null, not omitted.

object[] · required

Top co-mentioned entities from a bounded recent sample of primary/significant wire items.

EntityRecentWireItem

Recent wire item where this entity is primary or significant.

wire_id

integer · required

source_timestamp

string · date-time · required

headline

string · required

Wire headline.

novelty

string · enum · required

Novelty label.

Enum values:

new

update

correction

relevance

string · enum · required

Entity relevance.

Enum values:

primary

significant

EntitySentimentBar

One UTC calendar-day bar of relevance-weighted entity sentiment.

end_timestamp

string · date-time · required

Exclusive end of this UTC calendar-day bar.

required

Relevance-weighted average sentiment in [-1, 1] for the day. Null when there were no observations.

required

Relevance-weighted standard deviation of sentiment for the day. Null when there were no observations.

mention_count

integer · min: 0 · required

Number of wire items contributing to this bar.

EntitySummary

Resolved entity identity.

entity_id

integer · required

Root entity id.

canonical_name

string · required

Root entity name.

required

EventFromDB

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.

EventSearchParams

System timestamp; Inclusive ISO 8601

System timestamp; Inclusive ISO 8601; null=realtime

Match any.

Example: ["NVDA","AAPL"]

limit

integer · min: 1 · max: 10

Default: 5

developments_per_event

integer · min: 0 · max: 5

Default: 3

include_future_developments

boolean

Include future occurrence times relative to end_timestamp or now.

Default: true

detail

string · enum

essential:minimal; full:all.

Enum values:

full

essential

Default: full

EventSummary

Lightweight event summary embedded within a DevelopmentFromDB response. Provides enough context for the user to understand what event a development belongs to without requiring a separate event lookup.

event_id

integer · required

Logical identifier for the event across updates.

name

string · required

Name of the event.

description

string · required

Description of the event.

event_type

string · required

Type of the event.

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).

Factor

Dimension for differentiating stakeholders as they relate to the situation

name

string · required

Unique snake_case mechanism label. Compressed so it is decision-useful alone; reusable across similar situations.

description

string · required

Self-contained definition of what the factor represents.

factor_scale

string · enum · required

Scale of factor.

Enum values:

BINARY

CATEGORICAL

CONTINUOUS

SIGNED_CONTINUOUS

rubric

string · required

Short operational scoring rubric with observable criteria to ensure global consistency when reused.

Only for CATEGORICAL: enum of allowed category strings.

FactorAssessment

Factor assessment information with relevant sources

rationale

string · required

Self-contained brief explanation of the assessment for this stakeholder on this factor.

required

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.

object[] · minItems: 1 · required

List of sources (with exact quotes) that support this factor assessment.

FactorMatrixRow

A row in the factor matrix, containing assessments for the stakeholders this factor applies to.

object · required

Factor definition.

object · required

Map: stakeholder symbol -> assessment object for this factor.

FeedsSourceMetadata

source_metadata for rows where source_table == "feeds". RSS headline rows. publisher is the internal feed/publisher key (nullable when unknown).

title

string · required

Feed entry title.

required

Internal publisher/feed key when known.

FilingDocumentSourceMetadata

source_metadata for rows where source_table == "fi_documents". No title column on fi_documents — do not invent one. document_class is not here: it is already GuidanceValue.source_type. fiscal_year / fiscal_quarter are the document's completed report period, not the guided period on the series — a Q2 release guiding FY revenue has Q2 here and FY on the series. Filing: fi_filings (nullable on a guidance update or an annual quarter). Call: fi_earnings_calls (always both; Q4 is 4). url lives on Source, not here: filing exhibits keep the document url; transcripts have none and Source mints a capability URL (ultralayer_python.source_url).

symbol

string · required

Listing symbol of the filer.

required

Filer fiscal year of the completed period this document reports, when it reports one.

required

Filer fiscal quarter of that completed period; null for a full-year report or a document that reports no completed period.

document_type

string · required

Source-native document label, e.g. EX-99.1 or transcript.

GuidanceBias

Aggregate score of company guidance versus reported actuals for one report period.

symbol

string · required

Listing symbol of the filer.

required

Filer name.

required

SEC CIK of the filer.

timestamp

string · date-time · required

System timestamp of the latest actual in this period.

source_timestamp

string · date-time · required

When the latest actual in this period became public.

fiscal_year

integer · required

Filer fiscal year of the report that printed the actual.

required

Filer fiscal quarter of that report; null for a full-year report.

bias_score

number · required

Mean of mapped labels: significantly_exceeded=2, exceeded=1, in_line=0, missed=-1, significantly_missed=-2.

resolved_count

integer · required

Resolved outcomes in the mean.

object · required

Resolved label counts in the mean.

GuidanceBiasParams

symbol

string · required

Listing symbol of the filer.

System timestamp; Inclusive ISO 8601

System timestamp; Inclusive ISO 8601; null=realtime

GuidanceListParams

System timestamp; Inclusive ISO 8601

System timestamp; Inclusive ISO 8601; null=realtime

limit

integer · min: 1 · max: 100

Default: 10

Match any.

Example: ["NVDA","AAPL"]

Match any.

Example: ["revenue"]

metric_key_exact_match

boolean

true: exact metric_keys, case-insensitive; false: case-insensitive substring. Ignored without metric_keys.

Default: false

Match any.

Match any. 'null' is consolidated.

Example: ["null"]

Match any.

Inclusive guided period-end date.

Match any. Document class the observation was read from.

Example: ["earnings_release"]

Match any; latest observation only.

sort

string · enum

timestamp: recently updated; guided_period_end: period date; comparable: strongest like-for-like number in the match set; revision_delta: largest midpoint move.

Enum values:

timestamp

guided_period_end

comparable

revision_delta

Default: timestamp

values_mode

string · enum

all: revision history, newest first; latest: newest observation only.

Enum values:

all

latest

Default: all

detail

string · enum

essential:quotes; standard:citable; full:all.

Enum values:

full

standard

essential

Default: full

GuidanceOutcome

Company guidance versus the reported actual.

symbol

string · required

Listing symbol of the filer.

required

Filer name.

required

SEC CIK of the filer.

timestamp

string · date-time · required

System timestamp of the outcome.

source_timestamp

string · date-time · required

When the actual became public.

metric_key

string · required

Normalized metric identity.

metric_basis

string · enum · required

gaap, non_gaap, or unspecified.

Enum values:

gaap

non_gaap

unspecified

required

Segment cut; null for consolidated guidance.

guided_period_type

string · enum · required

Kind of period being guided.

Enum values:

quarter

fiscal_year

half

multi_year

other

guided_fiscal_year

integer · required

Filer fiscal year of the guided period.

required

Filer fiscal quarter of the guided period; null for a full year.

required

Calendar day the guided period ends.

guidance_source_type

string · required

Document class the scored guide was issued from.

actual_source_type

string · required

Document class the actual was reported in.

outcome

string · enum · required

Judgment of the actual against the guide.

Enum values:

significantly_exceeded

exceeded

in_line

missed

significantly_missed

indeterminate

rationale

string · required

Why this outcome label.

guidance_quote

string · required

Stating sentence of the scored guide.

actual_quote

string · required

Sentence or table row the actual was read from.

value_type

string · enum · required

Shape of the stated guide.

Enum values:

range

point

floor

ceiling

approximate

qualitative

value_form

string · enum · required

absolute is a level; relative is a change vs a temporal base.

Enum values:

absolute

relative

required

Lower bound of the scored guide as stated.

required

Upper bound of the scored guide as stated.

required

Midpoint of the scored guide as stated.

unit

string · enum · required

Unit of the stated guide.

Enum values:

currency

percent

basis_points

ratio

shares

count

other

required

ISO currency code when unit is currency.

required

Reported actual, scaled.

required

Unit of the reported actual.

comparability

string · enum · required

Whether the actual can be scored against the guide.

Enum values:

comparable

not_comparable

required

Actual minus guide midpoint, in the comparison unit.

required

Actual vs midpoint as a percent of the midpoint; 5.0 means 5% above.

required

Actual minus guide low bound.

required

Actual minus guide high bound.

object · required

Document the scored guide was issued from.

object · required

Document the actual was reported in.

GuidanceOutcomeListParams

Request body for POST /v0/filings/list_guidance_outcomes.

System timestamp; Inclusive ISO 8601

System timestamp; Inclusive ISO 8601; null=realtime

limit

integer · min: 1 · max: 100

Default: 10

Match any.

Example: ["NVDA","AAPL"]

Match any.

Example: ["revenue"]

metric_key_exact_match

boolean

true: exact metric_keys, case-insensitive; false: case-insensitive substring. Ignored without metric_keys.

Default: false

Match any.

Match any. 'null' is consolidated.

Example: ["null"]

Match any.

Inclusive guided period-end date.

detail

string · enum

essential:identity; standard:citable; full:all.

Enum values:

full

standard

essential

Default: full

Match any. Omit: resolved labels only.

sort

string · enum

timestamp: newest actual first; outcome_abs: largest |score| first.

Enum values:

timestamp

outcome_abs

Default: timestamp

GuidanceSeries

One guided metric for one filer for one guided period, with its observation history.

symbol

string · required

Listing symbol of the filer.

required

Filer name.

required

SEC CIK of the filer.

metric_key

string · required

Normalized metric identity.

metric_basis

string · enum · required

gaap, non_gaap, or unspecified.

Enum values:

gaap

non_gaap

unspecified

required

Segment cut; null for consolidated guidance.

guided_period_type

string · enum · required

Kind of period being guided.

Enum values:

quarter

fiscal_year

half

multi_year

other

guided_fiscal_year

integer · required

Filer fiscal year of the guided period.

required

Filer fiscal quarter of the guided period; null for a full year.

required

Calendar day the guided period ends.

observation_count

integer · required

Observations in this series as of the request end timestamp.

object[] · required

Point-in-time observations, newest first.

GuidanceValue

One point-in-time observation of a guidance series.

quote

string · required

Stating sentence from the source document.

timestamp

string · date-time · required

System timestamp of this observation.

source_type

string · required

Document class this observation was read from.

guidance_nature

string · enum · required

explicit if stated directly; implied_in_text if inferred from wording.

Enum values:

explicit

implied_in_text

value_type

string · enum · required

Shape of the stated value.

Enum values:

range

point

floor

ceiling

approximate

qualitative

value_form

string · enum · required

absolute is a level; relative is a change vs a temporal base.

Enum values:

absolute

relative

required

Lower bound as stated. Equal to value_high for a point.

required

Upper bound as stated.

required

Midpoint of the stated bounds. For a floor or ceiling, the stated bound.

unit

string · enum · required

Unit of the stated value.

Enum values:

currency

percent

basis_points

ratio

shares

count

other

required

ISO currency code when unit is currency.

required

Stated wording when value_type is qualitative.

required

Year-over-year change, lower bound.

required

Year-over-year change, upper bound.

required

Year-over-year change, midpoint. For a floor or ceiling, the stated YoY bound.

required

percent or basis_points.

required

Fiscal year of the prior-year actual used for the year-over-year change.

required

Fiscal quarter of that prior-year actual; null for a full-year guide.

required

Prior-year actual level used to compute the year-over-year change.

required

Direction of the midpoint vs the prior observation.

required

How the stated range changed vs the prior observation.

required

New midpoint minus prior midpoint, in the stated unit.

required

Midpoint change as a percent of the absolute prior midpoint; 5.0 means raised 5%. Positive is an increase.

object · required

Document this observation was read from.

HTTPValidationError

object[]

MarketBar

One bucket of wire activity for a market scope value.

bar

string · date-time · required

Exclusive bucket end.

count

integer · required

Wire items about the scope value.

sentiment

number · required

Net sum of entity mention sentiments (-1..1 each); 0 when empty or no mentions.

required

Dispersion (population std) of those mention sentiments; null when no mentions.

partial

boolean

True on the in-progress bucket.

Default: false

MarketSignalParams

value

string · required

One sector, country (ISO 3166-1 alpha-2, lowercase), or asset class.

System timestamp; Inclusive ISO 8601; omitted=last 14 bars; max 60d

System timestamp; Inclusive ISO 8601; null=realtime

resolution

string · pattern: ^([1-9]|[12][0-9]|30…

Bucket length in UTC days; 1d-30d.

Default: 1d

novelty

string[] · minItems: 1 · maxItems: 4

Match any.

Enum values:

new

update

duplicate

correction

Default: ["new","update","duplicate","correction"]

MarketSignalResponse

Contiguous market bar series.

signal

string · required

Signal family.

methodology_version

integer · required

Bumped when the signal definition changes.

resolution

string · required

Bucket length used.

object[] · required

Oldest first; empty buckets included.

NewsSourceMetadata

source_metadata for rows where source_table == "news". News always has these two, so they are required (non-nullable). Do NOT widen this model for other sources; define a sibling model and register it in SOURCE_METADATA_BY_TABLE instead.

title

string · required

Title of the news article.

publisher

string · required

Publisher of the news article.

PublisherSourceMetadataFilter

key

string · const

Const value: publisher

Default: publisher

ReceiverResult

Outcome of delivering one envelope to one receiver. Embedded in a delivery record so partial failures (e.g. webhook ok, telegram down) stay visible.

type

string · enum · required

The receiver channel.

Enum values:

webhook

email

target

string · required

Where it was delivered (webhook url, telegram chat id, or account email).

status

string · enum · required

Whether delivery to this receiver succeeded.

Enum values:

success

failed

When this receiver was successfully delivered to, or null on failure.

Failure reason, or null on success.

RetrieveDevelopmentParams

development_id

integer · required

System timestamp; Inclusive ISO 8601; null=realtime

detail

string · enum

essential:minimal; standard:scored+citable; full:all.

Enum values:

full

standard

essential

Default: full

RetrieveEntityParams

entity

string · minLength: 1 · maxLength: 200 · required

Entity name

Example: Apple Inc.

RetrieveEventDevelopmentsParams

event_id

integer · required

System timestamp; Inclusive ISO 8601

System timestamp; Inclusive ISO 8601; null=realtime

limit

integer · min: 1 · max: 20

Default: 5

include_future_developments

boolean

Include future occurrence times relative to end_timestamp or now.

Default: true

detail

string · enum

essential:minimal; standard:scored+citable; full:all.

Enum values:

full

standard

essential

Default: full

SemanticSearchParams

queries

string[] · minItems: 1 · maxItems: 8 · required

max_tokens

integer · min: 1000 · max: 50000

Snippet token budget

Default: 2000

System timestamp; Inclusive ISO 8601

Default: 2026-01-01T00:00:00Z

System timestamp; Inclusive ISO 8601; null=realtime

Exact metadata include/exclude filters.

Match any.

0-.2 noise; .2-.4 low; .4-.6 mod; .6-.8 high; .8-1 critical

Default: 0.4

-1..1; +-.2 neutral; +-.2-.6 mod; +-.6+ strong; mutually exclusive with max_sentiment_score

detail

string · enum

essential:minimal; standard:citable; full:all.

Enum values:

full

standard

essential

Default: full

SemanticSearchResult

One document of semantic-search context. Chunks that share a document_id are grouped into parallel snippet arrays so the caller sees ordered passages from the same document without paying for a nested object key on every snippet. snippet_cosine_similarities[i] always describes snippets[i]. Result order is by each document's best snippet similarity (desc); there is no separate top-level cosine_similarity field because that value is exactly max(snippet_cosine_similarities).

timestamp

string · date-time · required

System imestamp of the document.

document_id

integer · required

Identifier of the indexed document.

required

Title of the source document, if available.

snippets

string[] · minItems: 1 · required

Passage texts from this document, ordered as they appear in the document.

snippet_cosine_similarities

number[] · minItems: 1 · required

Cosine similarity of each snippet to the query. Same length and order as snippets.

o200k_base_n_tokens

integer · min: 1 · required

o200k_base token count of the returned snippets.

canonical_entity_names

string[] · required

Canonical entity names across the returned snippets.

utility_score

number · required

Token-weighted utility score of the returned snippets, between 0.0 and 1.0.

sentiment_score

number · required

Token-weighted sentiment score of the returned snippets, between -1.0 and 1.0.

object · required

Source information.

SiFactorAssessmentSourceMetadata

source_metadata for rows where source_table == "si_factor_assessments". Lightweight identifiers only; full assessment content is retrieved via source_id. Assessments are first-party and have no public root URL; Source.coerce_source_metadata_and_url always mints /source/si_factor_assessments/{id}/{key} onto Source.url.

factor_name

string · required

Factor name from the historical assessment.

stakeholder_symbol

string · required

Stakeholder ticker from the historical assessment.

SiStakeholderImpactSourceMetadata

source_metadata for rows where source_table == "si_stakeholder_impacts". Lightweight identifiers only; full impact content (rationale, scores) is retrieved via source_id. Impacts are first-party and have no public root URL; Source.coerce_source_metadata_and_url always mints /source/si_stakeholder_impacts/{id}/{key} onto Source.url.

stakeholder_symbol

string · required

Stakeholder ticker from the historical impact.

stakeholder_name

string · required

Stakeholder name from the historical impact.

Source

Full source information to be returned to end user.

source_timestamp

string · date-time · required

Timestamp of the source item.

source_table

string · enum · required

Table (Type) of the source item.

Enum values:

news

x_news

youtube

feeds

x_posts

tradingview_news

telegram_messages

web

source_id

integer · required

'id' of the source item

url

string · minLength: 1 · required

Link to the source item. External sources link to the original page; first-party and synthesis sources link to their Ultralayer source page.

required

Per-source metadata.

SourceWithQuotes

Source information with relevant quotes

source_timestamp

string · date-time · required

Timestamp of the source item.

source_table

string · enum · required

Table (Type) of the source item.

Enum values:

news

x_news

youtube

feeds

x_posts

tradingview_news

telegram_messages

web

source_id

integer · required

'id' of the source item

url

string · minLength: 1 · required

Link to the source item. External sources link to the original page; first-party and synthesis sources link to their Ultralayer source page.

required

Per-source metadata.

quotes

string[] · minItems: 1 · required

List of EXACT quotes from the source material.

StakeholderBase

Stakeholder information

name

string · required

Name of the stakeholder

stakeholder_type

string · const · required

The type of stakeholder. ONLY the following are allowed: [PUBLIC_COMPANY].

Const value: PUBLIC_COMPANY

symbol

string · required

Ticker symbol of the stakeholder

StakeholderIdentificationParams

query

string · maxLength: 2000 · required

Additional context

Additional guidance

As-of system timestamp; inclusive ISO 8601; null=realtime

detail

string · enum

essential:minimal; standard:scored+citable; full:all.

Enum values:

full

standard

essential

Default: full

StakeholderIdentificationResponse

Response model for stakeholder identification

object[] · minItems: 0 · required

List of identified stakeholders with their impact details.

object[] · minItems: 0 · required

Comparison dimensions for stakeholders relating to the situation.

StakeholderImpact

Stakeholder impact information with relevant sources

object · required

The stakeholder being identified.

impact_score

number · min: -1 · max: 1 · required

+-.5+ strong; 0..+-.5 weak; 0 neutral

confidence_score

number · min: 0 · max: 1 · required

0-.25 low; .25-.5 med; .5-.75 high; .75-1 very high

rationale

string · required

Self-contained brief explanation of why this stakeholder is relevant to the query.

object[] · minItems: 1 · required

List of sources (with quotes) that support the identification of this stakeholder.

TelegramMessagesSourceMetadata

source_metadata for rows where source_table == "telegram_messages". Channel posts have no title column — only channel→publisher taxonomy.

required

Channel→publisher taxonomy when known.

TelegramReceiver

type

string · const · required

Const value: telegram

chat_id

string · required

Chat ID; start the alerts bot first.

TradingviewSourceMetadata

source_metadata for rows where source_table == "tradingview_news". TradingView stories always have a title; publisher is the normalized provider id.

title

string · required

TradingView story title.

required

Normalized provider id when known.

ValidationError

array · required

msg

string · required

type

string · required

input

ctx

object

WebSourceMetadata

source_metadata for rows where source_table == "web".

title

string · required

Title of the web record.

record_type

string · required

Kind of web record (e.g. exa_search, azure_grounded).

WebhookReceiver

type

string · const · required

Const value: webhook

url

string · maxLength: 2048 · required

POST headers.

Place the alert envelope under this body key. Dot-separated for one level of nesting (e.g. variables.PAYLOAD).

body_wrap_as_string

boolean

JSON-encode the envelope to a string before placing it under body_wrap_key. Requires body_wrap_key.

Default: false

Static keys merged into the top level of the body. String, number, boolean or null values only.

WireAbout

Market-level scope dimensions for a wire item. May be inferred, not only explicitly named.

sectors

string[]

GICS-style sectors this item is about.

Enum values:

communication_services

consumer_discretionary

consumer_staples

energy

financials

health_care

industrials

information_technology

industries

string[]

Free-form industry labels this item is about.

countries

string[]

Lowercase country codes this item is about.

asset_classes

string[]

Asset classes this item is about.

Enum values:

equities

fixed_income

currencies

commodities

crypto

real_estate

WireEntityDetail

One grounded entity on a wire item, with per-entity relevance and sentiment.

entity_id

integer · required

Stable Ultralayer entity id.

canonical_name

string · required

Canonical entity name.

entity_type

string · required

Entity type label (e.g. COMPANY, PERSON).

relevance

string · enum · required

How central the entity is to the item.

Enum values:

primary

significant

contextual

incidental

sentiment

number · min: -1 · max: 1 · required

-1..1 directional market implication of this item for this entity.

identifiers

string[]

Document-grounded lexical references to this entity in the item text.

WireItem

A wire item.

wire_id

integer · required

Primary key of the wire row.

timestamp

string · date-time · required

Canonical system time when this item was put on the wire.

source_timestamp

string · date-time · required

Source last-update time.

headline

string · required

Ultralayer-generated headline.

required

Normalized publisher/source label, when known.

url

string · required

Link to the original item.

content_type

string · enum · required

Kind of item.

Enum values:

news

analysis

opinion

press_release

data_release

categories

string[] · required

Multi-label event/theme tags.

recency

string · enum · required

Whether the item is about now, the past, or the future.

Enum values:

realtime

report_of_past

report_of_future

source_relationship

string · enum · required

How close the source is to the information.

Enum values:

first_party

reporting

second_hand

factuality

string · enum · required

Epistemic status of the item's core claim.

Enum values:

confirmed

reported

rumor

speculation

forecast

novelty

string · enum · required

Story-lifecycle label relative to prior wire items.

Enum values:

new

update

duplicate

correction

required

Matched earlier wire item for update|duplicate|correction; null for new.

trustworthiness_score

number · min: 0 · max: 1 · required

0..1 source credibility score.

importance_score

number · min: 0 · max: 1 · required

0..1 market-importance score.

object · required

Market-level scope dimensions (sectors, industries, countries, asset_classes).

object[] · required

Grounded entities with per-entity relevance and sentiment.

WireListParams

System timestamp; Inclusive ISO 8601

System timestamp; Inclusive ISO 8601; null=realtime

max_records

integer · min: 1 · max: 100

Default: 20

Match any.

Example: ["earnings"]

Match any.

Example: ["Apple Inc.","TSLA"]

Match any.

+-.2 neutral; +-.2-.6 mod; +-.6+ strong; both: >=min OR <=max

Match any.

Example: ["automobiles"]

Match any; lowercase ISO 3166-1 alpha-2

Example: ["us"]

Match any.

Example: ["reuters"]

0-.2 noise; .2-.4 low; .4-.6 mod; .6-.8 high; .8-1 critical

<.2 anon; .4-.6 mod; .6+ reputable; .8+ official

detail

string · enum

essential:minimal; standard:citable; full:all.

Enum values:

full

standard

essential

Default: full

WireStoryline

Storyline cluster for a seed wire item: ancestor chain plus first-degree branches.

seed_wire_id

integer · required

The wire_id that was requested.

required

Wire id of the novelty root (prior_wire_id IS NULL) when the ancestor walk reached it; null when the walk stopped early (time window or depth cap).

object[] · required

Storyline members ordered by source_timestamp ascending.

WireStorylineParams

wire_id

integer · required

System timestamp; Inclusive ISO 8601

System timestamp; Inclusive ISO 8601; null=realtime

Match any.

Default: ["new","update","correction"]

max_ancestor_depth

integer · min: 1 · max: 64

Ancestor cap, including seed.

Default: 32

max_children

integer · min: 1 · max: 64

Branched children cap

Default: 32

detail

string · enum

essential:minimal; standard:citable; full:all.

Enum values:

full

standard

essential

Default: full

XNewsSourceMetadata

source_metadata for rows where source_table == "x_news". Only title: source_metadata is reserved for essential or genuinely filterable fields. x_id is encoded in Source.url; post_ids live in x_news.cluster_posts_results.

title

string · required

X story title.

XPostsSourceMetadata

source_metadata for rows where source_table == "x_posts". Raw first-party posts have no title column — only publisher taxonomy.

required

Publisher/rule-tag taxonomy when known.

YouTubeSourceMetadata

source_metadata for rows where source_table == "youtube". Fields chosen for search filtering and source presentation: publisher links related channels; video_type distinguishes VIDEO, SHORT, and PODCAST; channel_name is the internal stable channel identity from YT_CONFIG. video_type / channel_name are optional because wire-derived citations only carry title/publisher from WireItemInternal. The documents-indexing path still sets both.

title

string · required

YouTube video title.

required

Internal publisher key linking related channels, e.g. bloomberg.

VIDEO, SHORT, or PODCAST when known.

Internal stable channel identity from YT_CONFIG when known.