GraphSheets API

GraphSheets holds financial models as typed graphs. This API lets a program read them, evaluate them, and propose changes, which land marked for the person's review. It is the API a connected app reaches; the machine-readable description is /api/v1/openapi.json, and the catalog is /.well-known/api-catalog.

Signing in

OAuth 2.1 with PKCE; clients register themselves (RFC 7591). The authorization server's metadata is at /.well-known/oauth-authorization-server. A person may instead make a personal access token on their profile page and send it as Authorization: Bearer gsp_….

• models:read — Read the models you can open, and keep your own private scenarios on them
• models:write — Create models and make changes, which land marked for your review
• data:fetch — Fetch market prices and company filings through GraphSheets
• changes:approve — Approve or reject the changes it proposed, when you tell it to in the conversation

Agent accounts

An agent may have an account of its own, which owns its models and pays for its work. It has no person behind it and no password:

1. POST /api/v1/agents/register with its name, its purpose, jwks: one to three public keys (EdDSA, ES256 or RS256), each with a kid, and acceptTerms: true, accepting the Terms of Service, and at least one working way to tell it things (its account's warnings, key changes): an ownerEmail (the person who answers for it), an agentEmail (its own inbox) and/or a webhookUrl, which must answer a test POST with a 2xx at registration. Each email is mailed its own link; its token, POSTed to /api/v1/agents/register/verify, confirms it, so an agent confirms its own inbox itself. The two are told different things, and only the owner's is shown on its profile. A confirmed email lets it join an organisation that claimed its domain. The answer gives the clientId it will sign in as, a statusUrl and the tokenEndpoint.
2. Once it can be reached (a checked webhook, or the email confirmed), an administrator approves or declines — or it is approved then and there, where this workspace needs no approval for agents. GET the statusUrl to see which: awaiting_approval, approved, declined, suspended (by the administrator) or blocked (by its owner), with reachable.
3. Once approved, it signs in at the token endpoint with grant_type=client_credentials, client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer and client_assertion: A JWT signed with one of your registered keys (EdDSA, ES256 or RS256), its kid the key's: iss and sub your clientId, aud the tokenEndpoint, exp at most 300 seconds after iat, and a jti never used before. An access token for an hour, and no refresh token: sign a fresh assertion when it lapses. The authorization server's metadata does not list private_key_jwt, so that apps signing in for a person do not choose it.
4. To replace its keys, PUT /api/v1/me/keys with the new jwks and an assertion signed with a key it holds now, its aud that route's address; a token alone is refused. Its owner, its own inbox and its webhook are told. GET /api/v1/me/keys lists the keys it holds.

An agent account has no free allowance: every model call, request and stored byte is paid from its credit, at GET /api/v1/me/credit. Where the server takes in-band payment, POST /api/v1/billing/topup answers 402 with an MPP or x402 challenge; by card, POST /api/v1/billing/checkout answers a Stripe Checkout url for whoever pays for the account to open, and the credit lands when Stripe confirms the payment.

Building a model

POST /api/v1/models with title, granularity (month, quarter, half, year or week), start (the first period's label: 2027-01, 2027-Q1, 2027-H1, 2027 or 2027-W01) and periods makes an empty model. Its contents arrive as change-sets: POST /api/v1/models/{uid}/changesets with the model's baseHash, a message, and ops. Each op states what it expects to find, so the order matters. For example:

{"op": "group.add", "group": {"path": "plan", "title": "Plan"}}
{"op": "node.add", "node": {"uid": "node_cups0001", "name": "plan.cups", "title": "Cups sold", "kind": "input",
  "unit": "cups", "inputValues": {"base": [18000, 21000, 24000]}}}
{"op": "node.add", "node": {"uid": "node_rev00001", "name": "plan.revenue", "title": "Revenue", "kind": "calculated",
  "unit": "USD", "formula": "plan.cups * plan.price"}}
{"op": "node.set_formula", "uid": "node_rev00001", "from": "plan.cups * plan.price", "to": "plan.cups * plan.price * 0.98"}
{"op": "values.set", "uid": "node_cups0001", "scenario": "base", "changes": [{"period": "2027", "from": 18000, "to": 19000}]}

The operations are: node.add, node.remove, node.rename, node.set_formula, node.set_kind, node.set_meta, values.set, actuals.set, constant.set, uncertainty.set, statistic.rename, group.add, group.remove, group.rename, group.set_meta, scenario.add, scenario.remove, scenario.rename, scenario.set_meta, ledger.add, ledger.remove, ledger.set_categories, ledger.splice_categories, ledger.set_date_field, ledger.set_span_field, ledger.set_union, entry.add, entry.remove, entry.set, model.set_meta, presentation.set, axis.migrate, unknown.set. A node's fields, and a whole model document (which POST /api/v1/models also takes, as document), are described by the JSON Schema at /api/v1/schemas/model.json.

MCP

The same API is served as an MCP server at https://mcp.graphsheets.ai/mcp, signed in the same way. Its server card is at https://mcp.graphsheets.ai/mcp/server-card, listed in the AI Catalog at /.well-known/ai-catalog.json.

A2A

The same connection answers the Agent2Agent protocol (1.0, JSON-RPC) at https://mcp.graphsheets.ai/a2a; its agent card is at /.well-known/agent-card.json. Each skill is one of the connector's read-only tools, asked for with a data part {"skill": "read-values", "arguments": {…}} and answered at once with a message.

Routes

Errors answer {"error": {"code", "message", "details"}}. Health: /api/v1/health.