Layer 0 — Story Clustering
API Reference
Articles
Retrieve processed articles with quality scores, semantic fingerprints, and optional embeddings. Articles are created by submitting text through the Layer 0 processing pipeline.
The article object
An article object is created when a submitted job completes processing. It contains everything Layer 0 extracted: a quality score, a content fingerprint for deduplication, a token count, and references to the stored embedding.
{
"article_id": "art_8f7h2k9s",
"title": "Fed Holds Rates Steady, Signals Cuts Later This
Year",
"url": "https://reuters.com/fed-rates-2026",
"source": "Reuters",
"published_date": "2026-04-29T12:00:00Z",
"quality_score": 0.8335,
"semantic_hash": "9eeb68200965e3cf",
"token_count": 107,
"embedding_id": "emb_9x2k4m",
"created_at": "2026-04-29T12:00:03Z"
}
| Field | Type | Description |
|---|---|---|
| article_id | string | Unique identifier. Stable across duplicate submissions — the same content always produces the same
article_id.
|
| title | string | From metadata.title at submission time. |
| url | string | From metadata.url. Also used as the deduplication key if provided. |
| source | string | Publisher name from metadata.source. Factors into source credibility scoring. |
| published_date | ISO 8601 | Original publication datetime from metadata.published_date. |
| quality_score | float | 0–1. Articles scoring below 0.53 are not forwarded to Layer 1 or Layer 2. |
| semantic_hash | string | Content fingerprint for cross-source deduplication — independent of URL or title. |
| token_count | integer | Number of meaningful tokens extracted from the article body. |
| embedding_id | string | Reference to the 384-dimensional vector stored in the embedding index. |
| created_at | ISO 8601 | When Layer 0 processing completed. |
Retrieve an article
GET
/v1/article/{article_id}
Returns a processed article by ID. The article_id is returned when a job completes — either
from the submit response directly, or from polling /v1/status/{job_id}.
| Parameter | Type | Description |
|---|---|---|
| article_idrequired | string | The article identifier returned at job completion. |
| include_embedding | boolean | Include the raw 384-dimensional embedding vector in the response. Default: false. Omitted
by default to keep responses fast — pass ?include_embedding=true when you need the
vector. |
GET /v1/article/art_8f7h2k9s
Authorization: Bearer YOUR_API_KEY
{
"article_id": "art_8f7h2k9s",
"title": "Fed Holds Rates Steady, Signals Cuts Later This
Year",
"url": "https://reuters.com/fed-rates-2026",
"source": "Reuters",
"published_date": "2026-04-29T12:00:00Z",
"quality_score": 0.8335,
"semantic_hash": "9eeb68200965e3cf",
"token_count": 107,
"embedding_id": "emb_9x2k4m",
"created_at": "2026-04-29T12:00:03Z"
}
With embedding
GET /v1/article/art_8f7h2k9s?include_embedding=true
Authorization: Bearer YOUR_API_KEY
{
"article_id": "art_8f7h2k9s",
"title": "Fed Holds Rates Steady, Signals Cuts Later This
Year",
"quality_score": 0.8335,
"semantic_hash": "9eeb68200965e3cf",
"token_count": 107,
"embedding": [0.0231, -0.0412, 0.0178, ... 384 floats
total],
"created_at": "2026-04-29T12:00:03Z"
}
Embedding latency. Retrieving an article with
include_embedding=true takes
longer than a standard fetch — the vector is computed from the token index on first request and cached
for subsequent calls. Omit the parameter unless you specifically need the raw vector.
Error responses
# Article not found
{ "detail": "Article not found" } HTTP 404
# Invalid or missing API key
{ "detail": "Invalid API key" } HTTP 401
Finding articles
To discover articles by topic rather than by ID, use Search. To find articles grouped by story across sources, use Clusters.