Revinho Developer API Reference

1. 1

   Create an API token

   Open Setup your agent in the Revinho app navigation. Tokens begin with rv_live_and are shown only once.

2. 2

   Set the bearer header

   Store the token as REVINHO_TOKEN in a secret manager or private environment file.

3. 3

   Call a report

   Use the workspace slug from the app URL. The reporting range defaults to 30 days.

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

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

Clients that expose MCP prompts can invoke investigate_business with a required question plus optional range and comparison. It guides the agent through a bounded investigation, including evidence checks, stopping conditions, and the final answer contract.

Every tool declares read-only, non-destructive, idempotent, and closed-world annotations. Results are returned against an explicit output schema as both structured content and a JSON text content block.

• An absent or invalid range falls back to 30d.
• Opportunities use their deterministic evaluation period and ignore range.
• Comparison defaults to previous_period. Use previous_year, none, or an earlier equal-length custom interval when needed.
• REST and MCP both support presets and custom ranges.

{
  "groups": [
    {
      "operator": "and",
      "clauses": [
        { "dimension": "channel", "values": ["Organic Search"] },
        { "dimension": "country", "values": ["PT", "GB"] }
      ]
    }
  ]
}

FILTERS='{"groups":[{"operator":"and","clauses":[{"dimension":"channel","values":["Organic Search"]}]}]}'

curl --get \
  --header "Authorization: Bearer $REVINHO_TOKEN" \
  --data-urlencode "range=30d" \
  --data-urlencode "filters=$FILTERS" \
  "https://www.revinho.com/api/v1/workspaces/acme/growth"

Source support varies by dimension. Read filterApplicability before describing a result as filtered. Stripe totals in a filtered overview remain unfiltered associated context.

Every authenticated HTTP request counts, including requests that return validation or not-found errors. Cache responses when appropriate and use bounded backoff after a 429 response.

{
  "workspace": "acme",
  "resource": "overview",
  "range": "30d",
  "generatedAt": "2026-08-07T10:42:18.000Z",
  "data": {
    "currency": "EUR",
    "ready": true,
    "period": {
      "startDate": "2026-07-08T00:00:00.000Z",
      "endDate": "2026-08-06T00:00:00.000Z"
    },
    "metrics": { "...": "resource-specific fields" },
    "insights": [],
    "filterApplicability": {
      "googleAnalytics": "unfiltered",
      "stripe": "unfiltered"
    }
  },
  "filters": { "groups": [] },
  "annotations": [],
  "annotationBoundary": "Annotations provide context, not causal evidence."
}

Dates are ISO 8601 strings. Integers too large for safe JSON numbers, including financial bigint values, are serialized as strings. Sensitive credential fields are removed.

{
  "error": {
    "code": "unauthorized",
    "message": "A valid Revinho bearer token is required.",
    "resolution": "Create an active workspace token in Setup your agent, then send it as Authorization: Bearer <token>."
  }
}

MCP authentication failures use JSON-RPC error code -32001 with HTTP status 401. MCP rate-limit failures use -32029 with HTTP status 429. Provider-level issues can appear inside a successful report as an error field, null report, or missing flag.