{"openapi":"3.1.0","jsonSchemaDialect":"https://json-schema.org/draft/2020-12/schema","info":{"title":"Revinho Developer API","version":"1.0.0","description":"Read-only, workspace-scoped access to Revinho business-intelligence reports. Stripe is the source of truth for revenue. Preserve verified, modeled, and associated attribution labels, and do not describe association as causation.","contact":{"name":"Revinho developer support","email":"hello@revinho.com"}},"servers":[{"url":"https://www.revinho.com","description":"Production"}],"externalDocs":{"description":"Revinho REST API, authentication, MCP, filters, and interpretation documentation","url":"https://www.revinho.com/docs"},"tags":[{"name":"Discovery","description":"Public machine-readable API directories."},{"name":"Workspace reports","description":"Authenticated, read-only workspace intelligence."}],"paths":{"/api":{"get":{"operationId":"getApiDirectory","summary":"Discover Revinho developer resources","tags":["Discovery"],"security":[],"responses":{"200":{"description":"Links to the OpenAPI contract, human documentation, REST API, MCP server, and llms.txt.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/api/v1":{"get":{"operationId":"getApiV1Directory","summary":"Discover Revinho API v1","tags":["Discovery"],"security":[],"responses":{"200":{"description":"The API v1 resource directory and authentication scheme.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/api/v1/workspaces/{workspaceSlug}/overview":{"get":{"operationId":"getWorkspaceOverview","summary":"Get the business overview","description":"Returns headline metrics, previous-period comparisons, trends, acquisition context, and top deterministic insights.","tags":["Workspace reports"],"security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/WorkspaceSlug"},{"$ref":"#/components/parameters/Range"},{"$ref":"#/components/parameters/Comparison"},{"$ref":"#/components/parameters/Filters"},{"$ref":"#/components/parameters/Funnel"}],"responses":{"200":{"description":"A workspace-scoped report envelope. Data can be partial when a provider is unavailable.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ReportEnvelope"},{"type":"object","properties":{"resource":{"const":"overview"},"data":{"$ref":"#/components/schemas/OverviewData"}}}]}}}},"400":{"description":"The reporting filters are invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"The bearer token is missing, invalid, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"The workspace or report resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"The shared per-token request limit was exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"The report could not be generated because of an unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/workspaces/{workspaceSlug}/growth":{"get":{"operationId":"getWorkspaceGrowth","summary":"Get acquisition performance","description":"Returns channels, sources, campaigns, organic search demand, page acquisition, and daily traffic trends.","tags":["Workspace reports"],"security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/WorkspaceSlug"},{"$ref":"#/components/parameters/Range"},{"$ref":"#/components/parameters/Comparison"},{"$ref":"#/components/parameters/Filters"}],"responses":{"200":{"description":"A workspace-scoped report envelope. Data can be partial when a provider is unavailable.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ReportEnvelope"},{"type":"object","properties":{"resource":{"const":"growth"},"data":{"$ref":"#/components/schemas/GrowthData"}}}]}}}},"400":{"description":"The reporting filters are invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"The bearer token is missing, invalid, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"The workspace or report resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"The shared per-token request limit was exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"The report could not be generated because of an unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/workspaces/{workspaceSlug}/funnels":{"get":{"operationId":"getWorkspaceFunnels","summary":"Get saved GA4 journeys","description":"Returns available funnel definitions and step-by-step performance for the selected GA4 journey.","tags":["Workspace reports"],"security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/WorkspaceSlug"},{"$ref":"#/components/parameters/Range"},{"$ref":"#/components/parameters/Funnel"}],"responses":{"200":{"description":"A workspace-scoped report envelope. Data can be partial when a provider is unavailable.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ReportEnvelope"},{"type":"object","properties":{"resource":{"const":"funnels"},"data":{"$ref":"#/components/schemas/FunnelsData"}}}]}}}},"400":{"description":"The reporting filters are invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"The bearer token is missing, invalid, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"The workspace or report resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"The shared per-token request limit was exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"The report could not be generated because of an unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/workspaces/{workspaceSlug}/pages":{"get":{"operationId":"getWorkspacePages","summary":"Get page intelligence","description":"Returns page traffic, key events, conversion, Search Console demand, classifications, and source freshness.","tags":["Workspace reports"],"security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/WorkspaceSlug"},{"$ref":"#/components/parameters/Range"},{"$ref":"#/components/parameters/Comparison"},{"$ref":"#/components/parameters/Filters"}],"responses":{"200":{"description":"A workspace-scoped report envelope. Data can be partial when a provider is unavailable.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ReportEnvelope"},{"type":"object","properties":{"resource":{"const":"pages"},"data":{"$ref":"#/components/schemas/PagesData"}}}]}}}},"400":{"description":"The reporting filters are invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"The bearer token is missing, invalid, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"The workspace or report resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"The shared per-token request limit was exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"The report could not be generated because of an unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/workspaces/{workspaceSlug}/revenue":{"get":{"operationId":"getWorkspaceRevenue","summary":"Get Stripe revenue intelligence","description":"Returns Stripe-sourced revenue, refunds, MRR, subscriptions, customers, plans, countries, and currency-conversion metadata.","tags":["Workspace reports"],"security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/WorkspaceSlug"},{"$ref":"#/components/parameters/Range"},{"$ref":"#/components/parameters/Comparison"},{"$ref":"#/components/parameters/Filters"}],"responses":{"200":{"description":"A workspace-scoped report envelope. Data can be partial when a provider is unavailable.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ReportEnvelope"},{"type":"object","properties":{"resource":{"const":"revenue"},"data":{"$ref":"#/components/schemas/RevenueData"}}}]}}}},"400":{"description":"The reporting filters are invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"The bearer token is missing, invalid, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"The workspace or report resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"The shared per-token request limit was exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"The report could not be generated because of an unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/workspaces/{workspaceSlug}/opportunities":{"get":{"operationId":"getWorkspaceOpportunities","summary":"Get ranked opportunities","description":"Returns up to 30 active deterministic insights with score, severity, evidence, attribution quality, and reporting period.","tags":["Workspace reports"],"security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/WorkspaceSlug"}],"responses":{"200":{"description":"A workspace-scoped report envelope. Data can be partial when a provider is unavailable.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ReportEnvelope"},{"type":"object","properties":{"resource":{"const":"opportunities"},"data":{"$ref":"#/components/schemas/OpportunitiesData"}}}]}}}},"400":{"description":"The reporting filters are invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"The bearer token is missing, invalid, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"The workspace or report resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"The shared per-token request limit was exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"The report could not be generated because of an unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"rv_live_ token","description":"Create a revocable, workspace-scoped token from Setup your agent in Revinho."}},"parameters":{"WorkspaceSlug":{"name":"workspaceSlug","in":"path","required":true,"description":"Workspace slug from the Revinho app URL. It must match the token's workspace.","schema":{"type":"string","minLength":1}},"Range":{"name":"range","in":"query","required":false,"description":"Reporting window. Presets use measured days; custom REST intervals use inclusive UTC dates. Defaults to 30d.","schema":{"type":"string","pattern":"^(7d|30d|90d|mtd|custom:[0-9]{4}-[0-9]{2}-[0-9]{2}:[0-9]{4}-[0-9]{2}-[0-9]{2})$","default":"30d"}},"Comparison":{"name":"compare","in":"query","required":false,"description":"Comparison baseline. Custom intervals must be earlier than and equal in duration to the selected range.","schema":{"type":"string","pattern":"^(previous_period|previous_year|none|custom:[0-9]{4}-[0-9]{2}-[0-9]{2}:[0-9]{4}-[0-9]{2}-[0-9]{2})$","default":"previous_period"}},"Filters":{"name":"filters","in":"query","required":false,"description":"URL-encoded reporting-filter JSON with up to 4 groups, 8 clauses per group, and 20 values per clause.","schema":{"type":"string","maxLength":8000}},"Funnel":{"name":"funnel","in":"query","required":false,"description":"A funnel ID returned by the API, such as preset:purchase or custom:<id>.","schema":{"type":"string"}}},"schemas":{"ReportEnvelope":{"type":"object","required":["workspace","resource","generatedAt","data","filters","annotations","annotationBoundary"],"properties":{"workspace":{"type":"string"},"resource":{"type":"string","enum":["overview","growth","funnels","pages","revenue","opportunities"]},"range":{"type":"string","description":"Normalized range. Omitted for opportunities."},"comparison":{"type":"string","description":"Normalized comparison selection. Omitted for opportunities and funnels."},"generatedAt":{"type":"string","format":"date-time","description":"Response generation time, not provider-data freshness."},"data":{"type":["object","null"],"additionalProperties":true},"filters":{"type":"object","additionalProperties":true},"annotations":{"type":"array","items":{"type":"object","additionalProperties":true}},"annotationBoundary":{"type":"string"}}},"ErrorEnvelope":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","resolution"],"properties":{"code":{"type":"string","enum":["invalid_filters","unauthorized","not_found","rate_limited","method_not_allowed","server_error"]},"message":{"type":"string"},"resolution":{"type":"string"},"retryAfterSeconds":{"type":"integer","minimum":1}}}}},"OverviewData":{"type":["object","null"],"description":"Resource-specific report data. Provider availability and filters determine which optional fields are present.","properties":{"currency":{},"ready":{},"missing":{},"period":{},"metrics":{},"insights":{},"trend":{},"acquisition":{},"funnel":{},"lastUpdatedAt":{},"filterApplicability":{}},"additionalProperties":true},"GrowthData":{"type":["object","null"],"description":"Resource-specific report data. Provider availability and filters determine which optional fields are present.","properties":{"range":{},"totals":{},"channels":{},"sources":{},"campaigns":{},"countries":{},"organicQueries":{},"pages":{},"trend":{},"sourceTrend":{},"latestRun":{},"filterApplicability":{}},"additionalProperties":true},"FunnelsData":{"type":["object","null"],"description":"Resource-specific report data. Provider availability and filters determine which optional fields are present.","properties":{"property":{},"period":{},"funnels":{},"selectedFunnel":{},"report":{},"error":{}},"additionalProperties":true},"PagesData":{"type":["object","null"],"description":"Resource-specific report data. Provider availability and filters determine which optional fields are present.","properties":{"workspace":{},"ga":{},"searchConsole":{},"range":{},"pages":{},"latestSearchDate":{},"filterOptions":{},"filterApplicability":{}},"additionalProperties":true},"RevenueData":{"type":["object","null"],"description":"Resource-specific report data. Provider availability and filters determine which optional fields are present.","properties":{"range":{},"totals":{},"mrr":{},"activeSubscriptions":{},"trend":{},"revenueStreams":{},"plans":{},"countries":{},"customerMix":{},"conversion":{},"nativeTotals":{},"latestRun":{},"filterApplicability":{}},"additionalProperties":true},"OpportunitiesData":{"type":["object","null"],"description":"Resource-specific report data. Provider availability and filters determine which optional fields are present.","properties":{"period":{},"insights":{},"hasSearchConsole":{}},"additionalProperties":true}}},"x-revinho-mcp":{"endpoint":"https://www.revinho.com/api/mcp","transport":"Streamable HTTP","authentication":"Bearer rv_live_<token>","documentation":"https://www.revinho.com/docs#mcp","note":"MCP uses the same workspace-scoped token and shared rate limit as REST."}}