> ## 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.
# List Themes
> Retrieve all themes with signal counts and trend stats
Filter by axis: `value_chain` or `market_force`.
List of theme objects.
`value_chain` or `market_force`.
Theme name (e.g., `Foundation Models`).
Total signals tagged with this theme.
Trend analytics including `share_of_voice`, `streak`, `current_week`, and `prior_week`.
`Rising`, `Stable`, or `Declining`.
`Significant` or `Insignificant`.
`Volatile` or `Steady`.
`High`, `Medium`, `Low`, or `Negligible`. How much this theme warrants attention right now.
Explanation of the notability assignment.
```bash cURL theme={null}
curl -H "X-API-Key: gld_your_key" \
"https://api.gildea.ai/v1/themes?axis=value_chain"
```
```python Python theme={null}
import requests
resp = requests.get(
"https://api.gildea.ai/v1/themes",
headers={"X-API-Key": "gld_your_key"},
params={"axis": "value_chain"},
)
themes = resp.json()
```
```javascript JavaScript theme={null}
const resp = await fetch(
"https://api.gildea.ai/v1/themes?axis=value_chain",
{ headers: { "X-API-Key": "gld_your_key" } }
);
const themes = await resp.json();
```
```json 200 theme={null}
{
"themes": [
{
"axis": "value_chain",
"label": "Foundation Models",
"signal_count": 245,
"trend": {
"share_of_voice": 0.22,
"streak": 3,
"current_week": 28,
"prior_week": 24
},
"direction": "Rising",
"confidence": "Significant",
"stability": "Steady",
"notability": "High",
"notability_reasoning": "Theme with confirmed upward trend and consistent coverage; notable upward shift reliably gaining traction."
},
{
"axis": "value_chain",
"label": "Infrastructure",
"signal_count": 198,
"trend": {
"share_of_voice": 0.18,
"streak": 2,
"current_week": 22,
"prior_week": 20
},
"direction": "Rising",
"confidence": "Significant",
"stability": "Steady",
"notability": "High",
"notability_reasoning": "Theme with confirmed upward trend and consistent coverage; notable upward shift reliably gaining traction."
}
]
}
```
## OpenAPI
````yaml GET /v1/themes
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/themes:
get:
tags:
- themes
summary: List themes
description: >-
Retrieve all themes with signal counts and trend stats. Optionally
filter by taxonomy axis (value_chain or market_force).
operationId: list_themes_v1_themes_get
parameters:
- name: axis
in: query
required: false
schema:
anyOf:
- enum:
- value_chain
- market_force
type: string
- type: 'null'
description: 'Filter by taxonomy axis: ''value_chain'' or ''market_force''.'
title: Axis
description: 'Filter by taxonomy axis: ''value_chain'' or ''market_force''.'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/ThemeListResponse'
type: object
additionalProperties: true
title: Response List Themes V1 Themes Get
'401':
description: Invalid or missing API key.
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:
ThemeListResponse:
properties:
themes:
items:
$ref: '#/components/schemas/ThemeOverview'
type: array
title: Themes
description: >-
Themes with trend stats and interpretation. Not paginated (bounded
taxonomy).
type: object
required:
- themes
title: ThemeListResponse
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
ThemeOverview:
properties:
axis:
type: string
title: Axis
description: 'Taxonomy axis: ''value_chain'' or ''market_force''.'
label:
type: string
title: Label
examples:
- Foundation Models
signal_count:
type: integer
title: Signal Count
description: Total signals tagged with this theme.
trend:
$ref: '#/components/schemas/ThemeTrend'
direction:
anyOf:
- type: string
enum:
- Rising
- Stable
- Declining
- New
- type: 'null'
title: Direction
description: 'Interpretation: trend direction.'
confidence:
anyOf:
- type: string
enum:
- Significant
- Insignificant
- type: 'null'
title: Confidence
description: 'Interpretation: statistical confidence.'
stability:
anyOf:
- type: string
enum:
- Volatile
- Steady
- type: 'null'
title: Stability
description: 'Interpretation: signal stability.'
notability:
anyOf:
- type: string
enum:
- High
- Medium
- Low
- Negligible
- type: 'null'
title: Notability
description: 'Interpretation: foreground vs background.'
notability_reasoning:
anyOf:
- type: string
- type: 'null'
title: Notability Reasoning
type: object
required:
- axis
- label
- signal_count
- trend
title: ThemeOverview
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
ThemeTrend:
properties:
share_of_voice:
type: number
title: Share Of Voice
description: Share of total corpus over the trailing window (0–1).
examples:
- 0.22
streak:
type: integer
title: Streak
description: Consecutive weeks of growth.
examples:
- 4
current_week:
type: integer
title: Current Week
description: Signal count in the current week.
examples:
- 170
prior_week:
type: integer
title: Prior Week
description: Signal count in the prior week.
examples:
- 160
type: object
required:
- share_of_voice
- streak
- current_week
- prior_week
title: ThemeTrend
description: >-
Legible trend counts. Raw estimators (Theil-Sen, chi-square, Cramér's V,
CoV)
are not exposed — the interpretation fields summarize them.
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`.
````