Type Reference

This page documents every type in the Trove GraphQL schema.

Scalars

Scalar	Format	Example
DateTime	ISO 8601 string	"2026-03-25T12:00:00Z"
JSON	Arbitrary JSON value	{ "key": "value" }, 42, [1, 2, 3]

---

Output Types

SearchResults

Container for search and discovery query results.

Field	Type	Description
results	[SearchResult!]!	Array of ranked search results.
totalMatches	Int!	Total number of matching documents (may exceed the returned results).
queryTimeMs	Int!	Time taken to execute the search in milliseconds.

SearchResult

A single search result with its document and relevance metadata.

Field	Type	Description
document	Document!	The matched document.
snippet	String!	A text snippet showing the most relevant passage.
relevanceScore	Float!	Similarity score between 0 and 1. Higher is more relevant.

Document

A piece of content stored in your knowledge base.

Field	Type	Nullable	Description
id	ID!	No	Unique document identifier.
source	Source!	No	The source this document belongs to.
feed	Feed	Yes	The feed within the source that produced this document.
externalId	String!	No	Identifier from the upstream system (e.g., tweet ID, article URL hash).
title	String	Yes	Document title.
url	String	Yes	Original URL.
author	String	Yes	Document author.
contentDate	DateTime	Yes	Original publication or creation date from the upstream.
indexedAt	DateTime!	No	Timestamp when the document was indexed in Trove.
previewText	String	Yes	First ~300 words of the document, stored inline for fast access. Use this for listings and summaries.
fullText	String	Yes	Complete document text. Lazy-loaded from blob storage on demand. Only request this field when you need the full content.
wordCount	Int	Yes	Total word count of the document.
contentType	ContentType!	No	The kind of content — see the ContentType enum.
tags	[String!]!	No	Array of tags applied to the document.
metadata	JSON	Yes	Arbitrary metadata from the upstream system.
createdAt	DateTime!	No	Timestamp when the document record was created.

DocumentConnection

Paginated document list returned by the documents query.

Field	Type	Description
nodes	[Document!]!	Array of documents in the current page.
totalCount	Int!	Total number of documents matching the filters.
hasMore	Boolean!	Whether more documents exist beyond the current page.

Source

A configured source that fills your knowledge base with documents.

Field	Type	Nullable	Description
id	ID!	No	Unique source identifier.
sourceType	String!	No	Type of source (e.g., "rss", "hacker-news", "podcast", "manual").
name	String!	No	Display name.
description	String	Yes	Optional description.
icon	String	Yes	Icon identifier or emoji.
status	SourceStatus!	No	Current status: ACTIVE, PAUSED, ERROR, or SETUP.
kind	SourceKind!	No	Execution contract — how the source collects. See SourceKind.
transport	Transport	Yes	Mechanism it uses to reach the upstream. See Transport. null for the manual/saved source.
documentSemantics	DocumentSemantics!	No	Whether documents are appended or upserted. See DocumentSemantics.
config	JSON	Yes	Source configuration. Holds preferences only — never credentials.
documentCount	Int!	No	Total number of documents from this source.
lastSyncedAt	DateTime	Yes	Timestamp of the last successful sync.
errorMessage	String	Yes	Error message if the source is in ERROR status.
createdAt	DateTime!	No	Timestamp when the source was created.
updatedAt	DateTime!	No	Timestamp of the last update.
recentDocuments	[Document!]!	No	Latest documents from this source. Accepts limit argument (default 5).
topAuthors	[AuthorStat!]!	No	Most prolific authors in this source. Accepts limit argument (default 20).
dateRange	DateRange	Yes	Earliest and latest document dates in this source.
syncRuns	[SyncRun!]!	No	Recent sync run history. Accepts limit argument (default 5).
feeds	[Feed!]!	No	The individual feeds/streams within this source, each with its own sync state.

Feed

A single publication, channel, or profile within a source. Multi-feed sources (e.g. an RSS source with several feeds) have one Feed per publication, each tracking its own sync position.

