Docs Developers API

API.

Every figure a screen shows, as JSON. Read-only: nothing here approves, changes or writes, and every number is calculated from your records, never estimated.

Authorization

Two kinds of bearer token: the organization's key from Settings → Claude Code and Cursor, or the token an app gets when a person signs in through the MCP server.

A key reads one organization. A token reads one organization as one person.

curl https://app.valistry.ai/api/v1/inventory?days=30 \
  -H "Authorization: Bearer vly_mcp_…"

Resources

/api/v1/estate: Total, sources, coverage, unallocated, low-effort savings, governed share, the spike, the month at this pace. Parameters: days.
/api/v1/spend: Spend by one dimension, each group's share and tokens; against the period before when asked. Parameters: by, days, compare.
/api/v1/findings: Every opportunity with its evidence, the change to make, how it is verified, and where it is tracked. Parameters: status: open, approved, verified or all.
/api/v1/ledger: Every decision, with the saving expected on approval and the saving measured after.
/api/v1/policies: Every policy with what happens if it goes over, owner, the metric against its threshold, and the budget at this pace. Parameters: days.
/api/v1/forecast: Where this month lands from your own days, its method in one sentence, the band, and the assumptions that produced it. Parameters: basis: 30, 90 or 180; growth, share, to, change, vendor, seats, taken.
/api/v1/alerts: Every alert raised in this period, with its state and whether it was sent. Parameters: days, state.
/api/v1/ask: A question in plain words, answered with the figure, the plan that produced it and the evidence. Parameters: q, days.
POST /api/v1/records: Your own records, in the shape every connector writes: a bill, an export, a vendor we have no connector for. Needs the push key, not the read key.

Every response says the period it covers. A Starter organization gets what its screens show: what was spent, never who owns it or what to change.

On Enterprise, the same figures are also pushed nightly to an endpoint you name, signed.

The MCP server

The same tools, as a Model Context Protocol server at the same address, for Claude Code, Cursor and Claude. A question in plain words becomes a typed plan, the plan runs over the engine, and the figure comes back with its evidence. In a chat app, you sign in; in an editor, you use the key.

Endpoint: https://app.valistry.ai/api/mcp
Transport: Streamable HTTP, JSON-RPC by POST, stateless.
Sign-in: OAuth 2.1 with PKCE; the server registers clients itself and names its metadata on a 401.
Tools: ask · spend · estate · opportunities · ledger · policies · alerts

For an agent that reads before it signs in, these docs are also one text file: llms.txt.