Data sources
Add and manage the sources Nuvelics collects articles from, run one now, and see its harvest runs.
x-api-key<token>A service key (nvs_...) in the x-api-key header. A service key belongs to one organization: an X-Org-Id header is optional and, when sent, must name that organization. This header also accepts any credential the bearer scheme does, and when a request sends both headers, this one is used.
limit?integerMaximum items per page (1–100, default 25)
1 <= value <= 10025cursor?stringOpaque cursor from a prior nextCursor
sort?stringSort order: "-field" descending, "field" ascending. Accepted: name, -name, createdAt, -createdAt, updatedAt, -updatedAt (default -updatedAt)
A page of datasources, most-recently-updated first. Items carry health only when the request includes ?include=health.
application/json- response
items*array<||||||||||>pagination*sort*filters*facets?Value/count breakdown for each field requested via ?facets=. Present only when facets were requested.
included?curl -X GET 'https://api.nuvelics.com/api/tenant/v1/datasources'{ "items": [ { "id": "string", "orgId": "string", "name": "string", "createdAt": "2019-08-24T14:15:22Z", "updatedAt": "2019-08-24T14:15:22Z", "version": 0, "enabled": true, "credentialId": "string", "fetchConfig": { "maxBodyBytes": 0, "maxFeedItems": 0, "timeoutMs": 0, "userAgent": "string", "throttleDelayMs": 0 }, "topic": "financial", "location": "string", "type": "web", "url": "http://example.com", "followLinks": true, "iconId": "string", "health": { "state": "ok", "since": "2019-08-24T14:15:22Z", "lastError": "string" } } ], "pagination": { "nextCursor": "string" }, "sort": { "applied": "string", "default": "string", "available": [ "string" ] }, "filters": { "applied": { "property1": null, "property2": null }, "available": [ { "field": "string", "kind": "string", "facetable": true } ] }, "facets": { "property1": { "values": [ { "value": "string", "count": 0 } ], "capped": true }, "property2": { "values": [ { "value": "string", "count": 0 } ], "capped": true } }, "included": { "datasources": { "property1": { "id": "string", "name": "string", "type": "string", "vendor": "datafactory", "iconId": "string" }, "property2": { "id": "string", "name": "string", "type": "string", "vendor": "datafactory", "iconId": "string" } }, "credentials": { "property1": { "id": "string", "name": "string", "schemeType": "string" }, "property2": { "id": "string", "name": "string", "schemeType": "string" } }, "users": { "property1": { "id": "string", "name": "string", "email": "string" }, "property2": { "id": "string", "name": "string", "email": "string" } }, "articlePitches": { "property1": [ { "id": "string", "title": "string", "status": "string", "newsdeskId": "string" } ], "property2": [ { "id": "string", "title": "string", "status": "string", "newsdeskId": "string" } ] } }}x-api-key<token>A service key (nvs_...) in the x-api-key header. A service key belongs to one organization: an X-Org-Id header is optional and, when sent, must name that organization. This header also accepts any credential the bearer scheme does, and when a request sends both headers, this one is used.
application/json- body
Web datasource
name*stringDatasource display name
1 <= lengthcredentialId?stringThe credential this source authenticates with when fetching, if it requires or accepts one.
fetchConfig?Per-datasource HTTP fetch tuning overrides; all fields optional
topic?stringThe one topic this source covers, for a source dedicated to a single topic. Leave empty for a mixed feed, where per-article classification decides. A routing hint, not a guarantee.
"financial""global_news""global_sports""local_news""local_traffic""lottery""national_news""national_sports""other""politics""schools_closings""weather"location?stringOptional single-valued editorial coverage hint: the one location this source is known to cover, for the minority of sources that are monolithic on this dimension. Omitted for mixed feeds, where per-event classification decides. A routing/classification prior, not authoritative. Distinct from a datasource kind's own params.location (e.g. a Grok x-search's free-text search target): this field describes the source's own editorial coverage, not a search parameter.
1 <= lengthtype*"web""web"url*stringFeed or article URL (https only)
urifollowLinks?booleanEnrich feed summaries with full body
Datasource registered
application/json- response
Web datasource
id*stringDatasource identifier
^[0-7][0-9A-HJKMNP-TV-Z]{25}$orgId*stringOwning organization identifier
^[0-7][0-9A-HJKMNP-TV-Z]{25}$name*stringDatasource display name
1 <= lengthcreatedAt*stringISO 8601 creation timestamp
date-timeupdatedAt*stringISO 8601 last-modified timestamp
date-timeversion*integerMonotonic row version; used as concurrency token
enabled*booleanWhen false the datasource is excluded from harvesting
credentialId?stringThe credential this source authenticates with when fetching, if it requires or accepts one.
fetchConfig?Per-datasource HTTP fetch tuning overrides; all fields optional
topic?stringThe one topic this source covers, for a source dedicated to a single topic. Leave empty for a mixed feed, where per-article classification decides. A routing hint, not a guarantee.
"financial""global_news""global_sports""local_news""local_traffic""lottery""national_news""national_sports""other""politics""schools_closings""weather"location?stringOptional single-valued editorial coverage hint: the one location this source is known to cover, for the minority of sources that are monolithic on this dimension. Omitted for mixed feeds, where per-event classification decides. A routing/classification prior, not authoritative. Distinct from a datasource kind's own params.location (e.g. a Grok x-search's free-text search target): this field describes the source's own editorial coverage, not a search parameter.
1 <= lengthtype*"web""web"url*stringFeed or article URL (https only)
urifollowLinks?booleanEnrich feed summaries with full body
iconId?stringIdentifier addressing this source's fetched icon, for use with GET /icons/{iconId}. Derived from the source's configured URL origin; absent until the read model computes it.
curl -X POST 'https://api.nuvelics.com/api/tenant/v1/datasources' \ -H 'Content-Type: application/json' \ -d '{ "name": "string", "type": "web", "url": "http://example.com"}'{ "id": "string", "orgId": "string", "name": "string", "createdAt": "2019-08-24T14:15:22Z", "updatedAt": "2019-08-24T14:15:22Z", "version": 0, "enabled": true, "credentialId": "string", "fetchConfig": { "maxBodyBytes": 0, "maxFeedItems": 0, "timeoutMs": 0, "userAgent": "string", "throttleDelayMs": 0 }, "topic": "financial", "location": "string", "type": "web", "url": "http://example.com", "followLinks": true, "iconId": "string"}x-api-key<token>A service key (nvs_...) in the x-api-key header. A service key belongs to one organization: an X-Org-Id header is optional and, when sent, must name that organization. This header also accepts any credential the bearer scheme does, and when a request sends both headers, this one is used.
Datasource kinds that can be saved without a credential
application/json- response
kinds*array<>Datasource kinds that can be saved without a credential for this organization.
curl -X GET 'https://api.nuvelics.com/api/tenant/v1/datasources/credential-opt-in-kinds'{ "kinds": [ "web" ]}x-api-key<token>A service key (nvs_...) in the x-api-key header. A service key belongs to one organization: an X-Org-Id header is optional and, when sent, must name that organization. This header also accepts any credential the bearer scheme does, and when a request sends both headers, this one is used.
id*stringDatasource identifier
^[0-7][0-9A-HJKMNP-TV-Z]{25}$Datasource found
application/json- response
id*stringDatasource identifier
^[0-7][0-9A-HJKMNP-TV-Z]{25}$orgId*stringOwning organization identifier
^[0-7][0-9A-HJKMNP-TV-Z]{25}$name*stringDatasource display name
1 <= lengthcreatedAt*stringISO 8601 creation timestamp
date-timeupdatedAt*stringISO 8601 last-modified timestamp
date-timeversion*integerMonotonic row version; used as concurrency token
enabled*booleanWhen false the datasource is excluded from harvesting
credentialId?stringThe credential this source authenticates with when fetching, if it requires or accepts one.
fetchConfig?Per-datasource HTTP fetch tuning overrides; all fields optional
topic?stringThe one topic this source covers, for a source dedicated to a single topic. Leave empty for a mixed feed, where per-article classification decides. A routing hint, not a guarantee.
"financial""global_news""global_sports""local_news""local_traffic""lottery""national_news""national_sports""other""politics""schools_closings""weather"location?stringOptional single-valued editorial coverage hint: the one location this source is known to cover, for the minority of sources that are monolithic on this dimension. Omitted for mixed feeds, where per-event classification decides. A routing/classification prior, not authoritative. Distinct from a datasource kind's own params.location (e.g. a Grok x-search's free-text search target): this field describes the source's own editorial coverage, not a search parameter.
1 <= lengthtype*"web""web"url*stringFeed or article URL (https only)
urifollowLinks?booleanEnrich feed summaries with full body
iconId?stringIdentifier addressing this source's fetched icon, for use with GET /icons/{iconId}. Derived from the source's configured URL origin; absent until the read model computes it.
health*Health of the datasource's most recent harvest run, null when never run
activity*Derived acquisition state for a datasource, computed at read time from stored schedule state
curl -X GET 'https://api.nuvelics.com/api/tenant/v1/datasources/string'{ "id": "string", "orgId": "string", "name": "string", "createdAt": "2019-08-24T14:15:22Z", "updatedAt": "2019-08-24T14:15:22Z", "version": 0, "enabled": true, "credentialId": "string", "fetchConfig": { "maxBodyBytes": 0, "maxFeedItems": 0, "timeoutMs": 0, "userAgent": "string", "throttleDelayMs": 0 }, "topic": "financial", "location": "string", "type": "web", "url": "http://example.com", "followLinks": true, "iconId": "string", "health": { "status": "healthy", "lastError": "string", "updatedAt": "2019-08-24T14:15:22Z" }, "activity": { "state": "ok", "since": "2019-08-24T14:15:22Z", "lastError": "string" }}x-api-key<token>A service key (nvs_...) in the x-api-key header. A service key belongs to one organization: an X-Org-Id header is optional and, when sent, must name that organization. This header also accepts any credential the bearer scheme does, and when a request sends both headers, this one is used.
id*stringDatasource identifier
^[0-7][0-9A-HJKMNP-TV-Z]{25}$application/json- body
name?string1 <= lengthurl?stringuricredentialId?string1 <= lengthfetchConfig?Per-datasource HTTP fetch tuning overrides; all fields optional
enabled?booleantopic?string"financial""global_news""global_sports""local_news""local_traffic""lottery""national_news""national_sports""other""politics""schools_closings""weather"nulllocation?string1 <= lengthparams?Kind-specific params patch, accepted opaquely; validated against the stored kind's concrete params schema in the use-case.
followLinks?booleanKind-scoped enrich flag (web/x-follows/x-status); applicability enforced in the use-case.
Datasource updated
application/json- response
Web datasource
id*stringDatasource identifier
^[0-7][0-9A-HJKMNP-TV-Z]{25}$orgId*stringOwning organization identifier
^[0-7][0-9A-HJKMNP-TV-Z]{25}$name*stringDatasource display name
1 <= lengthcreatedAt*stringISO 8601 creation timestamp
date-timeupdatedAt*stringISO 8601 last-modified timestamp
date-timeversion*integerMonotonic row version; used as concurrency token
enabled*booleanWhen false the datasource is excluded from harvesting
credentialId?stringThe credential this source authenticates with when fetching, if it requires or accepts one.
fetchConfig?Per-datasource HTTP fetch tuning overrides; all fields optional
topic?stringThe one topic this source covers, for a source dedicated to a single topic. Leave empty for a mixed feed, where per-article classification decides. A routing hint, not a guarantee.
"financial""global_news""global_sports""local_news""local_traffic""lottery""national_news""national_sports""other""politics""schools_closings""weather"location?stringOptional single-valued editorial coverage hint: the one location this source is known to cover, for the minority of sources that are monolithic on this dimension. Omitted for mixed feeds, where per-event classification decides. A routing/classification prior, not authoritative. Distinct from a datasource kind's own params.location (e.g. a Grok x-search's free-text search target): this field describes the source's own editorial coverage, not a search parameter.
1 <= lengthtype*"web""web"url*stringFeed or article URL (https only)
urifollowLinks?booleanEnrich feed summaries with full body
iconId?stringIdentifier addressing this source's fetched icon, for use with GET /icons/{iconId}. Derived from the source's configured URL origin; absent until the read model computes it.
curl -X PATCH 'https://api.nuvelics.com/api/tenant/v1/datasources/string' \ -H 'Content-Type: application/json' \ -d '{}'{ "id": "string", "orgId": "string", "name": "string", "createdAt": "2019-08-24T14:15:22Z", "updatedAt": "2019-08-24T14:15:22Z", "version": 0, "enabled": true, "credentialId": "string", "fetchConfig": { "maxBodyBytes": 0, "maxFeedItems": 0, "timeoutMs": 0, "userAgent": "string", "throttleDelayMs": 0 }, "topic": "financial", "location": "string", "type": "web", "url": "http://example.com", "followLinks": true, "iconId": "string"}x-api-key<token>A service key (nvs_...) in the x-api-key header. A service key belongs to one organization: an X-Org-Id header is optional and, when sent, must name that organization. This header also accepts any credential the bearer scheme does, and when a request sends both headers, this one is used.
id*stringDatasource identifier
^[0-7][0-9A-HJKMNP-TV-Z]{25}$Datasource deleted
curl -X DELETE 'https://api.nuvelics.com/api/tenant/v1/datasources/string'x-api-key<token>A service key (nvs_...) in the x-api-key header. A service key belongs to one organization: an X-Org-Id header is optional and, when sent, must name that organization. This header also accepts any credential the bearer scheme does, and when a request sends both headers, this one is used.
id*stringDatasource identifier
^[0-7][0-9A-HJKMNP-TV-Z]{25}$Acquisition result (ok or not_modified)
application/json- response
Per-URL acquisition outcome
url*stringThe input URL, echoed for correlation
status*"ok""ok"warnings?array<>articles*array<>curl -X POST 'https://api.nuvelics.com/api/tenant/v1/datasources/string/run'{ "url": "string", "status": "ok", "warnings": [ { "type": "acquisition_items_truncated", "detail": "string" } ], "articles": [ { "datasourceId": "string", "title": "string", "url": "string", "publishedAt": "string", "updatedAt": "string", "authors": [ "string" ], "source": { "kind": "feed", "title": "string", "url": "string" }, "parts": [ { "type": "text/markdown", "role": "body", "text": "string", "lang": "string", "signals": [ "paywalled" ], "provenance": [] } ], "links": [], "priority": "ROUTINE", "genre": "string", "editorNote": "string", "usageTerms": [ "string" ], "contentWarnings": [ "string" ] } ]}x-api-key<token>A service key (nvs_...) in the x-api-key header. A service key belongs to one organization: an X-Org-Id header is optional and, when sent, must name that organization. This header also accepts any credential the bearer scheme does, and when a request sends both headers, this one is used.
id*stringDatasource identifier
^[0-7][0-9A-HJKMNP-TV-Z]{25}$cursor?stringlimit?integer0 <= value <= 100sort?stringSort order: "-field" descending, "field" ascending. Accepted: startedAt, -startedAt (default -startedAt)
Paginated harvest runs for the datasource, newest first
application/json- response
items*array<>pagination*sort*filters*facets?Value/count breakdown for each field requested via ?facets=. Present only when facets were requested.
included?curl -X GET 'https://api.nuvelics.com/api/tenant/v1/datasources/string/runs'{ "items": [ { "id": "string", "datasourceId": "string", "status": "running", "startedAt": "2019-08-24T14:15:22Z", "finishedAt": "2019-08-24T14:15:22Z", "stats": { "property1": 0, "property2": 0 } } ], "pagination": { "nextCursor": "string" }, "sort": { "applied": "string", "default": "string", "available": [ "string" ] }, "filters": { "applied": { "property1": null, "property2": null }, "available": [ { "field": "string", "kind": "string", "facetable": true } ] }, "facets": { "property1": { "values": [ { "value": "string", "count": 0 } ], "capped": true }, "property2": { "values": [ { "value": "string", "count": 0 } ], "capped": true } }, "included": { "datasources": { "property1": { "id": "string", "name": "string", "type": "string", "vendor": "datafactory", "iconId": "string" }, "property2": { "id": "string", "name": "string", "type": "string", "vendor": "datafactory", "iconId": "string" } }, "credentials": { "property1": { "id": "string", "name": "string", "schemeType": "string" }, "property2": { "id": "string", "name": "string", "schemeType": "string" } }, "users": { "property1": { "id": "string", "name": "string", "email": "string" }, "property2": { "id": "string", "name": "string", "email": "string" } }, "articlePitches": { "property1": [ { "id": "string", "title": "string", "status": "string", "newsdeskId": "string" } ], "property2": [ { "id": "string", "title": "string", "status": "string", "newsdeskId": "string" } ] } }}