Field	Type	Nullable	Description
id	ID!	No	Unique feed identifier.
source	Source!	No	The source this feed belongs to.
externalKey	String!	No	Identifier for the feed within its source (feed URL, username, or "default").
name	String!	No	Display name.
status	FeedStatus!	No	Current status: ACTIVE, PAUSED, or ERROR.
cursor	String	Yes	Raw resume position (typed-watermark JSON). Prefer watermark for a parsed view.
watermark	FeedWatermark!	No	Parsed view of cursor — how the feed resumes and where it’s up to.
documentCount	Int!	No	Number of documents from this feed.
lastSyncedAt	DateTime	Yes	Timestamp of the last successful sync.
errorMessage	String	Yes	Error message if the feed is in ERROR status.
config	JSON	Yes	Feed-specific preferences. Never credentials.
recentDocuments	[Document!]!	No	Latest documents from this feed. Accepts limit argument.

FeedWatermark

A human-meaningful view of a feed’s sync position, projected from its cursor.

Field	Type	Nullable	Description
strategy	WatermarkStrategy!	No	How the feed resumes: DATE, ID_SET, or NONE.
syncedThrough	DateTime	Yes	For DATE: the high-water timestamp synced through.
trackedCount	Int	Yes	For ID_SET: how many ids/URLs are remembered.
atCapacity	Boolean	Yes	For ID_SET: whether the bounded set has reached its limit.

AuthorStat

Author frequency data for a source.

Field	Type	Description
author	String!	Author name.
documentCount	Int!	Number of documents by this author.

DateRange

Date bounds for documents in a source.

Field	Type	Nullable	Description
earliest	DateTime	Yes	Earliest document date. null if the source has no dated documents.
latest	DateTime	Yes	Latest document date. null if the source has no dated documents.

SyncRun

A record of a source sync, written by the sync client via createSyncRun.

Field	Type	Nullable	Description
id	ID!	No	Unique sync run identifier.
source	Source!	No	The source this sync run belongs to.
feedId	ID!	No	The feed within the source that was synced.
status	SyncRunStatus!	No	Current status: RUNNING, SUCCESS, ERROR, or CANCELLED.
documentsSynced	Int!	No	Number of documents indexed in this run.
cursorBefore	String	Yes	Cursor position before the sync started.
cursorAfter	String	Yes	Cursor position after the sync completed.
errorMessage	String	Yes	Error message if the sync failed.
startedAt	DateTime!	No	Timestamp when the sync started.
completedAt	DateTime	Yes	Timestamp when the sync completed. null if still running.
durationMs	Int	Yes	Total sync duration in milliseconds. null if still running.
logs	String	Yes	The run’s transcript, when the client recorded one.

UserStats

Account-level statistics and aggregates.

Field	Type	Description
totalDocuments	Int!	Total number of documents across all sources.
totalSources	Int!	Total number of sources.
activeSources	Int!	Number of sources with ACTIVE status.
documentsBySourceType	[SourceTypeStat!]!	Document count breakdown by source type.
documentsByContentType	[ContentTypeStat!]!	Document count breakdown by content type.
topAuthors	[AuthorStat!]!	Most prolific authors across all sources. Accepts limit argument (default 50).
recentSyncRuns	[SyncRun!]!	Recent sync runs across all sources. Accepts limit argument (default 5).

SourceTypeStat

Document count for a specific source type.

Field	Type	Description
sourceType	String!	The source type (e.g., "rss", "hacker-news").
documentCount	Int!	Number of documents from sources of this type.

ContentTypeStat

Document count for a specific content type.

Field	Type	Description
contentType	ContentType!	The content type — see the ContentType enum.
documentCount	Int!	Number of documents with this content type.

IngestResult

Result of a batch document ingestion.

Field	Type	Nullable	Description
documentsIndexed	Int!	No	Number of documents successfully indexed.
documentsSkipped	Int!	No	Number of documents skipped (already exist with the same (feedId, externalId)).
transcriptionsQueued	Int!	No	Number of audio documents queued for asynchronous transcription.
documentsQueued	Int!	No	Number of document files (e.g. PDFs) queued for asynchronous text extraction.
cursor	String	Yes	Updated cursor position for the feed.
errors	[IngestError!]	Yes	Array of per-document errors, if any. null when all documents succeed.

IngestError

Error details for a single document that failed during ingestion.

Field	Type	Description
externalId	String!	The externalId of the document that failed.
message	String!	Description of the error.

---

Input Types

CreateSourceInput

Input for the createSource mutation.

