# Revinho Developer API, MCP, and OpenAPI Reference
> Developer documentation for the Revinho read-only REST API, OpenAPI contract, and MCP server.
- Canonical: https://www.revinho.com/docs
- Markdown: https://www.revinho.com/docs.md
- Updated: 2026-08-23

---

Query the same evidence-led business intelligence shown in Revinho through a small read-only REST API or hosted MCP server. One workspace token gives trusted server-side access to six report resources and a bounded investigation workflow.

- REST base URL: `https://www.revinho.com/api/v1`
- MCP endpoint: `https://www.revinho.com/api/mcp`
- OpenAPI 3.1 specification: `https://www.revinho.com/openapi.json`
- JSON responses
- Bearer authentication
- No write methods

## Quickstart

1. Open **Setup your agent** in Revinho and create a token. Tokens begin with `rv_live_` and are shown once.
2. Store it as `REVINHO_TOKEN` in a secret manager or private environment file.
3. Use the workspace slug from the app URL and request a report. The default reporting range is 30 days.

```sh
curl --request GET \
  --url "https://www.revinho.com/api/v1/workspaces/acme/overview?range=30d" \
  --header "Authorization: Bearer $REVINHO_TOKEN"
```

## Authentication

REST and MCP use the same workspace-scoped bearer token:

```http
Authorization: Bearer rv_live_your_private_token
```

Treat tokens like passwords. Never place one in a URL, browser client, prompt, screenshot, repository, shared terminal, or application log.

