.article
article.add
effect · write
audited
v1
Add an article by providing canonical fields directly.
Primary write path for articles. The caller provides canonical fields (URL, title, etc.); the system handles ID generation, provenance, and storage. Articles are identified by canonical.url. If an article with the same URL already exists, returns it with `created: false` rather than inserting a duplicate. Hard UNIQUE constraint lands in Week 4 with the resolution queue migration; until then the dedup is a SELECT-then-INSERT inside the runner's transaction.
REST · POST /articles
Input schema (JSON Schema)
{
"type": "object",
"properties": {
"id": {
"type": "string"
},
"canonical": {
"type": "object",
"properties": {
"title": {
"type": "string"
},
"subtitle": {
"type": "string"
},
"description": {
"type": "string"
},
"authors": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"ref": {
"type": "string"
},
"matchConfidence": {
"type": "string",
"enum": [
"exact",
"fuzzy",
"unresolved",
"pending_review"
]
},
"role": {
"type": "string"
}
},
"required": [
"name"
],
"additionalProperties": false
},
"default": []
},
"language": {
"type": "string",
"default": "en"
},
"url": {
"type": "string",
"format": "uri"
},
"archivedUrl": {
"type": "string",
"format": "uri"
},
"headline": {
"type": "string"
},
"imageUrl": {
"type": "string",
"format": "uri"
},
"articleSection": {
"type": "string"
},
"publication": {
"$ref": "#/properties/canonical/properties/authors/items"
},
"publishedAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
},
"excerpt": {
"type": "string"
},
"fullText": {
"type": "string"
},
"wordCount": {
"type": "integer"
},
"readingTimeMinutes": {
"type": "number"
},
"topics": {
"type": "array",
"items": {
"type": "string"
},
"default": []
},
"placesReferenced": {
"type": "array",
"items": {
"$ref": "#/properties/canonical/properties/authors/items"
},
"default": []
},
"peopleReferenced": {
"type": "array",
"items": {
"$ref": "#/properties/canonical/properties/authors/items"
},
"default": []
},
"entitiesReferenced": {
"type": "array",
"items": {
"$ref": "#/properties/canonical/properties/authors/items"
},
"default": []
},
"type": {
"type": "string",
"enum": [
"news",
"analysis",
"opinion",
"feature",
"interview",
"essay",
"blog-post",
"newsletter",
"press-release",
"other"
]
}
},
"required": [
"title",
"url"
],
"additionalProperties": false
},
"overlay": {
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": [
"untried",
"tried",
"regular",
"retired"
]
},
"rating": {
"type": "number",
"minimum": 1,
"maximum": 10
},
"favorite": {
"type": "boolean"
},
"notes": {
"type": "string"
},
"tags": {
"type": "array",
"items": {
"type": "string"
},
"default": []
},
"wishlist": {
"type": "boolean"
},
"queue": {
"type": "string",
"enum": [
"to-read",
"reading",
"read",
"skipped"
]
},
"readLog": {
"type": "array",
"items": {
"type": "object",
"properties": {
"date": {
"type": "string",
"format": "date"
},
"durationMinutes": {
"type": "number"
},
"context": {
"type": "string"
}
},
"required": [
"date"
],
"additionalProperties": false
},
"default": []
},
"highlights": {
"type": "array",
"items": {
"type": "object",
"properties": {
"text": {
"type": "string"
},
"note": {
"type": "string"
},
"position": {
"type": "number"
},
"createdAt": {
"type": "string",
"format": "date-time"
}
},
"required": [
"text",
"createdAt"
],
"additionalProperties": false
},
"default": []
},
"summary": {
"type": "string"
},
"citedIn": {
"type": "array",
"items": {
"type": "string"
},
"default": []
}
},
"additionalProperties": false
},
"tags": {
"type": "array",
"items": {
"type": "string"
}
},
"provenance": {
"type": "object",
"properties": {
"source": {
"type": "string"
},
"sourceUrl": {
"type": "string",
"format": "uri"
},
"capturedAt": {
"type": "string",
"format": "date-time"
},
"enrichedBy": {
"type": "string"
},
"enrichedAt": {
"type": "string",
"format": "date-time"
},
"schemaVersion": {
"type": "string"
},
"rawCapture": {},
"template": {
"type": "string"
}
},
"additionalProperties": false
}
},
"required": [
"canonical"
],
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
}
Output schema (JSON Schema)
{
"type": "object",
"properties": {
"article": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"type": {
"type": "string",
"const": "article"
},
"tier": {
"type": "string",
"enum": [
"active",
"reference"
]
},
"slug": {
"type": "string"
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
},
"sameAs": {
"type": "array",
"items": {
"type": "object",
"properties": {
"source": {
"type": "string"
},
"id": {
"type": "string"
},
"url": {
"type": "string",
"format": "uri"
},
"kind": {
"type": "string",
"enum": [
"authority",
"reference",
"review",
"reservation",
"order",
"watch",
"listen",
"buy",
"social",
"website",
"article",
"video",
"edition",
"subtitle",
"other"
]
}
},
"required": [
"source"
],
"additionalProperties": false
},
"default": []
},
"tags": {
"type": "array",
"items": {
"type": "string"
},
"default": []
},
"provenance": {
"type": "object",
"properties": {
"source": {
"type": "string"
},
"sourceUrl": {
"type": "string",
"format": "uri"
},
"capturedAt": {
"type": "string",
"format": "date-time"
},
"enrichedBy": {
"type": "string"
},
"enrichedAt": {
"type": "string",
"format": "date-time"
},
"schemaVersion": {
"type": "string"
},
"rawCapture": {},
"template": {
"type": "string"
}
},
"required": [
"source",
"capturedAt",
"schemaVersion"
],
"additionalProperties": false
},
"canonical": {
"type": "object",
"properties": {
"title": {
"type": "string"
},
"subtitle": {
"type": "string"
},
"description": {
"type": "string"
},
"authors": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"ref": {
"type": "string"
},
"matchConfidence": {
"type": "string",
"enum": [
"exact",
"fuzzy",
"unresolved",
"pending_review"
]
},
"role": {
"type": "string"
}
},
"required": [
"name"
],
"additionalProperties": false
},
"default": []
},
"language": {
"type": "string",
"default": "en"
},
"url": {
"type": "string",
"format": "uri"
},
"archivedUrl": {
"type": "string",
"format": "uri"
},
"headline": {
"type": "string"
},
"imageUrl": {
"type": "string",
"format": "uri"
},
"articleSection": {
"type": "string"
},
"publication": {
"$ref": "#/properties/article/properties/canonical/properties/authors/items"
},
"publishedAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
},
"excerpt": {
"type": "string"
},
"fullText": {
"type": "string"
},
"wordCount": {
"type": "integer"
},
"readingTimeMinutes": {
"type": "number"
},
"topics": {
"type": "array",
"items": {
"type": "string"
},
"default": []
},
"placesReferenced": {
"type": "array",
"items": {
"$ref": "#/properties/article/properties/canonical/properties/authors/items"
},
"default": []
},
"peopleReferenced": {
"type": "array",
"items": {
"$ref": "#/properties/article/properties/canonical/properties/authors/items"
},
"default": []
},
"entitiesReferenced": {
"type": "array",
"items": {
"$ref": "#/properties/article/properties/canonical/properties/authors/items"
},
"default": []
},
"type": {
"type": "string",
"enum": [
"news",
"analysis",
"opinion",
"feature",
"interview",
"essay",
"blog-post",
"newsletter",
"press-release",
"other"
]
}
},
"required": [
"title",
"url"
],
"additionalProperties": false
},
"overlay": {
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": [
"untried",
"tried",
"regular",
"retired"
]
},
"rating": {
"type": "number",
"minimum": 1,
"maximum": 10
},
"favorite": {
"type": "boolean"
},
"notes": {
"type": "string"
},
"tags": {
"type": "array",
"items": {
"type": "string"
},
"default": []
},
"wishlist": {
"type": "boolean"
},
"queue": {
"type": "string",
"enum": [
"to-read",
"reading",
"read",
"skipped"
]
},
"readLog": {
"type": "array",
"items": {
"type": "object",
"properties": {
"date": {
"type": "string",
"format": "date"
},
"durationMinutes": {
"type": "number"
},
"context": {
"type": "string"
}
},
"required": [
"date"
],
"additionalProperties": false
},
"default": []
},
"highlights": {
"type": "array",
"items": {
"type": "object",
"properties": {
"text": {
"type": "string"
},
"note": {
"type": "string"
},
"position": {
"type": "number"
},
"createdAt": {
"type": "string",
"format": "date-time"
}
},
"required": [
"text",
"createdAt"
],
"additionalProperties": false
},
"default": []
},
"summary": {
"type": "string"
},
"citedIn": {
"type": "array",
"items": {
"type": "string"
},
"default": []
}
},
"additionalProperties": false
}
},
"required": [
"id",
"type",
"tier",
"createdAt",
"updatedAt",
"provenance",
"canonical"
],
"additionalProperties": false
},
"created": {
"type": "boolean"
}
},
"required": [
"article",
"created"
],
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
}
article.get
scope · reader
effect · read
v1
Retrieve a full article by ID, including canonical and overlay.
REST · GET /articles/:id
Input schema (JSON Schema)
{
"type": "object",
"properties": {
"id": {
"type": "string"
},
"includeOverlay": {
"type": "boolean",
"default": true
}
},
"required": [
"id"
],
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
}
Output schema (JSON Schema)
{
"type": "object",
"properties": {
"id": {
"type": "string"
},
"type": {
"type": "string",
"const": "article"
},
"tier": {
"type": "string",
"enum": [
"active",
"reference"
]
},
"slug": {
"type": "string"
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
},
"sameAs": {
"type": "array",
"items": {
"type": "object",
"properties": {
"source": {
"type": "string"
},
"id": {
"type": "string"
},
"url": {
"type": "string",
"format": "uri"
},
"kind": {
"type": "string",
"enum": [
"authority",
"reference",
"review",
"reservation",
"order",
"watch",
"listen",
"buy",
"social",
"website",
"article",
"video",
"edition",
"subtitle",
"other"
]
}
},
"required": [
"source"
],
"additionalProperties": false
},
"default": []
},
"tags": {
"type": "array",
"items": {
"type": "string"
},
"default": []
},
"provenance": {
"type": "object",
"properties": {
"source": {
"type": "string"
},
"sourceUrl": {
"type": "string",
"format": "uri"
},
"capturedAt": {
"type": "string",
"format": "date-time"
},
"enrichedBy": {
"type": "string"
},
"enrichedAt": {
"type": "string",
"format": "date-time"
},
"schemaVersion": {
"type": "string"
},
"rawCapture": {},
"template": {
"type": "string"
}
},
"required": [
"source",
"capturedAt",
"schemaVersion"
],
"additionalProperties": false
},
"canonical": {
"type": "object",
"properties": {
"title": {
"type": "string"
},
"subtitle": {
"type": "string"
},
"description": {
"type": "string"
},
"authors": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"ref": {
"type": "string"
},
"matchConfidence": {
"type": "string",
"enum": [
"exact",
"fuzzy",
"unresolved",
"pending_review"
]
},
"role": {
"type": "string"
}
},
"required": [
"name"
],
"additionalProperties": false
},
"default": []
},
"language": {
"type": "string",
"default": "en"
},
"url": {
"type": "string",
"format": "uri"
},
"archivedUrl": {
"type": "string",
"format": "uri"
},
"headline": {
"type": "string"
},
"imageUrl": {
"type": "string",
"format": "uri"
},
"articleSection": {
"type": "string"
},
"publication": {
"$ref": "#/properties/canonical/properties/authors/items"
},
"publishedAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
},
"excerpt": {
"type": "string"
},
"fullText": {
"type": "string"
},
"wordCount": {
"type": "integer"
},
"readingTimeMinutes": {
"type": "number"
},
"topics": {
"type": "array",
"items": {
"type": "string"
},
"default": []
},
"placesReferenced": {
"type": "array",
"items": {
"$ref": "#/properties/canonical/properties/authors/items"
},
"default": []
},
"peopleReferenced": {
"type": "array",
"items": {
"$ref": "#/properties/canonical/properties/authors/items"
},
"default": []
},
"entitiesReferenced": {
"type": "array",
"items": {
"$ref": "#/properties/canonical/properties/authors/items"
},
"default": []
},
"type": {
"type": "string",
"enum": [
"news",
"analysis",
"opinion",
"feature",
"interview",
"essay",
"blog-post",
"newsletter",
"press-release",
"other"
]
}
},
"required": [
"title",
"url"
],
"additionalProperties": false
},
"overlay": {
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": [
"untried",
"tried",
"regular",
"retired"
]
},
"rating": {
"type": "number",
"minimum": 1,
"maximum": 10
},
"favorite": {
"type": "boolean"
},
"notes": {
"type": "string"
},
"tags": {
"type": "array",
"items": {
"type": "string"
},
"default": []
},
"wishlist": {
"type": "boolean"
},
"queue": {
"type": "string",
"enum": [
"to-read",
"reading",
"read",
"skipped"
]
},
"readLog": {
"type": "array",
"items": {
"type": "object",
"properties": {
"date": {
"type": "string",
"format": "date"
},
"durationMinutes": {
"type": "number"
},
"context": {
"type": "string"
}
},
"required": [
"date"
],
"additionalProperties": false
},
"default": []
},
"highlights": {
"type": "array",
"items": {
"type": "object",
"properties": {
"text": {
"type": "string"
},
"note": {
"type": "string"
},
"position": {
"type": "number"
},
"createdAt": {
"type": "string",
"format": "date-time"
}
},
"required": [
"text",
"createdAt"
],
"additionalProperties": false
},
"default": []
},
"summary": {
"type": "string"
},
"citedIn": {
"type": "array",
"items": {
"type": "string"
},
"default": []
}
},
"additionalProperties": false
}
},
"required": [
"id",
"type",
"tier",
"createdAt",
"updatedAt",
"provenance",
"canonical"
],
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
}
article.ingest_from_url
effect · write
audited
v1
Ingest an article from a URL. Fetches the page, extracts metadata via the enrichment ladder (meta-tags → Jina → URL path), persists via article.add. Phase A0: no AI classification.
Paste-a-URL flow for articles. The URL is canonicalized (utm_*, fbclid, gclid stripped). Enrichment cascades through three tiers and lands at least a title every time. The article is created via article.add — same soft URL-dedup + validation + audit path as direct creation. Returns the created (or pre-existing-matching) article plus the enrichment trail. In Phase A0, `canonical.topics`, `peopleReferenced`, `entitiesReferenced`, and `placesReferenced` land empty. Classifier + entity-ref extraction land in Phase A1 once ANTHROPIC_API_KEY is wired in Railway.
REST · POST /articles/ingest
Input schema (JSON Schema)
{
"type": "object",
"properties": {
"url": {
"type": "string",
"format": "uri",
"description": "The URL to ingest. Will be canonicalized (utm_*, fbclid, gclid stripped) before storage."
},
"tags": {
"type": "array",
"items": {
"type": "string"
},
"maxItems": 10,
"description": "Optional tags to attach to the new article row."
},
"overlay": {
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": [
"untried",
"tried",
"regular",
"retired"
]
},
"rating": {
"type": "number",
"minimum": 1,
"maximum": 10
},
"favorite": {
"type": "boolean"
},
"notes": {
"type": "string"
},
"tags": {
"type": "array",
"items": {
"type": "string"
},
"default": []
},
"wishlist": {
"type": "boolean"
},
"queue": {
"type": "string",
"enum": [
"to-read",
"reading",
"read",
"skipped"
]
},
"readLog": {
"type": "array",
"items": {
"type": "object",
"properties": {
"date": {
"type": "string",
"format": "date"
},
"durationMinutes": {
"type": "number"
},
"context": {
"type": "string"
}
},
"required": [
"date"
],
"additionalProperties": false
},
"default": []
},
"highlights": {
"type": "array",
"items": {
"type": "object",
"properties": {
"text": {
"type": "string"
},
"note": {
"type": "string"
},
"position": {
"type": "number"
},
"createdAt": {
"type": "string",
"format": "date-time"
}
},
"required": [
"text",
"createdAt"
],
"additionalProperties": false
},
"default": []
},
"summary": {
"type": "string"
},
"citedIn": {
"type": "array",
"items": {
"type": "string"
},
"default": []
}
},
"additionalProperties": false,
"description": "Optional initial overlay — e.g. {queue: \"to-read\"} to add to a read-later queue."
}
},
"required": [
"url"
],
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
}
Output schema (JSON Schema)
{
"type": "object",
"properties": {
"article": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"type": {
"type": "string",
"const": "article"
},
"tier": {
"type": "string",
"enum": [
"active",
"reference"
]
},
"slug": {
"type": "string"
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
},
"sameAs": {
"type": "array",
"items": {
"type": "object",
"properties": {
"source": {
"type": "string"
},
"id": {
"type": "string"
},
"url": {
"type": "string",
"format": "uri"
},
"kind": {
"type": "string",
"enum": [
"authority",
"reference",
"review",
"reservation",
"order",
"watch",
"listen",
"buy",
"social",
"website",
"article",
"video",
"edition",
"subtitle",
"other"
]
}
},
"required": [
"source"
],
"additionalProperties": false
},
"default": []
},
"tags": {
"type": "array",
"items": {
"type": "string"
},
"default": []
},
"provenance": {
"type": "object",
"properties": {
"source": {
"type": "string"
},
"sourceUrl": {
"type": "string",
"format": "uri"
},
"capturedAt": {
"type": "string",
"format": "date-time"
},
"enrichedBy": {
"type": "string"
},
"enrichedAt": {
"type": "string",
"format": "date-time"
},
"schemaVersion": {
"type": "string"
},
"rawCapture": {},
"template": {
"type": "string"
}
},
"required": [
"source",
"capturedAt",
"schemaVersion"
],
"additionalProperties": false
},
"canonical": {
"type": "object",
"properties": {
"title": {
"type": "string"
},
"subtitle": {
"type": "string"
},
"description": {
"type": "string"
},
"authors": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"ref": {
"type": "string"
},
"matchConfidence": {
"type": "string",
"enum": [
"exact",
"fuzzy",
"unresolved",
"pending_review"
]
},
"role": {
"type": "string"
}
},
"required": [
"name"
],
"additionalProperties": false
},
"default": []
},
"language": {
"type": "string",
"default": "en"
},
"url": {
"type": "string",
"format": "uri"
},
"archivedUrl": {
"type": "string",
"format": "uri"
},
"headline": {
"type": "string"
},
"imageUrl": {
"type": "string",
"format": "uri"
},
"articleSection": {
"type": "string"
},
"publication": {
"$ref": "#/properties/article/properties/canonical/properties/authors/items"
},
"publishedAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
},
"excerpt": {
"type": "string"
},
"fullText": {
"type": "string"
},
"wordCount": {
"type": "integer"
},
"readingTimeMinutes": {
"type": "number"
},
"topics": {
"type": "array",
"items": {
"type": "string"
},
"default": []
},
"placesReferenced": {
"type": "array",
"items": {
"$ref": "#/properties/article/properties/canonical/properties/authors/items"
},
"default": []
},
"peopleReferenced": {
"type": "array",
"items": {
"$ref": "#/properties/article/properties/canonical/properties/authors/items"
},
"default": []
},
"entitiesReferenced": {
"type": "array",
"items": {
"$ref": "#/properties/article/properties/canonical/properties/authors/items"
},
"default": []
},
"type": {
"type": "string",
"enum": [
"news",
"analysis",
"opinion",
"feature",
"interview",
"essay",
"blog-post",
"newsletter",
"press-release",
"other"
]
}
},
"required": [
"title",
"url"
],
"additionalProperties": false
},
"overlay": {
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": [
"untried",
"tried",
"regular",
"retired"
]
},
"rating": {
"type": "number",
"minimum": 1,
"maximum": 10
},
"favorite": {
"type": "boolean"
},
"notes": {
"type": "string"
},
"tags": {
"type": "array",
"items": {
"type": "string"
},
"default": []
},
"wishlist": {
"type": "boolean"
},
"queue": {
"type": "string",
"enum": [
"to-read",
"reading",
"read",
"skipped"
]
},
"readLog": {
"type": "array",
"items": {
"type": "object",
"properties": {
"date": {
"type": "string",
"format": "date"
},
"durationMinutes": {
"type": "number"
},
"context": {
"type": "string"
}
},
"required": [
"date"
],
"additionalProperties": false
},
"default": []
},
"highlights": {
"type": "array",
"items": {
"type": "object",
"properties": {
"text": {
"type": "string"
},
"note": {
"type": "string"
},
"position": {
"type": "number"
},
"createdAt": {
"type": "string",
"format": "date-time"
}
},
"required": [
"text",
"createdAt"
],
"additionalProperties": false
},
"default": []
},
"summary": {
"type": "string"
},
"citedIn": {
"type": "array",
"items": {
"type": "string"
},
"default": []
}
},
"additionalProperties": false
}
},
"required": [
"id",
"type",
"tier",
"createdAt",
"updatedAt",
"provenance",
"canonical"
],
"additionalProperties": false
},
"created": {
"type": "boolean"
},
"enrichment": {
"type": "object",
"properties": {
"source": {
"type": "string",
"enum": [
"meta-tags",
"jina",
"url-path",
"mercury",
"firecrawl",
"ai"
]
},
"trail": {
"type": "array",
"items": {
"type": "object",
"properties": {
"tier": {
"type": "string"
},
"outcome": {
"type": "string",
"enum": [
"success",
"no-content",
"timeout",
"error"
]
},
"ms": {
"type": "number"
},
"error": {
"type": "string"
}
},
"required": [
"tier",
"outcome",
"ms"
],
"additionalProperties": false
}
},
"totalMs": {
"type": "number"
}
},
"required": [
"source",
"trail",
"totalMs"
],
"additionalProperties": false
}
},
"required": [
"article",
"created",
"enrichment"
],
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
}
article.search
scope · reader
effect · read
v1
Search articles by title (ILIKE), type, publication, topics, or queue status.
Article search via SQL filters: ILIKE on canonical.title (no trigram index on articles in Phase 1), JSONB containment on topics, eq on type / publication.ref / overlay.queue. Sorted by updated_at DESC, id DESC. Use article.get for full details.
REST · GET /articles/search
Input schema (JSON Schema)
{
"type": "object",
"properties": {
"query": {
"type": "string"
},
"type": {
"type": "string",
"enum": [
"news",
"analysis",
"opinion",
"feature",
"interview",
"essay",
"blog-post",
"newsletter",
"press-release",
"other"
]
},
"tier": {
"type": "string",
"enum": [
"active",
"reference"
]
},
"tags": {
"type": "array",
"items": {
"type": "string"
},
"maxItems": 10
},
"mode": {
"type": "string",
"enum": [
"sql",
"semantic",
"hybrid"
],
"default": "sql"
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 200,
"default": 20
},
"cursor": {
"type": "string"
},
"publicationId": {
"type": "string"
},
"topics": {
"type": "array",
"items": {
"type": "string"
},
"maxItems": 10
},
"queue": {
"type": "string",
"enum": [
"to-read",
"reading",
"read",
"skipped"
]
}
},
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
}
Output schema (JSON Schema)
{
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"title": {
"type": "string"
},
"publication": {
"type": "string"
},
"publishedAt": {
"type": "string"
},
"type": {
"type": "string"
},
"queue": {
"type": "string"
}
},
"required": [
"id",
"title"
],
"additionalProperties": false
}
},
"nextCursor": {
"type": [
"string",
"null"
]
},
"totalCount": {
"type": "integer"
}
},
"required": [
"items",
"nextCursor"
],
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
}
article.update_canonical
scope · admin
effect · write
audited
v1
Replace canonical fields on an article (admin-tier).
Whole-canonical replacement. The caller sends the complete ArticleCanonicalSchema; the handler validates and writes. Identity fields (id, type, tier, provenance) are envelope-level and are not affected. Sets embedding_stale_at=now() so a future re-embedding pass picks up the change. Optional ifMatch on updatedAt enforces optimistic concurrency.
REST · PUT /articles/:articleId/canonical
Input schema (JSON Schema)
{
"type": "object",
"properties": {
"articleId": {
"type": "string"
},
"canonical": {
"type": "object",
"properties": {
"title": {
"type": "string"
},
"subtitle": {
"type": "string"
},
"description": {
"type": "string"
},
"authors": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"ref": {
"type": "string"
},
"matchConfidence": {
"type": "string",
"enum": [
"exact",
"fuzzy",
"unresolved",
"pending_review"
]
},
"role": {
"type": "string"
}
},
"required": [
"name"
],
"additionalProperties": false
},
"default": []
},
"language": {
"type": "string",
"default": "en"
},
"url": {
"type": "string",
"format": "uri"
},
"archivedUrl": {
"type": "string",
"format": "uri"
},
"headline": {
"type": "string"
},
"imageUrl": {
"type": "string",
"format": "uri"
},
"articleSection": {
"type": "string"
},
"publication": {
"$ref": "#/properties/canonical/properties/authors/items"
},
"publishedAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
},
"excerpt": {
"type": "string"
},
"fullText": {
"type": "string"
},
"wordCount": {
"type": "integer"
},
"readingTimeMinutes": {
"type": "number"
},
"topics": {
"type": "array",
"items": {
"type": "string"
},
"default": []
},
"placesReferenced": {
"type": "array",
"items": {
"$ref": "#/properties/canonical/properties/authors/items"
},
"default": []
},
"peopleReferenced": {
"type": "array",
"items": {
"$ref": "#/properties/canonical/properties/authors/items"
},
"default": []
},
"entitiesReferenced": {
"type": "array",
"items": {
"$ref": "#/properties/canonical/properties/authors/items"
},
"default": []
},
"type": {
"type": "string",
"enum": [
"news",
"analysis",
"opinion",
"feature",
"interview",
"essay",
"blog-post",
"newsletter",
"press-release",
"other"
]
}
},
"required": [
"title",
"url"
],
"additionalProperties": false
},
"ifMatch": {
"type": "string",
"format": "date-time"
}
},
"required": [
"articleId",
"canonical"
],
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
}
Output schema (JSON Schema)
{
"type": "object",
"properties": {
"id": {
"type": "string"
},
"type": {
"type": "string",
"const": "article"
},
"tier": {
"type": "string",
"enum": [
"active",
"reference"
]
},
"slug": {
"type": "string"
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
},
"sameAs": {
"type": "array",
"items": {
"type": "object",
"properties": {
"source": {
"type": "string"
},
"id": {
"type": "string"
},
"url": {
"type": "string",
"format": "uri"
},
"kind": {
"type": "string",
"enum": [
"authority",
"reference",
"review",
"reservation",
"order",
"watch",
"listen",
"buy",
"social",
"website",
"article",
"video",
"edition",
"subtitle",
"other"
]
}
},
"required": [
"source"
],
"additionalProperties": false
},
"default": []
},
"tags": {
"type": "array",
"items": {
"type": "string"
},
"default": []
},
"provenance": {
"type": "object",
"properties": {
"source": {
"type": "string"
},
"sourceUrl": {
"type": "string",
"format": "uri"
},
"capturedAt": {
"type": "string",
"format": "date-time"
},
"enrichedBy": {
"type": "string"
},
"enrichedAt": {
"type": "string",
"format": "date-time"
},
"schemaVersion": {
"type": "string"
},
"rawCapture": {},
"template": {
"type": "string"
}
},
"required": [
"source",
"capturedAt",
"schemaVersion"
],
"additionalProperties": false
},
"canonical": {
"type": "object",
"properties": {
"title": {
"type": "string"
},
"subtitle": {
"type": "string"
},
"description": {
"type": "string"
},
"authors": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"ref": {
"type": "string"
},
"matchConfidence": {
"type": "string",
"enum": [
"exact",
"fuzzy",
"unresolved",
"pending_review"
]
},
"role": {
"type": "string"
}
},
"required": [
"name"
],
"additionalProperties": false
},
"default": []
},
"language": {
"type": "string",
"default": "en"
},
"url": {
"type": "string",
"format": "uri"
},
"archivedUrl": {
"type": "string",
"format": "uri"
},
"headline": {
"type": "string"
},
"imageUrl": {
"type": "string",
"format": "uri"
},
"articleSection": {
"type": "string"
},
"publication": {
"$ref": "#/properties/canonical/properties/authors/items"
},
"publishedAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
},
"excerpt": {
"type": "string"
},
"fullText": {
"type": "string"
},
"wordCount": {
"type": "integer"
},
"readingTimeMinutes": {
"type": "number"
},
"topics": {
"type": "array",
"items": {
"type": "string"
},
"default": []
},
"placesReferenced": {
"type": "array",
"items": {
"$ref": "#/properties/canonical/properties/authors/items"
},
"default": []
},
"peopleReferenced": {
"type": "array",
"items": {
"$ref": "#/properties/canonical/properties/authors/items"
},
"default": []
},
"entitiesReferenced": {
"type": "array",
"items": {
"$ref": "#/properties/canonical/properties/authors/items"
},
"default": []
},
"type": {
"type": "string",
"enum": [
"news",
"analysis",
"opinion",
"feature",
"interview",
"essay",
"blog-post",
"newsletter",
"press-release",
"other"
]
}
},
"required": [
"title",
"url"
],
"additionalProperties": false
},
"overlay": {
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": [
"untried",
"tried",
"regular",
"retired"
]
},
"rating": {
"type": "number",
"minimum": 1,
"maximum": 10
},
"favorite": {
"type": "boolean"
},
"notes": {
"type": "string"
},
"tags": {
"type": "array",
"items": {
"type": "string"
},
"default": []
},
"wishlist": {
"type": "boolean"
},
"queue": {
"type": "string",
"enum": [
"to-read",
"reading",
"read",
"skipped"
]
},
"readLog": {
"type": "array",
"items": {
"type": "object",
"properties": {
"date": {
"type": "string",
"format": "date"
},
"durationMinutes": {
"type": "number"
},
"context": {
"type": "string"
}
},
"required": [
"date"
],
"additionalProperties": false
},
"default": []
},
"highlights": {
"type": "array",
"items": {
"type": "object",
"properties": {
"text": {
"type": "string"
},
"note": {
"type": "string"
},
"position": {
"type": "number"
},
"createdAt": {
"type": "string",
"format": "date-time"
}
},
"required": [
"text",
"createdAt"
],
"additionalProperties": false
},
"default": []
},
"summary": {
"type": "string"
},
"citedIn": {
"type": "array",
"items": {
"type": "string"
},
"default": []
}
},
"additionalProperties": false
}
},
"required": [
"id",
"type",
"tier",
"createdAt",
"updatedAt",
"provenance",
"canonical"
],
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
}
article.update_overlay
effect · write
audited
v1
Update overlay fields on an article (queue, highlights, read log, etc.).
Shallow-merge patch — only fields you pass are changed. Does not touch canonical fields. NOTE: array fields like highlights/readLog are REPLACED if the caller passes them; append-only helper ops (article.add_highlight, article.log_read) come later. Today, callers wanting to append must read the current overlay, push the new entry, and pass the full array back.
REST · PATCH /articles/:articleId/overlay
Input schema (JSON Schema)
{
"type": "object",
"properties": {
"articleId": {
"type": "string"
},
"patch": {
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": [
"untried",
"tried",
"regular",
"retired"
]
},
"rating": {
"type": "number",
"minimum": 1,
"maximum": 10
},
"favorite": {
"type": "boolean"
},
"notes": {
"type": "string"
},
"tags": {
"type": "array",
"items": {
"type": "string"
},
"default": []
},
"wishlist": {
"type": "boolean"
},
"queue": {
"type": "string",
"enum": [
"to-read",
"reading",
"read",
"skipped"
]
},
"readLog": {
"type": "array",
"items": {
"type": "object",
"properties": {
"date": {
"type": "string",
"format": "date"
},
"durationMinutes": {
"type": "number"
},
"context": {
"type": "string"
}
},
"required": [
"date"
],
"additionalProperties": false
},
"default": []
},
"highlights": {
"type": "array",
"items": {
"type": "object",
"properties": {
"text": {
"type": "string"
},
"note": {
"type": "string"
},
"position": {
"type": "number"
},
"createdAt": {
"type": "string",
"format": "date-time"
}
},
"required": [
"text",
"createdAt"
],
"additionalProperties": false
},
"default": []
},
"summary": {
"type": "string"
},
"citedIn": {
"type": "array",
"items": {
"type": "string"
},
"default": []
}
},
"additionalProperties": false
}
},
"required": [
"articleId",
"patch"
],
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
}
Output schema (JSON Schema)
{
"type": "object",
"properties": {
"id": {
"type": "string"
},
"type": {
"type": "string",
"const": "article"
},
"tier": {
"type": "string",
"enum": [
"active",
"reference"
]
},
"slug": {
"type": "string"
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
},
"sameAs": {
"type": "array",
"items": {
"type": "object",
"properties": {
"source": {
"type": "string"
},
"id": {
"type": "string"
},
"url": {
"type": "string",
"format": "uri"
},
"kind": {
"type": "string",
"enum": [
"authority",
"reference",
"review",
"reservation",
"order",
"watch",
"listen",
"buy",
"social",
"website",
"article",
"video",
"edition",
"subtitle",
"other"
]
}
},
"required": [
"source"
],
"additionalProperties": false
},
"default": []
},
"tags": {
"type": "array",
"items": {
"type": "string"
},
"default": []
},
"provenance": {
"type": "object",
"properties": {
"source": {
"type": "string"
},
"sourceUrl": {
"type": "string",
"format": "uri"
},
"capturedAt": {
"type": "string",
"format": "date-time"
},
"enrichedBy": {
"type": "string"
},
"enrichedAt": {
"type": "string",
"format": "date-time"
},
"schemaVersion": {
"type": "string"
},
"rawCapture": {},
"template": {
"type": "string"
}
},
"required": [
"source",
"capturedAt",
"schemaVersion"
],
"additionalProperties": false
},
"canonical": {
"type": "object",
"properties": {
"title": {
"type": "string"
},
"subtitle": {
"type": "string"
},
"description": {
"type": "string"
},
"authors": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"ref": {
"type": "string"
},
"matchConfidence": {
"type": "string",
"enum": [
"exact",
"fuzzy",
"unresolved",
"pending_review"
]
},
"role": {
"type": "string"
}
},
"required": [
"name"
],
"additionalProperties": false
},
"default": []
},
"language": {
"type": "string",
"default": "en"
},
"url": {
"type": "string",
"format": "uri"
},
"archivedUrl": {
"type": "string",
"format": "uri"
},
"headline": {
"type": "string"
},
"imageUrl": {
"type": "string",
"format": "uri"
},
"articleSection": {
"type": "string"
},
"publication": {
"$ref": "#/properties/canonical/properties/authors/items"
},
"publishedAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
},
"excerpt": {
"type": "string"
},
"fullText": {
"type": "string"
},
"wordCount": {
"type": "integer"
},
"readingTimeMinutes": {
"type": "number"
},
"topics": {
"type": "array",
"items": {
"type": "string"
},
"default": []
},
"placesReferenced": {
"type": "array",
"items": {
"$ref": "#/properties/canonical/properties/authors/items"
},
"default": []
},
"peopleReferenced": {
"type": "array",
"items": {
"$ref": "#/properties/canonical/properties/authors/items"
},
"default": []
},
"entitiesReferenced": {
"type": "array",
"items": {
"$ref": "#/properties/canonical/properties/authors/items"
},
"default": []
},
"type": {
"type": "string",
"enum": [
"news",
"analysis",
"opinion",
"feature",
"interview",
"essay",
"blog-post",
"newsletter",
"press-release",
"other"
]
}
},
"required": [
"title",
"url"
],
"additionalProperties": false
},
"overlay": {
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": [
"untried",
"tried",
"regular",
"retired"
]
},
"rating": {
"type": "number",
"minimum": 1,
"maximum": 10
},
"favorite": {
"type": "boolean"
},
"notes": {
"type": "string"
},
"tags": {
"type": "array",
"items": {
"type": "string"
},
"default": []
},
"wishlist": {
"type": "boolean"
},
"queue": {
"type": "string",
"enum": [
"to-read",
"reading",
"read",
"skipped"
]
},
"readLog": {
"type": "array",
"items": {
"type": "object",
"properties": {
"date": {
"type": "string",
"format": "date"
},
"durationMinutes": {
"type": "number"
},
"context": {
"type": "string"
}
},
"required": [
"date"
],
"additionalProperties": false
},
"default": []
},
"highlights": {
"type": "array",
"items": {
"type": "object",
"properties": {
"text": {
"type": "string"
},
"note": {
"type": "string"
},
"position": {
"type": "number"
},
"createdAt": {
"type": "string",
"format": "date-time"
}
},
"required": [
"text",
"createdAt"
],
"additionalProperties": false
},
"default": []
},
"summary": {
"type": "string"
},
"citedIn": {
"type": "array",
"items": {
"type": "string"
},
"default": []
}
},
"additionalProperties": false
}
},
"required": [
"id",
"type",
"tier",
"createdAt",
"updatedAt",
"provenance",
"canonical"
],
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
}