{"openapi":"3.0.0","paths":{"/healthz":{"get":{"operationId":"HealthController_healthz","parameters":[],"responses":{"200":{"description":""}},"tags":["Health"]}},"/readyz":{"get":{"operationId":"HealthController_readyz","parameters":[],"responses":{"200":{"description":""}},"tags":["Health"]}},"/v1/connect/request":{"get":{"operationId":"ConnectController_request","parameters":[],"responses":{"200":{"description":""}},"summary":"Pending authorization: requesting client, plan limits and discovered accounts","tags":["connect"]}},"/v1/connect/approve":{"post":{"operationId":"ConnectController_approve","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountsSelectionDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RedirectDto"}}}}},"summary":"Enable the selected accounts and finish the authorization","tags":["connect"]}},"/v1/connect/deny":{"post":{"operationId":"ConnectController_deny","parameters":[],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RedirectDto"}}}}},"summary":"Deny the authorization request","tags":["connect"]}},"/v1/auth/google/start":{"get":{"operationId":"PanelController_start","parameters":[{"name":"return_to","required":true,"in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"summary":"Start the dashboard Google login (browser redirect)","tags":["panel"]}},"/v1/me":{"get":{"operationId":"PanelController_me","parameters":[],"responses":{"200":{"description":""}},"summary":"Current user, organization plan and Google connections","tags":["panel"]}},"/v1/logout":{"post":{"operationId":"PanelController_logout","parameters":[],"responses":{"204":{"description":""}},"tags":["panel"]}},"/v1/accounts":{"get":{"operationId":"PanelController_list","parameters":[],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/AccountDto"}}}}}},"tags":["panel"]},"put":{"operationId":"PanelController_update","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountsSelectionDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/AccountDto"}}}}}},"summary":"Replace the set of enabled accounts (checked against the plan limit)","tags":["panel"]}},"/v1/connections/{id}":{"delete":{"operationId":"PanelController_disconnect","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"204":{"description":""}},"summary":"Disconnect a Google login: revokes it at Google and ends all MCP sessions","tags":["panel"]}},"/v1/billing":{"get":{"operationId":"BillingController_status","parameters":[],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BillingStatusDto"}}}}},"tags":["billing"]}},"/v1/billing/checkout":{"post":{"operationId":"BillingController_checkout","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckoutDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckoutResponseDto"}}}}},"summary":"Start a subscription (returns the payment URL) or switch between Pro and Max","tags":["billing"]}},"/v1/billing/portal":{"post":{"operationId":"BillingController_portal","parameters":[],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UrlDto"}}}}},"summary":"Link to the payment provider portal (card, invoices, cancel)","tags":["billing"]}},"/v1/billing/cancel":{"post":{"operationId":"BillingController_cancel","parameters":[],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BillingStatusDto"}}}}},"summary":"Cancel at the end of the paid period","tags":["billing"]}},"/v1/rules":{"get":{"operationId":"AutomationController_rules","parameters":[{"name":"customer_id","required":false,"in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/RuleDto"}}}}}},"summary":"Scheduled rules (created through the AI with create_rule) and their last runs","tags":["automation"]}},"/v1/rules/{id}":{"delete":{"operationId":"AutomationController_deleteRule","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"204":{"description":""}},"tags":["automation"]}},"/v1/alerts":{"get":{"operationId":"AutomationController_alerts","parameters":[{"name":"customer_id","required":false,"in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/AlertDto"}}}}}},"summary":"Email alerts (created through the AI with create_alert)","tags":["automation"]}},"/v1/alerts/{id}":{"delete":{"operationId":"AutomationController_deleteAlert","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"204":{"description":""}},"tags":["automation"]}},"/v1/changes":{"get":{"operationId":"AutomationController_changes","parameters":[{"name":"customer_id","required":false,"in":"query","schema":{"type":"string"}},{"name":"limit","required":false,"in":"query","description":"1–200, default 50","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ChangeDto"}}}}}},"summary":"Changes applied through Querya (most recent first)","tags":["automation"]}},"/v1/accounts/{customerId}/change-history":{"get":{"operationId":"AutomationController_accountChanges","parameters":[{"name":"customerId","required":true,"in":"path","schema":{"type":"string"}},{"name":"from","required":false,"in":"query","description":"YYYY-MM-DD (account time zone)","schema":{"type":"string"}},{"name":"to","required":false,"in":"query","description":"YYYY-MM-DD (account time zone)","schema":{"type":"string"}},{"name":"limit","required":false,"in":"query","description":"1–200, default 50","schema":{"type":"string"}},{"name":"cursor","required":false,"in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountChangesDto"}}}}},"summary":"Every change made to an enabled account (web, API, scripts and Querya), copied daily from Google Ads","tags":["automation"]}},"/v1/accounts/{customerId}/change-timeline":{"get":{"operationId":"AutomationController_changeTimeline","parameters":[{"name":"customerId","required":true,"in":"path","schema":{"type":"string"}},{"name":"days","required":false,"in":"query","description":"1–365, default 30","schema":{"type":"string"}},{"name":"campaign_id","required":false,"in":"query","schema":{"type":"string"}},{"name":"changed_by","required":false,"in":"query","description":"Author email contains","schema":{"type":"string"}},{"name":"language","required":false,"in":"query","description":"Default: user's","schema":{"enum":["pt","en"],"type":"string"}},{"name":"limit","required":false,"in":"query","description":"1–500, default 200","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TimelineDto"}}}}},"summary":"Readable timeline of what changed in the account and who did it (same as the get_change_timeline tool)","tags":["automation"]}},"/v1/usage":{"get":{"operationId":"AutomationController_usage","parameters":[],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsageDto"}}}}},"summary":"Tool calls in the last 30 days (product metrics)","tags":["automation"]}}},"info":{"title":"Querya API","description":"REST API for the Querya dashboard (app.querya.io).","version":"1","contact":{}},"tags":[],"servers":[],"components":{"securitySchemes":{"cookie":{"type":"apiKey","in":"cookie","name":"qy_session"}},"schemas":{"AccountSelectionDto":{"type":"object","properties":{"id":{"type":"string","description":"Internal account id (from the accounts list)","format":"uuid"},"write_enabled":{"type":"boolean","description":"Allow write tools on this account","default":false}},"required":["id","write_enabled"]},"AccountsSelectionDto":{"type":"object","properties":{"accounts":{"description":"Complete set of accounts to enable. Accounts left out are disabled.","type":"array","items":{"$ref":"#/components/schemas/AccountSelectionDto"}}},"required":["accounts"]},"RedirectDto":{"type":"object","properties":{"redirect_url":{"type":"string","description":"Where the browser must navigate next"}},"required":["redirect_url"]},"AccountDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"customer_id":{"type":"string","example":"1234567890"},"name":{"type":"string","nullable":true},"currency":{"type":"string","nullable":true,"example":"BRL"},"time_zone":{"type":"string","nullable":true,"example":"America/Sao_Paulo"},"is_manager":{"type":"boolean"},"via_manager":{"type":"string","nullable":true,"description":"Manager (MCC) used to access the account"},"parent_customer_id":{"type":"string","nullable":true},"enabled":{"type":"boolean"},"write_enabled":{"type":"boolean"}},"required":["id","customer_id","name","currency","time_zone","is_manager","via_manager","parent_customer_id","enabled","write_enabled"]},"LimitsDto":{"type":"object","properties":{"max_accounts":{"type":"number","nullable":true,"description":"null = unlimited"},"allow_manager":{"type":"boolean"},"writes":{"type":"boolean"},"max_rules":{"type":"number"},"max_alerts":{"type":"number"}},"required":["max_accounts","allow_manager","writes","max_rules","max_alerts"]},"PriceDto":{"type":"object","properties":{"plan":{"type":"string","enum":["pro","max"]},"usd":{"type":"number"},"brl":{"type":"number"}},"required":["plan","usd","brl"]},"ProvidersDto":{"type":"object","properties":{"stripe":{"type":"boolean"},"abacatepay":{"type":"boolean"}},"required":["stripe","abacatepay"]},"WindowAccountDto":{"type":"object","properties":{"customer_id":{"type":"string","example":"1234567890"},"last_used_at":{"type":"string"},"expires_at":{"type":"string","description":"When this account leaves the window if not used again"},"can_use":{"type":"boolean","description":"false = beyond the plan limit (e.g. after a downgrade)"}},"required":["customer_id","last_used_at","expires_at","can_use"]},"AccountUsageDto":{"type":"object","properties":{"enforced":{"type":"boolean","description":"true = the limit is being enforced (show the usage; drop the rollout notice)"},"window_days":{"type":"number","example":30},"limit":{"type":"number","nullable":true,"description":"null = unlimited (Max)"},"used":{"type":"number"},"remaining":{"type":"number","nullable":true,"description":"null = unlimited"},"next_slot_available_at":{"type":"string","nullable":true,"description":"When a new account can be used again (null = a slot is free or unlimited)"},"accounts":{"description":"Accounts in the window, most recent first","type":"array","items":{"$ref":"#/components/schemas/WindowAccountDto"}}},"required":["enforced","window_days","limit","used","remaining","next_slot_available_at","accounts"]},"BillingStatusDto":{"type":"object","properties":{"plan":{"type":"string","enum":["free","pro","max"]},"provider":{"type":"string","enum":["stripe","abacatepay"],"nullable":true},"status":{"type":"string","nullable":true,"description":"active | past_due | null"},"cancel_at_period_end":{"type":"boolean"},"current_period_end":{"type":"string","nullable":true},"limits":{"$ref":"#/components/schemas/LimitsDto"},"prices":{"type":"array","items":{"$ref":"#/components/schemas/PriceDto"}},"providers":{"description":"Which payment options are available","allOf":[{"$ref":"#/components/schemas/ProvidersDto"}]},"account_usage":{"description":"Distinct Google Ads accounts used in the rolling 30-day window (plan limit)","allOf":[{"$ref":"#/components/schemas/AccountUsageDto"}]}},"required":["plan","provider","status","cancel_at_period_end","current_period_end","limits","prices","providers","account_usage"]},"CheckoutDto":{"type":"object","properties":{"plan":{"type":"string","enum":["pro","max"]},"provider":{"type":"string","enum":["stripe","abacatepay"],"description":"stripe = card in USD; abacatepay = card or Pix in BRL"}},"required":["plan","provider"]},"CheckoutResponseDto":{"type":"object","properties":{"url":{"type":"string","nullable":true,"description":"Redirect the user here to pay. Null when an existing subscription was switched (Pro ↔ Max)."},"changed":{"type":"boolean"}}},"UrlDto":{"type":"object","properties":{"url":{"type":"string"}},"required":["url"]},"RuleRunDto":{"type":"object","properties":{"at":{"type":"string"},"status":{"type":"string","description":"ok | no_match | failed | skipped"},"matched":{"type":"number"},"plan_id":{"type":"string","nullable":true},"applied":{"type":"boolean"},"error":{"type":"string","nullable":true}},"required":["at","status","matched","plan_id","applied","error"]},"RuleDto":{"type":"object","properties":{"rule_id":{"type":"string"},"customer_id":{"type":"string"},"name":{"type":"string"},"entity":{"type":"string","enum":["keyword","ad_group","campaign","ad","search_term"]},"conditions":{"type":"string","example":"cost > 100 AND conversions = 0"},"period_days":{"type":"number"},"action":{"type":"string","example":"pause"},"campaign_id":{"type":"string","nullable":true},"schedule":{"type":"string","example":"daily at 08:00 (account time zone)"},"auto_apply":{"type":"boolean"},"status":{"type":"string","description":"active | paused_plan (paused by a downgrade to Free)"},"last_run_at":{"type":"string","nullable":true},"recent_runs":{"type":"array","items":{"$ref":"#/components/schemas/RuleRunDto"}}},"required":["rule_id","customer_id","name","entity","conditions","period_days","action","campaign_id","schedule","auto_apply","status","last_run_at","recent_runs"]},"AlertDto":{"type":"object","properties":{"alert_id":{"type":"string"},"customer_id":{"type":"string"},"type":{"type":"string","enum":["conversions_drop","cpa_above_target","budget_exhausted","ad_disapproved"]},"title":{"type":"string"},"params":{"type":"object"},"schedule":{"type":"string"},"status":{"type":"string"},"last_checked_at":{"type":"string","nullable":true},"last_triggered_at":{"type":"string","nullable":true}},"required":["alert_id","customer_id","type","title","params","schedule","status","last_checked_at","last_triggered_at"]},"ChangeLineDto":{"type":"object","properties":{"resource":{"type":"string"},"field":{"type":"string"},"before":{"type":"object"},"after":{"type":"object"}},"required":["resource","field","after"]},"ChangeDto":{"type":"object","properties":{"change_id":{"type":"string"},"applied_at":{"type":"string"},"customer_id":{"type":"string"},"tool":{"type":"string"},"title":{"type":"string"},"changes":{"type":"array","items":{"$ref":"#/components/schemas/ChangeLineDto"}},"undone_at":{"type":"string","nullable":true},"undoable":{"type":"boolean","description":"Can be reverted (ask the AI: undo_change)"},"not_reversible":{"type":"array","items":{"type":"string"}},"google_request_id":{"type":"string","nullable":true}},"required":["change_id","applied_at","customer_id","tool","title","changes","undone_at","undoable","not_reversible","google_request_id"]},"ChangeSyncDto":{"type":"object","properties":{"status":{"type":"string","enum":["pending","syncing","ready","paused","needs_reconnect","error"]},"coverage_from":{"type":"string","nullable":true,"description":"Stored history starts here (account time zone)"},"synced_through":{"type":"string","nullable":true},"last_run_at":{"type":"string","nullable":true}},"required":["status","coverage_from","synced_through","last_run_at"]},"AccountChangeDto":{"type":"object","properties":{"id":{"type":"string"},"changed_at":{"type":"string","description":"When it happened, in the account time zone","example":"2026-11-16 14:03:22.123456"},"resource_type":{"type":"string","example":"CAMPAIGN_BUDGET"},"resource_id":{"type":"string","nullable":true},"campaign_id":{"type":"string","nullable":true},"ad_group_id":{"type":"string","nullable":true},"operation":{"type":"string","nullable":true,"example":"UPDATE"},"client_type":{"type":"string","nullable":true,"description":"GOOGLE_ADS_WEB_CLIENT, GOOGLE_ADS_API, GOOGLE_ADS_SCRIPTS…"},"via_querya":{"type":"boolean","description":"Matched a change applied through Querya"},"changed_by":{"type":"string","nullable":true,"description":"Who made the change (may be empty)"},"changed_fields":{"type":"array","items":{"type":"string"}},"old_value":{"type":"object","nullable":true,"description":"Previous values of the changed fields"},"new_value":{"type":"object","nullable":true,"description":"New values of the changed fields"}},"required":["id","changed_at","resource_type","resource_id","campaign_id","ad_group_id","operation","client_type","via_querya","changed_by","changed_fields","old_value","new_value"]},"AccountChangesDto":{"type":"object","properties":{"sync":{"$ref":"#/components/schemas/ChangeSyncDto"},"items":{"type":"array","items":{"$ref":"#/components/schemas/AccountChangeDto"}},"next_cursor":{"type":"string","nullable":true,"description":"Pass as cursor for the next page"}},"required":["sync","items","next_cursor"]},"TimelineEntryDto":{"type":"object","properties":{"date":{"type":"string","example":"2026-11-16","description":"Account time zone"},"time":{"type":"string","example":"14:09"},"resource_type":{"type":"string","example":"CAMPAIGN_BUDGET"},"actor":{"type":"string","example":"maria@agencia.com (interface do Google Ads)"},"tool":{"type":"string","description":"GOOGLE_ADS_WEB_CLIENT, GOOGLE_ADS_API, GOOGLE_ADS_SCRIPTS, QUERYA…"},"description":{"type":"string","example":"mudou o orçamento de R$ 100,00 para R$ 200,00"},"campaign_id":{"type":"string","nullable":true},"campaign":{"type":"string","nullable":true},"ad_group_id":{"type":"string","nullable":true},"ad_group":{"type":"string","nullable":true},"changes":{"type":"number","description":"Grouped changes in this line"},"change_ids":{"description":"Querya change ids (can be undone by asking the AI: undo_change)","type":"array","items":{"type":"string"}}},"required":["date","time","resource_type","actor","tool","description","campaign_id","campaign","ad_group_id","ad_group","changes","change_ids"]},"TimelinePeriodDto":{"type":"object","properties":{"start":{"type":"string"},"end":{"type":"string"}},"required":["start","end"]},"TimelineDto":{"type":"object","properties":{"entries":{"description":"Newest first","type":"array","items":{"$ref":"#/components/schemas/TimelineEntryDto"}},"period":{"$ref":"#/components/schemas/TimelinePeriodDto"},"language":{"type":"string","enum":["pt","en"]},"time_zone":{"type":"string"},"changes":{"type":"number","description":"Raw changes in the period"},"stored_history_from":{"type":"string","nullable":true,"description":"Stored history starts here"},"truncated":{"type":"boolean"}},"required":["entries","period","language","time_zone","changes","stored_history_from","truncated"]},"UsageRowDto":{"type":"object","properties":{"tool":{"type":"string"},"calls":{"type":"number"},"errors":{"type":"number"}},"required":["tool","calls","errors"]},"UsageDto":{"type":"object","properties":{"days":{"type":"number"},"total_calls":{"type":"number"},"by_tool":{"type":"array","items":{"$ref":"#/components/schemas/UsageRowDto"}}},"required":["days","total_calls","by_tool"]}}}}