GraphQL Queries

All queries require an Authorization: Bearer <token> header. Every query is scoped to the authenticated user’s data.

search

Semantic search across your knowledge base. Uses vector similarity to find documents matching the meaning of your query, not just keywords.

SDL

search(
  query: String!
  sourceId: ID
  sourceType: String
  author: String
  after: DateTime
  before: DateTime
  contentType: ContentType
  tags: [String!]
  feedId: ID
  limit: Int = 10
): SearchResults!

Parameters

Parameter	Type	Default	Description
`query`	`String!`	required	The search query. Interpreted semantically, not as exact keyword match.
`sourceId`	`ID`	`null`	Filter results to a specific source.
`sourceType`	`String`	`null`	Filter by source type (e.g., `"rss"`, `"hacker-news"`).
`author`	`String`	`null`	Filter by document author.
`after`	`DateTime`	`null`	Only include documents dated after this timestamp.
`before`	`DateTime`	`null`	Only include documents dated before this timestamp.
`contentType`	`ContentType`	`null`	Filter by content type — see the ContentType enum.
`tags`	`[String!]`	`null`	Filter to documents matching all specified tags.
`feedId`	`ID`	`null`	Filter results to a specific feed within a source.
`limit`	`Int`	`10`	Number of results to return. Maximum 50.

Return Type

Returns SearchResults containing an array of ranked results, each with a document, snippet, and relevance score.

Example

curl -X POST https://api.ontrove.sh/graphql \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "query Search($q: String!, $limit: Int) { search(query: $q, limit: $limit) { totalMatches queryTimeMs results { relevanceScore snippet document { id title url author contentDate } } } }",
    "variables": { "q": "distributed systems consensus", "limit": 5 }
  }'

discover

Thematic exploration of your knowledge base. Similar to search but optimized for browsing a topic rather than answering a specific question.

SDL

discover(
  topic: String!
  sourceId: ID
  sourceType: String
  feedId: ID
  limit: Int = 10
): SearchResults!

Parameters

Parameter	Type	Default	Description
`topic`	`String!`	required	The topic to explore.
`sourceId`	`ID`	`null`	Filter results to a specific source.
`sourceType`	`String`	`null`	Filter by source type.
`feedId`	`ID`	`null`	Filter results to a specific feed within a source.
`limit`	`Int`	`10`	Number of results to return. Maximum 50.

Return Type

Returns SearchResults, the same structure as search.

Example

curl -X POST https://api.ontrove.sh/graphql \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "query Discover($topic: String!) { discover(topic: $topic, limit: 10) { totalMatches results { relevanceScore snippet document { id title url author } } } }",
    "variables": { "topic": "machine learning infrastructure" }
  }'

recent

Chronological listing of your most recently indexed documents, newest first.

SDL

recent(
  sourceId: ID
  sourceType: String
  author: String
  since: DateTime
  feedId: ID
  limit: Int = 15
): [Document!]!

Parameters

Parameter	Type	Default	Description
`sourceId`	`ID`	`null`	Filter to a specific source.
`sourceType`	`String`	`null`	Filter by source type.
`author`	`String`	`null`	Filter by document author.
`since`	`DateTime`	`null`	Only include documents indexed after this timestamp.
`feedId`	`ID`	`null`	Filter to a specific feed within a source.
`limit`	`Int`	`15`	Number of documents to return. Maximum 50.

Return Type

Returns an array of Document objects.

Example

curl -X POST https://api.ontrove.sh/graphql \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "query Recent { recent(limit: 5) { id title author contentDate source { sourceType } } }"
  }'

document

Retrieve a single document by its ID. This is the only query that returns the full document text.

SDL

document(id: ID!): Document

Parameters

Parameter	Type	Default	Description
`id`	`ID!`	required	The document ID.

Return Type

Returns a Document or null if not found.

The fullText field is lazy-loaded from blob storage on demand. Only request it when you need the complete document content. Use previewText for summaries and listings.

Example

curl -X POST https://api.ontrove.sh/graphql \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "query GetDocument($id: ID!) { document(id: $id) { id title url author contentDate previewText fullText wordCount contentType tags metadata } }",
    "variables": { "id": "doc_abc123" }
  }'

documents

Paginated document listing with filtering and sorting. Use this for building document browsers, filtered views, and data exports.

SDL

documents(
  sourceId: ID
  sourceType: String
  author: String
  contentType: ContentType
  tags: [String!]
  after: DateTime
  before: DateTime
  search: String
  sortBy: DocumentSortField = INDEXED_AT
  sortOrder: SortOrder = DESC
  limit: Int = 25
  offset: Int = 0
): DocumentConnection!

Parameters

Parameter	Type	Default	Description
`sourceId`	`ID`	`null`	Filter to a specific source.
`sourceType`	`String`	`null`	Filter by source type.
`author`	`String`	`null`	Filter by document author.
`contentType`	`ContentType`	`null`	Filter by content type — see the ContentType enum.
`tags`	`[String!]`	`null`	Filter to documents matching all specified tags.
`after`	`DateTime`	`null`	Only include documents dated after this timestamp.
`before`	`DateTime`	`null`	Only include documents dated before this timestamp.
`search`	`String`	`null`	Text search filter (keyword match, not semantic).
`sortBy`	`DocumentSortField`	`INDEXED_AT`	Sort field. One of: `INDEXED_AT`, `CONTENT_DATE`, `TITLE`, `AUTHOR`.
`sortOrder`	`SortOrder`	`DESC`	Sort direction. `ASC` or `DESC`.
`limit`	`Int`	`25`	Page size. Maximum 100.
`offset`	`Int`	`0`	Number of documents to skip (offset-based pagination).

