API, SDK, and MCP

Download the OpenAPI 3.1 definition.

Surface	URL
GEO Platform	https://geo.thyris.cloud
GEO REST API	https://geo.thyris.cloud/api/v1/geo
GEO MCP	https://geo.thyris.cloud/api/v1/geo/mcp

Authentication

Send a GEO platform API key as either:

Authorization: Bearer <api-key>

or:

x-api-key: <api-key>

Keys belong to a tenant and can be tenant-, workspace-, or custom-workspace-scoped. Recommended permissions are geo:read, geo:signals:write, geo:draft, geo:approve, geo:execute, and the mutation permission geo:write where enabled. Use minimum permissions, expiration and revocation.

Public API surfaces

Endpoint	Purpose
GET /api/v1/geo/analytics	Query versioned datasets such as metrics, recommendations, actions, reports, attribution, content and dashboards
GET/POST /api/v1/geo/target-graph	Read/import the graph or merge canonical targets
GET/POST /api/v1/geo/privacy	Read or submit pseudonymous privacy requests
POST /api/v1/geo/mcp	JSON-RPC MCP endpoint
GET /api/v1/geo/exports/{exportId}	Download an authorized export
POST /api/v2/geo/events	Ingest consent-aware tracking events using a site token
Dashboard share routes	Create/revoke governed shares and read a valid shared dashboard token

Target Graph mutations require Idempotency-Key. Workspace ownership is verified against the key's Organization and Tenant; passing another Workspace UUID does not broaden access.

Request conventions

Concern	Contract
Workspace	Supply the required workspaceId; authorization is still verified server-side
Idempotency	Required for Target Graph mutation and external-action contracts that declare it
Limits	Dataset and MCP list operations enforce bounded limits
Versions	Metric, target, content, report and experiment results retain version context
Time	Send/interpret timestamps as ISO 8601; reporting timezones are explicit configuration
Errors	Do not infer resource existence from unauthorized responses
Secrets	Use API keys only from server-side clients; tracking uses a separate site token

TypeScript SDK

import { GeoClient } from "@thyris/geo-sdk";

const geo = new GeoClient({
  baseUrl: "https://geo.thyris.cloud",
  apiKey: process.env.THYRIS_GEO_API_KEY!,
});

const metrics = await geo.analytics(process.env.GEO_WORKSPACE_ID!, "metrics");
const graph = await geo.targetGraph(process.env.GEO_WORKSPACE_ID!);

Keep API keys server-side. The SDK exposes analytics, Target Graph read/import/merge, privacy requests and MCP calls.

MCP tools

The MCP server supports target graph, metrics, recommendations, actions, content, experiments and immutable reports. geo_request_action_approval moves an action into review; it never executes or publishes it. Read tools require geo:read; approval requests require geo:write.

Tool	Permission	Purpose
geo_get_target_graph	geo:read	Read workspace targets and relations
geo_list_metrics	geo:read	List versioned metrics with confidence/evidence metadata
geo_list_recommendations	geo:read	List evidence-backed recommendations
geo_list_actions	geo:read	List governed actions and approval state
geo_list_content	geo:read	List governed content and approval status
geo_list_experiments	geo:read	List observed experiments separately from simulations
geo_get_report	geo:read	Read an immutable report run
geo_request_action_approval	geo:write	Move a proposed action into approval review only

MCP initialization

The remote endpoint uses JSON-RPC and advertises the supported protocol version and tools. A client should initialize, request tools/list, and invoke only tools allowed by its key and workspace scope.

curl -X POST "https://geo.thyris.cloud/api/v1/geo/mcp" \
  -H "Authorization: Bearer geo_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Example metric request:

curl -X POST "https://geo.thyris.cloud/api/v1/geo/mcp" \
  -H "Authorization: Bearer geo_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"geo_list_metrics","arguments":{"workspaceId":"WORKSPACE_UUID","limit":25}}}'

An MCP client cannot execute or publish an action through the approval-request tool. Execution remains in the governed Action Center workflow.

Error expectations

• 400: invalid request or JSON-RPC shape
• 401: missing/invalid API key or site token
• 403: missing permission, expired authorization, or workspace denial
• 404: owned resource not found
• 409: idempotency conflict
• 422: invalid or cyclic target graph

JSON-RPC errors use protocol error objects even when HTTP status also communicates authentication or validation failure. Clients should inspect both layers and must not retry authorization, schema or cyclic-graph errors as transient failures.