{"openapi":"3.1.0","info":{"title":"Apphud (BYOK) API","version":"0.1.0","description":"Apphud (BYOK) lets an AI assistant read your own Apphud data through the Apphud API with a key you supply (Apphud S2S API key (Expert plan or higher)). Read-only: 8 tools (list_charts, get_chart_options, list_filter_values, get_line_chart, get_line_chart_by_segment, get_column_chart, list_dashboard_widgets, get_dashboard_widget). The BYOK key travels with each request, is used for that one call...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-apphud.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-apphud/docs"},"termsOfService":"https://connectorbay.com/byok-apphud/terms"},"servers":[{"url":"https://byok-apphud.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-apphud/docs"},"security":[{"upstreamKey":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Optional. A Pro API key raises rate limits; no credentials are required."},"upstreamKey":{"type":"apiKey","in":"header","name":"X-Upstream-Key","description":"Your own key for the service this connector wraps (bring your own key). Used for that one call only; never stored, logged or cached."}},"schemas":{"Error":{"type":"object","properties":{"ok":{"const":false},"error":{"type":"object"}}}}},"paths":{"/v1/tools/list_charts":{"post":{"operationId":"list_charts","summary":"List the analytics charts available to the app (MRR, proceeds, retention and more) with each chart's type, locked flag a","description":"List the analytics charts available to the app (MRR, proceeds, retention and more) with each chart's type, locked flag and the calculation options it needs. Analytics API needs an Expert or higher plan. Use for \"Which Apphud analytics charts can I query\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"app_id":{"description":"Apphud application id, an eight-character value such as '60b9058d' from App settings (not the bundle id).","maxLength":200,"title":"App Id","type":"string"}},"required":["app_id"],"title":"list_chartsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_chart_options":{"post":{"operationId":"get_chart_options","summary":"List the segments (split-by fields) and filters a chart supports for the app, plus its calculation options. Use for \"How","description":"List the segments (split-by fields) and filters a chart supports for the app, plus its calculation options. Use for \"How can I split the Apphud proceeds chart\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"app_id":{"description":"Apphud application id, an eight-character value such as '60b9058d' from App settings (not the bundle id).","maxLength":200,"title":"App Id","type":"string"},"chart_id":{"description":"Chart id from list_charts, for example 'proceeds'.","maxLength":200,"title":"Chart Id","type":"string"}},"required":["app_id","chart_id"],"title":"get_chart_optionsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_filter_values":{"post":{"operationId":"list_filter_values","summary":"List the values present in your data for one filter of a chart, for example the countries seen in proceeds. Use for \"Whi","description":"List the values present in your data for one filter of a chart, for example the countries seen in proceeds. Use for \"Which countries appear in my Apphud proceeds data\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"app_id":{"description":"Apphud application id, an eight-character value such as '60b9058d' from App settings (not the bundle id).","maxLength":200,"title":"App Id","type":"string"},"chart_id":{"description":"Chart id from list_charts, for example 'proceeds' or 'mrr'.","maxLength":200,"title":"Chart Id","type":"string"},"filter_id":{"description":"Filter id from get_chart_options, for example 'customer_country'.","maxLength":200,"title":"Filter Id","type":"string"}},"required":["app_id","chart_id","filter_id"],"title":"list_filter_valuesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_line_chart":{"post":{"operationId":"get_line_chart","summary":"Get one aggregate time series for a line chart (for example proceeds or mrr) over a date range, one point per day, week ","description":"Get one aggregate time series for a line chart (for example proceeds or mrr) over a date range, one point per day, week or month. Use for \"What were my Apphud proceeds per week in Q1\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"app_id":{"description":"Apphud application id, an eight-character value such as '60b9058d' from App settings (not the bundle id).","maxLength":200,"title":"App Id","type":"string"},"chart_id":{"description":"Chart id from list_charts, for example 'proceeds' or 'mrr'.","maxLength":200,"title":"Chart Id","type":"string"},"from_time":{"description":"Range start as ISO 8601 with offset, for example 2026-01-01T00:00:00.000+00:00. The offset sets the day boundaries.","maxLength":200,"title":"From Time","type":"string"},"to_time":{"description":"Range end as ISO 8601 with the same offset as the start, for example 2026-03-31T23:59:59.999+00:00.","maxLength":200,"title":"To Time","type":"string"},"view_by":{"anyOf":[{"enum":["86400","604800","2592000"],"type":"string"},{"type":"null"}],"default":null,"description":"Seconds per data point as text: 86400 (days), 604800 (weeks) or 2592000 (months). A range may produce at most 190 points.","title":"View By"},"calculate_using":{"anyOf":[{"enum":["proceeds","sales"],"type":"string"},{"type":"null"}],"default":null,"description":"Revenue basis for charts that support it: proceeds or sales.","title":"Calculate Using"},"exclude_refunds":{"anyOf":[{"enum":["with_refunds","without_refunds"],"type":"string"},{"type":"null"}],"default":null,"description":"Refund handling for charts that support it: with_refunds or without_refunds.","title":"Exclude Refunds"}},"required":["app_id","chart_id","from_time","to_time"],"title":"get_line_chartArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_line_chart_by_segment":{"post":{"operationId":"get_line_chart_by_segment","summary":"Get a line chart split into one series per segment value, for example proceeds per customer country. Use for \"Which coun","description":"Get a line chart split into one series per segment value, for example proceeds per customer country. Use for \"Which countries brought the most Apphud proceeds in Q1\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"app_id":{"description":"Apphud application id, an eight-character value such as '60b9058d' from App settings (not the bundle id).","maxLength":200,"title":"App Id","type":"string"},"chart_id":{"description":"Chart id from list_charts, for example 'proceeds' or 'mrr'.","maxLength":200,"title":"Chart Id","type":"string"},"from_time":{"description":"Range start as ISO 8601 with offset, for example 2026-01-01T00:00:00.000+00:00. The offset sets the day boundaries.","maxLength":200,"title":"From Time","type":"string"},"to_time":{"description":"Range end as ISO 8601 with the same offset as the start, for example 2026-03-31T23:59:59.999+00:00.","maxLength":200,"title":"To Time","type":"string"},"segment":{"description":"Segment id to split by, from get_chart_options, for example 'customer_country'.","maxLength":200,"title":"Segment","type":"string"},"view_by":{"anyOf":[{"enum":["86400","604800","2592000"],"type":"string"},{"type":"null"}],"default":null,"description":"Seconds per data point as text: 86400 (days), 604800 (weeks) or 2592000 (months). A range may produce at most 190 points.","title":"View By"},"calculate_using":{"anyOf":[{"enum":["proceeds","sales"],"type":"string"},{"type":"null"}],"default":null,"description":"Revenue basis for charts that support it: proceeds or sales.","title":"Calculate Using"},"exclude_refunds":{"anyOf":[{"enum":["with_refunds","without_refunds"],"type":"string"},{"type":"null"}],"default":null,"description":"Refund handling for charts that support it: with_refunds or without_refunds.","title":"Exclude Refunds"}},"required":["app_id","chart_id","from_time","to_time","segment"],"title":"get_line_chart_by_segmentArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_column_chart":{"post":{"operationId":"get_column_chart","summary":"Get a column-type report (for example renewals performance) as rows split by a segment, with paging and no total count. ","description":"Get a column-type report (for example renewals performance) as rows split by a segment, with paging and no total count. Use for \"How are my Apphud renewals performing by country\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"app_id":{"description":"Apphud application id, an eight-character value such as '60b9058d' from App settings (not the bundle id).","maxLength":200,"title":"App Id","type":"string"},"chart_id":{"description":"Chart id from list_charts, for example 'proceeds' or 'mrr'.","maxLength":200,"title":"Chart Id","type":"string"},"from_time":{"description":"Range start as ISO 8601 with offset, for example 2026-01-01T00:00:00.000+00:00. The offset sets the day boundaries.","maxLength":200,"title":"From Time","type":"string"},"to_time":{"description":"Range end as ISO 8601 with the same offset as the start, for example 2026-03-31T23:59:59.999+00:00.","maxLength":200,"title":"To Time","type":"string"},"segment":{"description":"Segment id to split by, from get_chart_options, for example 'customer_country'.","maxLength":200,"title":"Segment","type":"string"},"view_by":{"anyOf":[{"enum":["86400","604800","2592000"],"type":"string"},{"type":"null"}],"default":null,"description":"Seconds per data point as text: 86400 (days), 604800 (weeks) or 2592000 (months). A range may produce at most 190 points.","title":"View By"},"calculate_using":{"anyOf":[{"enum":["proceeds","sales"],"type":"string"},{"type":"null"}],"default":null,"description":"Revenue basis for charts that support it: proceeds or sales.","title":"Calculate Using"},"exclude_refunds":{"anyOf":[{"enum":["with_refunds","without_refunds"],"type":"string"},{"type":"null"}],"default":null,"description":"Refund handling for charts that support it: with_refunds or without_refunds.","title":"Exclude Refunds"},"limit":{"anyOf":[{"maximum":2000,"minimum":1,"type":"integer"},{"type":"null"}],"default":100,"description":"Rows per page (1 to 2000).","title":"Limit"},"offset":{"anyOf":[{"maximum":1000000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Rows to skip.","title":"Offset"}},"required":["app_id","chart_id","from_time","to_time","segment"],"title":"get_column_chartArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_dashboard_widgets":{"post":{"operationId":"list_dashboard_widgets","summary":"List the dashboard tile catalog: current-state tiles (MRR, active subscriptions) and period tiles (proceeds, trials, ref","description":"List the dashboard tile catalog: current-state tiles (MRR, active subscriptions) and period tiles (proceeds, trials, refunds) with their widget ids. Use for \"Which dashboard widgets does Apphud offer and what are their ids\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"list_dashboard_widgetsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_dashboard_widget":{"post":{"operationId":"get_dashboard_widget","summary":"Get one dashboard tile value for a period with the comparison to the previous period (for example proceeds in the last 3","description":"Get one dashboard tile value for a period with the comparison to the previous period (for example proceeds in the last 30 days). Use for \"How much did I earn in the last 30 days compared to before in Apphud\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"app_id":{"description":"Apphud application id, an eight-character value such as '60b9058d' from App settings (not the bundle id).","maxLength":200,"title":"App Id","type":"string"},"widget_id":{"description":"Widget id (a UUID) from list_dashboard_widgets.","maxLength":200,"title":"Widget Id","type":"string"},"time_ago":{"anyOf":[{"enum":["today","yesterday","last_7_days","last_30_days","last_90_days","this_month","last_month","this_year","last_year"],"type":"string"},{"type":"null"}],"default":"last_90_days","description":"Period preset: today, yesterday, last_7_days, last_30_days, last_90_days, this_month, last_month, this_year or last_year (default last_90_days).","title":"Time Ago"}},"required":["app_id","widget_id"],"title":"get_dashboard_widgetArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}}}}