Return Type

Returns DocumentConnection with nodes, totalCount, and hasMore.

Note: Avoid requesting fullText in paginated queries. Each fullText field triggers a read from object storage. Use previewText for listings and fetch full text via the document query for individual documents.

Example

curl -X POST https://api.ontrove.sh/graphql \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "query ListDocs($type: String, $limit: Int, $offset: Int) { documents(sourceType: $type, sortBy: CONTENT_DATE, sortOrder: DESC, limit: $limit, offset: $offset) { totalCount hasMore nodes { id title author contentDate contentType tags } } }",
    "variables": { "type": "rss", "limit": 20, "offset": 0 }
  }'

source

Retrieve a single source by ID, including its nested statistics and recent activity.

SDL

source(id: ID!): Source

Parameters

Parameter	Type	Default	Description
`id`	`ID!`	required	The source ID.

Return Type

Returns a Source or null if not found. The source type includes nested fields queryable in the same request:

feeds: The source’s feeds, each with its own cursor and status.
recentDocuments(limit: 5): Latest documents from this source.
topAuthors(limit: 20): Most prolific authors in this source.
dateRange: Earliest and latest document dates.
syncRuns(limit: 5): Recent sync history.

Example

curl -X POST https://api.ontrove.sh/graphql \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "query GetSource($id: ID!) { source(id: $id) { id sourceType name status documentCount lastSyncedAt recentDocuments(limit: 3) { id title contentDate } topAuthors(limit: 3) { author documentCount } dateRange { earliest latest } syncRuns(limit: 3) { id status startedAt documentsSynced } } }",
    "variables": { "id": "src_abc123" }
  }'

sources

List all sources with optional filters by type or status.

SDL

sources(
  sourceType: String
  status: SourceStatus
): [Source!]!

Parameters

Parameter	Type	Default	Description
`sourceType`	`String`	`null`	Filter by source type (e.g., `"rss"`, `"hacker-news"`).
`status`	`SourceStatus`	`null`	Filter by status: `ACTIVE`, `PAUSED`, `ERROR`, or `SETUP`.

Return Type

Returns an array of Source objects.

Example

curl -X POST https://api.ontrove.sh/graphql \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "query ListSources($status: SourceStatus) { sources(status: $status) { id sourceType name status documentCount lastSyncedAt } }",
    "variables": { "status": "ACTIVE" }
  }'

feed

Retrieve a single feed (a publication/stream within a source) by ID.

SDL

feed(id: ID!): Feed

Parameters

Parameter	Type	Default	Description
`id`	`ID!`	required	The feed ID.

Return Type

Returns a Feed or null if not found — including its watermark (parsed sync position) and recentDocuments.

Example

curl -X POST https://api.ontrove.sh/graphql \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "query GetFeed($id: ID!) { feed(id: $id) { id name status documentCount lastSyncedAt watermark { strategy syncedThrough trackedCount } } }",
    "variables": { "id": "feed_def456" }
  }'

feeds

List feeds, optionally filtered by source or status.

SDL

feeds(sourceId: ID, status: FeedStatus): [Feed!]!

Parameters

Parameter	Type	Default	Description
`sourceId`	`ID`	`null`	Only include feeds within this source.
`status`	`FeedStatus`	`null`	Only include feeds with this status (`ACTIVE`, `PAUSED`, `ERROR`).

Return Type

Returns an array of Feed.

Example

curl -X POST https://api.ontrove.sh/graphql \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "query($sourceId: ID) { feeds(sourceId: $sourceId) { id name status documentCount watermark { strategy syncedThrough } } }",
    "variables": { "sourceId": "src_abc123" }
  }'

syncRuns

Query sync run history across all sources or for a specific source.

SDL

syncRuns(
  sourceId: ID
  status: SyncRunStatus
  limit: Int = 20
  offset: Int = 0
): [SyncRun!]!

Parameters

Parameter	Type	Default	Description
`sourceId`	`ID`	`null`	Filter to a specific source.
`status`	`SyncRunStatus`	`null`	Filter by status: `RUNNING`, `SUCCESS`, `ERROR`, or `CANCELLED`.
`limit`	`Int`	`20`	Number of results.
`offset`	`Int`	`0`	Offset for pagination.

Return Type

Returns an array of SyncRun objects.

Example

curl -X POST https://api.ontrove.sh/graphql \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "query SyncHistory($sourceId: ID) { syncRuns(sourceId: $sourceId, limit: 10) { id status feedId documentsSynced startedAt completedAt durationMs errorMessage source { id name } } }",
    "variables": { "sourceId": "src_abc123" }
  }'

stats

Account-level aggregates: total documents, total sources, breakdowns by type, and recent sync activity.

SDL

stats: UserStats!

Parameters

None.

Return Type

Returns UserStats.

Example

curl -X POST https://api.ontrove.sh/graphql \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "{ stats { totalDocuments totalSources activeSources documentsBySourceType { sourceType documentCount } documentsByContentType { contentType documentCount } recentSyncRuns(limit: 3) { id status startedAt source { name } } } }"
  }'