API Overview

Trove exposes a single GraphQL endpoint for all data operations. Every request is scoped to the authenticated user. There are no shared databases or cross-tenant queries.

Base URL

https://api.ontrove.sh

GraphQL Endpoint

POST /graphql

Required Headers

Header	Value
`Authorization`	`Bearer <token>`
`Content-Type`	`application/json`

Request Body

{
  "query": "...",
  "variables": {},
  "operationName": "..."
}

query (required): The GraphQL query or mutation string.
variables (optional): A JSON object of variable values referenced in the query.
operationName (optional): The name of the operation to execute when the query contains multiple operations.

Example Request

curl -X POST https://api.ontrove.sh/graphql \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "{ stats { totalDocuments totalConnectors } }"
  }'

Response Format

Every response returns a JSON object with a data field and an optional errors array:

{
  "data": {
    "stats": {
      "totalDocuments": 1423,
      "totalConnectors": 5
    }
  }
}

When errors occur, the response includes an errors array:

{
  "data": null,
  "errors": [
    {
      "message": "Document not found",
      "locations": [{ "line": 1, "column": 3 }],
      "path": ["document"]
    }
  ]
}

Errors are masked in production. Client-facing messages are intentionally generic to avoid leaking internal state. Detailed error information is available in server logs.

Health Check

GET /health

Returns the service status without authentication:

curl https://api.ontrove.sh/health

{
  "status": "ok",
  "version": "v1"
}

CORS Policy

The API accepts cross-origin requests from the following origins:

Origin	Purpose
`https://ontrove.sh`	Web application
`https://api.ontrove.sh`	API subdomain
`tauri://localhost`	Desktop application

Allowed methods: GET, POST, DELETE, OPTIONS

Allowed headers: Authorization, Content-Type, MCP-Protocol-Version, MCP-Session-Id, Accept

Custom Scalars

The schema uses two custom scalar types:

Scalar	Format	Example
`DateTime`	ISO 8601 string	`"2026-03-25T12:00:00Z"`
`JSON`	Arbitrary JSON value	`{ "key": "value" }`

Other Interfaces

In addition to the GraphQL API, Trove provides:

Sync API (REST) at /api/sync/*. Used by the desktop app and custom connectors to push data into Trove. See Sync API.
MCP transport at /mcp. Model Context Protocol endpoint for AI assistant integrations. See the MCP documentation.