@yottagraph-app/aether-instructions 1.1.18 → 1.1.20

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -12,7 +12,7 @@ The schema defines the data model: what **entity types** (flavors) exist and wha
12
12
  ## Key Concepts
13
13
 
14
14
  - **Flavors** = Entity types. Each entity belongs to exactly one flavor.
15
- - Examples: "ship" (FID 1), "organization" (FID 10), "person" (FID 9)
15
+ - Examples: "organization" (FID 10), "person" (FID 9), "financial_instrument" (FID 3)
16
16
  - Identified by a Flavor ID (FID) — a small integer
17
17
  - **Properties** = Attributes that entities can have. Each property has:
18
18
  - A Property ID (PID) — a small integer
@@ -30,8 +30,8 @@ There are two schema endpoints with different levels of detail:
30
30
  | `GET /elemental/metadata/schema` | fid, name only | pid, name, type only |
31
31
 
32
32
  **Use `/schema`** (recommended) when you need:
33
- - Human-readable display names (e.g., "Ship" vs "ship")
34
- - Units of measurement (e.g., "m", "kg", "knots")
33
+ - Human-readable display names (e.g., "Organization" vs "organization")
34
+ - Units of measurement (e.g., "m", "kg")
35
35
  - Which flavors a property applies to (`domain_findexes`)
36
36
 
37
37
  **Use `/elemental/metadata/schema`** when you just need basic FID/PID to name mappings.
@@ -48,28 +48,6 @@ There are two schema endpoints with different levels of detail:
48
48
  2. **Find entities of a type** → `POST /elemental/find` with `is_type` expression
49
49
  3. **Get property values** → `POST /elemental/entities/properties` to fetch values for those entities
50
50
 
51
- ## Common Properties by Entity Type
52
-
53
- This is a quick-reference for writing first-pass code. **The schema endpoint
54
- is the source of truth** — always call `GET /schema` to get actual PIDs and
55
- confirm which properties exist in a given deployment. Property availability
56
- varies by dataset.
57
-
58
- | Entity Type | Common Properties |
59
- |---|---|
60
- | **organization** | `name`, `country`, `ticker`, `industry`, `business_sector`, `sic_code`, `state_of_incorporation`, `mailing_address`, `business_phone`, `company_cik` |
61
- | **person** | `name`, `country`, `nationality`, `birth_date`, `position`, `person_cik`, `job_title` |
62
- | **financial_instrument** | `name`, `ticker`, `security_type`, `instrument_type`, `cusip_number` |
63
- | **document** (SEC filings) | `name`, `title`, `form_type`, `filing_date`, `report_date`, `accession_number`, `form_type_detail` |
64
- | **article** | `name`, `title`, `sentiment` |
65
- | **event** | `name`, `category`, `date`, `description`, `likelihood` |
66
- | **location** | `name`, `fixedLatitude`, `fixedLongitude` |
67
-
68
- **Relationship properties** (type `data_nindex`) link entities to each other.
69
- Common ones for organizations: `acquires`, `owns`, `competes_with`,
70
- `partnered_with`, `does_business_with`, `is_part_of`, `issues`, `has_subsidiary`.
71
- For people: `works_at`, `head_of`, `is_director`, `is_officer`, `is_colleague_of`.
72
-
73
51
  <!-- BEGIN GENERATED CONTENT -->
74
52
 
75
53
  ## Endpoints
@@ -102,7 +80,7 @@ GET /schema
102
80
  **Response:**
103
81
 
104
82
  ```json
105
- {"flavors": [{"findex": 1, "name": "ship", "singular_display_name": "Ship", "plural_display_name": "Ships"}, {"findex": 10, "name": "organization", "singular_display_name": "Organization", "plural_display_name": "Organizations"}], "properties": [{"pid": 8, "name": "name", "display_name": "Name", "value_type": "data_cat"}, {"pid": 22, "name": "length", "display_name": "Length", "unit": "m", "value_type": "data_float"}]}
83
+ {"flavors": [{"findex": 9, "name": "person", "singular_display_name": "Person", "plural_display_name": "People"}, {"findex": 10, "name": "organization", "singular_display_name": "Organization", "plural_display_name": "Organizations"}], "properties": [{"pid": 8, "name": "name", "display_name": "Name", "value_type": "data_cat"}, {"pid": 15, "name": "industry", "display_name": "Industry", "value_type": "data_cat"}]}
106
84
  ```
