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!
  connectorId: ID
  connectorType: String
  author: String
  after: DateTime
  before: DateTime
  contentType: String
  tags: [String!]
  limit: Int = 10
): SearchResults!

Parameters

Parameter	Type	Default	Description
query	String!	required	The search query. Interpreted semantically, not as exact keyword match.
connectorId	ID	null	Filter results to a specific connector.
connectorType	String	null	Filter by connector 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	String	null	Filter by content type (e.g., "text", "transcript").
tags	[String!]	null	Filter to documents matching all specified tags.
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!
  connectorId: ID
  connectorType: String
  limit: Int = 10
): SearchResults!

Parameters

Parameter	Type	Default	Description
topic	String!	required	The topic to explore.
connectorId	ID	null	Filter results to a specific connector.
connectorType	String	null	Filter by connector type.
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(
  connectorId: ID
  connectorType: String
  author: String
  since: DateTime
  limit: Int = 15
): [Document!]!

Parameters

Parameter	Type	Default	Description
connectorId	ID	null	Filter to a specific connector.
connectorType	String	null	Filter by connector type.
author	String	null	Filter by document author.
since	DateTime	null	Only include documents indexed after this timestamp.
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 connector { connectorType } } }"
  }'

---

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 R2 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(
  connectorId: ID
  connectorType: String
  author: String
  contentType: String
  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
connectorId	ID	null	Filter to a specific connector.
connectorType	String	null	Filter by connector type.
author	String	null	Filter by document author.
contentType	String	null	Filter by content type.
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(connectorType: $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 }
  }'

---

connector

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

SDL

connector(id: ID!): Connector

Parameters

Parameter	Type	Default	Description
id	ID!	required	The connector ID.

Return Type

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

• recentDocuments(limit: 5): Latest documents from this connector.
• topAuthors(limit: 5): Most prolific authors in this connector.
• 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 GetConnector($id: ID!) { connector(id: $id) { id connectorType name status execution documentCount lastSyncedAt nextSyncAt recentDocuments(limit: 3) { id title contentDate } topAuthors(limit: 3) { author documentCount } dateRange { earliest latest } syncRuns(limit: 3) { id status startedAt documentsSynced } } }",
    "variables": { "id": "conn_abc123" }
  }'

---

connectors

List all connectors with optional filters by type, status, or execution mode.

SDL

connectors(
  connectorType: String
  status: ConnectorStatus
  execution: ExecutionMode
): [Connector!]!

Parameters

Parameter	Type	Default	Description
connectorType	String	null	Filter by connector type (e.g., "rss", "hacker-news").
status	ConnectorStatus	null	Filter by status: ACTIVE, PAUSED, ERROR, or SETUP.
execution	ExecutionMode	null	Filter by execution mode: CLOUD or LOCAL.

Return Type

Returns an array of Connector objects.

Example

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

---

syncRuns

Query sync run history across all connectors or for a specific connector.

SDL

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

Parameters

Parameter	Type	Default	Description
connectorId	ID	null	Filter to a specific connector.
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($connectorId: ID) { syncRuns(connectorId: $connectorId, limit: 10) { id status source documentsSynced startedAt completedAt durationMs errorMessage connector { id name } } }",
    "variables": { "connectorId": "conn_abc123" }
  }'

---

stats

Account-level aggregates: total documents, total connectors, breakdowns by type, and upcoming sync information.

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 totalConnectors activeConnectors documentsByConnectorType { connectorType documentCount } documentsByContentType { contentType documentCount } recentSyncRuns(limit: 3) { id status startedAt connector { name } } nextScheduledSync { id name nextSyncAt } } }"
  }'