GraphQL Mutations

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

createConnector

Create a new connector to define a data source for ingestion.

SDL

createConnector(input: CreateConnectorInput!): Connector!

Input Fields

Field	Type	Required	Description
connectorType	String!	Yes	The type of connector (e.g., "rss", "hacker-news", "podcast").
name	String!	Yes	Display name for the connector.
description	String	No	Optional description of the data source.
icon	String	No	Optional icon identifier or emoji.
execution	ExecutionMode!	Yes	CLOUD for server-side syncs, LOCAL for desktop app syncs.
config	JSON!	Yes	Connector-specific configuration (e.g., feed URL, API credentials).
schedule	String	No	Schedule string for scheduled syncs. Supported values: "every 30 minutes", "every hour", "every 6 hours", "every 12 hours", "daily".

Return Type

Returns the created Connector.

Example

curl -X POST https://api.ontrove.sh/graphql \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "mutation CreateConnector($input: CreateConnectorInput!) { createConnector(input: $input) { id connectorType name status execution schedule createdAt } }",
    "variables": {
      "input": {
        "connectorType": "rss",
        "name": "Tech Blogs",
        "description": "Engineering blogs I follow",
        "execution": "CLOUD",
        "config": { "feedUrl": "https://example.com/feed.xml" },
        "schedule": "every 6 hours"
      }
    }
  }'

---

updateConnector

Update an existing connector’s settings. Only the fields you include in the input are changed.

SDL

updateConnector(id: ID!, input: UpdateConnectorInput!): Connector!

Parameters

Parameter	Type	Description
id	ID!	The connector ID to update.

Input Fields

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.
schedule	String	No	Updated schedule string. Supported values: "every 30 minutes", "every hour", "every 6 hours", "every 12 hours", "daily".

Return Type

Returns the updated Connector.

Example

curl -X POST https://api.ontrove.sh/graphql \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "mutation UpdateConnector($id: ID!, $input: UpdateConnectorInput!) { updateConnector(id: $id, input: $input) { id name schedule updatedAt } }",
    "variables": {
      "id": "conn_abc123",
      "input": {
        "name": "Tech Blogs (Updated)",
        "schedule": "every 12 hours"
      }
    }
  }'

---

deleteConnector

Delete a connector and all of its documents. This is a cascading delete that removes data from D1, R2, and Vectorize. This action is irreversible.

SDL

deleteConnector(id: ID!): Boolean!

Parameters

Parameter	Type	Description
id	ID!	The connector ID to delete.

Return Type

Returns true on success.

Example

curl -X POST https://api.ontrove.sh/graphql \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "mutation DeleteConnector($id: ID!) { deleteConnector(id: $id) }",
    "variables": { "id": "conn_abc123" }
  }'

---

pauseConnector

Pause a connector. Stops all scheduled syncs until the connector is resumed.

SDL

pauseConnector(id: ID!): Connector!

Parameters

Parameter	Type	Description
id	ID!	The connector ID to pause.

Return Type

Returns the updated Connector with status: PAUSED.

Example

curl -X POST https://api.ontrove.sh/graphql \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "mutation PauseConnector($id: ID!) { pauseConnector(id: $id) { id name status nextSyncAt } }",
    "variables": { "id": "conn_abc123" }
  }'

---

resumeConnector

Resume a paused connector. Scheduled syncs resume according to the connector’s schedule.

SDL

resumeConnector(id: ID!): Connector!

Parameters

Parameter	Type	Description
id	ID!	The connector ID to resume.

Return Type

Returns the updated Connector with status: ACTIVE.

Example

curl -X POST https://api.ontrove.sh/graphql \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "mutation ResumeConnector($id: ID!) { resumeConnector(id: $id) { id name status nextSyncAt } }",
    "variables": { "id": "conn_abc123" }
  }'

---

syncConnector

Trigger an immediate sync for a connector, regardless of its schedule. Returns the newly created sync run so you can track its progress.

SDL

syncConnector(id: ID!): SyncRun!

Parameters

Parameter	Type	Description
id	ID!	The connector ID to sync.

Return Type

Returns the created SyncRun.

Example

curl -X POST https://api.ontrove.sh/graphql \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "mutation TriggerSync($id: ID!) { syncConnector(id: $id) { id status source startedAt connector { id name } } }",
    "variables": { "id": "conn_abc123" }
  }'

---

saveDocument

Quick-save a piece of content to your knowledge base. Automatically creates a “Manual Saves” connector if one does not already exist.

SDL

saveDocument(input: SaveDocumentInput!): Document!

Input Fields

Field	Type	Required	Description
text	String	No	The text content to save.
url	String	No	URL of the source. If provided without text, the content is fetched.
title	String	No	Title for the saved document.
source	String	No	Label for the source (e.g., "clipboard", "share-extension").
tags	[String!]	No	Tags to apply to the document.