107
85
 
108
86
  ---
@@ -210,7 +188,7 @@ Returns comprehensive schema information including all entity types (flavors), p
210
188
 
211
189
  #### Guidance
212
190
 
213
- Response is wrapped in a 'schema' container object. Access flavors and properties via response.schema.flavors and response.schema.properties. Flavors contain: fid (unique identifier), name (e.g., 'ship', 'aircraft'). Properties contain: pid (unique identifier), name (e.g., 'latitude', 'name'), type (e.g., 'data_float', 'data_int', 'data_cat', 'data_nindex').
191
+ Response is wrapped in a 'schema' container object. Access flavors and properties via response.schema.flavors and response.schema.properties. Flavors contain: fid (unique identifier), name (e.g., 'organization', 'person'). Properties contain: pid (unique identifier), name (e.g., 'name', 'industry'), type (e.g., 'data_float', 'data_int', 'data_cat', 'data_nindex').
214
192
 
215
193
  #### Responses
216
194
 
@@ -231,7 +209,7 @@ GET /elemental/metadata/schema
231
209
  **Response:**
232
210
 
233
211
  ```json
234
- {"op_id": "40dc4cd9-f1b2-4b5c-85d0-c7c61256e5d9", "follow_up": false, "schema": {"flavors": [{"fid": 1, "name": "ship"}, {"fid": 2, "name": "handset"}, {"fid": 10, "name": "organization"}], "properties": [{"pid": 1, "name": "mmsi", "type": "data_cat"}, {"pid": 8, "name": "name", "type": "data_cat"}]}}
212
+ {"op_id": "40dc4cd9-f1b2-4b5c-85d0-c7c61256e5d9", "follow_up": false, "schema": {"flavors": [{"fid": 9, "name": "person"}, {"fid": 10, "name": "organization"}, {"fid": 3, "name": "financial_instrument"}], "properties": [{"pid": 8, "name": "name", "type": "data_cat"}, {"pid": 15, "name": "industry", "type": "data_cat"}]}}
235
213
  ```
236
214
 
237
215
  ---
@@ -279,10 +257,11 @@ Entity type (flavor) with human-readable display names
279
257
 
280
258
  | Field | Type | Description |
281
259
  |-------|------|-------------|
260
+ | description | string | Semantic description of what this flavor represents |
282
261
  | findex | integer | Unique flavor identifier (same as fid in other endpoints) |
283
262
  | name | string | Flavor name (internal identifier) |
284
- | plural_display_name | string | Human-readable plural name (e.g., "Ships") |
285
- | singular_display_name | string | Human-readable singular name (e.g., "Ship") |
263
+ | plural_display_name | string | Human-readable plural name (e.g., "People") |
264
+ | singular_display_name | string | Human-readable singular name (e.g., "Person") |
286
265
 
287
266
  ### SchemaProperty
288
267
 
@@ -290,6 +269,7 @@ Property with display name, unit, and domain information
290
269
 
291
270
  | Field | Type | Description |
292
271
  |-------|------|-------------|
272
+ | description | string | Semantic description of what this property represents |
293
273
  | display_name | string | Human-readable property name |
294
274
  | domain_findexes | integer[] | Flavor IDs (findexes) that can have this property |
295
275
  | name | string | Property name (internal identifier) |
