> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gildea.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Get Signal
> Retrieve a signal's full flat list of verified units
Unique signal identifier (e.g., `0001f3a7b9c8d4e5f6a7b8c9d0e1f2a3b4c5d6e7`).
`title`, `url`, and `published_at` always describe the full source. The `units` below may reflect only a segment of that source (e.g., a five-minute exchange in a two-hour podcast). See [Signal scope vs. source scope](/concepts/signals#signal-scope).
Unique signal identifier.
Source title. Describes the full source, not necessarily the extracted segment.
Source URL. Links to the full source.
ISO 8601 publication date of the full source.
`analysis` or `event`.
Source registrable domain (e.g. `reuters.com`).
Number of verified units; equals the length of `units`. The honest depth signal; use it, not statement length, to gauge analytical depth.
Themes with `value_chain` and `market_force` arrays.
Entities mentioned in this signal (`entity_id`, `name`, `type`).
Flat list of verified units, grouped by role (central statement → arguments → claims) in document order. **List position is the order**; there is no separate index field.
Unique unit identifier (stable; the same unit returns the same `id` from search).
`thesis` (analysis statement) · `synopsis` (event statement) · `argument` (supporting analysis sentence) · `claim` (atomic fact).
The verified text content.
Present only on `role=argument`. Group the units sharing this label, in list order, to reconstruct one argument as a paragraph.
Public IDs (`gld:/…`) of entities named in this unit.
Present only when a human reviewer signed off: `{ "human_reviewed": true }`. Omitted otherwise; baseline trust is the cited evidence.
Verbatim evidence `snippets` (each with `text` + `truncated`), returned by default.
```bash cURL theme={null}
curl -H "X-API-Key: gld_your_key" \
"https://api.gildea.ai/v1/signals/0001f3a7b9c8d4e5f6a7b8c9d0e1f2a3b4c5d6e7"
```
```python Python theme={null}
import requests
signal = requests.get(
"https://api.gildea.ai/v1/signals/0001f3a7b9c8d4e5f6a7b8c9d0e1f2a3b4c5d6e7",
headers={"X-API-Key": "gld_your_key"},
).json()
```
```javascript JavaScript theme={null}
const resp = await fetch(
"https://api.gildea.ai/v1/signals/0001f3a7b9c8d4e5f6a7b8c9d0e1f2a3b4c5d6e7",
{ headers: { "X-API-Key": "gld_your_key" } }
);
const signal = await resp.json();
```
```json 200 Analysis signal theme={null}
{
"signal_id": "0001f3a7b9c8d4e5f6a7b8c9d0e1f2a3b4c5d6e7",
"title": "NVIDIA H200 Shipments Surge as Supply Eases",
"url": "https://reuters.com/article",
"published_at": "2026-01-15T10:00:00Z",
"content_type": "analysis",
"domain": "reuters.com",
"verified_unit_count": 3,
"themes": {
"value_chain": ["Infrastructure"],
"market_force": ["Competitive Dynamics"]
},
"entities": [
{ "entity_id": "gld:/a1b2c3d4e5f6", "name": "NVIDIA", "type": "organization" }
],
"units": [
{
"id": "0005a1b2c3d4e5f60718293a4b5c6d7e8f9a0b1c",
"role": "thesis",
"text": "NVIDIA's H200 shipments increased significantly in Q4 as supply constraints eased.",
"verification": { "human_reviewed": true },
"evidence": {
"snippets": [
{ "text": "NVIDIA shipped over 400,000 H200 units in Q4, a 40% increase from…", "truncated": true }
]
}
},
{
"id": "0005d4e5f607182939a4b5c6d7e8f9a0b1c2d3e4",
"role": "argument",
"text": "Supply chain bottlenecks eased following TSMC capacity expansion.",
"argument_id": "a1",
"evidence": {
"snippets": [{ "text": "TSMC brought new CoWoS capacity online in late Q3…", "truncated": true }]
}
},
{
"id": "0004c6d0e2f1a3b5c7d9e1f3a5b7c9d1e3f5a7b9",
"role": "claim",
"text": "NVIDIA increased H200 shipments by 40% quarter-over-quarter.",
"evidence": {
"snippets": [{ "text": "…a 40% increase from the prior quarter.", "truncated": false }]
}
}
]
}
```
```json 200 Event signal theme={null}
{
"signal_id": "0001ace1234567890abcdef0123456789abcdef0",
"title": "EU Reaches Political Agreement on AI Act Implementation",
"url": "https://reuters.com/eu-ai-act",
"published_at": "2026-01-20T14:00:00Z",
"content_type": "event",
"domain": "reuters.com",
"verified_unit_count": 2,
"themes": {
"value_chain": ["Applications"],
"market_force": ["Regulatory & Legal"]
},
"entities": [
{ "entity_id": "gld:/7c4e1a90b2d3", "name": "EU AI Act", "type": "regulation_policy" }
],
"units": [
{
"id": "00057a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f",
"role": "synopsis",
"text": "The European Union reached a political agreement on implementing the AI Act.",
"evidence": {
"snippets": [{ "text": "EU member states reached agreement on the AI Act's implementation timeline…", "truncated": true }]
}
},
{
"id": "0004fed987654321ba9876543210fedcba987654",
"role": "claim",
"text": "General-purpose AI models must meet transparency requirements by August 2026.",
"evidence": {
"snippets": [{ "text": "…transparency obligations take effect in August 2026.", "truncated": false }]
}
}
]
}
```
```json 404 theme={null}
{
"error": {
"code": "not_found",
"message": "Signal 'sig_nonexistent' not found",
"status": 404
}
}
```
## OpenAPI
````yaml GET /v1/signals/{signal_id}
openapi: 3.1.0
info:
title: Gildea API
description: >-
Market intelligence on the AI economy, built for agents. Gildea ingests
expert sources (podcasts, essays, VC memos, X posts, research papers, news)
and decomposes them into verified, source-cited atomic facts: thesis
sentences, argument sentences, summary sentences, and claims.
**Key capabilities:**
- Verified atomic facts with verbatim source citations
- Entity intelligence with trend analytics across 8 entity types
- Theme taxonomy (6 value-chain segments + 6 market forces)
- Search verified text units by free-text query or by similarity to a known
unit
Only `verdict=pass` data is served. Every claim cites the source evidence it
was extracted from.
version: 0.1.0
servers:
- url: https://api.gildea.ai
description: Production
- url: http://localhost:8000
description: Local development
security:
- ApiKeyAuth: []
tags:
- name: signals
description: >-
Market intelligence signals — articles decomposed into verified text
units.
- name: entities
description: >-
Entity intelligence — companies, people, and products with trend
analytics.
- name: themes
description: Taxonomy themes — value chain segments and market forces with trend stats.
- name: search
description: >-
Search Gildea's verified text units — text queries or similarity to a
known unit.
- name: health
description: Service health and status.
- name: admin
description: Administrative operations (requires admin secret).
paths:
/v1/signals/{signal_id}:
get:
tags:
- signals
summary: Get signal detail
description: >-
Retrieve the full verified decomposition for a single signal as a flat
list of `units` — the central statement (thesis for analysis, synopsis
for events), argument sentences, and claims, each with its evidence
snippets. Reconstruct prose by role: join `thesis`/`synopsis` units, or
group `argument` units by `argument_id`.
operationId: get_signal_v1_signals__signal_id__get
parameters:
- name: signal_id
in: path
required: true
schema:
type: string
title: Signal Id
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/SignalDetail'
type: object
additionalProperties: true
title: Response Get Signal V1 Signals Signal Id Get
'401':
description: Invalid or missing API key.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Signal not found.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
'429':
description: Rate limit exceeded.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
components:
schemas:
SignalDetail:
properties:
signal_id:
type: string
title: Signal Id
examples:
- 0001f3a7b9c8d4e5f6a7b8c9d0e1f2a3b4c5d6e7
title:
anyOf:
- type: string
- type: 'null'
title: Title
url:
type: string
title: Url
published_at:
anyOf:
- type: string
- type: 'null'
title: Published At
description: Publication timestamp (ISO 8601).
content_type:
anyOf:
- type: string
enum:
- analysis
- event
- type: 'null'
title: Content Type
examples:
- analysis
domain:
anyOf:
- type: string
- type: 'null'
title: Domain
description: Source registrable domain.
examples:
- reuters.com
verified_unit_count:
type: integer
title: Verified Unit Count
description: >-
Number of verified units in the decomposition (equals len(units) in
detail). The honest depth signal — use this, not statement length,
to gauge analytical depth.
default: 0
themes:
$ref: '#/components/schemas/Themes'
entities:
items:
$ref: '#/components/schemas/EntitySummary'
type: array
title: Entities
units:
items:
$ref: '#/components/schemas/Unit'
type: array
title: Units
type: object
required:
- signal_id
- url
title: SignalDetail
description: >-
Full signal as a flat list of verified units (grouped by role, in
document order).
ErrorResponse:
properties:
error:
$ref: '#/components/schemas/ErrorDetail'
type: object
required:
- error
title: ErrorResponse
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
Themes:
properties:
value_chain:
items:
type: string
type: array
title: Value Chain
examples:
- - AI Infrastructure
market_force:
items:
type: string
type: array
title: Market Force
examples:
- - Competitive Dynamics
type: object
title: Themes
EntitySummary:
properties:
entity_id:
type: string
title: Entity Id
description: Stable public entity ID.
examples:
- gld:/a1b2c3d4e5f6
name:
type: string
title: Name
examples:
- NVIDIA
type:
type: string
title: Type
examples:
- organization
type: object
required:
- entity_id
- name
- type
title: EntitySummary
Unit:
properties:
id:
type: string
title: Id
description: Unique text-unit identifier.
role:
type: string
enum:
- thesis
- synopsis
- argument
- claim
title: Role
description: thesis | synopsis (central statement) · argument · claim.
examples:
- claim
text:
type: string
title: Text
description: The verified text content.
argument_id:
anyOf:
- type: string
- type: 'null'
title: Argument Id
description: >-
Present only on role=argument. Group units sharing this label, in
list order, to reconstruct one argument as a paragraph.
examples:
- a1
entities:
items:
type: string
type: array
title: Entities
description: Public IDs of entities named in this unit.
verification:
anyOf:
- $ref: '#/components/schemas/Verification'
- type: 'null'
description: >-
Present only when there's a trust signal to report (currently: human
review). Omitted otherwise — baseline trust is the cited evidence.
evidence:
anyOf:
- $ref: '#/components/schemas/Evidence'
- type: 'null'
description: Verbatim evidence snippets supporting this unit.
type: object
required:
- id
- role
- text
title: Unit
description: >-
One verified atomic text unit — the same shape in signal detail and
search hits.
ErrorDetail:
properties:
code:
type: string
title: Code
description: Machine-readable error code.
examples:
- not_found
message:
type: string
title: Message
description: Human-readable error description.
examples:
- Signal '0001f3a7b9c8d4e5f6a7b8c9d0e1f2a3b4c5d6e7' not found
status:
type: integer
title: Status
description: HTTP status code.
examples:
- 404
field:
anyOf:
- type: string
- type: 'null'
title: Field
description: 'For validation errors: path to the offending parameter.'
examples:
- body.text
request_id:
anyOf:
- type: string
- type: 'null'
title: Request Id
description: Correlation id (also on the X-Request-Id response header).
retry_after:
anyOf:
- type: integer
- type: 'null'
title: Retry After
description: >-
Seconds to wait before retrying (mirrors the Retry-After header).
Present on 429 (rate limited) and 503 (temporarily unavailable).
reset:
anyOf:
- type: integer
- type: 'null'
title: Reset
description: >-
Unix epoch seconds when the exceeded rate-limit window resets.
Present on 429.
type: object
required:
- code
- message
- status
title: ErrorDetail
ValidationError:
properties:
loc:
items:
anyOf:
- type: string
- type: integer
type: array
title: Location
msg:
type: string
title: Message
type:
type: string
title: Error Type
input:
title: Input
ctx:
type: object
title: Context
type: object
required:
- loc
- msg
- type
title: ValidationError
Verification:
properties:
human_reviewed:
anyOf:
- type: boolean
- type: 'null'
title: Human Reviewed
description: >-
Present and `true` only when a human reviewer approved this unit;
omitted otherwise. Baseline trust is the cited evidence, not this
flag.
type: object
title: Verification
Evidence:
properties:
snippets:
items:
$ref: '#/components/schemas/EvidenceSnippet'
type: array
title: Snippets
type: object
title: Evidence
EvidenceSnippet:
properties:
text:
type: string
title: Text
description: Verbatim evidence passage from the source (may be truncated).
truncated:
type: boolean
title: Truncated
description: True if the snippet was shortened for preview.
type: object
required:
- text
- truncated
title: EvidenceSnippet
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: X-API-Key
description: >-
API key for authentication. Include in every request as `X-API-Key:
gld_your_key_here`.
````