Return Type

Returns the created Document.

Example

curl -X POST https://api.ontrove.sh/graphql \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "mutation Save($input: SaveDocumentInput!) { saveDocument(input: $input) { id title tags indexedAt connector { id name } } }",
    "variables": {
      "input": {
        "title": "Interesting article on distributed systems",
        "url": "https://example.com/article",
        "text": "Full text of the article goes here...",
        "source": "web",
        "tags": ["distributed-systems", "architecture"]
      }
    }
  }'

---

ingestDocuments

Batch ingest documents for a specific connector. This is the primary way to push data into Trove programmatically. Documents with the same (connectorId, externalId) pair are skipped to prevent duplicates.

SDL

ingestDocuments(
  connectorId: ID!
  documents: [IngestDocumentInput!]!
  cursor: String
): IngestResult!

Parameters

Parameter	Type	Required	Description
connectorId	ID!	Yes	The connector to ingest documents into.
documents	[IngestDocumentInput!]!	Yes	Array of documents to ingest. Maximum 50 per call.
cursor	String	No	Pagination cursor for the connector’s sync state. Updated after successful ingestion.

Document Input Fields

Field	Type	Required	Description
externalId	String!	Yes	Unique identifier from the source system. Used for deduplication.
title	String	No	Document title.
text	String	No	Full text content. Required unless audioUrl is provided.
audioUrl	String	No	URL to an audio file for transcription.
url	String	No	Source URL.
author	String	No	Document author.
date	DateTime	No	Original publication or creation date.
contentType	String	No	Content type label. One of: "text", "transcript", "highlight", "bookmark".
tags	[String!]	No	Tags to apply.
metadata	JSON	No	Arbitrary metadata stored with the document.

Return Type

Returns IngestResult with counts of indexed and skipped documents, the updated cursor, and any errors.

Example

curl -X POST https://api.ontrove.sh/graphql \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "mutation Ingest($connectorId: ID!, $documents: [IngestDocumentInput!]!, $cursor: String) { ingestDocuments(connectorId: $connectorId, documents: $documents, cursor: $cursor) { documentsIndexed documentsSkipped cursor errors { externalId message } } }",
    "variables": {
      "connectorId": "conn_abc123",
      "cursor": "page-2",
      "documents": [
        {
          "externalId": "article-001",
          "title": "Understanding Raft Consensus",
          "text": "Full article text...",
          "url": "https://example.com/raft",
          "author": "Jane Doe",
          "date": "2026-03-20T10:00:00Z",
          "contentType": "text",
          "tags": ["distributed-systems", "consensus"]
        },
        {
          "externalId": "article-002",
          "title": "Paxos Made Simple",
          "text": "Another article...",
          "author": "John Smith",
          "date": "2026-03-21T14:30:00Z",
          "contentType": "text"
        }
      ]
    }
  }'

---

deleteDocument

Delete a single document. This is a cascading delete that removes the document from D1, its full text from R2, and its vector from Vectorize. This action is irreversible.

SDL

deleteDocument(id: ID!): Boolean!

Parameters

Parameter	Type	Description
id	ID!	The document ID to delete.

Return Type

Returns true on success.

Example

curl -X POST https://api.ontrove.sh/graphql \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "mutation DeleteDoc($id: ID!) { deleteDocument(id: $id) }",
    "variables": { "id": "doc_abc123" }
  }'

---

deleteDocumentsByConnector

Delete all documents belonging to a connector. Useful for clearing a connector’s data before a full re-sync. This action is irreversible.

SDL

deleteDocumentsByConnector(connectorId: ID!): Int!

Parameters

Parameter	Type	Description
connectorId	ID!	The connector whose documents should be deleted.

Return Type

Returns the number of documents deleted as an Int.

Example

curl -X POST https://api.ontrove.sh/graphql \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "mutation ClearConnector($connectorId: ID!) { deleteDocumentsByConnector(connectorId: $connectorId) }",
    "variables": { "connectorId": "conn_abc123" }
  }'

---

updateDocumentTags

Replace the full tag array on a document. This overwrites all existing tags with the new set.

SDL

updateDocumentTags(id: ID!, tags: [String!]!): Document!

Parameters

Parameter	Type	Description
id	ID!	The document ID.
tags	[String!]!	The new tag array. Pass an empty array to clear all tags.

Return Type

Returns the updated Document.

Example

curl -X POST https://api.ontrove.sh/graphql \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "mutation UpdateTags($id: ID!, $tags: [String!]!) { updateDocumentTags(id: $id, tags: $tags) { id title tags } }",
    "variables": {
      "id": "doc_abc123",
      "tags": ["architecture", "must-read", "2026"]
    }
  }'