The complete machine-readable REST contract is published as [Revinho OpenAPI 3.1 JSON](https://www.revinho.com/openapi.json).

## REST endpoints

All resources use `GET /workspaces/{workspaceSlug}/{resource}`. The workspace slug must match the token’s workspace. Successful responses use `Cache-Control: private, no-store`.

### GET /workspaces/{workspaceSlug}/overview — Business overview

Headline metrics, previous-period comparisons, trends, acquisition context, and top deterministic insights.

- Optional query parameters: range, filters, funnel
- Common `data` fields: currency, ready, missing, period, metrics, insights, trend, acquisition, funnel, lastUpdatedAt

### GET /workspaces/{workspaceSlug}/growth — Acquisition performance

Channels, sources, campaigns, organic search demand, page acquisition, and daily traffic trends.

- Optional query parameters: range, filters
- Common `data` fields: range, totals, channels, sources, campaigns, countries, organicQueries, pages, trend, sourceTrend, latestRun

### GET /workspaces/{workspaceSlug}/funnels — Saved GA4 journeys

Available funnel definitions and step-by-step performance for the selected GA4 journey.

- Optional query parameters: range, funnel
- Common `data` fields: property, period, funnels, selectedFunnel, report, error

### GET /workspaces/{workspaceSlug}/pages — Page intelligence

Page traffic, key events, conversion, Search Console demand, classifications, and source freshness.

- Optional query parameters: range, filters
- Common `data` fields: workspace, ga, searchConsole, range, pages, latestSearchDate, filterOptions, filterApplicability

### GET /workspaces/{workspaceSlug}/revenue — Stripe revenue

Stripe-sourced revenue, refunds, MRR, subscriptions, customers, plans, countries, and currency conversion metadata.

- Optional query parameters: range, filters
- Common `data` fields: range, totals, mrr, activeSubscriptions, trend, revenueStreams, plans, countries, customerMix, conversion, nativeTotals, latestRun

### GET /workspaces/{workspaceSlug}/opportunities — Ranked opportunities

Up to 30 active deterministic insights with score, severity, evidence, attribution quality, and reporting period.

- Optional query parameters: none
- Common `data` fields: period, insights, hasSearchConsole

## Streamable HTTP MCP server

Connect an MCP-compatible agent to `https://www.revinho.com/api/mcp`. The client manages initialization, sessions, and JSON-RPC transport.

During initialization, Revinho advertises instructions for choosing the smallest useful set of reports, keeping ranges and filters consistent, and preserving revenue, attribution, causality, freshness, annotation, and null-value boundaries.

```json
{
  "mcpServers": {
    "revinho": {
      "type": "streamable-http",
      "url": "https://www.revinho.com/api/mcp",
      "headers": {
        "Authorization": "Bearer rv_live_REPLACE_WITH_YOUR_TOKEN"
      }
    }
  }
}
```

Available tools:

- `get_overview`: Business overview; optional input: range, filters, funnel
- `get_growth`: Acquisition performance; optional input: range, filters
- `get_funnels`: Saved GA4 journeys; optional input: range, funnel
- `get_pages`: Page intelligence; optional input: range, filters
- `get_revenue`: Stripe revenue; optional input: range, filters
- `get_opportunities`: Ranked opportunities; optional input: none

Clients that expose MCP prompts can invoke `investigate_business` with a required `question` and optional `range`. The prompt guides the agent through evidence-checkable candidate explanations, relevant follow-up reports, stopping conditions, and a concise answer contract.

Every tool is read-only, non-destructive, idempotent, and closed-world. Results include an explicit output schema, structured content, and a JSON text block.

## Reporting ranges

- `7d`: last 7 days
- `30d`: last 30 days; default
- `90d`: last 90 days
- `mtd`: month to date
- Custom interval: `?range=custom:2026-07-01:2026-07-31`
- Comparison: `?compare=previous_period`, `previous_year`, `none`, or an earlier equal-length custom interval

Preset windows use measured days. Custom intervals use inclusive UTC dates and are available through REST and MCP. Opportunities ignore `range` and use their deterministic evaluation period.

## Reporting filters

Pass filter groups as URL-encoded JSON. Every group must match; clauses inside a group use its `and` or `or` operator. Supported dimensions are `page`, `landingPage`, `channel`, `source`, `medium`, `campaign`, `country`, `device`, and `currency`.

Limits: 4 groups, 8 clauses per group, 20 values per clause, and 8,000 serialized characters. Source support varies by dimension. Inspect `filterApplicability` before describing a result as filtered. Stripe totals in a filtered overview remain unfiltered associated context.

## Response envelope

Every REST report wraps resource-specific `data` with:

- `workspace`: requested workspace slug
- `resource`: report resource
- `range`: selected range, omitted for opportunities
- `comparison`: selected comparison, omitted for opportunities and funnels
- `generatedAt`: response generation time, not provider freshness
- `data`: resource-specific report; it may be null or partial
- `filters`: parsed filter model
- `annotations`: user-provided workspace events inside the period
- `annotationBoundary`: reminder that annotations are context, not causal evidence

Dates are ISO 8601 strings. Big integers, including financial bigint values, are serialized as strings. Sensitive credential fields are removed. Null is not zero.

## Errors

Every REST error returns JSON with `error.code`, `error.message`, and an actionable `error.resolution` hint.

- `400 invalid_filters`: validate and URL-encode filter JSON
- `401 unauthorized`: send a valid active bearer token
- `404 not_found`: check the resource and workspace slug
- `405 method_not_allowed`: use `GET` for read-only reports
- `429 rate_limited`: wait for the reported `Retry-After` interval
- `500 server_error`: retry later with bounded backoff

MCP authentication failures use JSON-RPC code `-32001` with HTTP 401. Provider issues may appear inside a successful report as an error field, null report, or missing flag.

## Data contracts agents must preserve

1. **Stripe is revenue truth.** Never substitute GA4 revenue or an acquisition estimate for Stripe financial facts.
2. **Money uses minor units.** Read the currency and field definition before formatting an integer.
3. **Attribution stays labeled.** Preserve verified, modeled, and associated provenance.
4. **Association is not causation.** Say “coincided with,” “associated with,” or “during the same period” unless evidence is deterministic.
5. **Freshness is explicit.** Use provider sync fields, not `generatedAt`, for data freshness.
6. **Null is not zero.** Missing evidence must not be silently coerced.

## Security

Tokens are read-only, workspace-scoped, stored as cryptographic hashes, and revocable. Create a separate named token for each agent, server, or environment; keep it in a secret manager; call Revinho only from a trusted runtime; and revoke access when it is no longer needed.