Field	Type	Required	Description
sourceType	String!	Yes	The type of source (e.g., "rss", "hacker-news", "podcast").
name	String!	Yes	Display name for the source.
description	String	No	Optional description.
icon	String	No	Icon identifier or emoji.
kind	SourceKind	No	Execution contract — see SourceKind.
transport	Transport	No	How the source reaches its upstream — see Transport.
documentSemantics	DocumentSemantics	No	Append vs upsert — see DocumentSemantics.
config	JSON!	Yes	Source-specific configuration (feed URLs, filters, etc.). Preferences only — never credentials.

UpdateSourceInput

Input for the updateSource mutation. All fields are optional; only included fields are updated.

Field	Type	Required	Description
name	String	No	New display name.
description	String	No	New description.
config	JSON	No	Updated configuration. Replaces the entire config object.

SaveDocumentInput

Input for the saveDocument mutation (quick save).

Field	Type	Required	Description
text	String	No	Text content to save.
url	String	No	Original URL.
title	String	No	Document title.
source	String	No	Free-form attribution label (e.g., "clipboard", "share-extension").
tags	[String!]	No	Tags to apply.

IngestDocumentInput

Input for a single document in the ingestDocuments mutation.

Field	Type	Required	Description
externalId	String!	Yes	Unique identifier from the upstream system. Used for deduplication with feedId (the (feedId, externalId) pair).
title	String	No	Document title.
text	String	No	Full text content. Required unless a file URL is provided.
fileUrl	String	No	Generic file-by-URL; routed by mimeType (PDF extracts text, audio transcribes).
mimeType	String	No	MIME type for fileUrl (e.g. application/pdf, audio/mpeg).
audioUrl	String	No	Shorthand for an mp3-by-URL; treated as fileUrl with mimeType: audio/mpeg.
url	String	No	Original URL.
author	String	No	Document author.
date	DateTime	No	Original publication or creation date.
contentType	ContentType	No	The kind of content — see the ContentType enum. Defaults to TEXT.
tags	[String!]	No	Tags to apply.
metadata	JSON	No	Arbitrary metadata stored with the document.

---

Enums

SourceStatus

The operational status of a source.

Value	Description
ACTIVE	Source is active. The sync client pushes new content as it syncs.
PAUSED	Source is paused. The sync client should stop syncing it until resumed.
ERROR	The last sync reported an error. Check errorMessage for details.
SETUP	Source is newly created and has not completed its first sync.

SyncRunStatus

The status of an individual sync run.

Value	Description
RUNNING	Sync is currently in progress.
SUCCESS	Sync completed successfully.
ERROR	Sync failed. Check errorMessage for details.
CANCELLED	Sync was cancelled before completion.

FeedStatus

The operational status of a feed within a source.

Value	Description
ACTIVE	Feed is active and syncing.
PAUSED	Feed is paused.
ERROR	The last sync of this feed reported an error.

ContentType

The kind of content a document holds.

Value	Description
TEXT	Article or page text.
TRANSCRIPT	Transcribed audio (e.g. a podcast episode).
HIGHLIGHT	A highlight or excerpt.
BOOKMARK	A saved link/bookmark.

SourceKind

A source’s execution contract — how it collects.

Value	Description
SCHEDULED_SYNC	Polls its upstream on a cadence and appends new documents (the only built kind today).
ON_DEMAND_FETCH	Fetches a single record on request (reserved).
ON_DEMAND_QUERY	Runs a parameterized query on request (reserved).

Transport

How a source reaches its upstream.

Value	Description
FEED	RSS/Atom feed.
SCRAPE	Sitemap or HTML crawl.
API	JSON/REST API.
BROWSER	Authenticated browser session.
LOCAL	Local files or database (reserved).

DocumentSemantics

How a source’s documents are written on ingest.

Value	Description
APPEND	Immutable — new documents are added, duplicates skipped.
UPSERT	Current-state — documents replace prior versions (reserved).

WatermarkStrategy

How a feed tracks its sync position (see FeedWatermark).

Value	Description
DATE	A high-water timestamp.
ID_SET	A bounded set of seen ids/URLs.
NONE	No watermark — re-scans each run, relying on dedup.

DocumentSortField

Available sort fields for the documents query.

Value	Description
INDEXED_AT	Sort by when the document was indexed in Trove (default).
CONTENT_DATE	Sort by the original publication date.
TITLE	Sort alphabetically by title.
AUTHOR	Sort alphabetically by author.

SortOrder

Sort direction for the documents query.

Value	Description
ASC	Ascending order (oldest first, A-Z).
DESC	Descending order (newest first, Z-A). Default.