Document

A single document a source returns from sync. The fields map 1:1 onto the GraphQL IngestDocumentInput the Mac app pushes via ingestDocuments:

SDK field	IngestDocumentInput field
id	externalId (required)
title	title
text	text
audioUrl	audioUrl
url	url
author	author
date	date (ISO 8601 DateTime)
tags	tags
metadata	metadata (JSON)
contentType	contentType (ContentType)

Dedup is keyed on (feed, id): returning the same id twice is safe and is skipped on the server, so sync can be idempotent and retried freely. At least one of text or audioUrl must be present — an audio-only document triggers transcription (Whisper), and the transcript becomes the document text.

Properties

Property	Type	Description
audioUrl?	string	URL to an audio file. Maps to IngestDocumentInput.audioUrl. Trove downloads and transcribes it; the transcript becomes the document text and the document is indexed as contentType: transcript. Provide instead of (or alongside) text.
author?	string	Content author. Maps to IngestDocumentInput.author. For podcasts, set this to the show name (Trove convention).
captureOnly?	boolean	Retain the artifact WITHOUT transcribing or extracting it. For an explicit “save this, do not spend on processing it” — the platform keeps the file and the metadata, and no speech-to-text or extraction runs.
contentType?	SourceContentType	One of text, transcript, highlight, bookmark. Maps to IngestDocumentInput.contentType. Defaults to text (transcribed audio becomes transcript automatically).
date?	string	Original creation date as an ISO 8601 string (e.g. "2026-06-14T09:00:00Z"). Maps to the DateTime IngestDocumentInput.date. Used for recency ranking and the “published” display.
fallback?	{ fileUrl: string; mimeType: string; }	A second rendering to fall back to when the primary one is unusable. arXiv is the case it exists for: a paper’s HTML carries readable $…$ maths, the same equation out of the PDF is glyph soup, and a two-column PDF welds paragraphs together — but the HTML only exists for recent papers. So the source offers the HTML and names the PDF as the fallback, and the platform uses it when the primary fetch fails or yields nothing.
fallback.fileUrl	string	-
fallback.mimeType	string	-
fileUrl?	string	URL to a file Trove should fetch and extract — a PDF, an EPUB, a document. The platform downloads it, retains the artifact, and derives the text. Use instead of text when the upstream’s real content is a file rather than a string. Pair with mimeType when the URL does not reveal the type.
id	string	The stable external identifier from the upstream system — the dedup key within the feed. Maps to IngestDocumentInput.externalId. Use the native id (HN objectID, RSS guid, Notion page id), never a value that changes between runs.
metadata?	Record<string, unknown>	Arbitrary source-specific JSON. Maps to IngestDocumentInput.metadata. Never put credentials or auth headers here.
mimeType?	string	The MIME type of fileUrl, when the URL alone does not say. Ignored without one.
tags?	string[]	Array of string tags. Maps to IngestDocumentInput.tags.
text?	string	Full plain-text content. Maps to IngestDocumentInput.text. Strip HTML/markup for best search quality. Required unless audioUrl is set.
title	string	Document title. Maps to IngestDocumentInput.title. REQUIRED, because every path that ingests one requires it — a titleless document is refused at the seam with “has no title”. Optional here until the two were lined up, which meant the type accepted something the platform would always reject, and you found out at run time on a schedule rather than at your desk.
url?	string	Canonical link back to the original. Maps to IngestDocumentInput.url.