@@ -1,386 +0,0 @@
1
- # Articles & Mentions
2
-
3
- Articles are one significant source of data for the Knowledge Graph. A **mention** is a specific reference to an entity within an article, capturing the context and sentiment of that reference.
4
-
5
- ## When to Use
6
-
7
- - You need to find news coverage about an entity
8
- - You want mention counts or volume over time
9
- - You have a specific article ID (ARTID) or mention code (MCODE) and need full details
10
- - You want to read the actual text or summary of an article
11
- - You need article metadata: publication name, date, URL, trustworthiness scores
12
-
13
- ## Key Concepts
14
-
15
- - **ARTID**: Unique identifier for each article.
16
- - Format: 20-character numeric string (same format as NEIDs)
17
- - Example: `05433395856363393596`
18
- - **MCODE**: A unique identifier for each mention, linking entity + article + context.
19
- - Format: `{neid}:{artid}` with colon separator
20
- - Example: `00416400910670863867:05433395856363393596`
21
- - **Mention Detail**: Includes the snippet, publication, sentiment, and other metadata
22
- - **Mention Counts**: Aggregated counts over time buckets, useful for tracking media attention
23
- - **Article Detail**: Full metadata including title, summary, publication info, and scores
24
- - **Article Text**: The actual content of the article (when available)
25
-
26
- ## Important Limitations
27
-
28
- ⚠️ **Volume Warning**: A single entity may have tens of thousands of associated articles. Avoid querying all articles for an entity over long time periods.
29
-
30
- **Recommended approach:**
31
- 1. Start with mention counts to understand volume
32
- 2. Use mention endpoints to identify specific mentions of interest
33
- 3. Then retrieve full article details only for those specific articles
34
-
35
- ## Tips
36
-
37
- - Start with mention counts to understand volume, then drill into specific mentions
38
- - Filter by time range to avoid overwhelming results for high-profile entities
39
- - Use neighborhood mentions to see what else was mentioned alongside your target entity
40
- - Article text may not be available for all articles (depends on licensing)
41
- - Use trustworthiness and page rank scores to assess source quality
42
-
43
- <!-- BEGIN GENERATED CONTENT -->
44
-
45
- ## Endpoints
46
-
47
- ### Get article detail
48
-
49
- `GET /articles/{artid}`
50
-
51
- Get detailed information about an article by its ID. Response is cached for 1 hour (articles are immutable).
52
-
53
- #### Guidance
54
-
55
- Response is wrapped in a 'detail' container object. Access article data via response.detail.
56
-
57
- #### Parameters
58
-
59
- | Name | Type | Required | Description |
60
- |------|------|----------|-------------|
61
- | artid | string | yes | Article ID |
62
-
63
- #### Responses
64
-
65
- | Status | Description |
66
- |--------|-------------|
67
- | 200 | Article detail (`GetArticleResponse`) |
68
- | 400 | Invalid ARTID (`Error`) |
69
- | 404 | Article not found (`Error`) |
70
- | 500 | Internal server error (`Error`) |
71
-
72
- #### Example
73
-
74
- **Request:**
75
-
76
- ```
77
- GET /articles/05433395856363393596
78
- ```
79
-
80
- **Response:**
81
-
82
- ```json
83
- {"detail": {"artid": "05433395856363393596", "publication_date": "2026-01-28T15:56:47Z", "title": "Apple's Cook says he's 'heartbroken' by Minneapolis events...", "summary": "The article details two fatal shootings by federal agents...", "batch": "7f302ee6808d7c45a09aed07c93ec785", "source": "7f302ee6808d7c45a09aed07c93ec785", "url": "https://www.cnbc.com/2026/01/28/...", "mentions": [{"neid": "00315863961550087877", "artid": "05433395856363393596"}], "topics": [], "events": ["00526686651102446795", "01090525413205193094"], "publication_name": "cnbc.com", "publication_home_url": "http://www.cnbc.com", "trustworthiness": 0.664, "original_publication_name": "CNBC", "tone": "neutral", "title_factuality": "accurate", "tone_objectivity_score": 0.533, "title_factuality_score": 7.133, "syndication_score": 1}}
84
- ```
85
-
86
- ---
87
-
88
- ### Get article text
89
-
90
- `GET /articles/{artid}/text`
91
-
92
- Get the full text content of an article by its ID. Response is cached for 10 minutes.
93
-
94
- #### Guidance
95
-
96
- This endpoint returns plain text, NOT JSON. Parse the response as text, not as a JSON object.
97
-
98
- #### Parameters
99
-
100
- | Name | Type | Required | Description |
101
- |------|------|----------|-------------|
102
- | artid | string | yes | Article ID |
103
-
104
- #### Responses
105
-
106
- | Status | Description |
107
- |--------|-------------|
108
- | 200 | Article text |
109
- | 400 | Invalid ARTID (`Error`) |
110
- | 500 | Internal server error (`Error`) |
111
-
112
- #### Example
113
-
114
- **Request:**
115
-
116
- ```
117
- GET /articles/05433395856363393596/text
118
- ```
119
-
120
- **Response:**
121
-
122
- ```
123
- Apple CEO Tim Cook said he was "heartbroken" by the situation in Minneapolis...
124
- ```
125
-
126
- ---
127
-
128
- ### Get mentions for entities
129
-
130
- `GET /mentions/lookup`
131
-
132
- Get list of mention codes (MCODEs) for named entities in a neighborhood within a time interval. Response is cached for 5 minutes.
133
-
134
- #### Parameters
135
-
136
- | Name | Type | Required | Description |
137
- |------|------|----------|-------------|
138
- | interval_start | string | yes | Start time of interval (RFC3339) |
139
- | interval_end | string | yes | End time of interval (RFC3339) |
140
- | neid | string[] | yes | Named Entity ID(s) in the neighborhood |
141
-
142
- #### Responses
143
-
144
- | Status | Description |
145
- |--------|-------------|
146
- | 200 | List of mention codes (`GetMentionsResponse`) |
147
- | 400 | Invalid parameters (`Error`) |
148
- | 500 | Internal server error (`Error`) |
149
-
150
- #### Example
151
-
152
- **Request:**
153
-
154
- ```
155
- GET /mentions/lookup?interval_start=2026-01-01T00:00:00Z&interval_end=2026-02-01T00:00:00Z&neid=00416400910670863867
156
- ```
157
-
158
- **Response:**
159
-
160
- ```json
161
- {"mcodes": [{"neid": "00416400910670863867", "artid": "05433395856363393596"}, {"neid": "00416400910670863867", "artid": "02706389331155211812"}]}
162
- ```
163
-
164
- ---
165
-
166
- ### Get mention counts over time
167
-
168
- `GET /mentions/lookup/counts`
169
-
170
- Get bucketed counts of mentions for entities in a neighborhood within a time interval
171
-
172
- #### Parameters
173
-
174
- | Name | Type | Required | Description |
175
- |------|------|----------|-------------|
176
- | interval_start | string | yes | Start time of interval (RFC3339) |
177
- | interval_end | string | yes | End time of interval (RFC3339) |
178
- | neid | string[] | yes | Named Entity ID(s) in the neighborhood |
179
- | numBuckets | integer | no | Number of time buckets |
180
-
181
- #### Responses
182
-
183
- | Status | Description |
184
- |--------|-------------|
185
- | 200 | Bucketed mention counts (`GetMentionCountsResponse`) |
186
- | 400 | Invalid parameters (`Error`) |
187
- | 500 | Internal server error (`Error`) |
188
-
189
- #### Example
190
-
191
- **Request:**
192
-
193
- ```
194
- GET /mentions/lookup/counts?interval_start=2026-01-15T00:00:00Z&interval_end=2026-01-20T00:00:00Z&neid=00416400910670863867&numBuckets=5
195
- ```
196
-
197
- **Response:**
198
-
199
- ```json
200
- {"buckets": [{"start": "2026-01-15T00:00:00Z", "width_hours": 24, "count": 51}, {"start": "2026-01-16T00:00:00Z", "width_hours": 24, "count": 28}]}
201
- ```
202
-
203
- ---
204
-
205
- ### Get mention details for a neighborhood
206
-
207
- `GET /mentions/lookup/detail`
208
-
209
- Get detailed information about all mentions for entities in a neighborhood within a time interval. Response is cached for 15 minutes.
210
-
211
- #### Parameters
212
-
213
- | Name | Type | Required | Description |
214
- |------|------|----------|-------------|
215
- | interval_start | string | yes | Start time of interval (RFC3339) |
216
- | interval_end | string | yes | End time of interval (RFC3339) |
217
- | neid | string[] | yes | Named Entity ID(s) in the neighborhood |
218
-
219
- #### Responses
220
-
221
- | Status | Description |
222
- |--------|-------------|
223
- | 200 | List of mention details (`GetMentionLookupDetailResponse`) |
224
- | 400 | Invalid parameters (`Error`) |
225
- | 500 | Internal server error (`Error`) |
226
-
227
- #### Example
228
-
229
- **Request:**
230
-
231
- ```
232
- GET /mentions/lookup/detail?interval_start=2026-01-28T00:00:00Z&interval_end=2026-01-29T00:00:00Z&neid=00416400910670863867
233
- ```
234
-
235
- **Response:**
236
-
237
- ```json
238
- {"details": [{"neid": "00416400910670863867", "artid": "06794762728091918955", "publication_date": "2026-01-28T14:01:17Z", "snippet": "...stiff competition from other major players such as YouTube and Apple...", "sentiment": 0, "explanation": "Apple is mentioned as a competitor in the music-streaming market...", "topics": [], "trustworthiness": 0.508, "original_publication_name": "Spotify", "tone": "Neutral", "title_factuality": "True", "tone_objectivity_score": 0.563, "title_factuality_score": 3.889, "events": ["06942391178010057368"]}]}
239
- ```
240
-
241
- ---
242
-
243
- ### Get mention detail
244
-
245
- `GET /mentions/{mcode}/detail`
246
-
247
- Get detailed information about a specific mention by its MCODE. Response is cached for 15 minutes.
248
-
249
- #### Guidance
250
-
251
- Response is wrapped in a 'detail' container object. Access mention data via response.detail.
252
-
253
- #### Parameters
254
-
255
- | Name | Type | Required | Description |
256
- |------|------|----------|-------------|
257
- | mcode | string | yes | Mention code in format NEID:ARTID |
258
-
259
- #### Responses
260
-
261
- | Status | Description |
262
- |--------|-------------|
263
- | 200 | Mention detail (`GetMentionDetailResponse`) |
264
- | 400 | Invalid MCODE format (`Error`) |
265
- | 404 | Mention not found (`Error`) |
266
- | 500 | Internal server error (`Error`) |
267
-
268
- #### Example
269
-
270
- **Request:**
271
-
272
- ```
273
- GET /mentions/00416400910670863867:05433395856363393596/detail
274
- ```
275
-
276
- **Response:**
277
-
278
- ```json
279
- {"detail": {"neid": "00416400910670863867", "artid": "05433395856363393596", "publication_date": "2026-01-28T15:56:47Z", "snippet": "Apple CEO Tim Cook said he was 'heartbroken'...", "sentiment": -0.75, "explanation": "CEO Tim Cook expressed heartbreak...", "topics": [], "trustworthiness": 0.664, "original_publication_name": "CNBC", "tone": "neutral", "title_factuality": "accurate", "tone_objectivity_score": 0.533, "title_factuality_score": 7.133, "events": ["07189853443333370710", "07880710486873721498"]}}
280
- ```
281
-
282
- ## Types
283
-
284
- ### ArticleDetail
285
-
286
- The article detail
287
-
288
- | Field | Type | Description |
289
- |-------|------|-------------|
290
- | artid | string | Article ID |
291
- | batch | string | Processing batch identifier |
292
- | events | string[] | Event IDs mentioned in this article |
293
- | mentions | `Mcode`[] | List of entity mentions in article |
294
- | moz_rank_score | number | Publisher's Moz rank value (0 to 1) @Minimum 0 @Maximum 1 |
295
- | original_publication_name | string | Original publication name when known (e.g., when article is syndicated) |
296
- | page_rank_score | number | Publisher's page rank value (0 to 1) @Minimum 0 @Maximum 1 |
297
- | publication_date | string | Publication date of the article @Format date-time |
298
- | publication_home_url | string | Home URL of the publication in which the article was published @Format uri |
299
- | publication_name | string | Name of the publication in which the article was published |
300
- | source | string | Article source identifier |
301
- | summary | string | Article summary |
302
- | syndication_score | integer | Syndication score indicating article distribution |
303
- | title | string | Article title |
304
- | title_factuality | string | Article title factuality classification |
305
- | title_factuality_score | number | Publisher's title factuality score (0 to 1) @Minimum 0 @Maximum 1 |
306
- | tone | string | Article tone classification |
307
- | tone_objectivity_score | number | Publisher's tone objectivity score (0 to 1) @Minimum 0 @Maximum 1 |
308
- | topics | `ArticleTopic`[] | Topics associated with this article |
309
- | trustworthiness | number | Trustworthiness score (0 to 1) @Minimum 0 @Maximum 1 |
310
- | url | string | Original article URL @Format uri |
311
-
312
- ### GetArticleResponse
313
-
314
- Response containing detailed information about an article
315
-
316
- | Field | Type | Description |
317
- |-------|------|-------------|
318
- | detail | `ArticleDetail` | |
319
-
320
- ### GetMentionCountsResponse
321
-
322
- Response containing bucketed mention counts over time
323
-
324
- | Field | Type | Description |
325
- |-------|------|-------------|
326
- | buckets | `Bucket`[] | Time buckets with mention counts |
327
-
328
- ### GetMentionDetailResponse
329
-
330
- Response containing detailed information about a mention
331
-
332
- | Field | Type | Description |
333
- |-------|------|-------------|
334
- | detail | `MentionDetail` | |
335
-
336
- ### GetMentionLookupDetailResponse
337
-
338
- Response containing detailed information about multiple mentions
339
-
340
- | Field | Type | Description |
341
- |-------|------|-------------|
342
- | details | `MentionDetail`[] | List of mention details |
343
-
344
- ### GetMentionsResponse
345
-
346
- Response containing mention codes for a lookup query
347
-
348
- | Field | Type | Description |
349
- |-------|------|-------------|
350
- | mcodes | `Mcode`[] | List of mention codes (NEID, ARTID pairs) |
351
-
352
- ### Mcode
353
-
354
- A tuple of (NEID, ARTID) representing one or more mentions of a Named Entity in an Article
355
-
356
- | Field | Type | Description |
357
- |-------|------|-------------|
358
- | artid | string | Article ID |
359
- | neid | string | Named Entity ID |
360
-
361
- ### MentionDetail
362
-
363
- The mention detail
364
-
365
- | Field | Type | Description |
366
- |-------|------|-------------|
367
- | artid | string | Article ID |
368
- | events | string[] | Event IDs that this mention is associated with |
369
- | explanation | string | Explanation of sentiment analysis |
370
- | moz_rank_score | number | Publisher's Moz rank value (0 to 1) @Minimum 0 @Maximum 1 |
371
- | neid | string | Named Entity ID |
372
- | original_publication_name | string | Original publication name when known (e.g., when article is syndicated) |
373
- | other_neid | string | NEID of the other entity in a relationship mention |
374
- | other_relation_type | string | Type of relationship with the other entity |
375
- | page_rank_score | number | Publisher's page rank value (0 to 1) @Minimum 0 @Maximum 1 |
376
- | publication_date | string | Publication date of the article @Format date-time |
377
- | sentiment | number | Sentiment score for the mention (-1 to 1) @Minimum -1 @Maximum 1 |
378
- | snippet | string | Text snippet containing the mention |
379
- | title_factuality | string | Article title factuality classification |
380
- | title_factuality_score | number | Publisher's title factuality score (0 to 1) @Minimum 0 @Maximum 1 |
381
- | tone | string | Article tone classification |
382
- | tone_objectivity_score | number | Publisher's tone objectivity score (0 to 1) @Minimum 0 @Maximum 1 |
383
- | topics | `ArticleTopic`[] | Topics associated with the article |
384
- | trustworthiness | number | Trustworthiness score (0 to 1) @Minimum 0 @Maximum 1 |
385
-
386
- <!-- END GENERATED CONTENT -->
@@ -1,145 +0,0 @@
1
- # Events
2
-
3
- Events are significant occurrences involving entities: mergers, acquisitions, lawsuits, executive changes, product launches, and other newsworthy happenings. Events are extracted from article content and link multiple entities and articles together.
4
-
5
- ## When to Use
6
-
7
- - You want to know what happened to/with an entity (not just mentions)
8
- - You want to see how different articles reference the same event(s), and understand that many articles may duplicate information about the same event(s).
9
- - You want to see what entities participated in an event, and what their roles were.
10
-
11
- ## Key Concepts
12
-
13
- - **Event ID (EVEID)**: Unique identifier for each event.
14
- - Format: 20-character numeric string (same format as NEIDs)
15
- - Example: `08640179941787350436`
16
- - **Event Roles**: Entities participate in events with roles (e.g., acquirer, target, plaintiff)
17
- - **Event Summary**: Brief description of what occurred
18
- - **Event Date**: When the event happened (may differ from article publication date)
19
-
20
- ## Tips
21
-
22
- - Multiple articles may reference the same event
23
- - Check entity roles to understand the nature of involvement
24
-
25
- <!-- BEGIN GENERATED CONTENT -->
26
-
27
- ## Endpoints
28
-
29
- ### Get events for an entity
30
-
31
- `GET /events/lookup`
32
-
33
- Get list of event IDs (EVEIDs) where an entity participates within a time interval. Response is cached for 5 minutes.
34
-
35
- #### Guidance
36
-
37
- Event IDs returned may not all be immediately retrievable via /events/{eveid}. Some events may return 404 due to event processing timing or data availability. Handle 404 responses gracefully.
38
-
39
- #### Parameters
40
-
41
- | Name | Type | Required | Description |
42
- |------|------|----------|-------------|
43
- | interval_start | string | yes | Start time of interval (RFC3339) |
44
- | interval_end | string | yes | End time of interval (RFC3339) |
45
- | neid | string | yes | Named Entity ID |
46
-
47
- #### Responses
48
-
49
- | Status | Description |
50
- |--------|-------------|
51
- | 200 | List of event IDs (`GetEventsForEntityResponse`) |
52
- | 400 | Invalid parameters (`Error`) |
53
- | 500 | Internal server error (`Error`) |
54
-
55
- #### Example
56
-
57
- **Request:**
58
-
59
- ```
60
- GET /events/lookup?interval_start=2026-01-28T00:00:00Z&interval_end=2026-01-29T00:00:00Z&neid=00416400910670863867
61
- ```
62
-
63
- **Response:**
64
-
65
- ```json
66
- {"event_ids": ["07880710486873721498", "07189853443333370710", "01188063638449369172"]}
67
- ```
68
-
69
- ---
70
-
71
- ### Get event detail
72
-
73
- `GET /events/{eveid}`
74
-
75
- Get detailed information about an event by its ID. Response is cached for 15 minutes.
76
-
77
- #### Guidance
78
-
79
- Response is wrapped in a 'detail' container object. Access event data via response.detail.
80
-
81
- #### Parameters
82
-
83
- | Name | Type | Required | Description |
84
- |------|------|----------|-------------|
85
- | eveid | string | yes | Event ID |
86
-
87
- #### Responses
88
-
89
- | Status | Description |
90
- |--------|-------------|
91
- | 200 | Event detail (`GetEventResponse`) |
92
- | 400 | Invalid EVEID (`Error`) |
93
- | 404 | Event not found (`Error`) |
94
- | 500 | Internal server error (`Error`) |
95
-
96
- #### Example
97
-
98
- **Request:**
99
-
100
- ```
101
- GET /events/08640179941787350436
102
- ```
103
-
104
- **Response:**
105
-
106
- ```json
107
- {"detail": {"eveid": "08640179941787350436", "name": "event|Apple plans to release a foldable device...|2026", "date": "2026", "description": "The new design and engineering changes in the iPhone Air could pave the way...", "category": "Product Development", "likelihood": "Medium", "severity": 0, "speculative": false, "participants": [{"neid": "00416400910670863867", "sentiment": 0.5, "explanation": "The launch of new products...", "role": "company", "snippet": "Apple is gearing up for the most extensive refresh...", "artid": "07521758285625650094"}]}}
108
- ```
109
-
110
- ## Types
111
-
112
- ### EventDetail
113
-
114
- The event detail
115
-
116
- | Field | Type | Description |
117
- |-------|------|-------------|
118
- | artids | string[] | Article IDs where this event was found |
119
- | category | string | Category of the event |
120
- | date | string | Date of the event |
121
- | description | string | Description of the event |
122
- | eveid | string | Event ID |
123
- | likelihood | string | Likelihood assessment of the event |
124
- | name | string | Name of the event |
125
- | participants | `EventParticipant`[] | Participants in the event |
126
- | severity | integer | Severity level of the event |
127
- | speculative | boolean | Whether the event is speculative |
128
-
129
- ### GetEventResponse
130
-
131
- Response containing detailed information about an event
132
-
133
- | Field | Type | Description |
134
- |-------|------|-------------|
135
- | detail | `EventDetail` | |
136
-
137
- ### GetEventsForEntityResponse
138
-
139
- Response containing event IDs for an entity
140
-
141
- | Field | Type | Description |
142
- |-------|------|-------------|
143
- | event_ids | string[] | List of event IDs |
144
-
145
- <!-- END GENERATED CONTENT -->
@@ -1,18 +0,0 @@
1
- # LLM (Ada)
2
-
3
- Ada is the AI assistant integrated into the Query Server, capable of answering natural language questions about the Knowledge Graph.
4
-
5
- ## Status: Not Currently Available
6
-
7
- ⚠️ The LLM/Ada endpoints are currently **excluded** from this skill because they are not functional in the current deployment. This documentation is a placeholder for when the feature becomes available.
8
-
9
- ## Intended Use Cases (Future)
10
-
11
- - Natural language queries about entities ("Tell me about Apple's recent news")
12
- - Conversational exploration of the Knowledge Graph
13
- - AI-assisted analysis and summarization
14
-
15
- <!-- BEGIN GENERATED CONTENT -->
16
-
17
-
18
- <!-- END GENERATED CONTENT -->