{"openapi":"3.1.0","info":{"title":"GravityAds API","version":"0.3.0","description":"Hosted GravityAds API for advertising data analysis and controlled, approval-gated actions across supported platforms."},"components":{"securitySchemes":{"GravityAdsApiKey":{"type":"http","scheme":"bearer","description":"Bearer API key or JWT. Also accepted as x-gravityads-api-key where configured."}},"schemas":{"Local1_BudgetPlan":{"additionalProperties":false,"properties":{"amount":{"maximum":1000000000000000.0,"minimum":0,"title":"Amount","type":"number"},"currency":{"pattern":"^[A-Z]{3}$","title":"Currency","type":"string"},"start":{"pattern":"^\\d{4}-\\d{2}-\\d{2}$","title":"Start","type":"string"},"end":{"pattern":"^\\d{4}-\\d{2}-\\d{2}$","title":"End","type":"string"}},"required":["amount","currency","start","end"],"title":"BudgetPlan","type":"object"},"Local2_ReviewOutcome":{"additionalProperties":false,"properties":{"metric":{"maxLength":120,"minLength":1,"title":"Metric","type":"string"},"value":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"title":"Value"},"unit":{"maxLength":40,"minLength":1,"title":"Unit","type":"string"},"source":{"maxLength":500,"minLength":1,"title":"Source","type":"string"},"missing_reason":{"default":"","maxLength":500,"title":"Missing Reason","type":"string"}},"required":["metric","unit","source"],"title":"ReviewOutcome","type":"object"},"Local2_ReviewPlan":{"additionalProperties":false,"properties":{"conclusion":{"maxLength":2000,"minLength":1,"title":"Conclusion","type":"string"},"outcomes":{"items":{"$ref":"#/components/schemas/Local2_ReviewOutcome"},"maxItems":10,"title":"Outcomes","type":"array"},"priorities":{"items":{"$ref":"#/components/schemas/Local2_ReviewPriority"},"maxItems":3,"title":"Priorities","type":"array"},"no_change_reason":{"default":"","maxLength":1000,"title":"No Change Reason","type":"string"}},"required":["conclusion"],"title":"ReviewPlan","type":"object"},"Local2_ReviewPriority":{"additionalProperties":false,"properties":{"decision":{"enum":["stop","start","continue"],"title":"Decision","type":"string"},"action":{"maxLength":500,"minLength":1,"title":"Action","type":"string"},"owner":{"maxLength":120,"minLength":1,"title":"Owner","type":"string"},"due_date":{"pattern":"^\\d{4}-\\d{2}-\\d{2}$","title":"Due Date","type":"string"},"rationale":{"maxLength":1000,"minLength":1,"title":"Rationale","type":"string"},"evidence_steps":{"items":{"enum":["performance","review_context"],"type":"string"},"maxItems":2,"minItems":1,"title":"Evidence Steps","type":"array"}},"required":["decision","action","owner","due_date","rationale","evidence_steps"],"title":"ReviewPriority","type":"object"},"Local3_BudgetAdjustment":{"additionalProperties":false,"properties":{"kind":{"const":"campaign_budget","title":"Kind","type":"string"},"campaign_id":{"pattern":"^[0-9]{1,30}$","title":"Campaign Id","type":"string"},"daily_amount":{"pattern":"^[0-9]{1,9}(\\.[0-9]{1,6})?$","title":"Daily Amount","type":"string"},"reason":{"maxLength":500,"minLength":1,"title":"Reason","type":"string"}},"required":["kind","campaign_id","daily_amount","reason"],"title":"BudgetAdjustment","type":"object"},"Local3_ChannelRole":{"additionalProperties":false,"properties":{"platform":{"enum":["google","meta","microsoft","tiktok","amazon","linkedin","pinterest","openai"],"title":"Platform","type":"string"},"role":{"enum":["acquisition","remarketing","brand","retail"],"title":"Role","type":"string"},"rationale":{"maxLength":500,"minLength":1,"title":"Rationale","type":"string"},"attribution_overlap":{"maxLength":500,"minLength":1,"title":"Attribution Overlap","type":"string"}},"required":["platform","role","rationale","attribution_overlap"],"title":"ChannelRole","type":"object"},"Local3_ExperimentPlan":{"additionalProperties":false,"properties":{"period_start":{"pattern":"^\\d{4}-\\d{2}-\\d{2}$","title":"Period Start","type":"string"},"period_end":{"pattern":"^\\d{4}-\\d{2}-\\d{2}$","title":"Period End","type":"string"},"kind":{"const":"experiment","title":"Kind","type":"string"},"hypothesis":{"maxLength":1000,"minLength":1,"title":"Hypothesis","type":"string"},"variable":{"maxLength":200,"minLength":1,"title":"Variable","type":"string"},"control":{"maxLength":1000,"minLength":1,"title":"Control","type":"string"},"variant":{"maxLength":1000,"minLength":1,"title":"Variant","type":"string"},"audience":{"maxLength":1000,"minLength":1,"title":"Audience","type":"string"},"primary_metric":{"maxLength":200,"minLength":1,"title":"Primary Metric","type":"string"},"guardrails":{"maxLength":1000,"minLength":1,"title":"Guardrails","type":"string"},"decision_rule":{"maxLength":1000,"minLength":1,"title":"Decision Rule","type":"string"},"stop_rule":{"maxLength":1000,"minLength":1,"title":"Stop Rule","type":"string"},"parallel_changes":{"maxLength":1000,"minLength":1,"title":"Parallel Changes","type":"string"},"design":{"enum":["randomized","observational"],"title":"Design","type":"string"},"assignment_method":{"maxLength":1000,"minLength":1,"title":"Assignment Method","type":"string"},"treatment_fraction":{"exclusiveMaximum":1,"exclusiveMinimum":0,"title":"Treatment Fraction","type":"number"},"budget_limit":{"minimum":0,"title":"Budget Limit","type":"number"},"currency":{"pattern":"^[A-Z]{3}$","title":"Currency","type":"string"},"planned_sample":{"anyOf":[{"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"title":"Planned Sample"},"sample_basis":{"maxLength":1000,"minLength":1,"title":"Sample Basis","type":"string"},"metric_type":{"default":"unknown","enum":["binary_rate","continuous","unknown"],"title":"Metric Type","type":"string"},"baseline_rate":{"anyOf":[{"exclusiveMaximum":1,"exclusiveMinimum":0,"type":"number"},{"type":"null"}],"default":null,"title":"Baseline Rate"},"minimum_detectable_absolute_lift":{"anyOf":[{"exclusiveMaximum":1,"exclusiveMinimum":0,"type":"number"},{"type":"null"}],"default":null,"title":"Minimum Detectable Absolute Lift"},"significance_level":{"default":0.05,"exclusiveMaximum":0.5,"exclusiveMinimum":0,"title":"Significance Level","type":"number"},"target_power":{"default":0.8,"exclusiveMaximum":1,"exclusiveMinimum":0.5,"title":"Target Power","type":"number"}},"required":["period_start","period_end","kind","hypothesis","variable","control","variant","audience","primary_metric","guardrails","decision_rule","stop_rule","parallel_changes","design","assignment_method","treatment_fraction","budget_limit","currency","sample_basis"],"title":"ExperimentPlan","type":"object"},"Local3_PauseSelection":{"additionalProperties":false,"properties":{"kind":{"const":"pause_campaigns","title":"Kind","type":"string"},"campaign_ids":{"items":{"type":"string"},"maxItems":20,"minItems":1,"title":"Campaign Ids","type":"array"},"reason":{"maxLength":500,"minLength":1,"title":"Reason","type":"string"}},"required":["kind","campaign_ids","reason"],"title":"PauseSelection","type":"object"},"Local3_PreparationItem":{"additionalProperties":false,"properties":{"task":{"maxLength":500,"minLength":1,"title":"Task","type":"string"},"owner":{"maxLength":120,"minLength":1,"title":"Owner","type":"string"},"due_date":{"pattern":"^\\d{4}-\\d{2}-\\d{2}$","title":"Due Date","type":"string"},"dependency":{"maxLength":500,"minLength":1,"title":"Dependency","type":"string"}},"required":["task","owner","due_date","dependency"],"title":"PreparationItem","type":"object"},"Local3_QuarterlyPlan":{"additionalProperties":false,"properties":{"period_start":{"pattern":"^\\d{4}-\\d{2}-\\d{2}$","title":"Period Start","type":"string"},"period_end":{"pattern":"^\\d{4}-\\d{2}-\\d{2}$","title":"Period End","type":"string"},"kind":{"const":"quarterly","title":"Kind","type":"string"},"objective":{"maxLength":1000,"minLength":1,"title":"Objective","type":"string"},"currency":{"pattern":"^[A-Z]{3}$","title":"Currency","type":"string"},"scenarios":{"items":{"$ref":"#/components/schemas/Local3_Scenario"},"maxItems":3,"minItems":3,"title":"Scenarios","type":"array"},"channels":{"items":{"$ref":"#/components/schemas/Local3_ChannelRole"},"maxItems":10,"minItems":1,"title":"Channels","type":"array"},"measurement":{"enum":["platform_attribution","randomized_lift","cross_channel_model"],"title":"Measurement","type":"string"},"measurement_inputs":{"maxLength":2000,"minLength":1,"title":"Measurement Inputs","type":"string"},"checklist":{"items":{"$ref":"#/components/schemas/Local3_PreparationItem"},"maxItems":20,"minItems":1,"title":"Checklist","type":"array"}},"required":["period_start","period_end","kind","objective","currency","scenarios","channels","measurement","measurement_inputs","checklist"],"title":"QuarterlyPlan","type":"object"},"Local3_Scenario":{"additionalProperties":false,"properties":{"name":{"enum":["conservative","base","ambitious"],"title":"Name","type":"string"},"budget":{"minimum":0,"title":"Budget","type":"number"},"assumptions":{"maxLength":1000,"minLength":1,"title":"Assumptions","type":"string"},"capacity":{"maxLength":500,"minLength":1,"title":"Capacity","type":"string"},"worst_case":{"maxLength":1000,"minLength":1,"title":"Worst Case","type":"string"}},"required":["name","budget","assumptions","capacity","worst_case"],"title":"Scenario","type":"object"},"Local4_SearchSelection":{"additionalProperties":false,"properties":{"row_id":{"pattern":"^[a-f0-9]{64}$","title":"Row Id","type":"string"},"match_type":{"default":"EXACT","enum":["EXACT","PHRASE","BROAD"],"title":"Match Type","type":"string"},"rationale":{"maxLength":500,"minLength":1,"title":"Rationale","type":"string"},"brand_reviewed":{"title":"Brand Reviewed","type":"boolean"},"exclusion_scope":{"default":"ad_group","enum":["ad_group","campaign"],"title":"Exclusion Scope","type":"string"}},"required":["row_id","rationale","brand_reviewed"],"title":"SearchSelection","type":"object"},"Local5_AccountIdentity":{"additionalProperties":false,"properties":{"platform":{"pattern":"^(google|meta|microsoft|tiktok|criteo|media_go|pinterest|linkedin|amazon)$","title":"Platform","type":"string"},"account_id":{"maxLength":40,"minLength":1,"title":"Account Id","type":"string"}},"required":["platform","account_id"],"title":"AccountIdentity","type":"object"},"Local5_ScopeDefinition":{"additionalProperties":false,"properties":{"query":{"default":"","maxLength":100,"title":"Query","type":"string"},"match_query":{"default":true,"title":"Match Query","type":"boolean"},"platform":{"default":"","pattern":"^(|google|meta|microsoft|tiktok|criteo|media_go|pinterest|linkedin|amazon)$","title":"Platform","type":"string"},"include":{"items":{"$ref":"#/components/schemas/Local5_AccountIdentity"},"maxItems":1000,"title":"Include","type":"array"},"exclude":{"items":{"$ref":"#/components/schemas/Local5_AccountIdentity"},"maxItems":1000,"title":"Exclude","type":"array"}},"title":"ScopeDefinition","type":"object"},"Local6_AccountIdentity":{"additionalProperties":false,"properties":{"platform":{"pattern":"^(google|meta|microsoft|tiktok|criteo|media_go|pinterest|linkedin|amazon)$","title":"Platform","type":"string"},"account_id":{"maxLength":40,"minLength":1,"title":"Account Id","type":"string"}},"required":["platform","account_id"],"title":"AccountIdentity","type":"object"},"Local6_ReportOptions":{"additionalProperties":false,"properties":{"timezone":{"default":"UTC","maxLength":100,"minLength":1,"title":"Timezone","type":"string"},"aggregation_method":{"default":"daily_arithmetic_mean","enum":["daily_arithmetic_mean","pooled_ratio"],"title":"Aggregation Method","type":"string"},"baseline_includes_target":{"default":false,"title":"Baseline Includes Target","type":"boolean"},"period_kind":{"default":"natural_week","enum":["natural_week","custom_period"],"title":"Period Kind","type":"string"}},"title":"ReportOptions","type":"object"},"Local6_ScopeDefinition":{"additionalProperties":false,"properties":{"query":{"default":"","maxLength":100,"title":"Query","type":"string"},"match_query":{"default":true,"title":"Match Query","type":"boolean"},"platform":{"default":"","pattern":"^(|google|meta|microsoft|tiktok|criteo|media_go|pinterest|linkedin|amazon)$","title":"Platform","type":"string"},"include":{"items":{"$ref":"#/components/schemas/Local6_AccountIdentity"},"maxItems":1000,"title":"Include","type":"array"},"exclude":{"items":{"$ref":"#/components/schemas/Local6_AccountIdentity"},"maxItems":1000,"title":"Exclude","type":"array"}},"title":"ScopeDefinition","type":"object"},"Local7_BusinessReference":{"additionalProperties":false,"properties":{"run_id":{"maxLength":100,"minLength":1,"title":"Run Id","type":"string"},"revision":{"minimum":1,"title":"Revision","type":"integer"}},"required":["run_id","revision"],"title":"BusinessReference","type":"object"},"Local7_ReportOptions":{"additionalProperties":false,"properties":{"timezone":{"default":"UTC","maxLength":100,"minLength":1,"title":"Timezone","type":"string"},"aggregation_method":{"default":"daily_arithmetic_mean","enum":["daily_arithmetic_mean","pooled_ratio"],"title":"Aggregation Method","type":"string"},"baseline_includes_target":{"default":false,"title":"Baseline Includes Target","type":"boolean"},"period_kind":{"default":"natural_week","enum":["natural_week","custom_period"],"title":"Period Kind","type":"string"}},"title":"ReportOptions","type":"object"},"Local8_CreativeBriefInput":{"additionalProperties":false,"properties":{"objective":{"maxLength":500,"minLength":1,"title":"Objective","type":"string"},"audience":{"maxLength":500,"minLength":1,"title":"Audience","type":"string"},"hypothesis":{"maxLength":1000,"minLength":1,"title":"Hypothesis","type":"string"},"variable":{"enum":["hook","visual","copy","cta","format"],"title":"Variable","type":"string"},"control":{"maxLength":1000,"minLength":1,"title":"Control","type":"string"},"variant":{"maxLength":1000,"minLength":1,"title":"Variant","type":"string"},"primary_metric":{"maxLength":200,"minLength":1,"title":"Primary Metric","type":"string"},"decision_rule":{"maxLength":1000,"minLength":1,"title":"Decision Rule","type":"string"},"observation_window":{"maxLength":500,"minLength":1,"title":"Observation Window","type":"string"},"production_requirements":{"maxLength":2000,"minLength":1,"title":"Production Requirements","type":"string"}},"required":["objective","audience","hypothesis","variable","control","variant","primary_metric","decision_rule","observation_window","production_requirements"],"title":"CreativeBriefInput","type":"object"},"Local9_BusinessBrief":{"additionalProperties":false,"properties":{"product":{"maxLength":1000,"minLength":1,"title":"Product","type":"string"},"outcome":{"maxLength":1000,"minLength":1,"title":"Outcome","type":"string"},"audience":{"default":"","maxLength":1000,"title":"Audience","type":"string"},"budget_limit":{"anyOf":[{"minimum":0,"type":"number"},{"type":"null"}],"default":null,"title":"Budget Limit"},"currency":{"default":"","pattern":"^(|[A-Z]{3})$","title":"Currency","type":"string"},"primary_metric":{"default":"","maxLength":200,"title":"Primary Metric","type":"string"},"guardrail_metrics":{"default":"","maxLength":1000,"title":"Guardrail Metrics","type":"string"},"assumptions":{"default":"","maxLength":2000,"title":"Assumptions","type":"string"},"constraints":{"default":"","maxLength":2000,"title":"Constraints","type":"string"}},"required":["product","outcome"],"title":"BusinessBrief","type":"object"}}},"security":[{"GravityAdsApiKey":[]}],"paths":{"/health":{"get":{"operationId":"health","summary":"Adapter health","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["status","service","auth_mode","writes_platform","request_thread_writes_platform","phase_contract"],"additionalProperties":true,"properties":{"status":{"type":"string","const":"ok"},"service":{"type":"string","const":"gravityads-openapi-adapter"},"runtime_content":{"type":"object","additionalProperties":true},"api_base":{"type":"string"},"state":{"type":"string"},"auth_mode":{"type":"string"},"auth_required":{"type":"boolean"},"hosted_read_only":{"type":"boolean"},"controlled_action_enabled":{"type":"boolean"},"writes_platform":{"type":"boolean"},"request_thread_writes_platform":{"type":"boolean"},"hosted_worker_live_execute_enabled":{"type":"boolean"},"phase_contract":{"type":"string"},"cors_allowed_origins_configured":{"type":"boolean"},"cors_allowed_origin_count":{"type":"integer","minimum":0}}}}}}},"x-gravityads-tool-name":"gravityads.health","x-gravityads-required-scope":"gravityads.read","x-gravityads-scope-source":"hosted_entitlements"}},"/.well-known/oauth-protected-resource":{"get":{"operationId":"oauth_protected_resource_metadata","summary":"OAuth protected resource metadata","responses":{"200":{"description":"Protected resource metadata","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}},"x-gravityads-tool-name":"gravityads.oauth.protected.resource.metadata","x-gravityads-required-scope":"gravityads.read","x-gravityads-scope-source":"hosted_entitlements"}},"/.well-known/security.txt":{"get":{"operationId":"security_txt","summary":"Responsible disclosure contact metadata","responses":{"200":{"description":"security.txt","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}},"x-gravityads-tool-name":"gravityads.security.txt","x-gravityads-required-scope":"gravityads.read","x-gravityads-scope-source":"hosted_entitlements"}},"/demo/workspace":{"get":{"operationId":"demo_workspace","summary":"Return redacted GTM demo workspace contract","description":"Returns route, data-mode and pricing-boundary metadata for the Portal demo workspace. It uses synthetic or redacted data only and never writes ad platforms.","parameters":[{"name":"workspace_slug","in":"query","required":false,"schema":{"type":"string"}},{"name":"demo_base_url","in":"query","required":false,"schema":{"type":"string","format":"uri"}}],"responses":{"200":{"description":"Redacted demo workspace contract","content":{"application/json":{"schema":{"type":"object","required":["schema_version","status","ready_for_demo_workspace","ready_for_gtm_handoff","demo_workspace","pricing_boundary","route_contracts","raw_secret_values_returned","raw_customer_data_returned","raw_account_ids_returned"],"properties":{"schema_version":{"type":"string","const":"gravityads.hosted_demo_workspace_bundle.v1"},"status":{"type":"string"},"ready_for_demo_workspace":{"type":"boolean"},"ready_for_gtm_handoff":{"type":"boolean"},"public_docs_readiness":{"type":"object"},"demo_workspace":{"type":"object","required":["workspace_slug","route_prefix","synthetic_demo_data_only","live_platform_write_allowed","raw_demo_base_url_returned"],"properties":{"workspace_slug":{"type":"string"},"route_prefix":{"type":"string"},"synthetic_demo_data_only":{"type":"boolean","const":true},"live_platform_write_allowed":{"type":"boolean","const":false},"raw_demo_base_url_returned":{"type":"boolean","const":false}}},"pricing_boundary":{"type":"object","required":["pricing_page_frontend_owned_by_portal","billing_source_of_truth","cost_metadata_mode","hosted_api_owns_provider_pricing"],"properties":{"pricing_page_frontend_owned_by_portal":{"type":"boolean","const":true},"billing_source_of_truth":{"type":"string","const":"/billing/plans"},"cost_metadata_mode":{"type":"string","const":"upstream_passthrough_only"},"hosted_api_owns_provider_pricing":{"type":"boolean","const":false}}},"claude_frontend_handoff":{"type":"object"},"route_contracts":{"type":"array","items":{"type":"object"}},"raw_secret_values_returned":{"type":"boolean","const":false},"raw_customer_data_returned":{"type":"boolean","const":false},"raw_account_ids_returned":{"type":"boolean","const":false}}}}}}},"x-gravityads-tool-name":"gravityads.demo.workspace","x-gravityads-required-scope":"gravityads.read","x-gravityads-scope-source":"hosted_entitlements"}},"/oauth/authorization-start":{"post":{"operationId":"oauth_authorization_start","summary":"Build hosted OAuth authorization URL with PKCE","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["platform","redirect_uri"],"properties":{"platform":{"type":"string","enum":["google","meta","microsoft","bing","tiktok","pinterest","linkedin"]},"redirect_uri":{"type":"string","format":"uri"},"client_id":{"type":"string","description":"Hosted OAuth app client id. Prefer env in production."},"connection_id":{"type":"string"},"account_hint":{"type":"string"},"access_mode":{"type":"string","enum":["read_only","controlled_write"],"default":"read_only"},"scopes":{"type":"array","items":{"type":"string"}},"authorization_purpose":{"type":"string","enum":["standard","new_creative","page_discovery","instagram_identity","threads_identity"],"default":"standard","description":"Meta controlled_write purposes: new_creative adds pages_read_engagement and pages_show_list; identity discovery also requests pages_manage_ads for promote_pages, with instagram_basic and threads_business_basic added by the selected identity purpose."}}}}}},"responses":{"200":{"description":"OAuth authorization URL","content":{"application/json":{"schema":{"type":"object","required":["schema_version","status","tenant_id","platform","connection_id","authorization_url","state","pkce","scopes","writes_platform","raw_token_forwarded_to_adapter"],"additionalProperties":true,"properties":{"schema_version":{"type":"string","const":"gravityads.hosted_oauth_authorization_start.v1"},"status":{"type":"string","const":"oauth_authorization_start_ready"},"tenant_id":{"type":"string"},"platform":{"type":"string"},"connection_id":{"type":"string"},"authorization_url":{"type":"string"},"state":{"type":"string"},"state_claims":{"type":"object"},"pkce":{"type":"object","additionalProperties":true,"properties":{"method":{"type":"string","enum":["S256","provider_not_supported"]},"provider_supported":{"type":"boolean"},"code_challenge":{"type":"string"},"code_verifier_secret_target":{"type":"string"},"code_verifier_returned":{"type":"boolean"}}},"scopes":{"type":"array","items":{"type":"string"}},"authorization_purpose":{"type":"string","enum":["standard","new_creative","page_discovery","instagram_identity","threads_identity"]},"access_mode":{"type":"string","enum":["read_only","controlled_write"]},"developer_token_required_in_connector":{"type":"boolean"},"writes_platform":{"type":"boolean","const":false},"raw_token_forwarded_to_adapter":{"type":"boolean","const":false}}}}}}},"x-gravityads-tool-name":"gravityads.oauth.authorization.start","x-gravityads-required-scope":"gravityads.read","x-gravityads-scope-source":"hosted_entitlements"}},"/oauth/callback-metadata":{"post":{"operationId":"oauth_callback_metadata","summary":"Validate hosted OAuth callback state without storing raw code","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["state"],"properties":{"state":{"type":"string"},"code":{"type":"string","description":"Raw provider code is accepted only for hashing/validation and is never returned."},"error":{"type":"string"}}}}}},"responses":{"200":{"description":"OAuth callback metadata","content":{"application/json":{"schema":{"type":"object","required":["schema_version","status","tenant_id","platform","connection_id","state_hash","next_step","raw_authorization_code_forwarded_to_adapter","writes_platform"],"additionalProperties":true,"properties":{"schema_version":{"type":"string","const":"gravityads.hosted_oauth_callback_metadata.v1"},"status":{"type":"string","enum":["oauth_callback_validated","oauth_callback_error"]},"tenant_id":{"type":"string"},"platform":{"type":"string"},"connection_id":{"type":"string"},"state_hash":{"type":"string"},"authorization_code_hash":{"type":"string"},"provider_error":{"type":"string"},"age_seconds":{"type":"integer","minimum":0},"next_step":{"type":"string"},"raw_authorization_code_forwarded_to_adapter":{"type":"boolean","const":false},"writes_platform":{"type":"boolean","const":false}}}}}}},"x-gravityads-tool-name":"gravityads.oauth.callback.metadata","x-gravityads-required-scope":"gravityads.read","x-gravityads-scope-source":"hosted_entitlements"}},"/oauth/provider-readiness":{"get":{"operationId":"oauth_provider_readiness","summary":"Return hosted OAuth provider configuration readiness","responses":{"200":{"description":"OAuth provider readiness","content":{"application/json":{"schema":{"type":"object","required":["status","provider_count","ready_provider_count","providers","token_vault","state_signing_secret_configured","raw_secrets_returned"],"additionalProperties":true,"properties":{"status":{"type":"string","const":"hosted_oauth_provider_readiness_ready"},"provider_count":{"type":"integer","minimum":0},"ready_provider_count":{"type":"integer","minimum":0},"ready_oauth_provider_count":{"type":"integer","minimum":0},"providers":{"type":"array","items":{"type":"object","required":["platform","display_name","connection_mode","ready_for_connection","ready_for_oauth_exchange","missing_config_items","raw_secrets_returned"],"additionalProperties":true,"properties":{"platform":{"type":"string"},"display_name":{"type":"string"},"connection_mode":{"type":"string","enum":["oauth_redirect","managed_client_credentials","managed_api_token","unsupported"]},"ready_for_connection":{"type":"boolean"},"ready_for_oauth_exchange":{"type":"boolean"},"missing_config_items":{"type":"array","items":{"type":"string"}},"read_scopes":{"type":"array","items":{"type":"string"}},"controlled_write_scopes":{"type":"array","items":{"type":"string"}},"controlled_write_oauth_supported":{"type":"boolean"},"new_creative_scopes":{"type":"array","items":{"type":"string"}},"developer_token_required":{"type":"boolean"},"oauth_client_id_configured":{"type":"boolean"},"oauth_client_secret_required":{"type":"boolean"},"oauth_client_secret_configured":{"type":"boolean"},"developer_token_configured":{"type":"boolean"},"token_endpoint_override_configured":{"type":"boolean"},"per_connection_credentials_required":{"type":"boolean"},"credential_input_mode":{"type":"string","enum":["provider_oauth_application","per_connection_vault"]},"runtime_global_connection_credential_allowed":{"type":"boolean","const":false},"platform_api_called":{"type":"boolean","const":false},"raw_secrets_returned":{"type":"boolean","const":false}}}},"token_vault":{"type":"object","required":["status","raw_secrets_returned"],"additionalProperties":true,"properties":{"status":{"type":"string"},"mode":{"type":"string"},"requires_secret_manager_iam":{"type":"boolean"},"raw_secrets_returned":{"type":"boolean","const":false}}},"state_signing_secret_configured":{"type":"boolean"},"hosted_auth_context":{"type":"object"},"raw_secrets_returned":{"type":"boolean","const":false}}}}}}},"x-gravityads-tool-name":"gravityads.oauth.provider.readiness","x-gravityads-required-scope":"gravityads.admin","x-gravityads-scope-source":"hosted_entitlements"}},"/portal-auth/identity/resolve":{"post":{"operationId":"portal_identity_resolve","summary":"Resolve or persist independently proven Portal subject ownership","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["provider","token","nonce","state_expires_at"],"additionalProperties":false,"properties":{"provider":{"type":"string","enum":["google","github"]},"token":{"type":"string","writeOnly":true,"maxLength":16384},"nonce":{"type":"string","maxLength":255},"state_expires_at":{"type":"integer"},"member_authorization":{"type":"string","writeOnly":true},"member_attestation":{"type":"string","writeOnly":true,"maxLength":16384},"subject_hash":{"type":"string","pattern":"^[0-9a-f]{64}$"},"tenant_id":{"type":"string"},"user_id":{"type":"string"},"actor_id":{"type":"string"},"signup":{"type":"object","description":"Existing BFF-validated registration/landing selections; enrollment only"}}}}}},"responses":{"200":{"description":"Bound identity or explicit enrollment/link requirement","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"403":{"description":"Independent exact-member proof required"},"409":{"description":"Inactive, revoked or conflicting ownership"},"503":{"description":"Identity store or provider verification unavailable"}},"x-gravityads-tool-name":"gravityads.portal.identity.resolve","x-gravityads-required-scope":"gravityads.read","x-gravityads-scope-source":"hosted_entitlements"}},"/portal-auth/identity/enroll":{"post":{"operationId":"portal_identity_enroll","summary":"Resolve or persist independently proven Portal subject ownership","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["provider","token","nonce","state_expires_at"],"additionalProperties":false,"properties":{"provider":{"type":"string","enum":["google","github"]},"token":{"type":"string","writeOnly":true,"maxLength":16384},"nonce":{"type":"string","maxLength":255},"state_expires_at":{"type":"integer"},"member_authorization":{"type":"string","writeOnly":true},"member_attestation":{"type":"string","writeOnly":true,"maxLength":16384},"subject_hash":{"type":"string","pattern":"^[0-9a-f]{64}$"},"tenant_id":{"type":"string"},"user_id":{"type":"string"},"actor_id":{"type":"string"},"signup":{"type":"object","description":"Existing BFF-validated registration/landing selections; enrollment only"}}}}}},"responses":{"200":{"description":"Bound identity or explicit enrollment/link requirement","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"403":{"description":"Independent exact-member proof required"},"409":{"description":"Inactive, revoked or conflicting ownership"},"503":{"description":"Identity store or provider verification unavailable"}},"x-gravityads-tool-name":"gravityads.portal.identity.enroll","x-gravityads-required-scope":"gravityads.read","x-gravityads-scope-source":"hosted_entitlements"}},"/portal-auth/identity/link":{"post":{"operationId":"portal_identity_link","summary":"Resolve or persist independently proven Portal subject ownership","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["provider","token","nonce","state_expires_at"],"additionalProperties":false,"properties":{"provider":{"type":"string","enum":["google","github"]},"token":{"type":"string","writeOnly":true,"maxLength":16384},"nonce":{"type":"string","maxLength":255},"state_expires_at":{"type":"integer"},"member_authorization":{"type":"string","writeOnly":true},"member_attestation":{"type":"string","writeOnly":true,"maxLength":16384},"subject_hash":{"type":"string","pattern":"^[0-9a-f]{64}$"},"tenant_id":{"type":"string"},"user_id":{"type":"string"},"actor_id":{"type":"string"},"signup":{"type":"object","description":"Existing BFF-validated registration/landing selections; enrollment only"}}}}}},"responses":{"200":{"description":"Bound identity or explicit enrollment/link requirement","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"403":{"description":"Independent exact-member proof required"},"409":{"description":"Inactive, revoked or conflicting ownership"},"503":{"description":"Identity store or provider verification unavailable"}},"x-gravityads-tool-name":"gravityads.portal.identity.link","x-gravityads-required-scope":"gravityads.read","x-gravityads-scope-source":"hosted_entitlements"}},"/portal-auth/identity/revoke":{"post":{"operationId":"portal_identity_revoke","summary":"Resolve or persist independently proven Portal subject ownership","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["provider","token","nonce","state_expires_at"],"additionalProperties":false,"properties":{"provider":{"type":"string","enum":["google","github"]},"token":{"type":"string","writeOnly":true,"maxLength":16384},"nonce":{"type":"string","maxLength":255},"state_expires_at":{"type":"integer"},"member_authorization":{"type":"string","writeOnly":true},"member_attestation":{"type":"string","writeOnly":true,"maxLength":16384},"subject_hash":{"type":"string","pattern":"^[0-9a-f]{64}$"},"tenant_id":{"type":"string"},"user_id":{"type":"string"},"actor_id":{"type":"string"},"signup":{"type":"object","description":"Existing BFF-validated registration/landing selections; enrollment only"}}}}}},"responses":{"200":{"description":"Bound identity or explicit enrollment/link requirement","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"403":{"description":"Independent exact-member proof required"},"409":{"description":"Inactive, revoked or conflicting ownership"},"503":{"description":"Identity store or provider verification unavailable"}},"x-gravityads-tool-name":"gravityads.portal.identity.revoke","x-gravityads-required-scope":"gravityads.read","x-gravityads-scope-source":"hosted_entitlements"}},"/portal-auth/identity/confirm":{"post":{"operationId":"portal_identity_confirm","summary":"Resolve or persist independently proven Portal subject ownership","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["nonce","state_expires_at"],"additionalProperties":false,"properties":{"provider":{"type":"string","enum":["google","github"]},"token":{"type":"string","writeOnly":true,"maxLength":16384},"nonce":{"type":"string","maxLength":255},"state_expires_at":{"type":"integer"},"member_authorization":{"type":"string","writeOnly":true},"member_attestation":{"type":"string","writeOnly":true,"maxLength":16384},"subject_hash":{"type":"string","pattern":"^[0-9a-f]{64}$"},"tenant_id":{"type":"string"},"user_id":{"type":"string"},"actor_id":{"type":"string"},"signup":{"type":"object","description":"Existing BFF-validated registration/landing selections; enrollment only"}}}}}},"responses":{"200":{"description":"Bound identity or explicit enrollment/link requirement","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"403":{"description":"Independent exact-member proof required"},"409":{"description":"Inactive, revoked or conflicting ownership"},"503":{"description":"Identity store or provider verification unavailable"}},"x-gravityads-tool-name":"gravityads.portal.identity.confirm","x-gravityads-required-scope":"gravityads.read","x-gravityads-scope-source":"hosted_entitlements"}},"/portal-auth/challenges/register":{"post":{"operationId":"portal_auth_challenge_register","summary":"Register a hashed one-time Portal auth challenge","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["challenge_hash","challenge_type","expires_at"],"additionalProperties":false,"properties":{"challenge_hash":{"type":"string","minLength":64,"maxLength":64,"description":"SHA-256 hash of the token nonce; raw nonce is forbidden."},"challenge_type":{"type":"string","enum":["email_magic_link","github_oauth_state","google_oauth_state","microsoft_oauth_state","password_reset"]},"identity_hash":{"type":"string","minLength":64,"maxLength":64},"expires_at":{"type":"string","format":"date-time"},"resolve_email_identity":{"type":"boolean","description":"Consume only: resolve canonical membership after an isolated Portal email attestation. No provider binding or automatic membership updates."},"email_attestation":{"type":"string","writeOnly":true,"maxLength":16384}}}}}},"responses":{"200":{"description":"Portal auth challenge registered","content":{"application/json":{"schema":{"type":"object","required":["status","challenge_type","raw_challenge_returned","raw_identity_returned","raw_secrets_returned"],"additionalProperties":true,"properties":{"status":{"type":"string","enum":["portal_auth_challenge_registered","portal_auth_challenge_already_exists","portal_auth_challenge_consumed","portal_auth_challenge_unavailable","portal_auth_challenge_unconfigured","portal_auth_challenge_degraded","portal_auth_challenge_failed"]},"registered":{"type":"boolean"},"consumed":{"type":"boolean"},"email_identity":{"type":"object","properties":{"status":{"type":"string","enum":["existing","new","ambiguous","inactive"]},"user":{"type":"object","description":"Canonical active DB membership and plan; existing status only."}}},"challenge_type":{"type":"string"},"hosted_auth_context":{"type":"object"},"raw_challenge_returned":{"type":"boolean","const":false},"raw_identity_returned":{"type":"boolean","const":false},"raw_secrets_returned":{"type":"boolean","const":false}}}}}}},"x-gravityads-tool-name":"gravityads.portal.auth.challenge.register","x-gravityads-required-scope":"gravityads.read","x-gravityads-scope-source":"hosted_entitlements"}},"/portal-auth/challenges/consume":{"post":{"operationId":"portal_auth_challenge_consume","summary":"Atomically consume a hashed Portal auth challenge","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["challenge_hash","challenge_type","expires_at"],"additionalProperties":false,"properties":{"challenge_hash":{"type":"string","minLength":64,"maxLength":64,"description":"SHA-256 hash of the token nonce; raw nonce is forbidden."},"challenge_type":{"type":"string","enum":["email_magic_link","github_oauth_state","google_oauth_state","microsoft_oauth_state","password_reset"]},"identity_hash":{"type":"string","minLength":64,"maxLength":64},"expires_at":{"type":"string","format":"date-time"},"resolve_email_identity":{"type":"boolean","description":"Consume only: resolve canonical membership after an isolated Portal email attestation. No provider binding or automatic membership updates."},"email_attestation":{"type":"string","writeOnly":true,"maxLength":16384}}}}}},"responses":{"200":{"description":"Portal auth challenge consumed","content":{"application/json":{"schema":{"type":"object","required":["status","challenge_type","raw_challenge_returned","raw_identity_returned","raw_secrets_returned"],"additionalProperties":true,"properties":{"status":{"type":"string","enum":["portal_auth_challenge_registered","portal_auth_challenge_already_exists","portal_auth_challenge_consumed","portal_auth_challenge_unavailable","portal_auth_challenge_unconfigured","portal_auth_challenge_degraded","portal_auth_challenge_failed"]},"registered":{"type":"boolean"},"consumed":{"type":"boolean"},"email_identity":{"type":"object","properties":{"status":{"type":"string","enum":["existing","new","ambiguous","inactive"]},"user":{"type":"object","description":"Canonical active DB membership and plan; existing status only."}}},"challenge_type":{"type":"string"},"hosted_auth_context":{"type":"object"},"raw_challenge_returned":{"type":"boolean","const":false},"raw_identity_returned":{"type":"boolean","const":false},"raw_secrets_returned":{"type":"boolean","const":false}}}}}}},"x-gravityads-tool-name":"gravityads.portal.auth.challenge.consume","x-gravityads-required-scope":"gravityads.read","x-gravityads-scope-source":"hosted_entitlements"}},"/connections/callback-exchange":{"post":{"operationId":"connections_callback_exchange","summary":"Exchange a hosted OAuth callback code, store the token in the configured vault, and persist a Secret Manager ref","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["state","code","redirect_uri"],"additionalProperties":false,"properties":{"state":{"type":"string"},"code":{"type":"string","description":"Raw provider authorization code. It is exchanged server-side and is never returned or logged."},"redirect_uri":{"type":"string","format":"uri"},"client_id":{"type":"string","description":"Optional override; production should use env config."},"code_verifier":{"type":"string","description":"PKCE verifier loaded by the Portal/connector boundary."},"secret_manager_resource":{"type":"string","description":"Optional Secret Manager secret resource override. Production defaults to GRAVITYADS_OAUTH_SECRET_RESOURCE_TEMPLATE and only a hash is returned."},"kms_key_resource":{"type":"string"},"version_alias":{"type":"string","default":"latest"}}}}}},"responses":{"200":{"description":"OAuth token exchanged","content":{"application/json":{"schema":{"type":"object","required":["status","tenant_id","platform","connection_id","ready_for_readonly_etl","database_url_configured","raw_authorization_code_returned","raw_token_material_returned","raw_secrets_returned"],"additionalProperties":true,"properties":{"status":{"type":"string","const":"connections_callback_exchange_completed"},"tenant_id":{"type":"string"},"platform":{"type":"string"},"connection_id":{"type":"string"},"secret_ref_id":{"type":"string"},"account_sync":{"type":"object","additionalProperties":true,"properties":{"status":{"type":"string","enum":["pending","running","succeeded","failed"]},"reason":{"type":"string"},"credential_version":{"type":"string"},"discovered_count":{"type":"integer"},"saved_count":{"type":"integer"},"started_at":{"type":"string"},"completed_at":{"type":"string"},"error_code":{"type":"string"},"retryable":{"type":"boolean"}}},"account_upsert":{"type":"object"},"account_discovery":{"type":"object"},"reauthorization":{"type":"boolean","description":"Existing connection authorization was renewed without changing selected accounts or ETL assignments; inspect account_sync independently."},"next_step":{"type":"string","description":"Google renewal returns to connections; Meta may select_accounts, return_to_connections or retry_account_sync."},"vault":{"type":"object"},"token_response_metadata":{"type":"object"},"permission_probe":{"type":"object"},"connection":{"type":"object"},"ready_for_readonly_etl":{"type":"boolean"},"database_url_configured":{"type":"boolean"},"hosted_auth_context":{"type":"object"},"raw_authorization_code_returned":{"type":"boolean","const":false},"raw_token_material_returned":{"type":"boolean","const":false},"raw_secrets_returned":{"type":"boolean","const":false}}}}}}},"x-gravityads-tool-name":"gravityads.connections.callback_exchange","x-gravityads-required-scope":"gravityads.admin","x-gravityads-scope-source":"hosted_entitlements"}},"/connections/managed-credentials":{"post":{"operationId":"connection_managed_credentials","summary":"Validate and vault tenant-managed connector credentials","description":"Accepts Criteo client credentials or a MediaGo API token, validates them against the provider, and writes them directly to the tenant-scoped token vault. Raw credentials are never returned or persisted in the control plane.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["platform"],"additionalProperties":false,"properties":{"platform":{"type":"string","enum":["criteo","media_go"]},"client_id":{"type":"string","description":"Criteo API client id; accepted only for server-side vaulting."},"client_secret":{"type":"string","format":"password","writeOnly":true,"description":"Criteo API client secret; never returned or logged."},"api_token":{"type":"string","format":"password","writeOnly":true,"description":"MediaGo API token; never returned or logged."}}}}}},"responses":{"200":{"description":"Managed connector credential stored","content":{"application/json":{"schema":{"type":"object","required":["status","tenant_id","platform","connection_id","ready_for_readonly_etl","raw_token_material_returned","raw_secrets_returned"],"additionalProperties":true,"properties":{"status":{"type":"string","const":"managed_connection_credentials_completed"},"tenant_id":{"type":"string"},"platform":{"type":"string","enum":["criteo","media_go"]},"connection_id":{"type":"string"},"secret_ref_id":{"type":"string"},"vault":{"type":"object"},"token_response_metadata":{"type":"object"},"account_discovery":{"type":"object"},"account_upsert":{"type":"object"},"connection":{"type":"object"},"ready_for_readonly_etl":{"type":"boolean"},"database_url_configured":{"type":"boolean"},"hosted_auth_context":{"type":"object"},"raw_token_material_returned":{"type":"boolean","const":false},"raw_secrets_returned":{"type":"boolean","const":false}}}}}}},"x-gravityads-tool-name":"gravityads.connection.managed_credentials","x-gravityads-required-scope":"gravityads.admin","x-gravityads-scope-source":"hosted_entitlements"}},"/connections/{connection_id}/secret-ref":{"post":{"operationId":"connection_secret_ref_record","summary":"Record or rotate a hosted connection Secret Manager ref","description":"Stores only hashed Secret Manager/KMS resource references in the control plane. It rejects raw OAuth tokens and never writes ad platforms.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["secret_manager_resource"],"additionalProperties":false,"properties":{"secret_manager_resource":{"type":"string","description":"Secret Manager resource name; hashed before persistence and never returned in responses."},"kms_key_resource":{"type":"string","description":"Optional KMS key resource name; hashed before persistence."},"version_alias":{"type":"string","default":"latest"},"status":{"type":"string","default":"active"},"connection_status":{"type":"string","default":"active"},"granted_scopes":{"type":"array","items":{"type":"string"}},"missing_scopes":{"type":"array","items":{"type":"string"}}}}}}},"responses":{"200":{"description":"Secret ref recorded","content":{"application/json":{"schema":{"type":"object","required":["status","tenant_id","connection_id","database_url_configured","platform_revoke_called","raw_secrets_returned"],"additionalProperties":true,"properties":{"status":{"type":"string","enum":["connection_secret_ref_recorded","connection_secret_ref_revoked","connection_secret_ref_rotated","connection_secret_ref_not_found","connection_secret_ref_unconfigured","connection_secret_ref_failed","connection_secret_ref_degraded"]},"tenant_id":{"type":"string"},"connection_id":{"type":"string"},"secret_ref_id":{"type":"string"},"version_alias":{"type":"string"},"revoked_count":{"type":"integer","minimum":0},"rotated_count":{"type":"integer","minimum":0},"connection":{"type":"object"},"secret_vault_readiness":{"type":"object"},"ready_for_readonly_etl":{"type":"boolean"},"database_url_configured":{"type":"boolean"},"platform_revoke_called":{"type":"boolean","const":false},"hosted_auth_context":{"type":"object"},"raw_secrets_returned":{"type":"boolean","const":false}}}}}}},"x-gravityads-tool-name":"gravityads.connection.secret.ref.record","x-gravityads-required-scope":"gravityads.admin","x-gravityads-scope-source":"hosted_entitlements"}},"/connections/{connection_id}/secret-ref/revoke":{"post":{"operationId":"connection_secret_ref_revoke","summary":"Revoke a hosted connection Secret Manager ref","description":"Marks the control-plane secret ref and connection revoked. Use /connections/{connection_id}/disconnect with revoke_provider_token=true for optional provider revoke.","requestBody":{"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"version_alias":{"type":"string","default":"latest"},"reason":{"type":"string"}}}}}},"responses":{"200":{"description":"Secret ref revoked","content":{"application/json":{"schema":{"type":"object","required":["status","tenant_id","connection_id","database_url_configured","platform_revoke_called","raw_secrets_returned"],"additionalProperties":true,"properties":{"status":{"type":"string","enum":["connection_secret_ref_recorded","connection_secret_ref_revoked","connection_secret_ref_rotated","connection_secret_ref_not_found","connection_secret_ref_unconfigured","connection_secret_ref_failed","connection_secret_ref_degraded"]},"tenant_id":{"type":"string"},"connection_id":{"type":"string"},"secret_ref_id":{"type":"string"},"version_alias":{"type":"string"},"revoked_count":{"type":"integer","minimum":0},"rotated_count":{"type":"integer","minimum":0},"connection":{"type":"object"},"secret_vault_readiness":{"type":"object"},"ready_for_readonly_etl":{"type":"boolean"},"database_url_configured":{"type":"boolean"},"platform_revoke_called":{"type":"boolean","const":false},"hosted_auth_context":{"type":"object"},"raw_secrets_returned":{"type":"boolean","const":false}}}}}}},"x-gravityads-tool-name":"gravityads.connection.secret.ref.revoke","x-gravityads-required-scope":"gravityads.admin","x-gravityads-scope-source":"hosted_entitlements"}},"/connections/{connection_id}/secret-ref/rotate":{"post":{"operationId":"connection_secret_ref_rotate","summary":"Rotate a hosted connection Secret Manager ref","description":"Marks older active control-plane secret refs as rotated, records the new hashed Secret Manager/KMS ref as active, and updates connection token metadata without returning raw token material.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["secret_manager_resource"],"additionalProperties":false,"properties":{"secret_manager_resource":{"type":"string","description":"Secret Manager resource name; hashed before persistence and never returned in responses."},"kms_key_resource":{"type":"string","description":"Optional KMS key resource name; hashed before persistence."},"version_alias":{"type":"string","default":"latest"},"status":{"type":"string","default":"active"},"connection_status":{"type":"string","default":"active"},"granted_scopes":{"type":"array","items":{"type":"string"}},"missing_scopes":{"type":"array","items":{"type":"string"}}}}}}},"responses":{"200":{"description":"Secret ref rotated","content":{"application/json":{"schema":{"type":"object","required":["status","tenant_id","connection_id","database_url_configured","platform_revoke_called","raw_secrets_returned"],"additionalProperties":true,"properties":{"status":{"type":"string","enum":["connection_secret_ref_recorded","connection_secret_ref_revoked","connection_secret_ref_rotated","connection_secret_ref_not_found","connection_secret_ref_unconfigured","connection_secret_ref_failed","connection_secret_ref_degraded"]},"tenant_id":{"type":"string"},"connection_id":{"type":"string"},"secret_ref_id":{"type":"string"},"version_alias":{"type":"string"},"revoked_count":{"type":"integer","minimum":0},"rotated_count":{"type":"integer","minimum":0},"connection":{"type":"object"},"secret_vault_readiness":{"type":"object"},"ready_for_readonly_etl":{"type":"boolean"},"database_url_configured":{"type":"boolean"},"platform_revoke_called":{"type":"boolean","const":false},"hosted_auth_context":{"type":"object"},"raw_secrets_returned":{"type":"boolean","const":false}}}}}}},"x-gravityads-tool-name":"gravityads.connection.secret.ref.rotate","x-gravityads-required-scope":"gravityads.admin","x-gravityads-scope-source":"hosted_entitlements"}},"/tenant/overview":{"get":{"operationId":"tenant_overview","summary":"Return hosted tenant plan, registry and scope overview","responses":{"200":{"description":"Tenant overview","content":{"application/json":{"schema":{"type":"object","required":["status","tenant_id","hosted_auth_context","plan","subscription","account_registry","account_scope","raw_secrets_returned"],"additionalProperties":true,"properties":{"status":{"type":"string","const":"tenant_overview_ready"},"tenant_id":{"type":"string"},"hosted_auth_context":{"type":"object"},"plan":{"type":"object"},"subscription":{"type":"object","required":["status","tenant_id","subscription_count","subscriptions","raw_provider_ids_returned","raw_secrets_returned"],"properties":{"status":{"type":"string"},"source":{"type":"string"},"tenant_id":{"type":"string"},"subscription_count":{"type":"integer","minimum":0},"database_url_configured":{"type":"boolean"},"default_plan_id":{"type":"string"},"plan":{"type":"object"},"subscriptions":{"type":"array","items":{"type":"object","required":["id","tenant_id","plan_id","provider","status","provider_customer_id_present","provider_customer_id_hash","provider_subscription_id_present","provider_subscription_id_hash"],"properties":{"id":{"type":"string"},"tenant_id":{"type":"string"},"plan_id":{"type":"string"},"provider":{"type":"string"},"status":{"type":"string"},"currency":{"type":"string"},"current_period_start":{"type":"string"},"current_period_end":{"type":"string"},"cancel_at_period_end":{"type":"boolean"},"trial_start":{"type":"string"},"trial_end":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"provider_customer_id_present":{"type":"boolean"},"provider_customer_id_hash":{"type":"string","description":"Short SHA-256 hash prefix; raw cus_* ids are not returned."},"provider_subscription_id_present":{"type":"boolean"},"provider_subscription_id_hash":{"type":"string","description":"Short SHA-256 hash prefix; raw provider subscription ids are not returned."}}}},"raw_provider_ids_returned":{"type":"boolean","const":false},"raw_secrets_returned":{"type":"boolean","const":false}}},"account_registry":{"type":"object"},"account_scope":{"type":"object","required":["account_permission_count","account_permissions","source"],"properties":{"account_permission_count":{"type":"integer","minimum":0},"account_permissions":{"type":"array","items":{"type":"object"}},"source":{"type":"string"}}},"raw_secrets_returned":{"type":"boolean","const":false}}}}}}},"x-gravityads-tool-name":"gravityads.tenant.overview","x-gravityads-required-scope":"gravityads.read","x-gravityads-scope-source":"hosted_entitlements"}},"/tenant/support-ticket":{"post":{"operationId":"tenant_support_ticket","summary":"Create a tenant-bound support ticket handoff","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["subject"],"properties":{"tenant_id":{"type":"string"},"request_id":{"type":"string"},"subject":{"type":"string","minLength":1},"description":{"type":"string"},"severity":{"type":"string","enum":["low","normal","high","critical"],"default":"normal"},"category":{"type":"string","enum":["billing","data","incident","platform","security","support"],"default":"support"},"created_by":{"type":"string"},"source":{"type":"string","default":"ops"},"send":{"type":"boolean","default":false},"incident_trace":{"type":"object"}}}}}},"responses":{"200":{"description":"Redacted tenant support ticket handoff","content":{"application/json":{"schema":{"type":"object","required":["schema_version","status","ticket_id","tenant_id_hash","request_id_hash","subject_hash","subject_length","description_hash","description_length","raw_ticket_payload_returned","raw_provider_target_returned","raw_secret_returned"],"properties":{"schema_version":{"type":"string","const":"gravityads.hosted_support_ticket.v1"},"status":{"type":"string"},"ticket_id":{"type":"string"},"created_at_utc":{"type":"string"},"tenant_id_hash":{"type":"string"},"request_id_hash":{"type":"string"},"subject_hash":{"type":"string"},"subject_length":{"type":"integer","minimum":0},"description_hash":{"type":"string"},"description_length":{"type":"integer","minimum":0},"severity":{"type":"string"},"category":{"type":"string"},"support_provider":{"type":"string"},"provider_target_hash":{"type":"string"},"support_ticket_correlation_header":{"type":"string"},"ready_for_support_ticket_handoff":{"type":"boolean"},"send_requested":{"type":"boolean"},"send_blocker":{"type":"string"},"provider_called":{"type":"boolean"},"sent":{"type":"boolean"},"provider_status_code":{"type":"integer"},"external_ticket_id_hash":{"type":"string"},"provider_response_hash":{"type":"string"},"control_plane_record":{"type":"object"},"raw_ticket_payload_returned":{"type":"boolean","const":false},"raw_provider_target_returned":{"type":"boolean","const":false},"raw_secret_returned":{"type":"boolean","const":false}}}}}}},"x-gravityads-tool-name":"gravityads.tenant.support_ticket","x-gravityads-required-scope":"gravityads.read","x-gravityads-scope-source":"hosted_entitlements"}},"/tenant/support-tickets":{"get":{"operationId":"tenant_support_tickets","summary":"List tenant support ticket handoff records","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":50}},{"name":"category","in":"query","required":false,"schema":{"type":"string"}},{"name":"source","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Redacted tenant support tickets","content":{"application/json":{"schema":{"type":"object","required":["status","tenant_id","support_ticket_count","support_tickets","raw_ticket_payload_returned","raw_provider_target_returned","raw_secrets_returned"],"properties":{"status":{"type":"string"},"tenant_id":{"type":"string"},"category_filter":{"type":"string"},"source_filter":{"type":"string"},"support_ticket_count":{"type":"integer","minimum":0},"support_tickets":{"type":"array","items":{"type":"object","required":["ticket_id","request_id_hash_prefix","subject_hash_prefix","description_hash_prefix","raw_ticket_payload_returned","raw_provider_target_returned","raw_secrets_returned"],"properties":{"ticket_id":{"type":"string"},"tenant_id":{"type":"string"},"request_id_hash_prefix":{"type":"string"},"subject_hash_prefix":{"type":"string"},"description_hash_prefix":{"type":"string"},"severity":{"type":"string"},"category":{"type":"string"},"support_provider":{"type":"string"},"provider_target_hash":{"type":"string"},"status":{"type":"string"},"provider_called":{"type":"boolean"},"sent":{"type":"boolean"},"external_ticket_id_hash":{"type":"string"},"provider_response_hash":{"type":"string"},"provider_status_code":{"type":"integer"},"created_by_user_id_hash_prefix":{"type":"string"},"source":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"raw_ticket_payload_returned":{"type":"boolean","const":false},"raw_provider_target_returned":{"type":"boolean","const":false},"raw_secrets_returned":{"type":"boolean","const":false}}}},"database_url_configured":{"type":"boolean"},"error_type":{"type":"string"},"raw_ticket_payload_returned":{"type":"boolean","const":false},"raw_provider_target_returned":{"type":"boolean","const":false},"raw_secrets_returned":{"type":"boolean","const":false}}}}}}},"x-gravityads-tool-name":"gravityads.tenant.support_tickets","x-gravityads-required-scope":"gravityads.read","x-gravityads-scope-source":"hosted_entitlements"}},"/tenant/data-deletion-requests":{"get":{"operationId":"tenant_data_deletion_requests","summary":"List tenant data deletion request records","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":50}}],"responses":{"200":{"description":"Redacted tenant data deletion requests","content":{"application/json":{"schema":{"type":"object","required":["schema_version","status","request_count","requests","raw_account_ids_returned","raw_customer_ids_returned","raw_ticket_payload_returned","raw_provider_target_returned","raw_secrets_returned"],"properties":{"schema_version":{"type":"string","const":"gravityads.tenant_data_deletion_requests.v1"},"status":{"type":"string"},"tenant_id":{"type":"string"},"request_count":{"type":"integer","minimum":0},"requests":{"type":"array","items":{"type":"object"}},"support_tickets":{"type":"array","items":{"type":"object","required":["ticket_id","request_id_hash_prefix","subject_hash_prefix","description_hash_prefix","raw_ticket_payload_returned","raw_provider_target_returned","raw_secrets_returned"],"properties":{"ticket_id":{"type":"string"},"tenant_id":{"type":"string"},"request_id_hash_prefix":{"type":"string"},"subject_hash_prefix":{"type":"string"},"description_hash_prefix":{"type":"string"},"severity":{"type":"string"},"category":{"type":"string"},"support_provider":{"type":"string"},"provider_target_hash":{"type":"string"},"status":{"type":"string"},"provider_called":{"type":"boolean"},"sent":{"type":"boolean"},"external_ticket_id_hash":{"type":"string"},"provider_response_hash":{"type":"string"},"provider_status_code":{"type":"integer"},"created_by_user_id_hash_prefix":{"type":"string"},"source":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"raw_ticket_payload_returned":{"type":"boolean","const":false},"raw_provider_target_returned":{"type":"boolean","const":false},"raw_secrets_returned":{"type":"boolean","const":false}}}},"database_url_configured":{"type":"boolean"},"ops_filter":{"type":"object"},"raw_account_ids_returned":{"type":"boolean","const":false},"raw_customer_ids_returned":{"type":"boolean","const":false},"raw_ticket_payload_returned":{"type":"boolean","const":false},"raw_provider_target_returned":{"type":"boolean","const":false},"raw_secrets_returned":{"type":"boolean","const":false}}}}}}},"x-gravityads-tool-name":"gravityads.tenant.data_deletion_requests.admin","x-gravityads-required-scope":"gravityads.admin","x-gravityads-scope-source":"hosted_entitlements"},"post":{"operationId":"tenant_data_deletion_request","summary":"Create a tenant data deletion request","description":"Creates a durable deletion job with a cooling-off period and redacted support/audit record. A recently authenticated JWT identity is required unless an explicitly enabled service principal submits the request.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"request_id":{"type":"string"},"request_type":{"type":"string","enum":["account_data_deletion","connection_data_deletion","connection_revoke_and_delete","retention_purge","tenant_data_deletion"],"default":"tenant_data_deletion"},"reason_code":{"type":"string","enum":["contract_termination","customer_request","other","privacy_request","provider_disconnect","test_data"],"default":"customer_request"},"connection_id":{"type":"string"},"platform":{"type":"string"},"platform_account_ref":{"type":"string","description":"Opaque GravityAds control-plane account reference."},"platform_account_id_hash":{"type":"string"},"account_id_hash":{"type":"string"},"request_note":{"type":"string"},"send":{"type":"boolean","default":false}},"additionalProperties":false}}}},"responses":{"200":{"description":"Redacted data deletion request","content":{"application/json":{"schema":{"type":"object","required":["schema_version","status","request_type","reason_code","support_ticket","next_actions","raw_account_ids_returned","raw_customer_ids_returned","raw_request_note_returned","raw_ticket_payload_returned","raw_secrets_returned"],"properties":{"schema_version":{"type":"string","const":"gravityads.tenant_data_deletion_request.v1"},"status":{"type":"string"},"request_type":{"type":"string"},"reason_code":{"type":"string"},"scope":{"type":"object"},"deletion_job":{"type":"object"},"support_ticket":{"type":"object","required":["schema_version","status","ticket_id","tenant_id_hash","request_id_hash","subject_hash","subject_length","description_hash","description_length","raw_ticket_payload_returned","raw_provider_target_returned","raw_secret_returned"],"properties":{"schema_version":{"type":"string","const":"gravityads.hosted_support_ticket.v1"},"status":{"type":"string"},"ticket_id":{"type":"string"},"created_at_utc":{"type":"string"},"tenant_id_hash":{"type":"string"},"request_id_hash":{"type":"string"},"subject_hash":{"type":"string"},"subject_length":{"type":"integer","minimum":0},"description_hash":{"type":"string"},"description_length":{"type":"integer","minimum":0},"severity":{"type":"string"},"category":{"type":"string"},"support_provider":{"type":"string"},"provider_target_hash":{"type":"string"},"support_ticket_correlation_header":{"type":"string"},"ready_for_support_ticket_handoff":{"type":"boolean"},"send_requested":{"type":"boolean"},"send_blocker":{"type":"string"},"provider_called":{"type":"boolean"},"sent":{"type":"boolean"},"provider_status_code":{"type":"integer"},"external_ticket_id_hash":{"type":"string"},"provider_response_hash":{"type":"string"},"control_plane_record":{"type":"object"},"raw_ticket_payload_returned":{"type":"boolean","const":false},"raw_provider_target_returned":{"type":"boolean","const":false},"raw_secret_returned":{"type":"boolean","const":false}}},"ops_followup":{"type":"object"},"next_actions":{"type":"array","items":{"type":"string"}},"raw_account_ids_returned":{"type":"boolean","const":false},"raw_customer_ids_returned":{"type":"boolean","const":false},"raw_request_note_returned":{"type":"boolean","const":false},"raw_ticket_payload_returned":{"type":"boolean","const":false},"raw_secrets_returned":{"type":"boolean","const":false}}}}}}},"x-gravityads-tool-name":"gravityads.tenant.data_deletion_request.admin","x-gravityads-required-scope":"gravityads.admin","x-gravityads-scope-source":"hosted_entitlements"}},"/tenant/data-deletion-requests/{job_id}/cancel":{"post":{"operationId":"tenant_data_deletion_cancel","summary":"Cancel a data deletion request during cooling-off","parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["confirmation"],"properties":{"confirmation":{"type":"string","const":"cancel data deletion"}}}}}},"responses":{"200":{"description":"Deletion request cancelled","content":{"application/json":{"schema":{"type":"object","required":["schema_version","status","cancelled","job","raw_user_ids_returned","raw_account_ids_returned","raw_secrets_returned"],"additionalProperties":true,"properties":{"schema_version":{"type":"string","const":"gravityads.tenant_data_deletion_cancel.v1"},"status":{"type":"string"},"cancelled":{"type":"boolean"},"job":{"type":"object"},"database_url_configured":{"type":"boolean"},"raw_user_ids_returned":{"type":"boolean","const":false},"raw_account_ids_returned":{"type":"boolean","const":false},"raw_secrets_returned":{"type":"boolean","const":false}}}}}},"409":{"description":"Deletion is already running or final"}},"x-gravityads-tool-name":"gravityads.tenant.data_deletion_cancel.admin","x-gravityads-required-scope":"gravityads.admin","x-gravityads-scope-source":"hosted_entitlements"}},"/tenant/design-partner-feedback":{"get":{"operationId":"tenant_design_partner_feedback_status","summary":"List redacted design partner feedback records","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":50}}],"responses":{"200":{"description":"Redacted design partner feedback records","content":{"application/json":{"schema":{"type":"object","required":["schema_version","status","tenant_id","feedback_count","feedback","raw_feedback_returned","raw_contact_returned","raw_company_returned","raw_quote_returned","raw_secret_values_returned"],"properties":{"schema_version":{"type":"string","const":"gravityads.hosted_design_partner_feedback.v1"},"status":{"type":"string"},"tenant_id":{"type":"string"},"feedback_count":{"type":"integer","minimum":0},"feedback_review":{"type":"object","description":"Bounded tenant feedback review, not host task completion or automatic policy changes."},"case_study_candidate_count":{"type":"integer","minimum":0},"feedback":{"type":"array","items":{"type":"object","required":["feedback_id","tenant_id","feedback_type","stage","status","rating","public_case_study_consent","raw_feedback_returned","raw_contact_returned","raw_company_returned","raw_quote_returned","raw_secret_values_returned"],"properties":{"feedback_id":{"type":"string"},"tenant_id":{"type":"string"},"request_id_hash_prefix":{"type":"string"},"feedback_type":{"type":"string"},"stage":{"type":"string"},"status":{"type":"string"},"source":{"type":"string"},"rating":{"type":"integer"},"onboarding_score":{"type":"integer"},"candidate_quality_score":{"type":"integer"},"freshness_score":{"type":"integer"},"pricing_fit_score":{"type":"integer"},"public_case_study_consent":{"type":"boolean"},"public_logo_consent":{"type":"boolean"},"public_quote_hash_prefix":{"type":"string"},"company_name_hash_prefix":{"type":"string"},"contact_email_hash_prefix":{"type":"string"},"role_title_hash_prefix":{"type":"string"},"feedback_text_hash_prefix":{"type":"string"},"blockers_hash_prefix":{"type":"string"},"created_by_user_id_hash_prefix":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"raw_feedback_returned":{"type":"boolean","const":false},"raw_contact_returned":{"type":"boolean","const":false},"raw_company_returned":{"type":"boolean","const":false},"raw_quote_returned":{"type":"boolean","const":false},"raw_secret_values_returned":{"type":"boolean","const":false}}}},"database_url_configured":{"type":"boolean"},"error_type":{"type":"string"},"raw_feedback_returned":{"type":"boolean","const":false},"raw_contact_returned":{"type":"boolean","const":false},"raw_company_returned":{"type":"boolean","const":false},"raw_quote_returned":{"type":"boolean","const":false},"raw_secret_values_returned":{"type":"boolean","const":false}}}}}}},"x-gravityads-tool-name":"gravityads.tenant.design_partner_feedback.status","x-gravityads-required-scope":"gravityads.read","x-gravityads-scope-source":"hosted_entitlements"},"post":{"operationId":"tenant_design_partner_feedback","summary":"Submit redacted design partner GTM feedback","description":"Hashes quote, company, email, role and free-form feedback before persistence. Raw case-study copy must go through separate legal/CMS approval.","requestBody":{"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"feedback_id":{"type":"string"},"request_id":{"type":"string"},"feedback_type":{"type":"string","enum":["onboarding","pricing","candidate_quality","freshness","controlled_action","support","case_study","general"]},"stage":{"type":"string","enum":["waitlist","trial","beta","ga"]},"rating":{"type":"integer","minimum":0,"maximum":10},"onboarding_score":{"type":"integer","minimum":0,"maximum":10},"candidate_quality_score":{"type":"integer","minimum":0,"maximum":10},"freshness_score":{"type":"integer","minimum":0,"maximum":10},"pricing_fit_score":{"type":"integer","minimum":0,"maximum":10},"public_case_study_consent":{"type":"boolean"},"public_logo_consent":{"type":"boolean"},"public_quote":{"type":"string","description":"Accepted for hashing only; raw quote is not persisted or returned."},"company_name":{"type":"string","description":"Accepted for hashing only; raw company is not persisted or returned."},"contact_email":{"type":"string","description":"Accepted for hashing only; raw email is not persisted or returned."},"role_title":{"type":"string"},"feedback_text":{"type":"string"},"blockers":{"type":"string"},"source":{"type":"string"}}}}}},"responses":{"200":{"description":"Redacted design partner feedback record","content":{"application/json":{"schema":{"type":"object","required":["schema_version","status","tenant_id","feedback","control_plane_record","raw_feedback_returned","raw_contact_returned","raw_company_returned","raw_quote_returned","raw_secret_values_returned"],"properties":{"schema_version":{"type":"string","const":"gravityads.hosted_design_partner_feedback.v1"},"status":{"type":"string"},"tenant_id":{"type":"string"},"feedback":{"type":"object","required":["feedback_id","tenant_id","feedback_type","stage","status","rating","public_case_study_consent","raw_feedback_returned","raw_contact_returned","raw_company_returned","raw_quote_returned","raw_secret_values_returned"],"properties":{"feedback_id":{"type":"string"},"tenant_id":{"type":"string"},"request_id_hash_prefix":{"type":"string"},"feedback_type":{"type":"string"},"stage":{"type":"string"},"status":{"type":"string"},"source":{"type":"string"},"rating":{"type":"integer"},"onboarding_score":{"type":"integer"},"candidate_quality_score":{"type":"integer"},"freshness_score":{"type":"integer"},"pricing_fit_score":{"type":"integer"},"public_case_study_consent":{"type":"boolean"},"public_logo_consent":{"type":"boolean"},"public_quote_hash_prefix":{"type":"string"},"company_name_hash_prefix":{"type":"string"},"contact_email_hash_prefix":{"type":"string"},"role_title_hash_prefix":{"type":"string"},"feedback_text_hash_prefix":{"type":"string"},"blockers_hash_prefix":{"type":"string"},"created_by_user_id_hash_prefix":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"raw_feedback_returned":{"type":"boolean","const":false},"raw_contact_returned":{"type":"boolean","const":false},"raw_company_returned":{"type":"boolean","const":false},"raw_quote_returned":{"type":"boolean","const":false},"raw_secret_values_returned":{"type":"boolean","const":false}}},"control_plane_record":{"type":"object"},"raw_feedback_returned":{"type":"boolean","const":false},"raw_contact_returned":{"type":"boolean","const":false},"raw_company_returned":{"type":"boolean","const":false},"raw_quote_returned":{"type":"boolean","const":false},"raw_secret_values_returned":{"type":"boolean","const":false}}}}}}},"x-gravityads-tool-name":"gravityads.tenant.design_partner_feedback.admin","x-gravityads-required-scope":"gravityads.admin","x-gravityads-scope-source":"hosted_entitlements"}},"/workbench/readiness":{"get":{"operationId":"workbench_readiness","summary":"Return Phase 1 read-only Workbench readiness contract","description":"Lists the Workbench readonly API surface and explicitly states that Phase 1 Workbench does not execute platform writes.","responses":{"200":{"description":"Workbench readonly readiness","content":{"application/json":{"schema":{"type":"object","required":["schema_version","status","ready_for_workbench_readonly_v1","phase_contract","read_only_boundary","raw_secret_values_returned","platform_write_called"],"properties":{"schema_version":{"type":"string","const":"gravityads.hosted_workbench_readiness.v1"},"status":{"type":"string"},"ready_for_workbench_readonly_v1":{"type":"boolean"},"phase_contract":{"type":"string","const":"phase1_workbench_readonly_never_executes_platform_writes"},"required_plan_ids":{"type":"array","items":{"type":"string"}},"read_only_boundary":{"type":"object","properties":{"writes_platform":{"type":"boolean","const":false},"controlled_execute_enabled_in_phase1":{"type":"boolean","const":false},"execute_requires_phase2_controlled_action_worker":{"type":"boolean","const":true}}},"endpoint_contract":{"type":"object"},"phase2_controlled_actions":{"type":"object"},"claude_frontend_handoff":{"type":"object"},"raw_secret_values_returned":{"type":"boolean","const":false},"raw_customer_ids_returned":{"type":"boolean","const":false},"raw_account_ids_returned":{"type":"boolean","const":false},"platform_write_called":{"type":"boolean","const":false}}}}}}},"x-gravityads-tool-name":"gravityads.workbench.readiness","x-gravityads-required-scope":"gravityads.read","x-gravityads-scope-source":"hosted_entitlements"}},"/workbench/overview":{"get":{"operationId":"workbench_overview","summary":"Return hosted Workbench overview dashboard state","description":"Aggregates tenant plan, subscription, account scope, connections, data freshness, ETL watermarks and usage for the customer Workbench without returning raw secrets.","parameters":[{"name":"usage_date","in":"query","schema":{"type":"string","description":"YYYY-MM-DD"}},{"name":"platform","in":"query","schema":{"type":"string"}},{"name":"account_id","in":"query","schema":{"type":"string"}},{"name":"etl_limit","in":"query","schema":{"type":"integer","default":20}},{"name":"include_bootstrap_detail","in":"query","schema":{"type":"boolean","default":false}}],"responses":{"200":{"description":"Workbench overview","content":{"application/json":{"schema":{"type":"object","required":["status","tenant_id","hosted_auth_context","plan","subscription","account_scope","connections","freshness","etl_status","usage","readiness","ui_contract","raw_secrets_returned","writes_platform"],"additionalProperties":true,"properties":{"status":{"type":"string","const":"workbench_overview_ready"},"tenant_id":{"type":"string"},"hosted_auth_context":{"type":"object"},"plan":{"type":"object"},"subscription":{"type":"object","required":["status","tenant_id","subscription_count","subscriptions","raw_provider_ids_returned","raw_secrets_returned"],"properties":{"status":{"type":"string"},"source":{"type":"string"},"tenant_id":{"type":"string"},"subscription_count":{"type":"integer","minimum":0},"database_url_configured":{"type":"boolean"},"default_plan_id":{"type":"string"},"plan":{"type":"object"},"subscriptions":{"type":"array","items":{"type":"object","required":["id","tenant_id","plan_id","provider","status","provider_customer_id_present","provider_customer_id_hash","provider_subscription_id_present","provider_subscription_id_hash"],"properties":{"id":{"type":"string"},"tenant_id":{"type":"string"},"plan_id":{"type":"string"},"provider":{"type":"string"},"status":{"type":"string"},"currency":{"type":"string"},"current_period_start":{"type":"string"},"current_period_end":{"type":"string"},"cancel_at_period_end":{"type":"boolean"},"trial_start":{"type":"string"},"trial_end":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"provider_customer_id_present":{"type":"boolean"},"provider_customer_id_hash":{"type":"string","description":"Short SHA-256 hash prefix; raw cus_* ids are not returned."},"provider_subscription_id_present":{"type":"boolean"},"provider_subscription_id_hash":{"type":"string","description":"Short SHA-256 hash prefix; raw provider subscription ids are not returned."}}}},"raw_provider_ids_returned":{"type":"boolean","const":false},"raw_secrets_returned":{"type":"boolean","const":false}}},"account_scope":{"type":"object","required":["account_permission_count","account_permissions","source"],"additionalProperties":true,"properties":{"account_permission_count":{"type":"integer","minimum":0},"account_permissions":{"type":"array","items":{"type":"object"}},"source":{"type":"string"}}},"connections":{"type":"object","additionalProperties":true,"properties":{"status":{"type":"string"},"connection_count":{"type":"integer","minimum":0},"platform_account_count":{"type":"integer","minimum":0},"visible_platform_account_count":{"type":"integer","minimum":0},"discovered_platform_account_count":{"type":"integer","minimum":0},"over_limit_platform_account_count":{"type":"integer","minimum":0},"plan_account_limit":{"type":"object"},"account_scope_count":{"type":"integer","minimum":0},"platform_accounts":{"type":"array","items":{"type":"object"}},"database_url_configured":{"type":"boolean"}}},"freshness":{"type":"object"},"etl_status":{"type":"object","additionalProperties":true,"properties":{"status":{"type":"string"},"run_count":{"type":"integer","minimum":0},"runs":{"type":"array","items":{"type":"object"}},"watermark_count":{"type":"integer","minimum":0},"watermarks":{"type":"array","items":{"type":"object"}},"database_url_configured":{"type":"boolean"}}},"usage":{"type":"object"},"readiness":{"type":"object","additionalProperties":true,"properties":{"status":{"type":"string"},"operational_state":{"type":"string"},"missing_setup_items":{"type":"array","items":{"type":"string"}},"database_url_configured":{"type":"boolean"}}},"ui_contract":{"type":"object","required":["surface","default_tab","read_only","writes_platform"],"additionalProperties":true,"properties":{"surface":{"type":"string","const":"ads_quant_workbench"},"default_tab":{"type":"string"},"read_only":{"type":"boolean","const":true},"writes_platform":{"type":"boolean","const":false},"sections":{"type":"array","items":{"type":"string"}}}},"raw_secrets_returned":{"type":"boolean","const":false},"writes_platform":{"type":"boolean","const":false}}}}}},"403":{"description":"Workbench is not enabled for the current plan","content":{"application/json":{"schema":{"type":"object","required":["status","tenant_id","plan","raw_secrets_returned"],"additionalProperties":true,"properties":{"status":{"type":"string","const":"error"},"code":{"type":"string","const":"workbench_not_enabled_for_plan"},"message":{"type":"string"},"retry":{"type":"boolean","const":false},"tenant_id":{"type":"string"},"plan":{"type":"object"},"hosted_auth_context":{"type":"object"},"raw_secrets_returned":{"type":"boolean","const":false}}}}}}},"x-gravityads-tool-name":"gravityads.workbench_context","x-gravityads-required-scope":"gravityads.read","x-gravityads-scope-source":"hosted_entitlements"}},"/tenant/readiness":{"get":{"operationId":"tenant_readiness","summary":"Return tenant commercial SaaS readiness summary","responses":{"200":{"description":"Tenant readiness summary","content":{"application/json":{"schema":{"type":"object","required":["status","tenant_id","operational_state","missing_setup_items","setup_action_count","setup_actions","required_setup_action_count","commercial_launch_action_count","raw_secrets_returned"],"additionalProperties":true,"properties":{"status":{"type":"string","enum":["tenant_readiness_ready","tenant_readiness_unconfigured","tenant_readiness_degraded"]},"tenant_id":{"type":"string"},"operational_state":{"type":"string","enum":["ready","needs_setup","attention_required","unconfigured","degraded"]},"missing_setup_items":{"type":"array","items":{"type":"string"}},"plan_id":{"type":"string"},"plan_usage_limits":{"type":"object"},"subscription":{"type":"object","properties":{"subscription_count":{"type":"integer","minimum":0},"active_subscription_count":{"type":"integer","minimum":0},"default_plan_id":{"type":"string"}}},"connections":{"type":"object","properties":{"connection_count":{"type":"integer","minimum":0},"ready_connection_count":{"type":"integer","minimum":0},"platform_account_count":{"type":"integer","minimum":0},"account_scope_count":{"type":"integer","minimum":0},"user_count":{"type":"integer","minimum":0},"validations":{"type":"array","items":{"type":"object"}}}},"freshness":{"type":"object","properties":{"run_count":{"type":"integer","minimum":0},"watermark_count":{"type":"integer","minimum":0},"watermark_status_counts":{"type":"object"},"latest_watermarks":{"type":"array","items":{"type":"object"}}}},"usage":{"type":"object","properties":{"row_count":{"type":"integer","minimum":0},"rows":{"type":"array","items":{"type":"object"}}}},"enterprise_sso":{"type":"object"},"setup_action_count":{"type":"integer","minimum":0},"setup_actions":{"type":"array","items":{"type":"object","required":["id","status"],"additionalProperties":true,"properties":{"id":{"type":"string"},"status":{"type":"string"},"owner":{"type":"string"},"path":{"type":"string"},"requires":{"type":"array","items":{"type":"string"}},"url_present":{"type":"boolean"},"session_id":{"type":"string"}}}},"required_setup_action_count":{"type":"integer","minimum":0},"commercial_launch_action_count":{"type":"integer","minimum":0},"database_url_configured":{"type":"boolean"},"raw_secrets_returned":{"type":"boolean","const":false}}}}}}},"x-gravityads-tool-name":"gravityads.tenant.readiness","x-gravityads-required-scope":"gravityads.admin","x-gravityads-scope-source":"hosted_entitlements"}},"/tenant/compliance":{"get":{"operationId":"tenant_compliance","summary":"Return tenant compliance and data retention controls","responses":{"200":{"description":"Tenant compliance controls","content":{"application/json":{"schema":{"type":"object","required":["status","tenant_id","database_url_configured","data_retention","data_deletion_requests","enterprise_sso","raw_secrets_returned"],"additionalProperties":true,"properties":{"status":{"type":"string","enum":["tenant_compliance_ready","tenant_compliance_unconfigured","tenant_compliance_degraded","tenant_compliance_updated","tenant_compliance_update_failed","tenant_compliance_update_degraded"]},"tenant_id":{"type":"string"},"database_url_configured":{"type":"boolean"},"tenant_found":{"type":"boolean"},"data_retention":{"type":"object"},"data_deletion_requests":{"type":"object"},"soc2_lite_checklist":{"type":"object"},"security_controls":{"type":"object"},"export_controls":{"type":"object"},"enterprise_sso":{"type":"object"},"hosted_auth_context":{"type":"object"},"raw_secrets_returned":{"type":"boolean","const":false}}}}}}},"x-gravityads-tool-name":"gravityads.tenant.compliance","x-gravityads-required-scope":"gravityads.admin","x-gravityads-scope-source":"hosted_entitlements"},"post":{"operationId":"tenant_compliance_update","summary":"Update tenant data retention controls","requestBody":{"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"data_retention_days":{"type":"integer","minimum":30,"maximum":2555},"benchmark_opt_out":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Tenant compliance updated","content":{"application/json":{"schema":{"type":"object","required":["status","tenant_id","database_url_configured","data_retention","data_deletion_requests","enterprise_sso","raw_secrets_returned"],"additionalProperties":true,"properties":{"status":{"type":"string","enum":["tenant_compliance_ready","tenant_compliance_unconfigured","tenant_compliance_degraded","tenant_compliance_updated","tenant_compliance_update_failed","tenant_compliance_update_degraded"]},"tenant_id":{"type":"string"},"database_url_configured":{"type":"boolean"},"tenant_found":{"type":"boolean"},"data_retention":{"type":"object"},"data_deletion_requests":{"type":"object"},"soc2_lite_checklist":{"type":"object"},"security_controls":{"type":"object"},"export_controls":{"type":"object"},"enterprise_sso":{"type":"object"},"hosted_auth_context":{"type":"object"},"raw_secrets_returned":{"type":"boolean","const":false}}}}}}},"x-gravityads-tool-name":"gravityads.tenant.compliance.update","x-gravityads-required-scope":"gravityads.admin","x-gravityads-scope-source":"hosted_entitlements"}},"/tenant/alerts":{"get":{"operationId":"tenant_alerts","summary":"Return tenant hosted operations alerts","responses":{"200":{"description":"Tenant alerts","content":{"application/json":{"schema":{"type":"object","required":["status","tenant_id","alert_count","severity_counts","alerts","database_url_configured","raw_secrets_returned"],"additionalProperties":true,"properties":{"status":{"type":"string","enum":["tenant_alerts_ready","tenant_alerts_unconfigured","tenant_alerts_degraded"]},"schema_version":{"type":"string"},"tenant_id":{"type":"string"},"billing_period":{"type":"object"},"alert_count":{"type":"integer","minimum":0},"severity_counts":{"type":"object"},"alerts":{"type":"array","items":{"type":"object"}},"usage_summary":{"type":"object"},"freshness_summary":{"type":"object"},"action_queue_summary":{"type":"object"},"database_url_configured":{"type":"boolean"},"hosted_auth_context":{"type":"object"},"raw_secrets_returned":{"type":"boolean","const":false}}}}}}},"x-gravityads-tool-name":"gravityads.tenant.alerts","x-gravityads-required-scope":"gravityads.admin","x-gravityads-scope-source":"hosted_entitlements"}},"/tenant/bootstrap":{"post":{"operationId":"tenant_bootstrap","summary":"Bootstrap a hosted tenant with first admin user","requestBody":{"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"tenant_name":{"type":"string"},"plan_id":{"type":"string","default":"free"},"admin_user_id":{"type":"string"},"admin_email_hash":{"type":"string"},"oidc_sub":{"type":"string"},"feishu_open_id":{"type":"string"},"display_name":{"type":"string"},"create_subscription":{"type":"boolean","default":false},"subscription_status":{"type":"string","default":"incomplete"},"provider":{"type":"string","default":"manual"},"provider_customer_id":{"type":"string"},"provider_subscription_id":{"type":"string"},"currency":{"type":"string","default":"usd"},"current_period_start":{"type":"string","format":"date-time"},"current_period_end":{"type":"string","format":"date-time"},"trial_start":{"type":"string","format":"date-time"},"trial_end":{"type":"string","format":"date-time"},"checkout":{"oneOf":[{"type":"boolean"},{"type":"object","additionalProperties":false,"properties":{"enabled":{"type":"boolean","default":false},"success_url":{"type":"string","format":"uri"},"cancel_url":{"type":"string","format":"uri"},"customer_id":{"type":"string"},"billing_interval":{"type":"string","enum":["monthly","annual"],"default":"monthly"},"request_key":{"type":"string","maxLength":150},"quantity":{"type":"integer","minimum":1,"maximum":999},"promotion_code":{"type":"string"},"allow_promotion_codes":{"type":"boolean","default":true},"metadata":{"type":"object","additionalProperties":{"type":"string"}}}}]},"signup_attribution":{"type":"object","additionalProperties":false,"properties":{"source":{"type":"string"},"registration_code_hash":{"type":"string"},"registration_code_type":{"type":"string"},"referral_code_hash":{"type":"string"},"promotion_code_hash":{"type":"string"},"product":{"type":"string"},"source_domain_hash":{"type":"string"},"email_domain_hash":{"type":"string"},"billing_mode":{"type":"string"}}},"landing_evidence":{"type":"object","additionalProperties":false,"required":["schema_version","event_id","occurred_at","entrypoint"],"properties":{"schema_version":{"type":"string","const":"gravityads.portal_landing.v1"},"event_id":{"type":"string","pattern":"^[a-f0-9]{64}$"},"occurred_at":{"type":"string","format":"date-time"},"entrypoint":{"type":"string","enum":["home","docs","pricing","security"]}}}}}}}},"responses":{"200":{"description":"Tenant bootstrapped","content":{"application/json":{"schema":{"type":"object","required":["status","raw_secrets_returned"],"additionalProperties":true,"properties":{"status":{"type":"string","enum":["tenant_bootstrapped","tenant_bootstrapped_checkout_setup_required","tenant_bootstrapped_checkout_failed","tenant_bootstrap_failed","tenant_bootstrap_degraded","tenant_bootstrap_unconfigured"]},"tenant_id":{"type":"string"},"admin_user_id":{"type":"string"},"plan":{"type":"object"},"subscription_created":{"type":"boolean"},"subscription":{"type":"object"},"users":{"type":"array","items":{"type":"object"}},"user_count":{"type":"integer","minimum":0},"database_url_configured":{"type":"boolean"},"checkout_requested":{"type":"boolean"},"checkout_session":{"type":"object","required":["status","raw_secrets_returned"],"additionalProperties":true,"properties":{"status":{"type":"string","enum":["stripe_checkout_session_created","stripe_checkout_setup_required","stripe_checkout_session_failed"]},"tenant_id":{"type":"string"},"plan_id":{"type":"string"},"session_id":{"type":"string"},"url":{"type":"string"},"client_secret":{"type":"string"},"mode":{"type":"string"},"payment_status":{"type":"string"},"error_code":{"type":"string"},"retry":{"type":"boolean"},"raw_secrets_returned":{"type":"boolean","const":false}}},"error_code":{"type":"string"},"message":{"type":"string"},"retry":{"type":"boolean"},"billing_setup_required":{"type":"boolean"},"self_service_checkout_ready":{"type":"boolean","const":false},"payment_collection_blocked":{"type":"boolean"},"tenant_bootstrapped":{"type":"boolean"},"internal_trial_active":{"type":"boolean"},"safe_to_continue_read_only_setup":{"type":"boolean"},"next_actions":{"type":"array","items":{"type":"object","required":["id","status"],"additionalProperties":true,"properties":{"id":{"type":"string"},"status":{"type":"string"},"owner":{"type":"string"},"path":{"type":"string"},"requires":{"type":"array","items":{"type":"string"}},"url_present":{"type":"boolean"},"session_id":{"type":"string"}}}},"raw_price_ids_returned":{"type":"boolean","const":false},"raw_secrets_returned":{"type":"boolean","const":false}}}}}}},"x-gravityads-tool-name":"gravityads.tenant.bootstrap","x-gravityads-required-scope":"gravityads.admin","x-gravityads-scope-source":"hosted_entitlements"}},"/tenant/users":{"get":{"operationId":"tenant_users","summary":"List hosted tenant users and roles","responses":{"200":{"description":"Tenant users","content":{"application/json":{"schema":{"type":"object","required":["status","tenant_id","user_count","users","role_count","roles","raw_secrets_returned"],"additionalProperties":true,"properties":{"status":{"type":"string","enum":["tenant_user_status_ready","tenant_user_status_unconfigured","tenant_user_status_degraded"]},"source":{"type":"string"},"tenant_id":{"type":"string"},"user_count":{"type":"integer","minimum":0},"users":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"id":{"type":"string"},"tenant_id":{"type":"string"},"email_hash_prefix":{"type":"string"},"oidc_sub":{"type":"string"},"feishu_open_id":{"type":"string"},"display_name":{"type":"string"},"status":{"type":"string"},"created_at":{"type":"string"},"roles":{"type":"array","items":{"type":"string"}}}}},"role_count":{"type":"integer","minimum":0},"roles":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"}}}},"database_url_configured":{"type":"boolean"},"hosted_auth_context":{"type":"object"},"raw_secrets_returned":{"type":"boolean","const":false}}}}}}},"x-gravityads-tool-name":"gravityads.tenant.users","x-gravityads-required-scope":"gravityads.admin","x-gravityads-scope-source":"hosted_entitlements"}},"/tenant/role-scope-policy":{"get":{"operationId":"tenant_role_scope_policy","summary":"Return the hosted tenant role-to-scope policy contract","responses":{"200":{"description":"Role scope policy","content":{"application/json":{"schema":{"type":"object","required":["status","roles"],"additionalProperties":true,"properties":{"status":{"type":"string","const":"role_scope_policy_ready"},"tenant_id":{"type":"string"},"roles":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}},"hosted_auth_context":{"type":"object"}}}}}}},"x-gravityads-tool-name":"gravityads.tenant.role.scope.policy","x-gravityads-required-scope":"gravityads.read","x-gravityads-scope-source":"hosted_entitlements"}},"/tenant/users/{user_id}/effective-permissions":{"get":{"operationId":"tenant_user_effective_permissions","summary":"Explain a hosted tenant user's effective ad account permissions","parameters":[{"name":"user_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Effective permissions","content":{"application/json":{"schema":{"type":"object","required":["status","tenant_id","user_id","exists","role_ids","account_permission_count","account_permissions","customer_group_count","customer_groups","raw_secrets_returned"],"additionalProperties":true,"properties":{"status":{"type":"string","enum":["tenant_user_effective_permissions_ready","tenant_user_effective_permissions_not_found","tenant_user_effective_permissions_unconfigured","tenant_user_effective_permissions_degraded"]},"source":{"type":"string"},"tenant_id":{"type":"string"},"user_id":{"type":"string"},"exists":{"type":"boolean"},"user":{"type":"object","additionalProperties":true,"properties":{"id":{"type":"string"},"tenant_id":{"type":"string"},"email_hash_prefix":{"type":"string"},"oidc_sub":{"type":"string"},"feishu_open_id":{"type":"string"},"display_name":{"type":"string"},"status":{"type":"string"},"created_at":{"type":"string"},"roles":{"type":"array","items":{"type":"string"}}}},"role_ids":{"type":"array","items":{"type":"string"}},"role_derived_scopes":{"type":"array","items":{"type":"string"}},"account_permission_count":{"type":"integer","minimum":0},"account_permissions":{"type":"array","items":{"type":"object"}},"customer_group_count":{"type":"integer","minimum":0},"customer_groups":{"type":"array","items":{"type":"object"}},"database_url_configured":{"type":"boolean"},"hosted_auth_context":{"type":"object"},"raw_secrets_returned":{"type":"boolean","const":false}}}}}}},"x-gravityads-tool-name":"gravityads.tenant.user.effective.permissions","x-gravityads-required-scope":"gravityads.admin","x-gravityads-scope-source":"hosted_entitlements"}},"/tenant/directory-sync/users":{"post":{"operationId":"tenant_directory_sync_users","summary":"Bulk sync hosted tenant users from an IdP directory","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["users"],"additionalProperties":false,"properties":{"source":{"type":"string","default":"idp_directory"},"replace_roles":{"type":"boolean","default":false},"users":{"type":"array","items":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string"},"email_hash":{"type":"string"},"oidc_sub":{"type":"string"},"feishu_open_id":{"type":"string"},"display_name":{"type":"string"},"status":{"type":"string","default":"active"},"roles":{"type":"array","items":{"type":"string"},"maxItems":20}}},"maxItems":500}}}}}},"responses":{"200":{"description":"Directory users synced","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}},"x-gravityads-tool-name":"gravityads.tenant.directory.sync.users","x-gravityads-required-scope":"gravityads.admin","x-gravityads-scope-source":"hosted_entitlements"}},"/scim/v2/ServiceProviderConfig":{"get":{"operationId":"scim_service_provider_config","summary":"Return GravityAds SCIM v2 service provider capabilities","responses":{"200":{"description":"SCIM service provider config","content":{"application/json":{"schema":{"type":"object","required":["schemas","patch","bulk","filter","authenticationSchemes","gravityads","raw_email_returned","raw_secrets_returned"],"additionalProperties":true,"properties":{"schemas":{"type":"array","items":{"type":"string"}},"patch":{"type":"object"},"bulk":{"type":"object"},"filter":{"type":"object"},"changePassword":{"type":"object"},"sort":{"type":"object"},"etag":{"type":"object"},"authenticationSchemes":{"type":"array","items":{"type":"object"}},"gravityads":{"type":"object"},"raw_email_returned":{"type":"boolean","const":false},"raw_secrets_returned":{"type":"boolean","const":false}}}}}}},"x-gravityads-tool-name":"gravityads.scim.service.provider.config","x-gravityads-required-scope":"gravityads.admin","x-gravityads-scope-source":"hosted_entitlements"}},"/scim/v2/ResourceTypes":{"get":{"operationId":"scim_resource_types","summary":"Return GravityAds SCIM v2 resource types","responses":{"200":{"description":"SCIM resource types","content":{"application/json":{"schema":{"type":"object","required":["schemas","totalResults","Resources","startIndex","itemsPerPage","gravityads","raw_email_returned","raw_secrets_returned"],"additionalProperties":true,"properties":{"schemas":{"type":"array","items":{"type":"string"}},"totalResults":{"type":"integer","minimum":0},"Resources":{"type":"array","items":{"type":"object","required":["schemas","id","gravityads"],"additionalProperties":true,"properties":{"schemas":{"type":"array","items":{"type":"string"}},"id":{"type":"string"},"externalId":{"type":"string"},"userName":{"type":"string"},"displayName":{"type":"string"},"active":{"type":"boolean","default":true},"emails":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"value":{"type":"string"},"display":{"type":"string"},"type":{"type":"string"},"primary":{"type":"boolean"}}}},"roles":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"value":{"type":"string"},"display":{"type":"string"},"type":{"type":"string"},"primary":{"type":"boolean"}}}},"groups":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"value":{"type":"string"},"display":{"type":"string"},"type":{"type":"string"},"primary":{"type":"boolean"}}}},"meta":{"type":"object"},"gravityads":{"type":"object"},"hosted_auth_context":{"type":"object"},"raw_email_returned":{"type":"boolean","const":false},"raw_secrets_returned":{"type":"boolean","const":false}}}},"startIndex":{"type":"integer","minimum":1},"itemsPerPage":{"type":"integer","minimum":0},"gravityads":{"type":"object"},"hosted_auth_context":{"type":"object"},"raw_email_returned":{"type":"boolean","const":false},"raw_secrets_returned":{"type":"boolean","const":false}}}}}}},"x-gravityads-tool-name":"gravityads.scim.resource.types","x-gravityads-required-scope":"gravityads.admin","x-gravityads-scope-source":"hosted_entitlements"}},"/scim/v2/Schemas":{"get":{"operationId":"scim_schemas","summary":"Return GravityAds SCIM v2 schema descriptors","responses":{"200":{"description":"SCIM schemas","content":{"application/json":{"schema":{"type":"object","required":["schemas","totalResults","Resources","startIndex","itemsPerPage","gravityads","raw_email_returned","raw_secrets_returned"],"additionalProperties":true,"properties":{"schemas":{"type":"array","items":{"type":"string"}},"totalResults":{"type":"integer","minimum":0},"Resources":{"type":"array","items":{"type":"object","required":["schemas","id","gravityads"],"additionalProperties":true,"properties":{"schemas":{"type":"array","items":{"type":"string"}},"id":{"type":"string"},"externalId":{"type":"string"},"userName":{"type":"string"},"displayName":{"type":"string"},"active":{"type":"boolean","default":true},"emails":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"value":{"type":"string"},"display":{"type":"string"},"type":{"type":"string"},"primary":{"type":"boolean"}}}},"roles":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"value":{"type":"string"},"display":{"type":"string"},"type":{"type":"string"},"primary":{"type":"boolean"}}}},"groups":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"value":{"type":"string"},"display":{"type":"string"},"type":{"type":"string"},"primary":{"type":"boolean"}}}},"meta":{"type":"object"},"gravityads":{"type":"object"},"hosted_auth_context":{"type":"object"},"raw_email_returned":{"type":"boolean","const":false},"raw_secrets_returned":{"type":"boolean","const":false}}}},"startIndex":{"type":"integer","minimum":1},"itemsPerPage":{"type":"integer","minimum":0},"gravityads":{"type":"object"},"hosted_auth_context":{"type":"object"},"raw_email_returned":{"type":"boolean","const":false},"raw_secrets_returned":{"type":"boolean","const":false}}}}}}},"x-gravityads-tool-name":"gravityads.scim.schemas","x-gravityads-required-scope":"gravityads.admin","x-gravityads-scope-source":"hosted_entitlements"}},"/tenant/scim/status":{"get":{"operationId":"tenant_scim_status","summary":"Return tenant SCIM configuration and directory status","responses":{"200":{"description":"Tenant SCIM status","content":{"application/json":{"schema":{"type":"object","required":["status","tenant_id","scim_supported","database_url_configured","raw_email_returned","raw_secrets_returned"],"properties":{"status":{"type":"string"},"tenant_id":{"type":"string"},"scim_supported":{"type":"boolean","const":true},"users_supported":{"type":"boolean","const":true},"groups_supported":{"type":"boolean","const":true},"ready_for_scim":{"type":"boolean"},"auth_surface":{"type":"string"},"scim_auth_requires_admin_scope":{"type":"boolean","const":true},"database_url_configured":{"type":"boolean"},"user_count":{"type":"integer","minimum":0},"active_user_count":{"type":"integer","minimum":0},"group_count":{"type":"integer","minimum":0},"role_group_ids":{"type":"array","items":{"type":"string"}},"endpoints":{"type":"object"},"raw_email_returned":{"type":"boolean","const":false},"raw_secrets_returned":{"type":"boolean","const":false}}}}}}},"x-gravityads-tool-name":"gravityads.tenant.scim.status","x-gravityads-required-scope":"gravityads.admin","x-gravityads-scope-source":"hosted_entitlements"}},"/scim/v2/Users":{"get":{"operationId":"scim_users_list","summary":"List hosted tenant users through a sanitized SCIM v2 façade","parameters":[{"name":"filter","in":"query","required":false,"schema":{"type":"string"}},{"name":"startIndex","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":1}},{"name":"count","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":500}}],"responses":{"200":{"description":"SCIM users listed","content":{"application/json":{"schema":{"type":"object","required":["schemas","totalResults","Resources","startIndex","itemsPerPage","gravityads","raw_email_returned","raw_secrets_returned"],"additionalProperties":true,"properties":{"schemas":{"type":"array","items":{"type":"string"}},"totalResults":{"type":"integer","minimum":0},"Resources":{"type":"array","items":{"type":"object","required":["schemas","id","gravityads"],"additionalProperties":true,"properties":{"schemas":{"type":"array","items":{"type":"string"}},"id":{"type":"string"},"externalId":{"type":"string"},"userName":{"type":"string"},"displayName":{"type":"string"},"active":{"type":"boolean","default":true},"emails":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"value":{"type":"string"},"display":{"type":"string"},"type":{"type":"string"},"primary":{"type":"boolean"}}}},"roles":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"value":{"type":"string"},"display":{"type":"string"},"type":{"type":"string"},"primary":{"type":"boolean"}}}},"groups":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"value":{"type":"string"},"display":{"type":"string"},"type":{"type":"string"},"primary":{"type":"boolean"}}}},"meta":{"type":"object"},"gravityads":{"type":"object"},"hosted_auth_context":{"type":"object"},"raw_email_returned":{"type":"boolean","const":false},"raw_secrets_returned":{"type":"boolean","const":false}}}},"startIndex":{"type":"integer","minimum":1},"itemsPerPage":{"type":"integer","minimum":0},"gravityads":{"type":"object"},"hosted_auth_context":{"type":"object"},"raw_email_returned":{"type":"boolean","const":false},"raw_secrets_returned":{"type":"boolean","const":false}}}}}}},"x-gravityads-tool-name":"gravityads.scim.users.list","x-gravityads-required-scope":"gravityads.admin","x-gravityads-scope-source":"hosted_entitlements"},"post":{"operationId":"scim_users_create","summary":"Create or sync one hosted tenant user through a SCIM v2 façade","requestBody":{"content":{"application/scim+json":{"schema":{"type":"object","additionalProperties":true,"properties":{"schemas":{"type":"array","items":{"type":"string"}},"id":{"type":"string"},"externalId":{"type":"string"},"userName":{"type":"string"},"displayName":{"type":"string"},"active":{"type":"boolean","default":true},"emails":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"value":{"type":"string"},"display":{"type":"string"},"type":{"type":"string"},"primary":{"type":"boolean"}}}},"roles":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"value":{"type":"string"},"display":{"type":"string"},"type":{"type":"string"},"primary":{"type":"boolean"}}}},"groups":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"value":{"type":"string"},"display":{"type":"string"},"type":{"type":"string"},"primary":{"type":"boolean"}}}}}}},"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"schemas":{"type":"array","items":{"type":"string"}},"id":{"type":"string"},"externalId":{"type":"string"},"userName":{"type":"string"},"displayName":{"type":"string"},"active":{"type":"boolean","default":true},"emails":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"value":{"type":"string"},"display":{"type":"string"},"type":{"type":"string"},"primary":{"type":"boolean"}}}},"roles":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"value":{"type":"string"},"display":{"type":"string"},"type":{"type":"string"},"primary":{"type":"boolean"}}}},"groups":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"value":{"type":"string"},"display":{"type":"string"},"type":{"type":"string"},"primary":{"type":"boolean"}}}}}}}}},"responses":{"201":{"description":"SCIM user synced","content":{"application/json":{"schema":{"type":"object","required":["schemas","id","gravityads"],"additionalProperties":true,"properties":{"schemas":{"type":"array","items":{"type":"string"}},"id":{"type":"string"},"externalId":{"type":"string"},"userName":{"type":"string"},"displayName":{"type":"string"},"active":{"type":"boolean","default":true},"emails":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"value":{"type":"string"},"display":{"type":"string"},"type":{"type":"string"},"primary":{"type":"boolean"}}}},"roles":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"value":{"type":"string"},"display":{"type":"string"},"type":{"type":"string"},"primary":{"type":"boolean"}}}},"groups":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"value":{"type":"string"},"display":{"type":"string"},"type":{"type":"string"},"primary":{"type":"boolean"}}}},"meta":{"type":"object"},"gravityads":{"type":"object"},"hosted_auth_context":{"type":"object"},"raw_email_returned":{"type":"boolean","const":false},"raw_secrets_returned":{"type":"boolean","const":false}}}}}}},"x-gravityads-tool-name":"gravityads.scim.users.create","x-gravityads-required-scope":"gravityads.admin","x-gravityads-scope-source":"hosted_entitlements"}},"/scim/v2/Users/{user_id}":{"get":{"operationId":"scim_user_get","summary":"Read one hosted tenant user through a sanitized SCIM v2 façade","parameters":[{"name":"user_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"SCIM user","content":{"application/json":{"schema":{"type":"object","required":["schemas","id","gravityads"],"additionalProperties":true,"properties":{"schemas":{"type":"array","items":{"type":"string"}},"id":{"type":"string"},"externalId":{"type":"string"},"userName":{"type":"string"},"displayName":{"type":"string"},"active":{"type":"boolean","default":true},"emails":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"value":{"type":"string"},"display":{"type":"string"},"type":{"type":"string"},"primary":{"type":"boolean"}}}},"roles":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"value":{"type":"string"},"display":{"type":"string"},"type":{"type":"string"},"primary":{"type":"boolean"}}}},"groups":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"value":{"type":"string"},"display":{"type":"string"},"type":{"type":"string"},"primary":{"type":"boolean"}}}},"meta":{"type":"object"},"gravityads":{"type":"object"},"hosted_auth_context":{"type":"object"},"raw_email_returned":{"type":"boolean","const":false},"raw_secrets_returned":{"type":"boolean","const":false}}}}}}},"x-gravityads-tool-name":"gravityads.scim.user.get","x-gravityads-required-scope":"gravityads.admin","x-gravityads-scope-source":"hosted_entitlements"},"put":{"operationId":"scim_user_replace","summary":"Replace one hosted tenant user through a SCIM v2 façade","parameters":[{"name":"user_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/scim+json":{"schema":{"type":"object","additionalProperties":true,"properties":{"schemas":{"type":"array","items":{"type":"string"}},"id":{"type":"string"},"externalId":{"type":"string"},"userName":{"type":"string"},"displayName":{"type":"string"},"active":{"type":"boolean","default":true},"emails":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"value":{"type":"string"},"display":{"type":"string"},"type":{"type":"string"},"primary":{"type":"boolean"}}}},"roles":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"value":{"type":"string"},"display":{"type":"string"},"type":{"type":"string"},"primary":{"type":"boolean"}}}},"groups":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"value":{"type":"string"},"display":{"type":"string"},"type":{"type":"string"},"primary":{"type":"boolean"}}}}}}},"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"schemas":{"type":"array","items":{"type":"string"}},"id":{"type":"string"},"externalId":{"type":"string"},"userName":{"type":"string"},"displayName":{"type":"string"},"active":{"type":"boolean","default":true},"emails":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"value":{"type":"string"},"display":{"type":"string"},"type":{"type":"string"},"primary":{"type":"boolean"}}}},"roles":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"value":{"type":"string"},"display":{"type":"string"},"type":{"type":"string"},"primary":{"type":"boolean"}}}},"groups":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"value":{"type":"string"},"display":{"type":"string"},"type":{"type":"string"},"primary":{"type":"boolean"}}}}}}}}},"responses":{"200":{"description":"SCIM user synced","content":{"application/json":{"schema":{"type":"object","required":["schemas","id","gravityads"],"additionalProperties":true,"properties":{"schemas":{"type":"array","items":{"type":"string"}},"id":{"type":"string"},"externalId":{"type":"string"},"userName":{"type":"string"},"displayName":{"type":"string"},"active":{"type":"boolean","default":true},"emails":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"value":{"type":"string"},"display":{"type":"string"},"type":{"type":"string"},"primary":{"type":"boolean"}}}},"roles":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"value":{"type":"string"},"display":{"type":"string"},"type":{"type":"string"},"primary":{"type":"boolean"}}}},"groups":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"value":{"type":"string"},"display":{"type":"string"},"type":{"type":"string"},"primary":{"type":"boolean"}}}},"meta":{"type":"object"},"gravityads":{"type":"object"},"hosted_auth_context":{"type":"object"},"raw_email_returned":{"type":"boolean","const":false},"raw_secrets_returned":{"type":"boolean","const":false}}}}}}},"x-gravityads-tool-name":"gravityads.scim.user.replace","x-gravityads-required-scope":"gravityads.admin","x-gravityads-scope-source":"hosted_entitlements"},"patch":{"operationId":"scim_user_patch","summary":"Patch one hosted tenant user through a SCIM v2 façade","parameters":[{"name":"user_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/scim+json":{"schema":{"type":"object","additionalProperties":true,"properties":{"schemas":{"type":"array","items":{"type":"string"}},"Operations":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"op":{"type":"string"},"path":{"type":"string"},"value":{}}}},"active":{"type":"boolean"},"roles":{"type":"array"},"groups":{"type":"array"}}}},"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"schemas":{"type":"array","items":{"type":"string"}},"Operations":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"op":{"type":"string"},"path":{"type":"string"},"value":{}}}},"active":{"type":"boolean"},"roles":{"type":"array"},"groups":{"type":"array"}}}}}},"responses":{"200":{"description":"SCIM user patched","content":{"application/json":{"schema":{"type":"object","required":["schemas","id","gravityads"],"additionalProperties":true,"properties":{"schemas":{"type":"array","items":{"type":"string"}},"id":{"type":"string"},"externalId":{"type":"string"},"userName":{"type":"string"},"displayName":{"type":"string"},"active":{"type":"boolean","default":true},"emails":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"value":{"type":"string"},"display":{"type":"string"},"type":{"type":"string"},"primary":{"type":"boolean"}}}},"roles":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"value":{"type":"string"},"display":{"type":"string"},"type":{"type":"string"},"primary":{"type":"boolean"}}}},"groups":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"value":{"type":"string"},"display":{"type":"string"},"type":{"type":"string"},"primary":{"type":"boolean"}}}},"meta":{"type":"object"},"gravityads":{"type":"object"},"hosted_auth_context":{"type":"object"},"raw_email_returned":{"type":"boolean","const":false},"raw_secrets_returned":{"type":"boolean","const":false}}}}}}},"x-gravityads-tool-name":"gravityads.scim.user.patch","x-gravityads-required-scope":"gravityads.admin","x-gravityads-scope-source":"hosted_entitlements"},"delete":{"operationId":"scim_user_delete","summary":"Deactivate one hosted tenant user through a SCIM v2 façade","parameters":[{"name":"user_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"SCIM user deactivated","content":{"application/json":{"schema":{"type":"object","required":["schemas","id","gravityads"],"additionalProperties":true,"properties":{"schemas":{"type":"array","items":{"type":"string"}},"id":{"type":"string"},"externalId":{"type":"string"},"userName":{"type":"string"},"displayName":{"type":"string"},"active":{"type":"boolean","default":true},"emails":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"value":{"type":"string"},"display":{"type":"string"},"type":{"type":"string"},"primary":{"type":"boolean"}}}},"roles":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"value":{"type":"string"},"display":{"type":"string"},"type":{"type":"string"},"primary":{"type":"boolean"}}}},"groups":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"value":{"type":"string"},"display":{"type":"string"},"type":{"type":"string"},"primary":{"type":"boolean"}}}},"meta":{"type":"object"},"gravityads":{"type":"object"},"hosted_auth_context":{"type":"object"},"raw_email_returned":{"type":"boolean","const":false},"raw_secrets_returned":{"type":"boolean","const":false}}}}}}},"x-gravityads-tool-name":"gravityads.scim.user.delete","x-gravityads-required-scope":"gravityads.admin","x-gravityads-scope-source":"hosted_entitlements"}},"/scim/v2/Groups":{"get":{"operationId":"scim_groups_list","summary":"List GravityAds roles as SCIM v2 Groups","parameters":[{"name":"startIndex","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":1}},{"name":"count","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":500}}],"responses":{"200":{"description":"SCIM groups listed","content":{"application/json":{"schema":{"type":"object","required":["schemas","totalResults","Resources","startIndex","itemsPerPage","gravityads","raw_email_returned","raw_secrets_returned"],"additionalProperties":true,"properties":{"schemas":{"type":"array","items":{"type":"string"}},"totalResults":{"type":"integer","minimum":0},"Resources":{"type":"array","items":{"type":"object","required":["schemas","id","displayName","gravityads"],"additionalProperties":true,"properties":{"schemas":{"type":"array","items":{"type":"string"}},"id":{"type":"string"},"displayName":{"type":"string"},"members":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"value":{"type":"string"},"display":{"type":"string"}}}},"meta":{"type":"object"},"gravityads":{"type":"object"},"hosted_auth_context":{"type":"object"},"raw_email_returned":{"type":"boolean","const":false},"raw_secrets_returned":{"type":"boolean","const":false}}}},"startIndex":{"type":"integer","minimum":1},"itemsPerPage":{"type":"integer","minimum":0},"gravityads":{"type":"object"},"hosted_auth_context":{"type":"object"},"raw_email_returned":{"type":"boolean","const":false},"raw_secrets_returned":{"type":"boolean","const":false}}}}}}},"x-gravityads-tool-name":"gravityads.scim.groups.list","x-gravityads-required-scope":"gravityads.admin","x-gravityads-scope-source":"hosted_entitlements"}},"/scim/v2/Groups/{group_id}":{"get":{"operationId":"scim_group_get","summary":"Read one GravityAds role as a SCIM v2 Group","parameters":[{"name":"group_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"SCIM group","content":{"application/json":{"schema":{"type":"object","required":["schemas","id","displayName","gravityads"],"additionalProperties":true,"properties":{"schemas":{"type":"array","items":{"type":"string"}},"id":{"type":"string"},"displayName":{"type":"string"},"members":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"value":{"type":"string"},"display":{"type":"string"}}}},"meta":{"type":"object"},"gravityads":{"type":"object"},"hosted_auth_context":{"type":"object"},"raw_email_returned":{"type":"boolean","const":false},"raw_secrets_returned":{"type":"boolean","const":false}}}}}}},"x-gravityads-tool-name":"gravityads.scim.group.get","x-gravityads-required-scope":"gravityads.admin","x-gravityads-scope-source":"hosted_entitlements"},"put":{"operationId":"scim_group_replace","summary":"Replace SCIM group membership for a GravityAds role","parameters":[{"name":"group_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/scim+json":{"schema":{"type":"object","additionalProperties":true,"properties":{"schemas":{"type":"array","items":{"type":"string"}},"id":{"type":"string"},"displayName":{"type":"string"},"members":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"value":{"type":"string"},"display":{"type":"string"}}}}}}},"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"schemas":{"type":"array","items":{"type":"string"}},"id":{"type":"string"},"displayName":{"type":"string"},"members":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"value":{"type":"string"},"display":{"type":"string"}}}}}}}}},"responses":{"200":{"description":"SCIM group replaced","content":{"application/json":{"schema":{"type":"object","required":["schemas","id","displayName","gravityads"],"additionalProperties":true,"properties":{"schemas":{"type":"array","items":{"type":"string"}},"id":{"type":"string"},"displayName":{"type":"string"},"members":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"value":{"type":"string"},"display":{"type":"string"}}}},"meta":{"type":"object"},"gravityads":{"type":"object"},"hosted_auth_context":{"type":"object"},"raw_email_returned":{"type":"boolean","const":false},"raw_secrets_returned":{"type":"boolean","const":false}}}}}}},"x-gravityads-tool-name":"gravityads.scim.group.replace","x-gravityads-required-scope":"gravityads.admin","x-gravityads-scope-source":"hosted_entitlements"},"patch":{"operationId":"scim_group_patch","summary":"Patch SCIM group membership for a GravityAds role","parameters":[{"name":"group_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/scim+json":{"schema":{"type":"object","additionalProperties":true,"properties":{"schemas":{"type":"array","items":{"type":"string"}},"Operations":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"op":{"type":"string"},"path":{"type":"string"},"value":{}}}},"active":{"type":"boolean"},"roles":{"type":"array"},"groups":{"type":"array"}}}},"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"schemas":{"type":"array","items":{"type":"string"}},"Operations":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"op":{"type":"string"},"path":{"type":"string"},"value":{}}}},"active":{"type":"boolean"},"roles":{"type":"array"},"groups":{"type":"array"}}}}}},"responses":{"200":{"description":"SCIM group patched","content":{"application/json":{"schema":{"type":"object","required":["schemas","id","displayName","gravityads"],"additionalProperties":true,"properties":{"schemas":{"type":"array","items":{"type":"string"}},"id":{"type":"string"},"displayName":{"type":"string"},"members":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"value":{"type":"string"},"display":{"type":"string"}}}},"meta":{"type":"object"},"gravityads":{"type":"object"},"hosted_auth_context":{"type":"object"},"raw_email_returned":{"type":"boolean","const":false},"raw_secrets_returned":{"type":"boolean","const":false}}}}}}},"x-gravityads-tool-name":"gravityads.scim.group.patch","x-gravityads-required-scope":"gravityads.admin","x-gravityads-scope-source":"hosted_entitlements"}},"/tenant/directory-sync/webhook":{"post":{"operationId":"tenant_directory_sync_webhook","summary":"Accept signed IdP directory sync webhook snapshots","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["tenant_id","users"],"additionalProperties":false,"properties":{"source":{"type":"string","default":"idp_directory"},"replace_roles":{"type":"boolean","default":false},"users":{"type":"array","items":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string"},"email_hash":{"type":"string"},"oidc_sub":{"type":"string"},"feishu_open_id":{"type":"string"},"display_name":{"type":"string"},"status":{"type":"string","default":"active"},"roles":{"type":"array","items":{"type":"string"},"maxItems":20}}},"maxItems":500},"tenant_id":{"type":"string"},"provider":{"type":"string"},"event_id":{"type":"string"}}}}}},"responses":{"200":{"description":"Directory webhook accepted","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}},"x-gravityads-tool-name":"gravityads.tenant.directory.sync.webhook","x-gravityads-required-scope":"gravityads.admin","x-gravityads-scope-source":"hosted_entitlements"}},"/tenant/idp-mapping/readiness":{"get":{"operationId":"tenant_idp_mapping_readiness","summary":"Return hosted IdP claim mapping readiness","responses":{"200":{"description":"IdP mapping readiness","content":{"application/json":{"schema":{"type":"object","required":["schema_version","status","provider","ready_for_claim_mapping","ready_for_enterprise_sso","raw_email_returned","raw_secrets_returned"],"additionalProperties":true,"properties":{"schema_version":{"type":"string","const":"gravityads.hosted_idp_mapping.v1"},"status":{"type":"string"},"tenant_id":{"type":"string"},"provider":{"type":"string"},"supported_providers":{"type":"array","items":{"type":"string"}},"provider_supported":{"type":"boolean"},"provider_configured":{"type":"boolean"},"role_mapping_configured":{"type":"boolean"},"tenant_mapping_configured":{"type":"boolean"},"ready_for_claim_mapping":{"type":"boolean"},"ready_for_jwt_auth":{"type":"boolean"},"ready_for_enterprise_sso":{"type":"boolean"},"readiness_checks":{"type":"array","items":{"type":"object"}},"missing_configuration":{"type":"array","items":{"type":"string"}},"configuration_errors":{"type":"array","items":{"type":"string"}},"hosted_auth_context":{"type":"object"},"raw_email_returned":{"type":"boolean","const":false},"raw_secrets_returned":{"type":"boolean","const":false}}}}}}},"x-gravityads-tool-name":"gravityads.tenant.idp.mapping.readiness","x-gravityads-required-scope":"gravityads.admin","x-gravityads-scope-source":"hosted_entitlements"}},"/tenant/domains":{"get":{"operationId":"tenant_domains","summary":"List tenant Enterprise domain verification records","responses":{"200":{"description":"Tenant domains","content":{"application/json":{"schema":{"type":"object","required":["schema_version","status","tenant_id","domain_count","verified_domain_count","domains","database_url_configured","dns_challenge_returned","raw_secrets_returned"],"additionalProperties":true,"properties":{"schema_version":{"type":"string","const":"gravityads.tenant_domain_verifications.v1"},"status":{"type":"string"},"tenant_id":{"type":"string"},"domain":{"type":"string"},"domain_count":{"type":"integer","minimum":0},"verified_domain_count":{"type":"integer","minimum":0},"domains":{"type":"array","items":{"type":"object"}},"database_url_configured":{"type":"boolean"},"ready_for_enterprise_sso_domain":{"type":"boolean"},"tenant_id_from_auth_context":{"type":"boolean","const":true},"live_dns_lookup":{"type":"boolean"},"dns_lookup_error_type":{"type":"string"},"hosted_auth_context":{"type":"object"},"dns_challenge_returned":{"type":"boolean"},"raw_secrets_returned":{"type":"boolean","const":false}}}}}}},"x-gravityads-tool-name":"gravityads.tenant.domains","x-gravityads-required-scope":"gravityads.admin","x-gravityads-scope-source":"hosted_entitlements"},"post":{"operationId":"tenant_domain_create","summary":"Create or rotate a tenant DNS TXT domain challenge","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["domain"],"additionalProperties":false,"properties":{"tenant_id":{"type":"string","description":"Ignored for tenant portal calls; auth context wins."},"domain":{"type":"string","description":"Bare DNS name, for example example.com."},"rotate_challenge":{"type":"boolean","default":false}}}}}},"responses":{"200":{"description":"Tenant domain challenge","content":{"application/json":{"schema":{"type":"object","required":["schema_version","status","tenant_id","domain_count","verified_domain_count","domains","database_url_configured","dns_challenge_returned","raw_secrets_returned"],"additionalProperties":true,"properties":{"schema_version":{"type":"string","const":"gravityads.tenant_domain_verifications.v1"},"status":{"type":"string"},"tenant_id":{"type":"string"},"domain":{"type":"string"},"domain_count":{"type":"integer","minimum":0},"verified_domain_count":{"type":"integer","minimum":0},"domains":{"type":"array","items":{"type":"object"}},"database_url_configured":{"type":"boolean"},"ready_for_enterprise_sso_domain":{"type":"boolean"},"tenant_id_from_auth_context":{"type":"boolean","const":true},"live_dns_lookup":{"type":"boolean"},"dns_lookup_error_type":{"type":"string"},"hosted_auth_context":{"type":"object"},"dns_challenge_returned":{"type":"boolean"},"raw_secrets_returned":{"type":"boolean","const":false}}}}}}},"x-gravityads-tool-name":"gravityads.tenant.domain_verification.create","x-gravityads-required-scope":"gravityads.admin","x-gravityads-scope-source":"hosted_entitlements"}},"/tenant/domains/verify":{"post":{"operationId":"tenant_domain_verify","summary":"Verify a tenant domain against DNS TXT proof","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["domain"],"additionalProperties":false,"properties":{"tenant_id":{"type":"string","description":"Ignored for tenant portal calls; auth context wins."},"domain":{"type":"string"},"observed_txt_values":{"type":"array","items":{"type":"string"},"description":"TXT values already read by the portal or test harness."},"live_dns_lookup":{"type":"boolean","default":false,"description":"When true, backend also checks DNS over HTTPS."}}}}}},"responses":{"200":{"description":"Tenant domain verified","content":{"application/json":{"schema":{"type":"object","required":["schema_version","status","tenant_id","domain_count","verified_domain_count","domains","database_url_configured","dns_challenge_returned","raw_secrets_returned"],"additionalProperties":true,"properties":{"schema_version":{"type":"string","const":"gravityads.tenant_domain_verifications.v1"},"status":{"type":"string"},"tenant_id":{"type":"string"},"domain":{"type":"string"},"domain_count":{"type":"integer","minimum":0},"verified_domain_count":{"type":"integer","minimum":0},"domains":{"type":"array","items":{"type":"object"}},"database_url_configured":{"type":"boolean"},"ready_for_enterprise_sso_domain":{"type":"boolean"},"tenant_id_from_auth_context":{"type":"boolean","const":true},"live_dns_lookup":{"type":"boolean"},"dns_lookup_error_type":{"type":"string"},"hosted_auth_context":{"type":"object"},"dns_challenge_returned":{"type":"boolean"},"raw_secrets_returned":{"type":"boolean","const":false}}}}}}},"x-gravityads-tool-name":"gravityads.tenant.domain_verification.verify","x-gravityads-required-scope":"gravityads.admin","x-gravityads-scope-source":"hosted_entitlements"}},"/tenant/sso/providers":{"get":{"operationId":"tenant_sso_providers","summary":"List tenant Enterprise SSO provider configuration","responses":{"200":{"description":"Tenant SSO providers","content":{"application/json":{"schema":{"type":"object","required":["schema_version","status","tenant_id","provider_count","providers","database_url_configured","idp_mapping_readiness","domain_verification","ready_for_enterprise_sso","raw_values_returned","raw_secrets_returned"],"additionalProperties":true,"properties":{"schema_version":{"type":"string","const":"gravityads.tenant_sso_providers.v1"},"status":{"type":"string"},"tenant_id":{"type":"string"},"provider_count":{"type":"integer","minimum":0},"providers":{"type":"array","items":{"type":"object"}},"database_url_configured":{"type":"boolean"},"idp_mapping_readiness":{"type":"object"},"domain_verification":{"type":"object"},"ready_for_enterprise_sso_config":{"type":"boolean"},"ready_for_enterprise_sso_domain":{"type":"boolean"},"ready_for_enterprise_sso":{"type":"boolean"},"hosted_auth_context":{"type":"object"},"raw_values_returned":{"type":"boolean","const":false},"raw_secrets_returned":{"type":"boolean","const":false}}}}}}},"x-gravityads-tool-name":"gravityads.tenant.sso.providers","x-gravityads-required-scope":"gravityads.admin","x-gravityads-scope-source":"hosted_entitlements"},"post":{"operationId":"tenant_sso_provider_upsert","summary":"Upsert tenant Enterprise SSO provider configuration","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["issuer"],"additionalProperties":false,"properties":{"id":{"type":"string"},"provider_type":{"type":"string","enum":["oidc","saml","feishu","google_workspace","microsoft_entra"],"default":"oidc"},"issuer":{"type":"string","description":"HTTPS issuer URL"},"jwks_uri":{"type":"string","description":"HTTPS JWKS URL for OIDC"},"metadata_url":{"type":"string","description":"HTTPS OIDC discovery or SAML metadata URL"},"status":{"type":"string","enum":["active","disabled","pending","failed"],"default":"active"}}}}}},"responses":{"200":{"description":"Tenant SSO provider upserted","content":{"application/json":{"schema":{"type":"object","required":["schema_version","status","tenant_id","provider_count","providers","database_url_configured","idp_mapping_readiness","domain_verification","ready_for_enterprise_sso","raw_values_returned","raw_secrets_returned"],"additionalProperties":true,"properties":{"schema_version":{"type":"string","const":"gravityads.tenant_sso_providers.v1"},"status":{"type":"string"},"tenant_id":{"type":"string"},"provider_count":{"type":"integer","minimum":0},"providers":{"type":"array","items":{"type":"object"}},"database_url_configured":{"type":"boolean"},"idp_mapping_readiness":{"type":"object"},"domain_verification":{"type":"object"},"ready_for_enterprise_sso_config":{"type":"boolean"},"ready_for_enterprise_sso_domain":{"type":"boolean"},"ready_for_enterprise_sso":{"type":"boolean"},"hosted_auth_context":{"type":"object"},"raw_values_returned":{"type":"boolean","const":false},"raw_secrets_returned":{"type":"boolean","const":false}}}}}}},"x-gravityads-tool-name":"gravityads.tenant.sso.provider.upsert","x-gravityads-required-scope":"gravityads.admin","x-gravityads-scope-source":"hosted_entitlements"}},"/tenant/idp-mapping/preview":{"post":{"operationId":"tenant_idp_mapping_preview","summary":"Preview or sync hosted IdP claims into a tenant user mapping","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["claims"],"additionalProperties":false,"properties":{"provider":{"type":"string","description":"IdP provider: generic_oidc, clerk, auth0, workos, google_workspace, microsoft_entra or feishu."},"claims":{"type":"object","additionalProperties":true,"description":"Raw IdP claims. Email may be supplied only for transient hashing and is never returned."},"role_mapping":{"type":"object","additionalProperties":true,"description":"Optional external role/group to GravityAds role mapping."},"tenant_mapping":{"type":"object","additionalProperties":{"type":"string"},"description":"Optional external org/tenant id to GravityAds tenant_id mapping."},"default_roles":{"type":"array","items":{"type":"string"}},"sync_user":{"type":"boolean","default":false},"replace_roles":{"type":"boolean","default":false}}}}}},"responses":{"200":{"description":"IdP mapping preview","content":{"application/json":{"schema":{"type":"object","required":["schema_version","status","tenant_id","provider","sync_user_requested","raw_email_returned","raw_secrets_returned"],"additionalProperties":true,"properties":{"schema_version":{"type":"string","const":"gravityads.hosted_idp_mapping.v1"},"status":{"type":"string"},"tenant_id":{"type":"string"},"provider":{"type":"string"},"external_tenant_id":{"type":"string"},"tenant_match":{"type":"boolean"},"tenant_mapping_match":{"type":"boolean"},"tenant_reference_hashes":{"type":"array","items":{"type":"string"}},"user_id":{"type":"string"},"user_id_hash":{"type":"string"},"email_hash_prefix":{"type":"string"},"has_email_hash":{"type":"boolean"},"directory_sync_user":{"type":"object"},"roles":{"type":"array","items":{"type":"string"}},"role_mapping":{"type":"object"},"role_source_count":{"type":"integer","minimum":0},"mapped_role_count":{"type":"integer","minimum":0},"sync_user_requested":{"type":"boolean"},"synced_count":{"type":"integer","minimum":0},"role_assigned_count":{"type":"integer","minimum":0},"role_revoked_count":{"type":"integer","minimum":0},"replace_roles":{"type":"boolean"},"database_url_configured":{"type":"boolean"},"hosted_auth_context":{"type":"object"},"raw_email_returned":{"type":"boolean","const":false},"raw_secrets_returned":{"type":"boolean","const":false}}}}}}},"x-gravityads-tool-name":"gravityads.tenant.idp.mapping.preview","x-gravityads-required-scope":"gravityads.admin","x-gravityads-scope-source":"hosted_entitlements"}},"/tenant/invites":{"get":{"operationId":"tenant_invites","summary":"List hosted tenant invites","responses":{"200":{"description":"Tenant invites","content":{"application/json":{"schema":{"type":"object","required":["status","tenant_id","invite_count","invites","raw_secrets_returned"],"additionalProperties":true,"properties":{"status":{"type":"string","enum":["tenant_invite_status_ready","tenant_invite_status_unconfigured","tenant_invite_status_degraded"]},"source":{"type":"string"},"tenant_id":{"type":"string"},"invite_count":{"type":"integer","minimum":0},"invites":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"id":{"type":"string"},"tenant_id":{"type":"string"},"email_hash_prefix":{"type":"string"},"role_id":{"type":"string"},"status":{"type":"string"},"invited_by_user_id":{"type":"string"},"accepted_user_id":{"type":"string"},"expires_at":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"revoked_at":{"type":"string"}}}},"database_url_configured":{"type":"boolean"},"hosted_auth_context":{"type":"object"},"raw_secrets_returned":{"type":"boolean","const":false}}}}}}},"x-gravityads-tool-name":"gravityads.tenant.invites","x-gravityads-required-scope":"gravityads.admin","x-gravityads-scope-source":"hosted_entitlements"},"post":{"operationId":"tenant_invite_create","summary":"Create a hosted tenant invite using email_hash","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["email_hash","role_id"],"additionalProperties":false,"properties":{"id":{"type":"string"},"email_hash":{"type":"string"},"delivery_email":{"type":"string","description":"Transient invite email recipient; never stored or returned."},"role_id":{"type":"string"},"status":{"type":"string","default":"pending"},"invited_by_user_id":{"type":"string"},"expires_at":{"type":"string","format":"date-time"}}}}}},"responses":{"200":{"description":"Tenant invite created","content":{"application/json":{"schema":{"type":"object","required":["status","tenant_id","invite_count","invites","raw_secrets_returned"],"additionalProperties":true,"properties":{"status":{"type":"string","enum":["tenant_invite_created","tenant_invite_create_unconfigured","tenant_invite_create_failed","tenant_invite_create_degraded"]},"source":{"type":"string"},"tenant_id":{"type":"string"},"invite_count":{"type":"integer","minimum":0},"invites":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"id":{"type":"string"},"tenant_id":{"type":"string"},"email_hash_prefix":{"type":"string"},"role_id":{"type":"string"},"status":{"type":"string"},"invited_by_user_id":{"type":"string"},"accepted_user_id":{"type":"string"},"expires_at":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"revoked_at":{"type":"string"}}}},"database_url_configured":{"type":"boolean"},"hosted_auth_context":{"type":"object"},"raw_secrets_returned":{"type":"boolean","const":false},"invite_id":{"type":"string"},"email_delivery":{"type":"object"}}}}}}},"x-gravityads-tool-name":"gravityads.tenant.invite.create","x-gravityads-required-scope":"gravityads.admin","x-gravityads-scope-source":"hosted_entitlements"}},"/tenant/invites/revoke":{"post":{"operationId":"tenant_invite_revoke","summary":"Revoke a hosted tenant invite","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["invite_id"],"additionalProperties":false,"properties":{"invite_id":{"type":"string"},"reason":{"type":"string"}}}}}},"responses":{"200":{"description":"Tenant invite revoked","content":{"application/json":{"schema":{"type":"object","required":["status","tenant_id","invite_count","invites","raw_secrets_returned"],"additionalProperties":true,"properties":{"status":{"type":"string","enum":["tenant_invite_revoked","tenant_invite_revoke_not_found","tenant_invite_revoke_unconfigured","tenant_invite_revoke_failed","tenant_invite_revoke_degraded"]},"source":{"type":"string"},"tenant_id":{"type":"string"},"invite_count":{"type":"integer","minimum":0},"invites":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"id":{"type":"string"},"tenant_id":{"type":"string"},"email_hash_prefix":{"type":"string"},"role_id":{"type":"string"},"status":{"type":"string"},"invited_by_user_id":{"type":"string"},"accepted_user_id":{"type":"string"},"expires_at":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"revoked_at":{"type":"string"}}}},"database_url_configured":{"type":"boolean"},"hosted_auth_context":{"type":"object"},"raw_secrets_returned":{"type":"boolean","const":false},"invite_id":{"type":"string"},"revoked_count":{"type":"integer","minimum":0}}}}}}},"x-gravityads-tool-name":"gravityads.tenant.invite.revoke","x-gravityads-required-scope":"gravityads.admin","x-gravityads-scope-source":"hosted_entitlements"}},"/tenant/invites/delivery-readiness":{"get":{"operationId":"tenant_invite_delivery_readiness","summary":"Return hosted invite email delivery readiness","responses":{"200":{"description":"Invite delivery readiness","content":{"application/json":{"schema":{"type":"object","required":["schema_version","status","provider","ready_for_invite_creation","ready_for_actionable_invite_email","provider_api_called","raw_email_returned","raw_secrets_returned"],"additionalProperties":true,"properties":{"schema_version":{"type":"string","const":"gravityads.hosted_invite_delivery_readiness.v1"},"status":{"type":"string"},"tenant_id":{"type":"string"},"provider":{"type":"string"},"delivery_enabled":{"type":"boolean"},"dry_run_enabled":{"type":"boolean"},"missing_configuration":{"type":"array","items":{"type":"string"}},"configuration_errors":{"type":"array","items":{"type":"string"}},"readiness_checks":{"type":"array","items":{"type":"object"}},"ready_for_invite_creation":{"type":"boolean"},"ready_for_dry_run_delivery":{"type":"boolean"},"ready_for_provider_call":{"type":"boolean"},"ready_for_actionable_invite_email":{"type":"boolean"},"provider_api_called":{"type":"boolean","const":false},"hosted_auth_context":{"type":"object"},"raw_email_returned":{"type":"boolean","const":false},"raw_secrets_returned":{"type":"boolean","const":false}}}}}}},"x-gravityads-tool-name":"gravityads.tenant.invite.delivery.readiness","x-gravityads-required-scope":"gravityads.admin","x-gravityads-scope-source":"hosted_entitlements"}},"/tenant/invites/accept":{"post":{"operationId":"tenant_invite_accept","summary":"Accept a hosted tenant invite with matching email_hash","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["invite_id"],"additionalProperties":false,"properties":{"invite_id":{"type":"string"}}}}}},"responses":{"200":{"description":"Tenant invite accepted","content":{"application/json":{"schema":{"type":"object","required":["status","tenant_id","invite_count","invites","raw_secrets_returned"],"additionalProperties":true,"properties":{"status":{"type":"string","enum":["tenant_invite_accepted","tenant_invite_accept_not_found","tenant_invite_expired","tenant_invite_accept_unconfigured","tenant_invite_accept_failed","tenant_invite_accept_degraded"]},"source":{"type":"string"},"tenant_id":{"type":"string"},"invite_count":{"type":"integer","minimum":0},"invites":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"id":{"type":"string"},"tenant_id":{"type":"string"},"email_hash_prefix":{"type":"string"},"role_id":{"type":"string"},"status":{"type":"string"},"invited_by_user_id":{"type":"string"},"accepted_user_id":{"type":"string"},"expires_at":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"revoked_at":{"type":"string"}}}},"database_url_configured":{"type":"boolean"},"hosted_auth_context":{"type":"object"},"raw_secrets_returned":{"type":"boolean","const":false},"invite_id":{"type":"string"},"accepted_count":{"type":"integer","minimum":0},"role_id":{"type":"string"},"user_id":{"type":"string"},"user_count":{"type":"integer","minimum":0},"users":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"id":{"type":"string"},"tenant_id":{"type":"string"},"email_hash_prefix":{"type":"string"},"oidc_sub":{"type":"string"},"feishu_open_id":{"type":"string"},"display_name":{"type":"string"},"status":{"type":"string"},"created_at":{"type":"string"},"roles":{"type":"array","items":{"type":"string"}}}}}}}}}}},"x-gravityads-tool-name":"gravityads.tenant.invite.accept","x-gravityads-required-scope":"gravityads.read","x-gravityads-scope-source":"hosted_entitlements"}},"/tenant/users/upsert":{"post":{"operationId":"tenant_user_upsert","summary":"Upsert hosted tenant user metadata","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["id"],"additionalProperties":false,"properties":{"id":{"type":"string"},"email_hash":{"type":"string"},"oidc_sub":{"type":"string"},"sso_provider_id":{"type":"string","description":"Registered provider for an explicit tenant SSO subject binding."},"feishu_open_id":{"type":"string"},"display_name":{"type":"string"},"status":{"type":"string","default":"active"}}}}}},"responses":{"200":{"description":"Tenant user upsert result","content":{"application/json":{"schema":{"type":"object","required":["status","tenant_id","user_count","users","role_count","roles","raw_secrets_returned"],"additionalProperties":true,"properties":{"status":{"type":"string","enum":["tenant_user_upserted","tenant_user_upsert_unconfigured","tenant_user_upsert_failed","tenant_user_upsert_degraded"]},"source":{"type":"string"},"tenant_id":{"type":"string"},"user_count":{"type":"integer","minimum":0},"users":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"id":{"type":"string"},"tenant_id":{"type":"string"},"email_hash_prefix":{"type":"string"},"oidc_sub":{"type":"string"},"feishu_open_id":{"type":"string"},"display_name":{"type":"string"},"status":{"type":"string"},"created_at":{"type":"string"},"roles":{"type":"array","items":{"type":"string"}}}}},"role_count":{"type":"integer","minimum":0},"roles":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"}}}},"database_url_configured":{"type":"boolean"},"hosted_auth_context":{"type":"object"},"raw_secrets_returned":{"type":"boolean","const":false},"user_id":{"type":"string"}}}}}}},"x-gravityads-tool-name":"gravityads.tenant.user.upsert","x-gravityads-required-scope":"gravityads.admin","x-gravityads-scope-source":"hosted_entitlements"}},"/tenant/users/roles/assign":{"post":{"operationId":"tenant_user_role_assign","summary":"Assign a hosted tenant role to a user","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["user_id","role_id"],"additionalProperties":false,"properties":{"user_id":{"type":"string"},"role_id":{"type":"string"}}}}}},"responses":{"200":{"description":"Role assignment result","content":{"application/json":{"schema":{"type":"object","required":["status","tenant_id","user_count","users","role_count","roles","raw_secrets_returned"],"additionalProperties":true,"properties":{"status":{"type":"string","enum":["user_role_assigned","user_role_revoked","user_role_revoke_not_found","user_role_mutation_unconfigured","user_role_mutation_failed","user_role_mutation_degraded"]},"source":{"type":"string"},"tenant_id":{"type":"string"},"user_count":{"type":"integer","minimum":0},"users":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"id":{"type":"string"},"tenant_id":{"type":"string"},"email_hash_prefix":{"type":"string"},"oidc_sub":{"type":"string"},"feishu_open_id":{"type":"string"},"display_name":{"type":"string"},"status":{"type":"string"},"created_at":{"type":"string"},"roles":{"type":"array","items":{"type":"string"}}}}},"role_count":{"type":"integer","minimum":0},"roles":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"}}}},"database_url_configured":{"type":"boolean"},"hosted_auth_context":{"type":"object"},"raw_secrets_returned":{"type":"boolean","const":false},"user_id":{"type":"string"},"role_id":{"type":"string"},"revoked_count":{"type":"integer","minimum":0}}}}}}},"x-gravityads-tool-name":"gravityads.tenant.user.role.assign","x-gravityads-required-scope":"gravityads.admin","x-gravityads-scope-source":"hosted_entitlements"}},"/tenant/users/roles/revoke":{"post":{"operationId":"tenant_user_role_revoke","summary":"Revoke a hosted tenant role from a user","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["user_id","role_id"],"additionalProperties":false,"properties":{"user_id":{"type":"string"},"role_id":{"type":"string"}}}}}},"responses":{"200":{"description":"Role revoke result","content":{"application/json":{"schema":{"type":"object","required":["status","tenant_id","user_count","users","role_count","roles","raw_secrets_returned"],"additionalProperties":true,"properties":{"status":{"type":"string","enum":["user_role_assigned","user_role_revoked","user_role_revoke_not_found","user_role_mutation_unconfigured","user_role_mutation_failed","user_role_mutation_degraded"]},"source":{"type":"string"},"tenant_id":{"type":"string"},"user_count":{"type":"integer","minimum":0},"users":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"id":{"type":"string"},"tenant_id":{"type":"string"},"email_hash_prefix":{"type":"string"},"oidc_sub":{"type":"string"},"feishu_open_id":{"type":"string"},"display_name":{"type":"string"},"status":{"type":"string"},"created_at":{"type":"string"},"roles":{"type":"array","items":{"type":"string"}}}}},"role_count":{"type":"integer","minimum":0},"roles":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"}}}},"database_url_configured":{"type":"boolean"},"hosted_auth_context":{"type":"object"},"raw_secrets_returned":{"type":"boolean","const":false},"user_id":{"type":"string"},"role_id":{"type":"string"},"revoked_count":{"type":"integer","minimum":0}}}}}}},"x-gravityads-tool-name":"gravityads.tenant.user.role.revoke","x-gravityads-required-scope":"gravityads.admin","x-gravityads-scope-source":"hosted_entitlements"}},"/tenant/connections":{"get":{"operationId":"tenant_connections","summary":"List hosted tenant connections, accounts and scopes","responses":{"200":{"description":"Tenant connections","content":{"application/json":{"schema":{"type":"object","required":["status","tenant_id","connection_count","connections","platform_account_count","platform_accounts","account_scope_count","account_scopes","raw_secrets_returned"],"additionalProperties":true,"properties":{"status":{"type":"string","enum":["tenant_connection_status_ready","tenant_connection_status_unconfigured","tenant_connection_status_degraded"]},"tenant_id":{"type":"string"},"connection_count":{"type":"integer","minimum":0},"meta_oauth_capability":{"type":"object","description":"Current plan/actor allowed_access_modes and recommended_access_mode; this is not an execution grant."},"connections":{"type":"array","items":{"type":"object"}},"platform_account_count":{"type":"integer","minimum":0},"platform_accounts":{"type":"array","items":{"type":"object"}},"discovered_platform_account_count":{"type":"integer","minimum":0},"over_limit_platform_account_count":{"type":"integer","minimum":0},"plan_account_limit":{"type":"object"},"account_scope_count":{"type":"integer","minimum":0},"account_scopes":{"type":"array","items":{"type":"object"}},"database_url_configured":{"type":"boolean"},"hosted_auth_context":{"type":"object"},"raw_secrets_returned":{"type":"boolean","const":false}}}}}}},"x-gravityads-tool-name":"gravityads.tenant.connections","x-gravityads-required-scope":"gravityads.admin","x-gravityads-scope-source":"hosted_entitlements"}},"/tenant/plan-account-selection":{"get":{"operationId":"tenant_plan_account_selection","summary":"List selectable active and over-limit accounts for the current plan","responses":{"200":{"description":"Tenant plan account selection","content":{"application/json":{"schema":{"type":"object","required":["status","tenant_id","plan_account_limit","platform_account_count","platform_accounts","active_platform_account_ids","raw_secrets_returned"],"additionalProperties":true,"properties":{"status":{"type":"string","enum":["tenant_plan_account_selection_ready","tenant_plan_account_selection_updated","tenant_plan_account_selection_unconfigured","tenant_plan_account_selection_failed","tenant_plan_account_selection_degraded"]},"tenant_id":{"type":"string"},"plan_id":{"type":"string"},"plan_account_limit":{"type":"object"},"platform_account_count":{"type":"integer","minimum":0},"platform_accounts":{"type":"array","items":{"type":"object"}},"active_platform_account_ids":{"type":"array","items":{"type":"string"}},"selected_platform_account_count":{"type":"integer","minimum":0},"plan_user_limit":{"type":"object"},"users":{"type":"array","items":{"type":"object"}},"active_user_ids":{"type":"array","items":{"type":"string"}},"selected_user_count":{"type":"integer","minimum":0},"ai_readiness_summary":{"type":"object"},"requested_active_platform_account_count":{"type":"integer","minimum":0},"activated_account_count":{"type":"integer","minimum":0},"over_limited_account_count":{"type":"integer","minimum":0},"reconciliation_summary":{"type":"object"},"database_url_configured":{"type":"boolean"},"raw_secrets_returned":{"type":"boolean","const":false}}}}}}},"x-gravityads-tool-name":"gravityads.tenant.plan.account.selection","x-gravityads-required-scope":"gravityads.read","x-gravityads-scope-source":"hosted_entitlements"},"post":{"operationId":"tenant_plan_account_selection_update","summary":"Choose which platform accounts are enabled under the current plan","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["active_platform_account_ids"],"additionalProperties":false,"properties":{"active_platform_account_ids":{"type":"array","items":{"type":"string"},"description":"Platform account row IDs to keep active under the current plan."},"active_user_ids":{"type":"array","items":{"type":"string"},"description":"Optional exact active-user selection. When present, account, user, scope, and ETL assignments are reconciled together."},"expected_pool_revision":{"type":"integer","minimum":0},"expected_pool_contract_token":{"type":"string","minLength":64,"maxLength":64},"request_key":{"type":"string","minLength":1,"maxLength":128},"confirm_archive":{"type":"boolean","default":false}}}}}},"responses":{"200":{"description":"Tenant plan account selection updated","content":{"application/json":{"schema":{"type":"object","required":["status","tenant_id","plan_account_limit","platform_account_count","platform_accounts","active_platform_account_ids","raw_secrets_returned"],"additionalProperties":true,"properties":{"status":{"type":"string","enum":["tenant_plan_account_selection_ready","tenant_plan_account_selection_updated","tenant_plan_account_selection_unconfigured","tenant_plan_account_selection_failed","tenant_plan_account_selection_degraded"]},"tenant_id":{"type":"string"},"plan_id":{"type":"string"},"plan_account_limit":{"type":"object"},"platform_account_count":{"type":"integer","minimum":0},"platform_accounts":{"type":"array","items":{"type":"object"}},"active_platform_account_ids":{"type":"array","items":{"type":"string"}},"selected_platform_account_count":{"type":"integer","minimum":0},"plan_user_limit":{"type":"object"},"users":{"type":"array","items":{"type":"object"}},"active_user_ids":{"type":"array","items":{"type":"string"}},"selected_user_count":{"type":"integer","minimum":0},"ai_readiness_summary":{"type":"object"},"requested_active_platform_account_count":{"type":"integer","minimum":0},"activated_account_count":{"type":"integer","minimum":0},"over_limited_account_count":{"type":"integer","minimum":0},"reconciliation_summary":{"type":"object"},"database_url_configured":{"type":"boolean"},"raw_secrets_returned":{"type":"boolean","const":false}}}}}}},"x-gravityads-tool-name":"gravityads.tenant.plan.account.selection.update","x-gravityads-required-scope":"gravityads.read","x-gravityads-scope-source":"hosted_entitlements"}},"/tenant/account-access/repair":{"post":{"operationId":"tenant_account_access_repair","summary":"Repair missing read scopes for the authenticated tenant principal","responses":{"200":{"description":"Tenant principal account access repaired","content":{"application/json":{"schema":{"type":"object","required":["status","tenant_id","repaired_account_count","remaining_scope_blocker_count","selection_changed","account_status_changed","system_assignment_changed","other_user_scopes_changed","mcp_key_owner_changed","raw_account_ids_returned","raw_user_ids_returned","raw_secrets_returned"],"additionalProperties":true,"properties":{"status":{"type":"string","enum":["tenant_account_access_repaired","tenant_account_access_ready","tenant_account_access_repair_failed","tenant_account_access_repair_unconfigured","tenant_account_access_repair_degraded"]},"tenant_id":{"type":"string"},"principal_resolved":{"type":"boolean"},"principal_role_ids":{"type":"array","items":{"type":"string"}},"repair_candidate_count":{"type":"integer","minimum":0},"repaired_account_count":{"type":"integer","minimum":0},"remaining_scope_blocker_count":{"type":"integer","minimum":0},"repair_limit":{"type":"integer","minimum":1},"selection_changed":{"type":"boolean","const":false},"account_status_changed":{"type":"boolean","const":false},"system_assignment_changed":{"type":"boolean","const":false},"other_user_scopes_changed":{"type":"boolean","const":false},"mcp_key_owner_changed":{"type":"boolean","const":false},"ai_readiness_summary":{"type":"object"},"database_url_configured":{"type":"boolean"},"hosted_auth_context":{"type":"object"},"raw_account_ids_returned":{"type":"boolean","const":false},"raw_user_ids_returned":{"type":"boolean","const":false},"raw_secrets_returned":{"type":"boolean","const":false}}}}}}},"x-gravityads-tool-name":"gravityads.tenant.account.access.repair","x-gravityads-required-scope":"gravityads.read","x-gravityads-scope-source":"hosted_entitlements"}},"/tenant/accounts/{account_id}/strategy-context":{"get":{"operationId":"tenant_account_strategy_context","summary":"Read the optimization strategy context for an ad account","parameters":[{"name":"account_id","in":"path","required":true,"description":"Platform account ID","schema":{"type":"string"}}],"responses":{"200":{"description":"Account strategy context","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}},"x-gravityads-tool-name":"gravityads.tenant.account.strategy.context","x-gravityads-required-scope":"gravityads.read","x-gravityads-scope-source":"hosted_entitlements"},"put":{"operationId":"tenant_account_strategy_context_update","summary":"Create or update the optimization strategy context for an ad account","parameters":[{"name":"account_id","in":"path","required":true,"description":"Platform account ID","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"responses":{"200":{"description":"Account strategy context updated","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}},"x-gravityads-tool-name":"gravityads.tenant.account.strategy.context.update","x-gravityads-required-scope":"gravityads.read","x-gravityads-scope-source":"hosted_entitlements"}},"/tenant/accounts/{account_id}/optimization-history":{"get":{"operationId":"tenant_account_optimization_history","summary":"List optimization changes and measured outcomes for an ad account","parameters":[{"name":"account_id","in":"path","required":true,"description":"Platform account ID","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200}}],"responses":{"200":{"description":"Account optimization history","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}},"x-gravityads-tool-name":"gravityads.tenant.account.optimization.history","x-gravityads-required-scope":"gravityads.read","x-gravityads-scope-source":"hosted_entitlements"},"post":{"operationId":"tenant_account_optimization_history_create","summary":"Record an optimization change or measured outcome for an ad account","parameters":[{"name":"account_id","in":"path","required":true,"description":"Platform account ID","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"responses":{"200":{"description":"Optimization outcome recorded","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}},"x-gravityads-tool-name":"gravityads.tenant.account.optimization.history.create","x-gravityads-required-scope":"gravityads.read","x-gravityads-scope-source":"hosted_entitlements"}},"/tenant/optimizer-report-schedules":{"get":{"operationId":"tenant_optimizer_report_schedules","summary":"List optimizer report schedules","responses":{"200":{"description":"Optimizer report schedules","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}},"x-gravityads-tool-name":"gravityads.tenant.optimizer.report.schedules","x-gravityads-required-scope":"gravityads.read","x-gravityads-scope-source":"hosted_entitlements"},"post":{"operationId":"tenant_optimizer_report_schedule_upsert","summary":"Create or update an optimizer report schedule","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"responses":{"200":{"description":"Optimizer report schedule saved","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}},"x-gravityads-tool-name":"gravityads.tenant.optimizer.report.schedule.upsert","x-gravityads-required-scope":"gravityads.read","x-gravityads-scope-source":"hosted_entitlements"}},"/tenant/optimizer-alert-rules":{"get":{"operationId":"tenant_optimizer_alert_rules","summary":"List optimizer alert rules","responses":{"200":{"description":"Optimizer alert rules","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}},"x-gravityads-tool-name":"gravityads.tenant.optimizer.alert.rules","x-gravityads-required-scope":"gravityads.read","x-gravityads-scope-source":"hosted_entitlements"},"post":{"operationId":"tenant_optimizer_alert_rule_upsert","summary":"Create or update an optimizer alert rule","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"responses":{"200":{"description":"Optimizer alert rule saved","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}},"x-gravityads-tool-name":"gravityads.tenant.optimizer.alert.rule.upsert","x-gravityads-required-scope":"gravityads.read","x-gravityads-scope-source":"hosted_entitlements"}},"/tenant/optimizer-automation-executions":{"get":{"operationId":"tenant_optimizer_automation_executions","summary":"List executed optimizer reports, alerts, and review reminders","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":500}}],"responses":{"200":{"description":"Optimizer automation executions","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}},"x-gravityads-tool-name":"gravityads.tenant.optimizer.automation.executions","x-gravityads-required-scope":"gravityads.read","x-gravityads-scope-source":"hosted_entitlements"}},"/tenant/attribution-evidence":{"post":{"operationId":"tenant_attribution_evidence","summary":"Read tenant-scoped Ads Quant order attribution evidence","description":"Returns Ads Quant attribution results without raw click IDs; it does not duplicate commerce connectors or attribution computation in MCP.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"responses":{"200":{"description":"Tenant attribution evidence","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}},"x-gravityads-tool-name":"gravityads.tenant.attribution.evidence","x-gravityads-required-scope":"gravityads.read","x-gravityads-scope-source":"hosted_entitlements"}},"/tenant/approval-policies":{"get":{"operationId":"tenant_approval_policies","summary":"List tenant controlled-action approval policies","responses":{"200":{"description":"Tenant approval policies","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}},"x-gravityads-tool-name":"gravityads.tenant.approval.policies","x-gravityads-required-scope":"gravityads.admin","x-gravityads-scope-source":"hosted_entitlements"},"post":{"operationId":"tenant_approval_policy_upsert","summary":"Upsert a tenant controlled-action approval policy","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["action_type"],"additionalProperties":false,"properties":{"id":{"type":"string"},"platform_account_id":{"type":"string"},"action_type":{"type":"string"},"max_delta_percent":{"type":"number","minimum":0},"max_budget_delta_amount":{"type":"number","minimum":0},"required_role":{"type":"string","default":"approver","enum":["viewer","optimizer","operator","approver","tenant_admin","gravity_ops","admin","owner"]},"allow_self_approval":{"type":"boolean","default":true},"status":{"type":"string","enum":["active","inactive"]}}}}}},"responses":{"200":{"description":"Tenant approval policy upserted","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}},"x-gravityads-tool-name":"gravityads.tenant.approval.policy.upsert","x-gravityads-required-scope":"gravityads.admin","x-gravityads-scope-source":"hosted_entitlements"}},"/tenant/customer-groups":{"get":{"operationId":"tenant_customer_groups","summary":"List hosted tenant customer groups","responses":{"200":{"description":"Tenant customer groups","content":{"application/json":{"schema":{"type":"object","required":["status","tenant_id","customer_group_count","customer_groups","database_url_configured","raw_secrets_returned"],"additionalProperties":true,"properties":{"status":{"type":"string","enum":["tenant_customer_group_status_ready","tenant_customer_group_status_unconfigured","tenant_customer_group_status_degraded","tenant_customer_group_upserted","tenant_customer_group_upsert_unconfigured","tenant_customer_group_upsert_failed","tenant_customer_group_upsert_degraded"]},"tenant_id":{"type":"string"},"customer_group_id":{"type":"string"},"customer_group_count":{"type":"integer","minimum":0},"customer_groups":{"type":"array","items":{"type":"object"}},"platform_account_count":{"type":"integer","minimum":0},"platform_accounts":{"type":"array","items":{"type":"object"}},"discovered_platform_account_count":{"type":"integer","minimum":0},"over_limit_platform_account_count":{"type":"integer","minimum":0},"plan_account_limit":{"type":"object"},"database_url_configured":{"type":"boolean"},"hosted_auth_context":{"type":"object"},"raw_secrets_returned":{"type":"boolean","const":false}}}}}}},"x-gravityads-tool-name":"gravityads.tenant.customer.groups","x-gravityads-required-scope":"gravityads.admin","x-gravityads-scope-source":"hosted_entitlements"},"post":{"operationId":"tenant_customer_group_upsert","summary":"Upsert a hosted tenant customer group","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["id","display_name"],"additionalProperties":false,"properties":{"id":{"type":"string"},"display_name":{"type":"string"},"normalized_name":{"type":"string"},"status":{"type":"string","default":"active"}}}}}},"responses":{"200":{"description":"Tenant customer group upserted","content":{"application/json":{"schema":{"type":"object","required":["status","tenant_id","customer_group_count","customer_groups","database_url_configured","raw_secrets_returned"],"additionalProperties":true,"properties":{"status":{"type":"string","enum":["tenant_customer_group_status_ready","tenant_customer_group_status_unconfigured","tenant_customer_group_status_degraded","tenant_customer_group_upserted","tenant_customer_group_upsert_unconfigured","tenant_customer_group_upsert_failed","tenant_customer_group_upsert_degraded"]},"tenant_id":{"type":"string"},"customer_group_id":{"type":"string"},"customer_group_count":{"type":"integer","minimum":0},"customer_groups":{"type":"array","items":{"type":"object"}},"platform_account_count":{"type":"integer","minimum":0},"platform_accounts":{"type":"array","items":{"type":"object"}},"discovered_platform_account_count":{"type":"integer","minimum":0},"over_limit_platform_account_count":{"type":"integer","minimum":0},"plan_account_limit":{"type":"object"},"database_url_configured":{"type":"boolean"},"hosted_auth_context":{"type":"object"},"raw_secrets_returned":{"type":"boolean","const":false}}}}}}},"x-gravityads-tool-name":"gravityads.tenant.customer.group.upsert","x-gravityads-required-scope":"gravityads.admin","x-gravityads-scope-source":"hosted_entitlements"}},"/tenant/customer-groups/merge":{"post":{"operationId":"tenant_customer_group_merge","summary":"Merge one hosted tenant customer group into another","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["source_customer_group_id","target_customer_group_id"],"additionalProperties":false,"properties":{"source_customer_group_id":{"type":"string"},"target_customer_group_id":{"type":"string"}}}}}},"responses":{"200":{"description":"Tenant customer groups merged","content":{"application/json":{"schema":{"type":"object","required":["status","tenant_id","mode","database_url_configured","raw_secrets_returned"],"additionalProperties":true,"properties":{"status":{"type":"string"},"tenant_id":{"type":"string"},"mode":{"type":"string","enum":["merge","split"]},"source_customer_group_id":{"type":"string"},"target_customer_group_id":{"type":"string"},"moved_account_count":{"type":"integer","minimum":0},"merged_account_count":{"type":"integer","minimum":0},"affected_count":{"type":"integer","minimum":0},"customer_group_count":{"type":"integer","minimum":0},"customer_groups":{"type":"array","items":{"type":"object"}},"database_url_configured":{"type":"boolean"},"hosted_auth_context":{"type":"object"},"raw_secrets_returned":{"type":"boolean","const":false}}}}}}},"x-gravityads-tool-name":"gravityads.tenant.customer.group.merge","x-gravityads-required-scope":"gravityads.admin","x-gravityads-scope-source":"hosted_entitlements"}},"/tenant/customer-groups/split":{"post":{"operationId":"tenant_customer_group_split","summary":"Move selected accounts into a hosted tenant customer group","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["target_customer_group_id","platform_account_ids"],"additionalProperties":false,"properties":{"source_customer_group_id":{"type":"string"},"target_customer_group_id":{"type":"string"},"platform_account_ids":{"type":"array","items":{"type":"string"},"minItems":1,"maxItems":500}}}}}},"responses":{"200":{"description":"Tenant customer group split result","content":{"application/json":{"schema":{"type":"object","required":["status","tenant_id","mode","database_url_configured","raw_secrets_returned"],"additionalProperties":true,"properties":{"status":{"type":"string"},"tenant_id":{"type":"string"},"mode":{"type":"string","enum":["merge","split"]},"source_customer_group_id":{"type":"string"},"target_customer_group_id":{"type":"string"},"moved_account_count":{"type":"integer","minimum":0},"merged_account_count":{"type":"integer","minimum":0},"affected_count":{"type":"integer","minimum":0},"customer_group_count":{"type":"integer","minimum":0},"customer_groups":{"type":"array","items":{"type":"object"}},"database_url_configured":{"type":"boolean"},"hosted_auth_context":{"type":"object"},"raw_secrets_returned":{"type":"boolean","const":false}}}}}}},"x-gravityads-tool-name":"gravityads.tenant.customer.group.split","x-gravityads-required-scope":"gravityads.admin","x-gravityads-scope-source":"hosted_entitlements"}},"/tenant/account-scopes/grant":{"post":{"operationId":"tenant_account_scope_grant","summary":"Grant a user account permission","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["user_id","platform_account_id","permission"],"additionalProperties":false,"properties":{"user_id":{"type":"string"},"platform_account_id":{"type":"string"},"permission":{"type":"string","enum":["read","draft","approve","execute"]},"granted_by":{"type":"string"}}}}}},"responses":{"200":{"description":"Account scope grant result","content":{"application/json":{"schema":{"type":"object","required":["status","tenant_id","database_url_configured","raw_secrets_returned"],"additionalProperties":true,"properties":{"status":{"type":"string","enum":["account_scope_granted","account_scope_revoked","account_scope_revoke_not_found","account_scope_mutation_unconfigured","account_scope_mutation_failed","account_scope_mutation_degraded"]},"tenant_id":{"type":"string"},"user_id":{"type":"string"},"platform_account_id":{"type":"string"},"permission":{"type":"string"},"revoked_count":{"type":"integer","minimum":0},"account_scope_count":{"type":"integer","minimum":0},"account_scopes":{"type":"array","items":{"type":"object"}},"database_url_configured":{"type":"boolean"},"hosted_auth_context":{"type":"object"},"raw_secrets_returned":{"type":"boolean","const":false}}}}}}},"x-gravityads-tool-name":"gravityads.tenant.account.scope.grant","x-gravityads-required-scope":"gravityads.admin","x-gravityads-scope-source":"hosted_entitlements"}},"/tenant/account-scopes/revoke":{"post":{"operationId":"tenant_account_scope_revoke","summary":"Revoke a user account permission","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["user_id","platform_account_id","permission"],"additionalProperties":false,"properties":{"user_id":{"type":"string"},"platform_account_id":{"type":"string"},"permission":{"type":"string","enum":["read","draft","approve","execute"]},"granted_by":{"type":"string"}}}}}},"responses":{"200":{"description":"Account scope revoke result","content":{"application/json":{"schema":{"type":"object","required":["status","tenant_id","database_url_configured","raw_secrets_returned"],"additionalProperties":true,"properties":{"status":{"type":"string","enum":["account_scope_granted","account_scope_revoked","account_scope_revoke_not_found","account_scope_mutation_unconfigured","account_scope_mutation_failed","account_scope_mutation_degraded"]},"tenant_id":{"type":"string"},"user_id":{"type":"string"},"platform_account_id":{"type":"string"},"permission":{"type":"string"},"revoked_count":{"type":"integer","minimum":0},"account_scope_count":{"type":"integer","minimum":0},"account_scopes":{"type":"array","items":{"type":"object"}},"database_url_configured":{"type":"boolean"},"hosted_auth_context":{"type":"object"},"raw_secrets_returned":{"type":"boolean","const":false}}}}}}},"x-gravityads-tool-name":"gravityads.tenant.account.scope.revoke","x-gravityads-required-scope":"gravityads.admin","x-gravityads-scope-source":"hosted_entitlements"}},"/tenant/account-scopes/default-policy/apply":{"post":{"operationId":"tenant_default_account_scope_policy_apply","summary":"Preview or apply default tenant account-scope grants","requestBody":{"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"role_ids":{"type":"array","items":{"type":"string"},"default":["tenant_admin"]},"permissions":{"type":"array","items":{"type":"string","enum":["read","draft","approve","execute","admin"]},"default":["read"]},"connection_id":{"type":"string"},"customer_group_id":{"type":"string"},"platform_account_ids":{"type":"array","items":{"type":"string"}},"granted_by":{"type":"string"},"dry_run":{"type":"boolean","default":true},"max_grants":{"type":"integer","default":5000,"minimum":1}}}}}},"responses":{"200":{"description":"Default account-scope policy result","content":{"application/json":{"schema":{"type":"object","required":["status","tenant_id","database_url_configured","raw_secrets_returned"],"additionalProperties":true,"properties":{"status":{"type":"string","enum":["default_account_scope_policy_previewed","default_account_scope_policy_applied","default_account_scope_policy_unconfigured","default_account_scope_policy_failed","default_account_scope_policy_degraded"]},"tenant_id":{"type":"string"},"dry_run":{"type":"boolean"},"grant_count":{"type":"integer","minimum":0},"affected_count":{"type":"integer","minimum":0},"account_scope_count":{"type":"integer","minimum":0},"account_scopes":{"type":"array","items":{"type":"object"}},"preview":{"type":"array","items":{"type":"object"}},"database_url_configured":{"type":"boolean"},"hosted_auth_context":{"type":"object"},"raw_secrets_returned":{"type":"boolean","const":false}}}}}}},"x-gravityads-tool-name":"gravityads.tenant.default.account.scope.policy.apply","x-gravityads-required-scope":"gravityads.admin","x-gravityads-scope-source":"hosted_entitlements"}},"/tenant/action-events":{"get":{"operationId":"tenant_action_events","summary":"List tenant controlled-action ledger events","parameters":[{"name":"action_id","in":"query","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":100}}],"responses":{"200":{"description":"Tenant action events","content":{"application/json":{"schema":{"type":"object","required":["status","source","tenant_id","action_id","event_count","events","raw_secrets_returned"],"additionalProperties":true,"properties":{"status":{"type":"string","const":"tenant_action_events_ready"},"source":{"type":"string"},"tenant_id":{"type":"string"},"action_id":{"type":"string"},"event_count":{"type":"integer","minimum":0},"events":{"type":"array","items":{"type":"object"}},"hosted_auth_context":{"type":"object"},"raw_secrets_returned":{"type":"boolean","const":false}}}}}}},"x-gravityads-tool-name":"gravityads.tenant.action_events.approve","x-gravityads-required-scope":"gravityads.approve","x-gravityads-scope-source":"hosted_entitlements"}},"/tenant/customer-groups/account-scopes/grant":{"post":{"operationId":"tenant_customer_group_scope_grant","summary":"Grant a user permission to all accounts in a customer group","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["user_id","customer_group_id","permission"],"additionalProperties":false,"properties":{"user_id":{"type":"string"},"customer_group_id":{"type":"string"},"permission":{"type":"string","enum":["read","draft","approve","execute"]},"granted_by":{"type":"string"}}}}}},"responses":{"200":{"description":"Customer group scope grant result","content":{"application/json":{"schema":{"type":"object","required":["status","tenant_id","user_id","customer_group_id","permission","affected_count","database_url_configured","raw_secrets_returned"],"additionalProperties":true,"properties":{"status":{"type":"string","enum":["customer_group_scope_granted","customer_group_scope_revoked","customer_group_scope_mutation_unconfigured","customer_group_scope_mutation_failed","customer_group_scope_mutation_degraded"]},"tenant_id":{"type":"string"},"user_id":{"type":"string"},"customer_group_id":{"type":"string"},"permission":{"type":"string"},"affected_count":{"type":"integer","minimum":0},"account_scope_count":{"type":"integer","minimum":0},"account_scopes":{"type":"array","items":{"type":"object"}},"database_url_configured":{"type":"boolean"},"hosted_auth_context":{"type":"object"},"raw_secrets_returned":{"type":"boolean","const":false}}}}}}},"x-gravityads-tool-name":"gravityads.tenant.customer.group.scope.grant","x-gravityads-required-scope":"gravityads.admin","x-gravityads-scope-source":"hosted_entitlements"}},"/tenant/customer-groups/account-scopes/revoke":{"post":{"operationId":"tenant_customer_group_scope_revoke","summary":"Revoke a user permission from all accounts in a customer group","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["user_id","customer_group_id","permission"],"additionalProperties":false,"properties":{"user_id":{"type":"string"},"customer_group_id":{"type":"string"},"permission":{"type":"string","enum":["read","draft","approve","execute"]},"granted_by":{"type":"string"}}}}}},"responses":{"200":{"description":"Customer group scope revoke result","content":{"application/json":{"schema":{"type":"object","required":["status","tenant_id","user_id","customer_group_id","permission","affected_count","database_url_configured","raw_secrets_returned"],"additionalProperties":true,"properties":{"status":{"type":"string","enum":["customer_group_scope_granted","customer_group_scope_revoked","customer_group_scope_mutation_unconfigured","customer_group_scope_mutation_failed","customer_group_scope_mutation_degraded"]},"tenant_id":{"type":"string"},"user_id":{"type":"string"},"customer_group_id":{"type":"string"},"permission":{"type":"string"},"affected_count":{"type":"integer","minimum":0},"account_scope_count":{"type":"integer","minimum":0},"account_scopes":{"type":"array","items":{"type":"object"}},"database_url_configured":{"type":"boolean"},"hosted_auth_context":{"type":"object"},"raw_secrets_returned":{"type":"boolean","const":false}}}}}}},"x-gravityads-tool-name":"gravityads.tenant.customer.group.scope.revoke","x-gravityads-required-scope":"gravityads.admin","x-gravityads-scope-source":"hosted_entitlements"}},"/tenant/usage":{"get":{"operationId":"tenant_usage","summary":"Return hosted tenant usage rollup","responses":{"200":{"description":"Tenant usage","content":{"application/json":{"schema":{"type":"object","required":["status","tenant_id","rows","row_count","tool_result_metrics","tool_call_guard_metrics","platform_quota_metrics","database_url_configured","raw_secrets_returned"],"additionalProperties":true,"properties":{"status":{"type":"string","enum":["hosted_usage_rollup_ready","hosted_usage_rollup_unconfigured","hosted_usage_rollup_degraded"]},"source":{"type":"string"},"tenant_id":{"type":"string"},"usage_date":{"type":"string"},"rows":{"type":"array","items":{"type":"object"}},"row_count":{"type":"integer","minimum":0},"tool_result_metrics":{"type":"object"},"tool_call_guard_metrics":{"type":"object"},"platform_quota_metrics":{"type":"object"},"database_url_configured":{"type":"boolean"},"hosted_auth_context":{"type":"object"},"raw_secrets_returned":{"type":"boolean","const":false}}}}}}},"x-gravityads-tool-name":"gravityads.tenant.usage","x-gravityads-required-scope":"gravityads.admin","x-gravityads-scope-source":"hosted_entitlements"}},"/tenant/usage-report":{"get":{"operationId":"tenant_usage_report","summary":"Export hosted tenant usage report for a billing period","parameters":[{"name":"start_date","in":"query","required":false,"schema":{"type":"string"}},{"name":"end_date","in":"query","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":100}}],"responses":{"200":{"description":"Tenant usage report","content":{"application/json":{"schema":{"type":"object","required":["status","schema_version","tenant_id","billing_period","daily_rollups","daily_row_count","tool_usage","tool_usage_count","database_url_configured","raw_secrets_returned"],"additionalProperties":true,"properties":{"status":{"type":"string","enum":["hosted_usage_report_ready","hosted_usage_report_unconfigured","hosted_usage_report_failed","hosted_usage_report_degraded"]},"schema_version":{"type":"string","const":"gravityads.hosted_usage_report.v1"},"tenant_id":{"type":"string"},"billing_period":{"type":"object"},"daily_rollups":{"type":"array","items":{"type":"object"}},"daily_row_count":{"type":"integer","minimum":0},"tool_usage":{"type":"array","items":{"type":"object"}},"tool_usage_count":{"type":"integer","minimum":0},"tool_result_metrics":{"type":"object"},"tool_call_guard_metrics":{"type":"object"},"platform_quota_metrics":{"type":"object"},"totals":{"type":"object"},"database_url_configured":{"type":"boolean"},"hosted_auth_context":{"type":"object"},"raw_secrets_returned":{"type":"boolean","const":false}}}}}}},"x-gravityads-tool-name":"gravityads.tenant.usage_report","x-gravityads-required-scope":"gravityads.admin","x-gravityads-scope-source":"hosted_entitlements"}},"/tenant/usage-meter-events":{"get":{"operationId":"tenant_usage_meter_events","summary":"List tenant usage meter worker send ledger events","parameters":[{"name":"usage_date","in":"query","required":false,"schema":{"type":"string","format":"date"}},{"name":"event_name","in":"query","required":false,"schema":{"type":"string"}},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["sent","skipped","failed"]}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":100}}],"responses":{"200":{"description":"Redacted tenant usage meter send ledger","content":{"application/json":{"schema":{"type":"object","required":["status","tenant_id","event_count","events","raw_customer_ids_returned","raw_secrets_returned"],"properties":{"status":{"type":"string"},"source":{"type":"string"},"tenant_id":{"type":"string"},"event_count":{"type":"integer","minimum":0},"database_url_configured":{"type":"boolean"},"events":{"type":"array","items":{"type":"object","required":["tenant_id","provider","event_name","identifier","status","raw_customer_ids_returned","raw_secrets_returned"],"properties":{"tenant_id":{"type":"string"},"provider":{"type":"string","const":"stripe"},"event_name":{"type":"string"},"identifier":{"type":"string"},"usage_date":{"type":"string","format":"date"},"value":{"type":"integer","minimum":0},"stripe_customer_id_hash":{"type":"string","description":"Short SHA-256 hash prefix; raw cus_* ids are not returned."},"status":{"type":"string","enum":["sent","skipped","failed"]},"worker_id":{"type":"string"},"sender_result_redacted":{"type":"object"},"sent_at":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"raw_customer_ids_returned":{"type":"boolean","const":false},"raw_secrets_returned":{"type":"boolean","const":false}}}},"raw_customer_ids_returned":{"type":"boolean","const":false},"raw_secrets_returned":{"type":"boolean","const":false}}}}}}},"x-gravityads-tool-name":"gravityads.tenant.usage_meter_events","x-gravityads-required-scope":"gravityads.admin","x-gravityads-scope-source":"hosted_entitlements"}},"/tenant/audit-export":{"get":{"operationId":"tenant_audit_export","summary":"Export tenant-scoped Enterprise audit evidence","description":"Returns tenant-scoped call log, control-plane audit log and controlled-action ledger evidence with raw secrets, raw account ids and raw chat/message identifiers removed.","parameters":[{"name":"operator_id","in":"query","required":false,"schema":{"type":"string"}},{"name":"operation","in":"query","required":false,"schema":{"type":"string"}},{"name":"date","in":"query","required":false,"schema":{"type":"string","description":"YYYY-MM-DD"}},{"name":"action_id","in":"query","required":false,"schema":{"type":"string"}},{"name":"account_id","in":"query","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":100,"maximum":500}}],"responses":{"200":{"description":"Tenant audit export","content":{"application/json":{"schema":{"type":"object","required":["schema_version","status","export_scope","tenant_id","filters","entry_count","entries","control_plane_audit_log","action_ledger","export_manifest","secret_values_redacted","raw_account_ids_returned","raw_chat_ids_returned","raw_message_ids_returned","raw_tool_call_ids_returned","raw_llm_response_ids_returned","raw_user_emails_returned","raw_secrets_returned"],"additionalProperties":true,"properties":{"schema_version":{"type":"string","const":"gravityads.tenant_audit_export.v1"},"status":{"type":"string","enum":["tenant_audit_export_ready","tenant_audit_export_degraded","tenant_audit_export_unconfigured"]},"export_scope":{"type":"string","const":"tenant"},"tenant_id":{"type":"string"},"call_log_status":{"type":"string"},"filters":{"type":"object"},"entry_count":{"type":"integer","minimum":0},"entries":{"type":"array","items":{"type":"object"}},"control_plane_audit_log":{"type":"object"},"action_ledger":{"type":"object"},"resource_links":{"type":"array","items":{"type":"object"}},"export_manifest":{"type":"object"},"hosted_auth_context":{"type":"object"},"secret_values_redacted":{"type":"boolean","const":true},"raw_account_ids_returned":{"type":"boolean","const":false},"raw_chat_ids_returned":{"type":"boolean","const":false},"raw_message_ids_returned":{"type":"boolean","const":false},"raw_tool_call_ids_returned":{"type":"boolean","const":false},"raw_llm_response_ids_returned":{"type":"boolean","const":false},"raw_user_emails_returned":{"type":"boolean","const":false},"raw_secrets_returned":{"type":"boolean","const":false}}}}}}},"x-gravityads-tool-name":"gravityads.tenant.audit_export","x-gravityads-required-scope":"gravityads.admin","x-gravityads-scope-source":"hosted_entitlements"}},"/tenant/audit-export/download":{"get":{"operationId":"tenant_audit_export_download","summary":"Download tenant-scoped Enterprise audit evidence package","description":"Returns a single JSON audit export package with manifest, JSONL evidence files, content-free file manifest, integrity hashes, tenant retention policy and download headers. It reuses tenant-scoped audit filters and keeps raw secrets, raw account ids and raw chat/message identifiers removed.","parameters":[{"name":"operator_id","in":"query","required":false,"schema":{"type":"string"}},{"name":"operation","in":"query","required":false,"schema":{"type":"string"}},{"name":"date","in":"query","required":false,"schema":{"type":"string","description":"YYYY-MM-DD"}},{"name":"action_id","in":"query","required":false,"schema":{"type":"string"}},{"name":"account_id","in":"query","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":100,"maximum":500}}],"responses":{"200":{"description":"Tenant audit export package","content":{"application/json":{"schema":{"type":"object","required":["package_schema_version","status","package_id","export_scope","tenant_id_hash","manifest","file_manifest","integrity","enterprise_export","download","secret_values_redacted","raw_account_ids_returned","raw_chat_ids_returned","raw_message_ids_returned","raw_tool_call_ids_returned","raw_llm_response_ids_returned","raw_user_emails_returned","raw_secrets_returned"],"additionalProperties":true,"properties":{"package_schema_version":{"type":"string","const":"gravityads.audit_export_package.v1"},"status":{"type":"string","const":"audit_export_package_ready"},"package_id":{"type":"string"},"generated_at_utc":{"type":"string"},"export_scope":{"type":"string","const":"tenant"},"tenant_id":{"type":"string"},"tenant_id_hash":{"type":"string"},"source_status":{"type":"string"},"manifest":{"type":"object"},"files":{"type":"array","items":{"type":"object"}},"file_manifest":{"type":"array","items":{"type":"object"}},"file_count":{"type":"integer","minimum":0},"total_byte_size":{"type":"integer","minimum":0},"package_sha256":{"type":"string"},"integrity":{"type":"object"},"enterprise_export":{"type":"object"},"download":{"type":"object"},"archive_targets":{"type":"object"},"archive":{"type":"object"},"secret_values_redacted":{"type":"boolean","const":true},"raw_account_ids_returned":{"type":"boolean","const":false},"raw_chat_ids_returned":{"type":"boolean","const":false},"raw_message_ids_returned":{"type":"boolean","const":false},"raw_tool_call_ids_returned":{"type":"boolean","const":false},"raw_llm_response_ids_returned":{"type":"boolean","const":false},"raw_user_emails_returned":{"type":"boolean","const":false},"raw_secrets_returned":{"type":"boolean","const":false}}}}}}},"x-gravityads-tool-name":"gravityads.tenant.audit_export.download","x-gravityads-required-scope":"gravityads.admin","x-gravityads-scope-source":"hosted_entitlements"}},"/tenant/action-execute-status":{"get":{"operationId":"tenant_action_execute_status","summary":"Return hosted controlled-action execute status","description":"Returns the tenant/plan live execute enablement, queue availability and worker-only platform write boundary for Phase 2 Actions UI without exposing raw allowlists.","responses":{"200":{"description":"Tenant controlled-action execute status","content":{"application/json":{"schema":{"type":"object","required":["status","tenant_id","ready_for_live_execute","phase_contract","execute_enablement","queue","platform_write_boundary","raw_allowlists_returned","raw_secrets_returned"],"properties":{"status":{"type":"string"},"tenant_id":{"type":"string"},"ready_for_live_execute":{"type":"boolean"},"phase_contract":{"type":"string"},"blockers":{"type":"array","items":{"type":"string"}},"execute_enablement":{"type":"object","properties":{"live_execute_enabled_for_current_tenant":{"type":"boolean"},"plan_allows_controlled_execute":{"type":"boolean"},"rollout_enabled_for_current_tenant":{"type":"boolean"},"enabled_by_global_flag":{"type":"boolean"},"enabled_by_current_tenant":{"type":"boolean"},"enabled_by_current_plan":{"type":"boolean"},"current_plan_id":{"type":"string"},"plan_source":{"type":"string"},"raw_allowlists_returned":{"type":"boolean","const":false}}},"capability_explanation":{"type":"object","properties":{"reason_code":{"type":"string"},"current_plan_id":{"type":"string"},"controlled_execute_included_in_plan":{"type":"boolean"},"live_execute_enabled_for_current_tenant":{"type":"boolean"},"next_step":{"type":"string"},"portal_path":{"type":"string"}}},"queue":{"type":"object","properties":{"enabled":{"type":"boolean"},"hosted_control_plane_enabled":{"type":"boolean"},"database_url_configured":{"type":"boolean"},"disabled_by_env":{"type":"boolean"},"disabled_reason":{"type":"string"},"status_endpoint":{"type":"string"}}},"platform_write_boundary":{"type":"object","properties":{"phase1_request_thread_platform_write_allowed":{"type":"boolean","const":false},"phase2_live_execute_worker_only":{"type":"boolean","const":true},"controlled_action_execute_endpoint":{"type":"string"},"queue_status_endpoint":{"type":"string"},"approval_policy_endpoint":{"type":"string"}}},"raw_allowlists_returned":{"type":"boolean","const":false},"raw_secrets_returned":{"type":"boolean","const":false}}}}}}},"x-gravityads-tool-name":"gravityads.tenant.action_status.approve","x-gravityads-required-scope":"gravityads.approve","x-gravityads-scope-source":"hosted_entitlements"}},"/tenant/action-readiness":{"get":{"operationId":"tenant_action_readiness","summary":"Return per-action hosted live execute readiness","description":"Combines action ledger, latest queue item, approval policy and tenant live execute enablement so Portal can render approval/execute buttons without attempting live execution.","parameters":[{"name":"action_id","in":"query","required":true,"schema":{"type":"string"}},{"name":"execute_mode","in":"query","required":false,"schema":{"type":"string","default":"live"}}],"responses":{"200":{"description":"Tenant action readiness","content":{"application/json":{"schema":{"type":"object","required":["schema_version","status","tenant_id","action_id","exists","execute_mode","ready_for_live_execute","action","execute_enablement","approval_policy","latest_queue_item","next_actions","raw_user_ids_returned","raw_account_ids_returned","raw_secrets_returned"],"properties":{"platform_create_scope":{"type":"array","items":{"type":"string"}},"creation_contract_valid":{"type":"boolean"},"can_reconcile":{"type":"boolean"},"creation_contract_error":{"type":"string"},"ad_create_spec":{"type":"object","additionalProperties":true},"requested_publish_state":{"type":"string"},"schema_version":{"type":"string"},"status":{"type":"string"},"tenant_id":{"type":"string"},"action_id":{"type":"string"},"exists":{"type":"boolean"},"execute_mode":{"type":"string"},"ready_for_live_execute":{"type":"boolean"},"blockers":{"type":"array","items":{"type":"string"}},"provider_permissions":{"type":"object","additionalProperties":true},"action":{"type":"object"},"execute_enablement":{"type":"object"},"approval_policy":{"type":"object"},"latest_queue_item":{"type":"object"},"latest_execution":{"type":"object"},"next_actions":{"type":"array","items":{"type":"object"}},"raw_user_ids_returned":{"type":"boolean","const":false},"raw_account_ids_returned":{"type":"boolean","const":false},"raw_secrets_returned":{"type":"boolean","const":false}}}}}}},"x-gravityads-tool-name":"gravityads.tenant.action_readiness.approve","x-gravityads-required-scope":"gravityads.approve","x-gravityads-scope-source":"hosted_entitlements"}},"/tenant/action-queue":{"get":{"operationId":"tenant_action_queue","summary":"Return hosted controlled-action queue for Approval UI","description":"Lists tenant action queue items joined with redacted ledger metadata so approvers can inspect pending, leased, failed or completed hosted worker handoffs.","parameters":[{"name":"state","in":"query","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":50}}],"responses":{"200":{"description":"Tenant action queue","content":{"application/json":{"schema":{"type":"object","required":["status","source","tenant_id","filters","queue_item_count","queue_items","state_counts","raw_secrets_returned"],"additionalProperties":true,"properties":{"status":{"type":"string","const":"hosted_action_queue_status_ready"},"source":{"type":"string"},"tenant_id":{"type":"string"},"filters":{"type":"object","additionalProperties":true,"properties":{"state":{"type":"array","items":{"type":"string"}},"limit":{"type":"integer","minimum":1,"maximum":200}}},"queue_item_count":{"type":"integer","minimum":0},"queue_items":{"type":"array","items":{"type":"object"}},"state_counts":{"type":"object"},"hosted_auth_context":{"type":"object"},"raw_secrets_returned":{"type":"boolean","const":false}}}}}}},"x-gravityads-tool-name":"gravityads.tenant.action_queue.approve","x-gravityads-required-scope":"gravityads.approve","x-gravityads-scope-source":"hosted_entitlements"}},"/tenant/etl-status":{"get":{"operationId":"tenant_etl_status","summary":"Return hosted tenant ETL and freshness status","responses":{"200":{"description":"Tenant ETL status","content":{"application/json":{"schema":{"type":"object","required":["status","tenant_id","run_count","runs","watermark_count","watermarks","database_url_configured","raw_secrets_returned"],"additionalProperties":true,"properties":{"status":{"type":"string","enum":["hosted_etl_status_ready","hosted_etl_status_unconfigured","hosted_etl_status_degraded"]},"source":{"type":"string"},"tenant_id":{"type":"string"},"filters":{"type":"object"},"run_count":{"type":"integer","minimum":0},"runs":{"type":"array","items":{"type":"object"}},"watermark_count":{"type":"integer","minimum":0},"watermarks":{"type":"array","items":{"type":"object"}},"stage_transition_count":{"type":"integer","minimum":0},"stage_transitions":{"type":"array","items":{"type":"object"}},"source_freshness_acceptance":{"type":"object"},"database_url_configured":{"type":"boolean"},"hosted_auth_context":{"type":"object"},"raw_secrets_returned":{"type":"boolean","const":false}}}}}}},"x-gravityads-tool-name":"gravityads.tenant.etl.status","x-gravityads-required-scope":"gravityads.admin","x-gravityads-scope-source":"hosted_entitlements"}},"/tenant/etl-runs/complete":{"post":{"operationId":"tenant_etl_run_complete","summary":"Record hosted ETL run completion and freshness watermark","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["run_id","platform","account_id","status"],"additionalProperties":false,"properties":{"run_id":{"type":"string"},"connection_id":{"type":"string"},"platform_account_id":{"type":"string"},"platform":{"type":"string","enum":["google","meta","microsoft","bing","tiktok","criteo","media_go","pinterest","linkedin","amazon"]},"account_id":{"type":"string"},"run_type":{"type":"string","default":"incremental"},"source_type":{"type":"string","default":"mini2_bridge"},"date_range_start":{"type":"string","format":"date"},"date_range_end":{"type":"string","format":"date"},"freshness_watermark":{"type":"string","format":"date"},"source_observed_through":{"type":"string","format":"date"},"extract_completed_through":{"type":"string","format":"date"},"published_through":{"type":"string","format":"date"},"serving_queryable_through":{"type":"string","format":"date"},"source_response_hash":{"type":"string"},"zero_row_confirmed":{"type":"boolean"},"serving_verified":{"type":"boolean"},"freshness_status":{"type":"string","default":"fresh"},"rows_synced":{"type":"integer","minimum":0},"status":{"type":"string","enum":["queued","running","succeeded","partial","failed"]},"error_code":{"type":"string"},"error_message":{"type":"string"},"retryable":{"type":"boolean"},"table_names":{"type":"array","items":{"type":"string"},"maxItems":20},"stale_after_days":{"type":"integer","minimum":0,"maximum":30},"completed_at":{"type":"string","format":"date-time"}}}}}},"responses":{"200":{"description":"ETL run completion recorded","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}},"x-gravityads-tool-name":"gravityads.tenant.etl.run.complete","x-gravityads-required-scope":"gravityads.ops","x-gravityads-scope-source":"hosted_entitlements"}},"/tenant/etl-runs/claim":{"post":{"operationId":"tenant_etl_run_claim","summary":"Claim the next queued hosted ETL run for a worker","requestBody":{"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"source_type":{"type":"string","enum":["mini2_bridge","cloud_oauth_connector","live_api_fallback","manual_import"]},"platform":{"type":"string","enum":["google","meta","microsoft","bing","tiktok","criteo","media_go","pinterest","linkedin","amazon"]},"run_type":{"type":"string","enum":["backfill","funding_refresh","incremental","snapshot_discovery","live_fallback"]}}}}}},"responses":{"200":{"description":"ETL run claimed","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}},"x-gravityads-tool-name":"gravityads.tenant.etl.run.claim","x-gravityads-required-scope":"gravityads.ops","x-gravityads-scope-source":"hosted_entitlements"}},"/tenant/api-keys":{"get":{"operationId":"tenant_api_keys","summary":"List hosted tenant API keys without raw key material","responses":{"200":{"description":"Tenant API keys","content":{"application/json":{"schema":{"type":"object","required":["status","tenant_id","key_count","keys","raw_key_returned","raw_secrets_returned"],"additionalProperties":true,"properties":{"status":{"type":"string","enum":["tenant_api_key_status_ready","tenant_api_keys_failed","error"]},"source":{"type":"string"},"tenant_id":{"type":"string"},"key_count":{"type":"integer","minimum":0},"keys":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"id":{"type":"string"},"tenant_id":{"type":"string"},"label":{"type":"string"},"key_fingerprint":{"type":"string"},"scopes":{"type":"array","items":{"type":"string"}},"missing_recommended_scopes":{"type":"array","items":{"type":"string"}},"mcp_capability_status":{"type":"string"},"status":{"type":"string"},"created_by_user_id":{"type":"string"},"expires_at":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"revoked_at":{"type":"string"},"revoked_reason":{"type":"string"}}}},"plan_id":{"type":"string"},"recommended_mcp_scopes":{"type":"array","items":{"type":"string"}},"active_key_count":{"type":"integer","minimum":0},"plan_capable_active_key_count":{"type":"integer","minimum":0},"requires_scope_rotation":{"type":"boolean"},"missing_recommended_scopes":{"type":"array","items":{"type":"string"}},"scope_migration":{"type":"object"},"hosted_auth_context":{"type":"object"},"raw_key_returned":{"type":"boolean","const":false},"raw_secrets_returned":{"type":"boolean","const":false}}}}}}},"x-gravityads-tool-name":"gravityads.tenant.api.keys","x-gravityads-required-scope":"gravityads.admin","x-gravityads-scope-source":"hosted_entitlements"},"post":{"operationId":"tenant_api_key_create","summary":"Create a hosted tenant API key","requestBody":{"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"label":{"type":"string"},"ttl_days":{"type":"integer","minimum":0,"maximum":366},"scopes":{"type":"array","items":{"type":"string"}}}}}}},"responses":{"200":{"description":"Tenant API key created","content":{"application/json":{"schema":{"type":"object","required":["status","tenant_id","key_id","key_fingerprint","raw_key_returned_once","raw_secrets_returned"],"additionalProperties":true,"properties":{"status":{"type":"string","enum":["tenant_api_key_created","tenant_api_key_create_unconfigured","tenant_api_key_create_failed","tenant_api_key_create_degraded"]},"tenant_id":{"type":"string"},"key_id":{"type":"string"},"label":{"type":"string"},"key_fingerprint":{"type":"string"},"fingerprint":{"type":"string"},"raw_key":{"type":"string"},"scopes":{"type":"array","items":{"type":"string"}},"expires_at":{"type":"string"},"hosted_auth_context":{"type":"object"},"database_url_configured":{"type":"boolean"},"raw_key_returned_once":{"type":"boolean","const":true},"raw_secrets_returned":{"type":"boolean","const":false}}}}}}},"x-gravityads-tool-name":"gravityads.tenant.api.key.create","x-gravityads-required-scope":"gravityads.admin","x-gravityads-scope-source":"hosted_entitlements"}},"/tenant/api-keys/ensure-default":{"post":{"operationId":"tenant_api_key_ensure_default","summary":"Ensure the tenant has a default read-only MCP API key","requestBody":{"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"label":{"type":"string","default":"Default MCP key","description":"Display label for the default Portal quickstart key."},"ttl_days":{"type":"integer","minimum":0,"maximum":366},"scopes":{"type":"array","items":{"type":"string"},"default":["gravityads.read"]}}}}}},"responses":{"200":{"description":"Default tenant MCP API key ready","content":{"application/json":{"schema":{"type":"object","required":["status","tenant_id","label","key_created","default_key_exists","requires_rotation_for_reveal","raw_key_returned_once","raw_secrets_returned"],"additionalProperties":true,"properties":{"status":{"type":"string","enum":["tenant_api_key_default_created","tenant_api_key_default_ready","tenant_api_key_default_ensure_failed","error"]},"tenant_id":{"type":"string"},"label":{"type":"string"},"key_id":{"type":"string"},"key_fingerprint":{"type":"string"},"fingerprint":{"type":"string"},"raw_key":{"type":"string"},"scopes":{"type":"array","items":{"type":"string"}},"hosted_auth_context":{"type":"object"},"key_created":{"type":"boolean"},"default_key_exists":{"type":"boolean","const":true},"requires_rotation_for_reveal":{"type":"boolean"},"raw_key_returned":{"type":"boolean"},"raw_key_returned_once":{"type":"boolean"},"raw_secrets_returned":{"type":"boolean","const":false}}}}}}},"x-gravityads-tool-name":"gravityads.tenant.api.key.ensure.default","x-gravityads-required-scope":"gravityads.admin","x-gravityads-scope-source":"hosted_entitlements"}},"/tenant/api-keys/revoke":{"post":{"operationId":"tenant_api_key_revoke","summary":"Revoke a hosted tenant API key","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["identifier"],"additionalProperties":false,"properties":{"identifier":{"type":"string"},"reason":{"type":"string"}}}}}},"responses":{"200":{"description":"Tenant API key revoked","content":{"application/json":{"schema":{"type":"object","required":["status","tenant_id","revoked_count","key_count","keys","raw_key_returned","raw_secrets_returned"],"additionalProperties":true,"properties":{"status":{"type":"string","const":"tenant_api_key_revoked"},"source":{"type":"string"},"tenant_id":{"type":"string"},"revoked_count":{"type":"integer","minimum":0},"key_count":{"type":"integer","minimum":0},"keys":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"id":{"type":"string"},"tenant_id":{"type":"string"},"label":{"type":"string"},"key_fingerprint":{"type":"string"},"scopes":{"type":"array","items":{"type":"string"}},"missing_recommended_scopes":{"type":"array","items":{"type":"string"}},"mcp_capability_status":{"type":"string"},"status":{"type":"string"},"created_by_user_id":{"type":"string"},"expires_at":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"revoked_at":{"type":"string"},"revoked_reason":{"type":"string"}}}},"hosted_auth_context":{"type":"object"},"raw_key_returned":{"type":"boolean","const":false},"raw_secrets_returned":{"type":"boolean","const":false}}}}}}},"x-gravityads-tool-name":"gravityads.tenant.api.key.revoke","x-gravityads-required-scope":"gravityads.admin","x-gravityads-scope-source":"hosted_entitlements"}},"/tenant/api-keys/self-revoke":{"post":{"operationId":"tenant_api_key_self_revoke","summary":"Revoke the currently authenticated hosted API key","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["confirmation_fingerprint"],"additionalProperties":false,"properties":{"confirmation_fingerprint":{"type":"string","minLength":12},"reason":{"type":"string"}}}}}},"responses":{"200":{"description":"Authenticated tenant API key revoked","content":{"application/json":{"schema":{"type":"object","required":["status","tenant_id","revoked_count","key_count","keys","raw_key_returned","raw_secrets_returned","self_key_fingerprint"],"additionalProperties":true,"properties":{"status":{"type":"string","const":"tenant_api_key_self_revoked"},"source":{"type":"string"},"tenant_id":{"type":"string"},"revoked_count":{"type":"integer","minimum":0},"key_count":{"type":"integer","minimum":0},"keys":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"id":{"type":"string"},"tenant_id":{"type":"string"},"label":{"type":"string"},"key_fingerprint":{"type":"string"},"scopes":{"type":"array","items":{"type":"string"}},"missing_recommended_scopes":{"type":"array","items":{"type":"string"}},"mcp_capability_status":{"type":"string"},"status":{"type":"string"},"created_by_user_id":{"type":"string"},"expires_at":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"revoked_at":{"type":"string"},"revoked_reason":{"type":"string"}}}},"hosted_auth_context":{"type":"object"},"raw_key_returned":{"type":"boolean","const":false},"raw_secrets_returned":{"type":"boolean","const":false},"self_key_fingerprint":{"type":"string"}}}}}}},"x-gravityads-tool-name":"gravityads.api_key.self_revoke","x-gravityads-required-scope":"gravityads.read","x-gravityads-scope-source":"hosted_entitlements"}},"/tenant/api-keys/rotate":{"post":{"operationId":"tenant_api_key_rotate","summary":"Atomically rotate a hosted tenant API key","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["identifier"],"properties":{"identifier":{"type":"string"},"label":{"type":"string"},"scopes":{"type":"array","items":{"type":"string"}},"ttl_days":{"type":"integer"},"reason":{"type":"string"}}}}}},"responses":{"200":{"description":"Tenant API key rotated","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}},"x-gravityads-tool-name":"gravityads.tenant.api.key.rotate","x-gravityads-required-scope":"gravityads.admin","x-gravityads-scope-source":"hosted_entitlements"}},"/tenant/api-clients":{"get":{"operationId":"tenant_api_clients","summary":"List registered hosted MCP/OpenAPI clients","responses":{"200":{"description":"Tenant API clients","content":{"application/json":{"schema":{"type":"object","required":["status","tenant_id","client_count","clients","raw_client_secret_returned","raw_secrets_returned"],"additionalProperties":true,"properties":{"status":{"type":"string","enum":["tenant_api_client_status_ready","tenant_api_clients_failed","error"]},"source":{"type":"string"},"tenant_id":{"type":"string"},"client_count":{"type":"integer","minimum":0},"clients":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"id":{"type":"string"},"tenant_id":{"type":"string"},"client_id_hash":{"type":"string"},"display_name":{"type":"string"},"client_type":{"type":"string"},"allowed_redirect_uris":{"type":"array","items":{"type":"string"}},"scopes":{"type":"array","items":{"type":"string"}},"status":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"}}}},"hosted_auth_context":{"type":"object"},"raw_client_secret_returned":{"type":"boolean","const":false},"raw_secrets_returned":{"type":"boolean","const":false}}}}}}},"x-gravityads-tool-name":"gravityads.tenant.api.clients","x-gravityads-required-scope":"gravityads.admin","x-gravityads-scope-source":"hosted_entitlements"},"post":{"operationId":"tenant_api_client_register","summary":"Register a hosted MCP/OpenAPI client","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["display_name"],"additionalProperties":false,"properties":{"id":{"type":"string"},"client_id":{"type":"string"},"client_id_hash":{"type":"string","minLength":64,"maxLength":64},"display_name":{"type":"string"},"client_type":{"type":"string","enum":["mcp_client","openapi_client","workbench","worker"]},"allowed_redirect_uris":{"type":"array","items":{"type":"string"},"maxItems":20},"scopes":{"type":"array","items":{"type":"string"}},"status":{"type":"string"}}}}}},"responses":{"200":{"description":"Tenant API client registered","content":{"application/json":{"schema":{"type":"object","required":["status","tenant_id","client_id_hash","raw_client_id_returned","raw_client_secret_returned","raw_secrets_returned"],"additionalProperties":true,"properties":{"status":{"type":"string","enum":["tenant_api_client_registered","tenant_api_client_register_unconfigured","tenant_api_client_register_failed","tenant_api_client_register_degraded"]},"tenant_id":{"type":"string"},"client_id_hash":{"type":"string"},"display_name":{"type":"string"},"client_type":{"type":"string"},"allowed_redirect_uris":{"type":"array","items":{"type":"string"}},"scopes":{"type":"array","items":{"type":"string"}},"hosted_auth_context":{"type":"object"},"database_url_configured":{"type":"boolean"},"raw_client_id_returned":{"type":"boolean","const":false},"raw_client_secret_returned":{"type":"boolean","const":false},"raw_secrets_returned":{"type":"boolean","const":false}}}}}}},"x-gravityads-tool-name":"gravityads.tenant.api.client.register","x-gravityads-required-scope":"gravityads.admin","x-gravityads-scope-source":"hosted_entitlements"}},"/tenant/api-clients/revoke":{"post":{"operationId":"tenant_api_client_revoke","summary":"Revoke a hosted MCP/OpenAPI client registration","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["identifier"],"additionalProperties":false,"properties":{"identifier":{"type":"string"},"reason":{"type":"string"}}}}}},"responses":{"200":{"description":"Tenant API client revoked","content":{"application/json":{"schema":{"type":"object","required":["status","tenant_id","revoked_count","client_count","clients","raw_client_id_returned","raw_client_secret_returned","raw_secrets_returned"],"additionalProperties":true,"properties":{"status":{"type":"string","const":"tenant_api_client_revoked"},"source":{"type":"string"},"tenant_id":{"type":"string"},"revoked_count":{"type":"integer","minimum":0},"client_count":{"type":"integer","minimum":0},"clients":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"id":{"type":"string"},"tenant_id":{"type":"string"},"client_id_hash":{"type":"string"},"display_name":{"type":"string"},"client_type":{"type":"string"},"allowed_redirect_uris":{"type":"array","items":{"type":"string"}},"scopes":{"type":"array","items":{"type":"string"}},"status":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"}}}},"hosted_auth_context":{"type":"object"},"raw_client_id_returned":{"type":"boolean","const":false},"raw_client_secret_returned":{"type":"boolean","const":false},"raw_secrets_returned":{"type":"boolean","const":false}}}}}}},"x-gravityads-tool-name":"gravityads.tenant.api.client.revoke","x-gravityads-required-scope":"gravityads.admin","x-gravityads-scope-source":"hosted_entitlements"}},"/billing/plans":{"get":{"operationId":"billing_plans","summary":"List hosted GravityAds billing plans","responses":{"200":{"description":"Billing plans","content":{"application/json":{"schema":{"oneOf":[{"type":"object","required":["schema_version","status","billing_model","pricing_basis","price_unit","currency_primary","billing_source_of_truth","cost_metadata_mode","llm_provider_pricing_exposed","llm_tokens_billable_unit","provider_cost_passthrough_to_customer","plans","agency_packaging","raw_price_ids_returned","raw_secrets_returned"],"properties":{"schema_version":{"type":"string","const":"gravityads.hosted_plan_catalog.v1"},"status":{"type":"string","const":"hosted_plan_catalog_ready"},"billing_model":{"type":"string","const":"subscription"},"pricing_basis":{"type":"string","const":"gravityads_saas_plan"},"price_unit":{"type":"string","const":"tenant_workspace"},"currency_primary":{"type":"string","const":"usd"},"billing_source_of_truth":{"type":"string","const":"/billing/plans"},"cost_metadata_mode":{"type":"string","const":"internal_attribution_only"},"llm_provider_pricing_exposed":{"type":"boolean","const":false},"llm_tokens_billable_unit":{"type":"boolean","const":false},"provider_cost_passthrough_to_customer":{"type":"boolean","const":false},"usage_metrics_customer_purpose":{"type":"string","const":"limits_overage_policy_and_reporting"},"plans":{"type":"array","items":{"type":"object","required":["plan_id","display_name","billing_model","pricing_basis","price_unit","price_cents","llm_provider_pricing_exposed","llm_tokens_billable_unit","provider_cost_passthrough_to_customer","max_accounts","max_users","allowed_scopes","commerce_attribution_evidence_enabled"],"properties":{"plan_id":{"type":"string","enum":["free","starter","pro","quant","enterprise"]},"display_name":{"type":"string"},"billing_model":{"type":"string","const":"subscription"},"pricing_basis":{"type":"string","const":"gravityads_saas_plan"},"price_unit":{"type":"string","const":"tenant_workspace"},"price_cents":{"type":"object","required":["monthly","annual","currency"],"properties":{"monthly":{"type":"integer","minimum":0},"annual":{"type":"integer","minimum":0},"currency":{"type":"string","const":"usd"}}},"llm_provider_pricing_exposed":{"type":"boolean","const":false},"llm_tokens_billable_unit":{"type":"boolean","const":false},"provider_cost_passthrough_to_customer":{"type":"boolean","const":false},"max_accounts":{"type":"integer","minimum":0},"max_users":{"type":"integer","minimum":0},"allowed_scopes":{"type":"array","items":{"type":"string"}},"workbench_enabled":{"type":"boolean"},"quant_intelligence_enabled":{"type":"boolean"},"audit_export_enabled":{"type":"boolean"},"sso_enabled":{"type":"boolean"},"commerce_attribution_evidence_enabled":{"type":"boolean"}}}},"trial_policy":{"type":"object","required":["schema_version","trial_plan_id","trial_duration_days","payment_method_required","redemption_key","max_redemptions_per_key","invite_policy","paid_subscription_precedence","server_side_enforced","raw_email_returned","raw_secrets_returned"],"additionalProperties":false,"properties":{"schema_version":{"type":"string","const":"gravityads.trial_policy.v1"},"trial_plan_id":{"type":"string","const":"pro"},"trial_duration_days":{"type":"integer","const":14},"payment_method_required":{"type":"boolean","const":false},"redemption_key":{"type":"string","const":"tenant_id_and_admin_email_hash"},"max_redemptions_per_key":{"type":"integer","const":1},"invite_policy":{"type":"string","const":"invite_never_resets_or_extends_trial"},"paid_subscription_precedence":{"type":"string","const":"paid_active_subscription_wins"},"server_side_enforced":{"type":"boolean","const":true},"raw_email_returned":{"type":"boolean","const":false},"raw_secrets_returned":{"type":"boolean","const":false}}},"agency_packaging":{"type":"object","required":["schema_version","status","base_plan_id","billing_model","base_monthly_cents","minimum_committed_managed_accounts","meter_unit","tiers","public_offer_enabled","requires_design_partner_validation","requires_margin_model_validation","raw_price_ids_returned","raw_secrets_returned"],"additionalProperties":true,"properties":{"schema_version":{"type":"string","const":"gravityads.agency_packaging.v1"},"status":{"type":"string","const":"design_partner_validation_required"},"base_plan_id":{"type":"string","const":"enterprise"},"billing_model":{"type":"string","const":"enterprise_commitment_plus_managed_account_addon"},"base_monthly_cents":{"type":"integer","const":79900},"minimum_committed_managed_accounts":{"type":"integer","const":20},"meter_unit":{"type":"string","const":"active_assigned_syncing_managed_ad_account_month"},"tiers":{"type":"array","items":{"type":"object"}},"public_offer_enabled":{"type":"boolean","const":false},"requires_design_partner_validation":{"type":"boolean","const":true},"requires_margin_model_validation":{"type":"boolean","const":true},"raw_price_ids_returned":{"type":"boolean","const":false},"raw_secrets_returned":{"type":"boolean","const":false}}},"raw_price_ids_returned":{"type":"boolean","const":false},"raw_secrets_returned":{"type":"boolean","const":false}},"not":{"required":["catalog_version"]}},{"type":"object","additionalProperties":true,"required":["catalog_version","schema_version","status","plans","raw_price_ids_returned","raw_secrets_returned"],"properties":{"catalog_version":{"type":"string","const":"launch-v4-20261001"},"schema_version":{"type":"string","const":"gravityads.hosted_plan_catalog.v1"},"status":{"type":"string","const":"hosted_plan_catalog_ready"},"price_unit":{"type":"string","const":"tenant_account_pool"},"plans":{"type":"array","items":{"type":"object","additionalProperties":true}},"raw_price_ids_returned":{"type":"boolean","const":false},"raw_secrets_returned":{"type":"boolean","const":false}}}]}}}}},"x-gravityads-tool-name":"gravityads.billing.plans","x-gravityads-required-scope":"gravityads.read","x-gravityads-scope-source":"hosted_entitlements"}},"/billing/readiness":{"get":{"operationId":"billing_readiness","summary":"Return hosted Stripe billing configuration readiness","parameters":[{"name":"verify_provider","in":"query","schema":{"type":"boolean","default":false},"description":"Admin-only explicit read-only Stripe Tax settings probe; configuration readiness alone is not paid-launch validation."}],"responses":{"200":{"description":"Billing readiness","content":{"application/json":{"schema":{"type":"object","required":["schema_version","status","provider","ready_for_checkout","ready_for_customer_portal","ready_for_subscription_billing","stripe_api_called","raw_price_ids_returned","raw_secrets_returned"],"additionalProperties":true,"properties":{"schema_version":{"type":"string","const":"gravityads.hosted_billing_readiness.v1"},"status":{"type":"string"},"tenant_id":{"type":"string"},"provider":{"type":"string","const":"stripe"},"checkout_api_key_configured":{"type":"boolean"},"meter_api_key_configured":{"type":"boolean"},"webhook_secret_configured":{"type":"boolean"},"portal_configuration_configured":{"type":"boolean"},"required_price_plans":{"type":"array","items":{"type":"string"}},"configured_price_plans":{"type":"array","items":{"type":"string"}},"configured_price_plan_count":{"type":"integer","minimum":0},"missing_price_plans":{"type":"array","items":{"type":"string"}},"missing_configuration":{"type":"array","items":{"type":"string"}},"configuration_errors":{"type":"array","items":{"type":"string"}},"readiness_checks":{"type":"array","items":{"type":"object"}},"ready_for_checkout":{"type":"boolean"},"ready_for_customer_portal":{"type":"boolean"},"ready_for_webhook_ingestion":{"type":"boolean"},"ready_for_usage_meter_preview":{"type":"boolean"},"ready_for_usage_meter_send":{"type":"boolean"},"ready_for_billing_worker":{"type":"boolean"},"ready_for_subscription_billing":{"type":"boolean"},"ready_for_production_billing":{"type":"boolean"},"ready_for_external_paid_checkout":{"type":"boolean"},"price_intervals":{"type":"object","properties":{"monthly":{"type":"array","items":{"type":"string"}},"annual":{"type":"array","items":{"type":"string"}}}},"tax_readiness":{"type":"object","properties":{"status":{"type":"string"},"active":{"type":["boolean","null"]},"provider_api_called":{"type":"boolean"},"registrations_verified":{"type":"boolean"}}},"hosted_auth_context":{"type":"object"},"stripe_api_called":{"type":"boolean"},"raw_price_ids_returned":{"type":"boolean","const":false},"raw_secrets_returned":{"type":"boolean","const":false}}}}}}},"x-gravityads-tool-name":"gravityads.billing.readiness","x-gravityads-required-scope":"gravityads.admin","x-gravityads-scope-source":"hosted_entitlements"}},"/billing/subscription":{"get":{"operationId":"billing_subscription","summary":"Return hosted tenant subscription status","responses":{"200":{"description":"Redacted tenant subscription status","content":{"application/json":{"schema":{"type":"object","required":["status","tenant_id","subscription_count","subscriptions","raw_provider_ids_returned","raw_secrets_returned"],"properties":{"status":{"type":"string"},"source":{"type":"string"},"tenant_id":{"type":"string"},"subscription_count":{"type":"integer","minimum":0},"database_url_configured":{"type":"boolean"},"default_plan_id":{"type":"string"},"plan":{"type":"object"},"subscriptions":{"type":"array","items":{"type":"object","required":["id","tenant_id","plan_id","provider","status","provider_customer_id_present","provider_customer_id_hash","provider_subscription_id_present","provider_subscription_id_hash"],"properties":{"id":{"type":"string"},"tenant_id":{"type":"string"},"plan_id":{"type":"string"},"provider":{"type":"string"},"status":{"type":"string"},"currency":{"type":"string"},"current_period_start":{"type":"string"},"current_period_end":{"type":"string"},"cancel_at_period_end":{"type":"boolean"},"trial_start":{"type":"string"},"trial_end":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"provider_customer_id_present":{"type":"boolean"},"provider_customer_id_hash":{"type":"string","description":"Short SHA-256 hash prefix; raw cus_* ids are not returned."},"provider_subscription_id_present":{"type":"boolean"},"provider_subscription_id_hash":{"type":"string","description":"Short SHA-256 hash prefix; raw provider subscription ids are not returned."}}}},"raw_provider_ids_returned":{"type":"boolean","const":false},"raw_secrets_returned":{"type":"boolean","const":false}}}}}},"503":{"description":"Subscription could not be read; no plan is inferred","content":{"application/json":{"schema":{"type":"object","required":["error","error_code","message","retry_possible"],"properties":{"error":{"type":"boolean","const":true},"error_code":{"type":"string","const":"tenant_subscription_unavailable"},"message":{"type":"string"},"retry_possible":{"type":"boolean","const":true}}}}}}},"x-gravityads-tool-name":"gravityads.billing.subscription","x-gravityads-required-scope":"gravityads.admin","x-gravityads-scope-source":"hosted_entitlements"}},"/billing/usage-meter-events":{"get":{"operationId":"billing_usage_meter_events","summary":"Preview Stripe usage meter events from tenant usage rollup","responses":{"200":{"description":"Redacted usage meter event preview","content":{"application/json":{"schema":{"type":"object","required":["schema_version","status","payload_mode","preview_only","worker_send_required","send_payload_redacted","raw_customer_ids_returned","event_count","events"],"properties":{"schema_version":{"type":"string","const":"gravityads.stripe_usage_meter_events.v1"},"status":{"type":"string","enum":["stripe_usage_meter_events_ready","usage_not_metered"]},"tenant_id":{"type":"string"},"event_name":{"type":"string"},"payload_mode":{"type":"string","const":"redacted_preview"},"preview_only":{"type":"boolean","const":true},"worker_send_required":{"type":"boolean"},"stripe_customer_id_present":{"type":"boolean"},"stripe_customer_id_hash":{"type":"string"},"send_payload_redacted":{"type":"boolean","const":true},"worker_only_raw_fields":{"type":"array","items":{"type":"string"},"description":"Fields available only inside the billing worker send payload."},"event_count":{"type":"integer","minimum":0},"events":{"type":"array","items":{"type":"object","required":["event_name","identifier","payload_mode","payload","ready_to_send","send_ready_if_unredacted"],"properties":{"event_name":{"type":"string"},"identifier":{"type":"string"},"payload_mode":{"type":"string","const":"redacted_preview"},"payload":{"type":"object","required":["tenant_id","usage_date","value","stripe_customer_id_present","stripe_customer_id_hash"],"properties":{"tenant_id":{"type":"string"},"usage_date":{"type":"string","format":"date"},"value":{"type":"integer","minimum":0},"stripe_customer_id_present":{"type":"boolean"},"stripe_customer_id_hash":{"type":"string","description":"Short SHA-256 hash prefix; raw cus_* ids are not returned."},"input_tokens":{"type":"integer","minimum":0},"output_tokens":{"type":"integer","minimum":0},"cache_read_tokens":{"type":"integer","minimum":0},"cache_write_tokens":{"type":"integer","minimum":0},"estimated_cost_micros":{"type":"integer","minimum":0,"description":"Pass-through upstream cost metadata when provided."}}},"ready_to_send":{"type":"boolean","const":false},"send_ready_if_unredacted":{"type":"boolean"}}}},"stripe_api_called":{"type":"boolean","const":false},"raw_customer_ids_returned":{"type":"boolean","const":false},"raw_secrets_returned":{"type":"boolean","const":false}}}}}}},"x-gravityads-tool-name":"gravityads.billing.usage_meter_events","x-gravityads-required-scope":"gravityads.admin","x-gravityads-scope-source":"hosted_entitlements"}},"/billing/quote":{"post":{"operationId":"billing_quote","summary":"Quote versioned account capacity without charging","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["catalog_version","plan_id","account_count","billing_interval"],"properties":{"catalog_version":{"type":"string"},"plan_id":{"type":"string"},"account_count":{"type":"integer","minimum":1,"maximum":10000},"billing_interval":{"type":"string","enum":["monthly","annual"]}}}}}},"responses":{"200":{"description":"Approved server quote; no payment or entitlement mutation","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}},"x-gravityads-tool-name":"gravityads.billing.quote","x-gravityads-required-scope":"gravityads.admin","x-gravityads-scope-source":"hosted_entitlements"}},"/billing/capacity-change":{"post":{"operationId":"billing_capacity_change","summary":"Preview or explicitly confirm paid capacity increase","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["account_count"],"properties":{"account_count":{"type":"integer","minimum":1,"maximum":10000},"quote_token":{"type":"string","maxLength":4096}}}}}},"responses":{"200":{"description":"Provider invoice preview or pending payment; entitlement awaits webhook verification","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}},"x-gravityads-tool-name":"gravityads.billing.capacity.change","x-gravityads-required-scope":"gravityads.admin","x-gravityads-scope-source":"hosted_entitlements"}},"/billing/start-trial":{"post":{"operationId":"billing_start_trial","summary":"Explicitly start a cardless Pro trial for the authenticated tenant administrator","responses":{"200":{"description":"Fixed 14-day trial recorded atomically; replay does not extend expiry","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}},"x-gravityads-tool-name":"gravityads.billing.start.trial","x-gravityads-required-scope":"gravityads.admin","x-gravityads-scope-source":"hosted_entitlements"}},"/billing/checkout-session":{"post":{"operationId":"billing_checkout_session","summary":"Create Stripe Checkout subscription session","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["plan_id","success_url","cancel_url"],"additionalProperties":false,"properties":{"plan_id":{"type":"string"},"catalog_version":{"type":"string"},"account_count":{"type":"integer","minimum":1,"maximum":10000},"billing_interval":{"type":"string","enum":["monthly","annual"],"default":"monthly"},"request_key":{"type":"string","maxLength":128},"success_url":{"type":"string","format":"uri"},"cancel_url":{"type":"string","format":"uri"},"customer_id":{"type":"string"},"quantity":{"type":"integer","minimum":1,"maximum":999},"promotion_code":{"type":"string"},"allow_promotion_codes":{"type":"boolean","default":true},"metadata":{"type":"object","additionalProperties":{"type":"string"}}}}}}},"responses":{"200":{"description":"Checkout session","content":{"application/json":{"schema":{"type":"object","required":["status","raw_secrets_returned"],"additionalProperties":true,"properties":{"status":{"type":"string","enum":["stripe_checkout_session_created","stripe_checkout_setup_required","stripe_checkout_session_failed"]},"tenant_id":{"type":"string"},"plan_id":{"type":"string"},"session_id":{"type":"string"},"url":{"type":"string"},"client_secret":{"type":"string"},"mode":{"type":"string"},"payment_status":{"type":"string"},"error_code":{"type":"string"},"retry":{"type":"boolean"},"raw_secrets_returned":{"type":"boolean","const":false},"subscription":{"type":"object"},"customer_id_source":{"type":"string","enum":["request","control_plane_subscription","none"]},"hosted_auth_context":{"type":"object"},"message":{"type":"string"},"billing_setup_required":{"type":"boolean"},"self_service_checkout_ready":{"type":"boolean","const":false},"payment_collection_blocked":{"type":"boolean"},"tenant_bootstrapped":{"type":"boolean"},"internal_trial_active":{"type":"boolean"},"safe_to_continue_read_only_setup":{"type":"boolean"},"next_actions":{"type":"array","items":{"type":"object","required":["id","status"],"additionalProperties":true,"properties":{"id":{"type":"string"},"status":{"type":"string"},"owner":{"type":"string"},"path":{"type":"string"},"requires":{"type":"array","items":{"type":"string"}},"url_present":{"type":"boolean"},"session_id":{"type":"string"}}}},"raw_price_ids_returned":{"type":"boolean","const":false}}}}}},"503":{"description":"Checkout setup required or Stripe unavailable","content":{"application/json":{"schema":{"type":"object","required":["status","raw_secrets_returned"],"additionalProperties":true,"properties":{"status":{"type":"string","enum":["stripe_checkout_session_created","stripe_checkout_setup_required","stripe_checkout_session_failed"]},"tenant_id":{"type":"string"},"plan_id":{"type":"string"},"session_id":{"type":"string"},"url":{"type":"string"},"client_secret":{"type":"string"},"mode":{"type":"string"},"payment_status":{"type":"string"},"error_code":{"type":"string"},"retry":{"type":"boolean"},"raw_secrets_returned":{"type":"boolean","const":false},"subscription":{"type":"object"},"customer_id_source":{"type":"string","enum":["request","control_plane_subscription","none"]},"hosted_auth_context":{"type":"object"},"message":{"type":"string"},"billing_setup_required":{"type":"boolean"},"self_service_checkout_ready":{"type":"boolean","const":false},"payment_collection_blocked":{"type":"boolean"},"tenant_bootstrapped":{"type":"boolean"},"internal_trial_active":{"type":"boolean"},"safe_to_continue_read_only_setup":{"type":"boolean"},"next_actions":{"type":"array","items":{"type":"object","required":["id","status"],"additionalProperties":true,"properties":{"id":{"type":"string"},"status":{"type":"string"},"owner":{"type":"string"},"path":{"type":"string"},"requires":{"type":"array","items":{"type":"string"}},"url_present":{"type":"boolean"},"session_id":{"type":"string"}}}},"raw_price_ids_returned":{"type":"boolean","const":false}}}}}}},"x-gravityads-tool-name":"gravityads.billing.checkout.session","x-gravityads-required-scope":"gravityads.admin","x-gravityads-scope-source":"hosted_entitlements"}},"/billing/customer-portal-session":{"post":{"operationId":"billing_customer_portal_session","summary":"Create Stripe Customer Portal session","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["return_url"],"additionalProperties":false,"properties":{"return_url":{"type":"string","format":"uri"},"customer_id":{"type":"string"},"configuration_id":{"type":"string"}}}}}},"responses":{"200":{"description":"Customer portal session","content":{"application/json":{"schema":{"type":"object","required":["status","raw_secrets_returned"],"additionalProperties":true,"properties":{"status":{"type":"string","enum":["stripe_customer_portal_session_created","customer_portal_session_failed"]},"tenant_id":{"type":"string"},"session_id":{"type":"string"},"url":{"type":"string"},"subscription":{"type":"object"},"hosted_auth_context":{"type":"object"},"error_code":{"type":"string"},"message":{"type":"string"},"retry":{"type":"boolean"},"billing_setup_required":{"type":"boolean"},"customer_portal_ready":{"type":"boolean","const":false},"customer_portal_blocked":{"type":"boolean"},"stripe_customer_present":{"type":"boolean"},"safe_to_manage_billing":{"type":"boolean","const":false},"next_actions":{"type":"array","items":{"type":"object","required":["id","status"],"additionalProperties":true,"properties":{"id":{"type":"string"},"status":{"type":"string"},"owner":{"type":"string"},"path":{"type":"string"},"requires":{"type":"array","items":{"type":"string"}},"url_present":{"type":"boolean"},"session_id":{"type":"string"}}}},"raw_provider_ids_returned":{"type":"boolean","const":false},"raw_secrets_returned":{"type":"boolean","const":false}}}}}},"400":{"description":"Customer portal setup or request issue","content":{"application/json":{"schema":{"type":"object","required":["status","raw_secrets_returned"],"additionalProperties":true,"properties":{"status":{"type":"string","enum":["stripe_customer_portal_session_created","customer_portal_session_failed"]},"tenant_id":{"type":"string"},"session_id":{"type":"string"},"url":{"type":"string"},"subscription":{"type":"object"},"hosted_auth_context":{"type":"object"},"error_code":{"type":"string"},"message":{"type":"string"},"retry":{"type":"boolean"},"billing_setup_required":{"type":"boolean"},"customer_portal_ready":{"type":"boolean","const":false},"customer_portal_blocked":{"type":"boolean"},"stripe_customer_present":{"type":"boolean"},"safe_to_manage_billing":{"type":"boolean","const":false},"next_actions":{"type":"array","items":{"type":"object","required":["id","status"],"additionalProperties":true,"properties":{"id":{"type":"string"},"status":{"type":"string"},"owner":{"type":"string"},"path":{"type":"string"},"requires":{"type":"array","items":{"type":"string"}},"url_present":{"type":"boolean"},"session_id":{"type":"string"}}}},"raw_provider_ids_returned":{"type":"boolean","const":false},"raw_secrets_returned":{"type":"boolean","const":false}}}}}},"503":{"description":"Stripe customer portal unavailable","content":{"application/json":{"schema":{"type":"object","required":["status","raw_secrets_returned"],"additionalProperties":true,"properties":{"status":{"type":"string","enum":["stripe_customer_portal_session_created","customer_portal_session_failed"]},"tenant_id":{"type":"string"},"session_id":{"type":"string"},"url":{"type":"string"},"subscription":{"type":"object"},"hosted_auth_context":{"type":"object"},"error_code":{"type":"string"},"message":{"type":"string"},"retry":{"type":"boolean"},"billing_setup_required":{"type":"boolean"},"customer_portal_ready":{"type":"boolean","const":false},"customer_portal_blocked":{"type":"boolean"},"stripe_customer_present":{"type":"boolean"},"safe_to_manage_billing":{"type":"boolean","const":false},"next_actions":{"type":"array","items":{"type":"object","required":["id","status"],"additionalProperties":true,"properties":{"id":{"type":"string"},"status":{"type":"string"},"owner":{"type":"string"},"path":{"type":"string"},"requires":{"type":"array","items":{"type":"string"}},"url_present":{"type":"boolean"},"session_id":{"type":"string"}}}},"raw_provider_ids_returned":{"type":"boolean","const":false},"raw_secrets_returned":{"type":"boolean","const":false}}}}}}},"x-gravityads-tool-name":"gravityads.billing.customer.portal.session","x-gravityads-required-scope":"gravityads.admin","x-gravityads-scope-source":"hosted_entitlements"}},"/connections/{connection_id}/validate":{"get":{"operationId":"connection_validate","summary":"Validate hosted connection metadata and optional token health","parameters":[{"name":"include_token_health","in":"query","required":false,"schema":{"type":"boolean"},"description":"When true, attempts a redacted provider token health check if the token vault runtime is ready."}],"responses":{"200":{"description":"Connection validation","content":{"application/json":{"schema":{"type":"object","required":["status","tenant_id","connection_id","exists","database_url_configured","raw_secrets_returned"],"additionalProperties":true,"properties":{"status":{"type":"string","enum":["connection_validation_ready","connection_validation_not_found","connection_validation_unconfigured","connection_validation_degraded"]},"source":{"type":"string"},"tenant_id":{"type":"string"},"connection_id":{"type":"string"},"exists":{"type":"boolean"},"connection":{"type":"object"},"secret_vault_readiness":{"type":"object"},"token_runtime_readiness":{"type":"object"},"provider_token_health":{"type":"object","additionalProperties":true,"properties":{"schema_version":{"type":"string"},"status":{"type":"string"},"provider_api_called":{"type":"boolean"},"provider_result":{"type":"object","additionalProperties":true,"properties":{"ready_for_controlled_write":{"type":"boolean"},"controlled_write_scope_count":{"type":"integer","minimum":0},"missing_controlled_write_scope_count":{"type":"integer","minimum":0}}},"raw_secrets_returned":{"type":"boolean","const":false}}},"platform_account_count":{"type":"integer","minimum":0},"platform_accounts":{"type":"array","items":{"type":"object"}},"ready_for_readonly_etl":{"type":"boolean"},"validation_mode":{"type":"string"},"database_url_configured":{"type":"boolean"},"hosted_auth_context":{"type":"object"},"raw_secrets_returned":{"type":"boolean","const":false}}}}}}},"x-gravityads-tool-name":"gravityads.connection.validate","x-gravityads-required-scope":"gravityads.admin","x-gravityads-scope-source":"hosted_entitlements"}},"/connections/{connection_id}/onboarding-status":{"get":{"operationId":"connection_onboarding_status","summary":"Summarize hosted connection onboarding steps for Portal","responses":{"200":{"description":"Connection onboarding status","content":{"application/json":{"schema":{"type":"object","required":["schema_version","status","tenant_id","connection_id","exists","phase_contract","ready_for_readonly_etl","ready_for_day1_backfill","steps","next_actions","endpoints","provider_api_called","raw_account_ids_returned","raw_token_material_returned","raw_secrets_returned"],"properties":{"schema_version":{"type":"string"},"status":{"type":"string"},"tenant_id":{"type":"string"},"connection_id":{"type":"string"},"exists":{"type":"boolean"},"platform":{"type":"string"},"connection":{"type":"object"},"phase_contract":{"type":"string"},"database_url_configured":{"type":"boolean"},"ready_for_readonly_etl":{"type":"boolean"},"ready_for_day1_backfill":{"type":"boolean"},"first_sync_completed":{"type":"boolean"},"platform_account_count":{"type":"integer","minimum":0},"synced_platform_account_count":{"type":"integer","minimum":0},"freshness_status":{"type":"string"},"latest_metric_date":{"type":"string"},"missing_scopes":{"type":"array","items":{"type":"string"}},"steps":{"type":"object"},"next_actions":{"type":"array","items":{"type":"object"}},"endpoints":{"type":"object"},"provider_api_called":{"type":"boolean","const":false},"raw_account_ids_returned":{"type":"boolean","const":false},"raw_token_material_returned":{"type":"boolean","const":false},"raw_secrets_returned":{"type":"boolean","const":false}}}}}}},"x-gravityads-tool-name":"gravityads.connection.onboarding.status","x-gravityads-required-scope":"gravityads.admin","x-gravityads-scope-source":"hosted_entitlements"}},"/connections/{connection_id}/disconnect":{"post":{"operationId":"connection_disconnect","summary":"Disconnect a hosted connection and optionally revoke provider token","requestBody":{"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["confirmation"],"properties":{"confirmation":{"type":"string","const":"disconnect connection","description":"Required guardrail for disconnecting a stored OAuth connection."},"reason":{"type":"string"},"revoke_provider_token":{"type":"boolean","description":"When true, attempts a redacted provider token revoke before marking the connection disconnected."}}}}}},"responses":{"200":{"description":"Connection disconnect result","content":{"application/json":{"schema":{"type":"object","required":["status","tenant_id","connection_id","disconnected_count","database_url_configured","provider_token_revoke","platform_revoke_called","raw_secrets_returned"],"additionalProperties":true,"properties":{"status":{"type":"string","enum":["connection_disconnected","connection_disconnect_not_found","connection_disconnect_unconfigured","connection_disconnect_degraded"]},"source":{"type":"string"},"tenant_id":{"type":"string"},"connection_id":{"type":"string"},"disconnected_count":{"type":"integer","minimum":0},"database_url_configured":{"type":"boolean"},"provider_token_revoke":{"type":"object","additionalProperties":true,"properties":{"schema_version":{"type":"string"},"status":{"type":"string"},"provider_api_called":{"type":"boolean"},"raw_secrets_returned":{"type":"boolean","const":false}}},"platform_revoke_called":{"type":"boolean"},"hosted_auth_context":{"type":"object"},"raw_secrets_returned":{"type":"boolean","const":false}}}}}}},"x-gravityads-tool-name":"gravityads.connection.disconnect","x-gravityads-required-scope":"gravityads.admin","x-gravityads-scope-source":"hosted_entitlements"}},"/connections/{connection_id}/accounts":{"get":{"operationId":"connection_accounts","summary":"List hosted platform accounts for a connection","responses":{"200":{"description":"Connection accounts","content":{"application/json":{"schema":{"type":"object","required":["status","tenant_id","connection_id","platform_account_count","platform_accounts","raw_secrets_returned"],"additionalProperties":true,"properties":{"status":{"type":"string","enum":["connection_accounts_ready","connection_accounts_not_found","connection_accounts_unconfigured","connection_accounts_degraded"]},"tenant_id":{"type":"string"},"connection_id":{"type":"string"},"connection":{"type":"object"},"platform_account_count":{"type":"integer","minimum":0},"platform_accounts":{"type":"array","items":{"type":"object"}},"plan_account_limit":{"type":"object"},"database_url_configured":{"type":"boolean"},"discovery_source":{"type":"string"},"hosted_auth_context":{"type":"object"},"raw_secrets_returned":{"type":"boolean","const":false}}}}}},"404":{"description":"Connection not found","content":{"application/json":{"schema":{"type":"object","required":["status","tenant_id","connection_id","platform_account_count","platform_accounts","raw_secrets_returned"],"additionalProperties":true,"properties":{"status":{"type":"string","enum":["connection_accounts_ready","connection_accounts_not_found","connection_accounts_unconfigured","connection_accounts_degraded"]},"tenant_id":{"type":"string"},"connection_id":{"type":"string"},"connection":{"type":"object"},"platform_account_count":{"type":"integer","minimum":0},"platform_accounts":{"type":"array","items":{"type":"object"}},"plan_account_limit":{"type":"object"},"database_url_configured":{"type":"boolean"},"discovery_source":{"type":"string"},"hosted_auth_context":{"type":"object"},"raw_secrets_returned":{"type":"boolean","const":false}}}}}}},"x-gravityads-tool-name":"gravityads.connection.accounts","x-gravityads-required-scope":"gravityads.admin","x-gravityads-scope-source":"hosted_entitlements"},"post":{"operationId":"connection_accounts_upsert","summary":"Upsert discovered platform accounts for a connection","requestBody":{"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"customer_group_id":{"type":"string"},"accounts":{"type":"array","items":{"type":"object","required":["account_id"],"additionalProperties":false,"properties":{"id":{"type":"string"},"customer_group_id":{"type":"string"},"customer_name":{"type":"string"},"platform":{"type":"string","enum":["google","meta","microsoft","bing","tiktok","criteo","media_go","pinterest","linkedin","amazon"]},"account_id":{"type":"string"},"account_number":{"type":"string"},"account_name":{"type":"string"},"manager_account_id":{"type":"string"},"account_type":{"type":"string","enum":["client","manager","unknown"]},"billing_transfer_status":{"type":"string"},"status":{"type":"string"},"latest_metric_date":{"type":"string"},"latest_etl_run_id":{"type":"string"},"provider_account_status":{"type":"string"},"provider_account_status_raw":{"type":"string"},"provider_account_status_reason":{"type":"string"},"provider_account_status_checked_at":{"type":"string"}}},"maxItems":200},"provider_accounts":{"type":"array","items":{"type":"object"},"maxItems":200,"description":"Raw provider account discovery records from a supported ad platform. They are normalized server-side before control-plane upsert."},"queue_day1_backfill":{"type":"boolean","description":"When true, queues readonly day-1 ETL runs immediately after the discovered accounts are upserted."},"backfill_date_range_start":{"type":"string","format":"date"},"backfill_date_range_end":{"type":"string","format":"date"},"backfill_run_type":{"type":"string","default":"day1_backfill"}}}}}},"responses":{"200":{"description":"Connection accounts upserted","content":{"application/json":{"schema":{"type":"object","required":["status","tenant_id","connection_id","raw_secrets_returned"],"additionalProperties":true,"properties":{"status":{"type":"string","enum":["connection_accounts_upserted","connection_accounts_upsert_unconfigured","connection_accounts_upsert_failed","connection_accounts_upsert_degraded"]},"tenant_id":{"type":"string"},"connection_id":{"type":"string"},"platform_account_count":{"type":"integer","minimum":0},"platform_accounts":{"type":"array","items":{"type":"object"}},"customer_group_count":{"type":"integer","minimum":0},"account_scope_count":{"type":"integer","minimum":0},"day1_backfill":{"type":"object"},"provider_accounts_normalized":{"type":"boolean"},"database_url_configured":{"type":"boolean"},"hosted_auth_context":{"type":"object"},"raw_secrets_returned":{"type":"boolean","const":false}}}}}}},"x-gravityads-tool-name":"gravityads.connection.accounts.upsert","x-gravityads-required-scope":"gravityads.admin","x-gravityads-scope-source":"hosted_entitlements"}},"/connections/{connection_id}/backfill":{"post":{"operationId":"connection_backfill","summary":"Queue hosted readonly ETL backfill for a connection","requestBody":{"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"date_range_start":{"type":"string","format":"date"},"date_range_end":{"type":"string","format":"date"},"run_type":{"type":"string","default":"day1_backfill"}}}}}},"responses":{"200":{"description":"Connection backfill queued","content":{"application/json":{"schema":{"type":"object","required":["status","tenant_id","connection_id","queued_count","runs","database_url_configured","worker_started","raw_secrets_returned"],"additionalProperties":true,"properties":{"status":{"type":"string","enum":["connection_backfill_queued","connection_backfill_not_found","connection_backfill_no_accounts","connection_backfill_not_ready","connection_backfill_unconfigured","connection_backfill_degraded"]},"tenant_id":{"type":"string"},"connection_id":{"type":"string"},"queued_count":{"type":"integer","minimum":0},"runs":{"type":"array","items":{"type":"object"}},"database_url_configured":{"type":"boolean"},"worker_started":{"type":"boolean"},"ready_for_readonly_etl":{"type":"boolean"},"hosted_auth_context":{"type":"object"},"raw_secrets_returned":{"type":"boolean","const":false}}}}}}},"x-gravityads-tool-name":"gravityads.connection.backfill","x-gravityads-required-scope":"gravityads.admin","x-gravityads-scope-source":"hosted_entitlements"}},"/tool-catalog":{"get":{"operationId":"tool_catalog","summary":"List GravityAds tool profiles","responses":{"200":{"description":"Tool catalog","content":{"application/json":{"schema":{"type":"object","required":["status","model_bindings","profiles","resource_templates"],"additionalProperties":true,"properties":{"status":{"type":"string","const":"tool_catalog_ready"},"ai_usage_cn":{"type":"array","items":{"type":"string"}},"model_bindings":{"type":"object"},"recommended_prompts_cn":{"type":"array","items":{"type":"string"}},"resource_templates":{"type":"array","items":{"type":"object"}},"profiles":{"type":"array","items":{"type":"object"}},"legacy_component_profiles":{"type":"array","items":{"type":"object"}}}}}}}},"x-gravityads-tool-name":"gravityads.tool.catalog","x-gravityads-required-scope":"gravityads.read","x-gravityads-scope-source":"hosted_entitlements"}},"/account-scope":{"post":{"operationId":"account_scope","summary":"Resolve optimizer account scope","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"operator_id":{"type":"string"},"customer_name":{"type":"string"},"platform":{"type":"string"},"account_id":{"type":"string"}}}}}},"responses":{"200":{"description":"Account scope","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}},"x-gravityads-tool-name":"gravityads.account.scope","x-gravityads-required-scope":"gravityads.read","x-gravityads-scope-source":"hosted_entitlements"}},"/account-overview":{"post":{"operationId":"account_overview","summary":"Get account and data-plane overview","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"operator_id":{"type":"string"},"customer_name":{"type":"string"},"platform":{"type":"string"},"account_id":{"type":"string"}}}}}},"responses":{"200":{"description":"Account overview","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}},"x-gravityads-tool-name":"gravityads.account.overview","x-gravityads-required-scope":"gravityads.read","x-gravityads-scope-source":"hosted_entitlements"}},"/workbench-context":{"post":{"operationId":"workbench_context","summary":"Build Ads Quant Workbench copilot context","description":"Read-only bridge for Ads Quant Workbench to pass the selected customer/account/candidate/action context into GravityMind AI without bypassing account scope.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"operator_id":{"type":"string"},"customer_name":{"type":"string"},"platform":{"type":"string"},"account_id":{"type":"string"},"candidate_id":{"type":"string"},"action_id":{"type":"string"},"limit":{"type":"integer","default":20}}}}}},"responses":{"200":{"description":"Workbench context","content":{"application/json":{"schema":{"type":"object","required":["status","operator_id","account_scope","candidate_count","candidates","copilot_context","hosted_auth_context","writes_platform"],"additionalProperties":true,"properties":{"status":{"type":"string","const":"workbench_context_ready"},"operator_id":{"type":"string"},"customer_name":{"type":"string"},"platform":{"type":"string"},"account_id":{"type":"string"},"candidate_id":{"type":"string"},"action_id":{"type":"string"},"account_scope":{"type":"object","additionalProperties":true},"candidate_count":{"type":"integer","minimum":0},"candidate_count_meaning":{"type":"object","additionalProperties":true},"candidates":{"type":"array","items":{"type":"object","additionalProperties":true}},"copilot_context":{"type":"object","additionalProperties":true},"hosted_auth_context":{"type":"object","additionalProperties":true},"writes_platform":{"type":"boolean","const":false}}}}}}},"x-gravityads-tool-name":"gravityads.workbench.context","x-gravityads-required-scope":"gravityads.read","x-gravityads-scope-source":"hosted_entitlements"}},"/decision-context":{"post":{"operationId":"decision_context","summary":"Get daily decision context","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"limit":{"type":"integer","default":5},"operator_id":{"type":"string"}}}}}},"responses":{"200":{"description":"Decision context","content":{"application/json":{"schema":{"type":"object","required":["schema_version","status","requested_limit","summary","cross_platform_decision_candidates","candidate_preflight_previews","hosted_auth_context"],"additionalProperties":true,"properties":{"schema_version":{"type":"string","const":"ads_quant.agent_decision_context_api.v1"},"status":{"type":"string","const":"agent_decision_context_ready"},"operator_id":{"type":"string"},"requested_limit":{"type":"integer","minimum":0},"summary":{"type":"object","additionalProperties":true},"platform_ai_input_focus":{"type":"object","additionalProperties":true},"cross_platform_decision_candidates":{"type":"array","items":{"type":"object","additionalProperties":true}},"candidate_preflight_previews":{"type":"array","items":{"type":"object","additionalProperties":true}},"hosted_auth_context":{"type":"object","additionalProperties":true}}}}}}},"x-gravityads-tool-name":"gravityads.decision.context","x-gravityads-required-scope":"gravityads.read","x-gravityads-scope-source":"hosted_entitlements"}},"/customer-metric-summary":{"post":{"operationId":"customer_metric_summary","summary":"Summarize customer/account spend metrics","description":"Read-only spend, impressions, clicks, conversions, revenue and derived rates from the serving warehouse. Use for questions about recent spend/performance. candidate_count=0 from candidate tools never proves metric data is absent.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"operator_id":{"type":"string"},"customer_name":{"type":"string"},"platform":{"type":"string"},"account_id":{"type":"string"},"start_date":{"type":"string","description":"YYYY-MM-DD"},"end_date":{"type":"string","description":"YYYY-MM-DD"},"days":{"type":"integer","default":7},"source_policy":{"type":"string","enum":["auto","warehouse_only"],"default":"auto","description":"warehouse_only never calls platform APIs, including on empty data or warehouse errors."},"granularity":{"type":"string","enum":["auto","account","campaign"],"default":"auto"},"limit":{"type":"integer","default":30}}}}}},"responses":{"200":{"description":"Customer metric summary","content":{"application/json":{"schema":{"type":"object","required":["schema_version","status","summary","date_window","account_summaries","daily_totals","request","hosted_auth_context"],"additionalProperties":true,"properties":{"schema_version":{"type":"string","const":"ads_quant.customer_metric_summary.v1"},"status":{"type":"string","const":"customer_metric_summary_ready"},"operator_id":{"type":"string"},"summary":{"type":"object","additionalProperties":true},"date_window":{"type":"object","additionalProperties":true},"account_summaries":{"type":"array","items":{"type":"object","additionalProperties":true}},"daily_totals":{"type":"array","items":{"type":"object","additionalProperties":true}},"request":{"type":"object","additionalProperties":true},"data_source_policy":{"type":"object","additionalProperties":true},"query_interpretation":{"type":"object","additionalProperties":true},"answer_contract":{"type":"object","additionalProperties":true},"candidate_metric_guard_cn":{"type":"string"},"hosted_auth_context":{"type":"object","additionalProperties":true}}}}}}},"x-gravityads-tool-name":"gravityads.metrics.summary","x-gravityads-required-scope":"gravityads.read","x-gravityads-scope-source":"hosted_entitlements"}},"/optimizer-daily-brief":{"post":{"operationId":"optimizer_daily_brief","summary":"Generate optimizer daily brief and plan","description":"Returns a localized customer-first daily brief for the current optimizer scope. Supports locale en/zh/ja. Read-only; does not create drafts or write ad platforms.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"operator_id":{"type":"string"},"report_date":{"type":"string","description":"YYYY-MM-DD"},"report_options":{"type":"object","additionalProperties":false,"properties":{"timezone":{"type":"string","description":"IANA timezone used to close calendar windows; metric dates retain provider timezone semantics."},"aggregation_method":{"type":"string","enum":["daily_arithmetic_mean","pooled_ratio"]},"baseline_includes_target":{"type":"boolean","default":false},"period_kind":{"type":"string","enum":["natural_week","custom_period"]}}},"report_thresholds":{"type":"object","additionalProperties":{"type":"number"}},"date":{"type":"string","description":"Alias of report_date"},"customer_name":{"type":"string"},"limit":{"type":"integer","default":8},"locale":{"type":"string","enum":["en","zh","ja"],"default":"zh","description":"Human-facing output locale."}}}}}},"responses":{"200":{"description":"Optimizer daily brief","content":{"application/json":{"schema":{"type":"object","required":["schema_version","status","report_type","summary","summary_cn","summary_text","customer_sections","top_candidates","hosted_auth_context"],"additionalProperties":true,"properties":{"schema_version":{"type":"string","const":"gravityads.optimizer_daily_brief.v2"},"status":{"type":"string","const":"optimizer_daily_brief_ready"},"report_type":{"type":"string"},"operator_id":{"type":"string"},"report_date":{"type":"string"},"language":{"type":"string"},"requested_locale":{"type":"string"},"supported_locales":{"type":"array","items":{"type":"string"}},"generated_at_utc":{"type":"string"},"summary":{"type":"object","additionalProperties":true},"summary_cn":{"type":"string"},"summary_text":{"type":"string"},"localized":{"type":"object","additionalProperties":true},"recommended_prompts":{"type":"array","items":{"type":"string"}},"performance_overview":{"type":"object","additionalProperties":true},"optimization_suggestions":{"type":"array","items":{"type":"object","additionalProperties":true}},"customer_sections":{"type":"array","items":{"type":"object","additionalProperties":true}},"top_candidates":{"type":"array","items":{"type":"object","additionalProperties":true}},"feedback_tasks":{"type":"object","additionalProperties":true},"data_window":{"type":"object","additionalProperties":true},"todays_plan_cn":{"type":"array","items":{"type":"string"}},"attention_items_cn":{"type":"array","items":{"type":"string"}},"risks_and_checks_cn":{"type":"array","items":{"type":"string"}},"hosted_auth_context":{"type":"object","additionalProperties":true}}}}}}},"x-gravityads-tool-name":"gravityads.optimizer_daily_brief","x-gravityads-required-scope":"gravityads.read","x-gravityads-scope-source":"hosted_entitlements"}},"/optimizer-weekly-plan":{"post":{"operationId":"optimizer_weekly_plan","summary":"Generate optimizer weekly review and plan","description":"Returns a localized customer-first weekly review and next week plan for the current optimizer scope. Supports locale en/zh/ja. Read-only; does not create drafts or write ad platforms.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"operator_id":{"type":"string"},"week_start":{"type":"string","description":"YYYY-MM-DD"},"report_options":{"type":"object","additionalProperties":false,"properties":{"timezone":{"type":"string","description":"IANA timezone used to close calendar windows; metric dates retain provider timezone semantics."},"aggregation_method":{"type":"string","enum":["daily_arithmetic_mean","pooled_ratio"]},"baseline_includes_target":{"type":"boolean","default":false},"period_kind":{"type":"string","enum":["natural_week","custom_period"]}}},"report_thresholds":{"type":"object","additionalProperties":{"type":"number"}},"week_end":{"type":"string","description":"YYYY-MM-DD"},"customer_name":{"type":"string"},"limit":{"type":"integer","default":10},"locale":{"type":"string","enum":["en","zh","ja"],"default":"zh","description":"Human-facing output locale."}}}}}},"responses":{"200":{"description":"Optimizer weekly plan","content":{"application/json":{"schema":{"type":"object","required":["schema_version","status","report_type","summary","weekly_review_cn","summary_text","next_week_plan_cn","customer_sections","top_candidates","hosted_auth_context"],"additionalProperties":true,"properties":{"schema_version":{"type":"string","const":"gravityads.optimizer_weekly_plan.v1"},"status":{"type":"string","const":"optimizer_weekly_plan_ready"},"report_type":{"type":"string"},"operator_id":{"type":"string"},"week_window":{"type":"object","additionalProperties":true},"language":{"type":"string"},"requested_locale":{"type":"string"},"supported_locales":{"type":"array","items":{"type":"string"}},"generated_at_utc":{"type":"string"},"summary":{"type":"object","additionalProperties":true},"summary_text":{"type":"string"},"localized":{"type":"object","additionalProperties":true},"recommended_prompts":{"type":"array","items":{"type":"string"}},"performance_overview":{"type":"object","additionalProperties":true},"weekly_review_cn":{"type":"array","items":{"type":"string"}},"next_week_plan_cn":{"type":"array","items":{"type":"string"}},"customer_sections":{"type":"array","items":{"type":"object","additionalProperties":true}},"top_candidates":{"type":"array","items":{"type":"object","additionalProperties":true}},"feedback_tasks":{"type":"object","additionalProperties":true},"data_window":{"type":"object","additionalProperties":true},"risks_and_checks_cn":{"type":"array","items":{"type":"string"}},"hosted_auth_context":{"type":"object","additionalProperties":true}}}}}}},"x-gravityads-tool-name":"gravityads.optimizer_weekly_plan","x-gravityads-required-scope":"gravityads.read","x-gravityads-scope-source":"hosted_entitlements"}},"/sota-action-input-queue":{"post":{"operationId":"sota_action_input_queue","summary":"Get review-only SOTA draft input queue","description":"Returns next C1 readout, experiment/lift, outcome, and action reward inputs. Read-only; does not create drafts or write ad platforms.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"limit":{"type":"integer","default":5},"operator_id":{"type":"string"}}}}}},"responses":{"200":{"description":"SOTA input queue","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}},"x-gravityads-tool-name":"gravityads.sota.action.input.queue","x-gravityads-required-scope":"gravityads.read","x-gravityads-scope-source":"hosted_entitlements"}},"/candidate-search":{"post":{"operationId":"candidate_search","summary":"Search decision candidates","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string"},"customer_name":{"type":"string"},"platform":{"type":"string"},"account_id":{"type":"string"},"operator_id":{"type":"string"},"limit":{"type":"integer","default":10}}}}}},"responses":{"200":{"description":"Candidate search","content":{"application/json":{"schema":{"type":"object","required":["status","operator_id","match_count","candidates","hosted_auth_context"],"additionalProperties":true,"properties":{"status":{"type":"string","const":"candidate_search_ready"},"operator_id":{"type":"string"},"customer_name":{"type":"string"},"query":{"type":"string"},"platform":{"type":"string"},"account_id":{"type":"string"},"account_scope_filter_count":{"type":"integer","minimum":0},"match_count":{"type":"integer","minimum":0},"candidates":{"type":"array","items":{"type":"object","additionalProperties":true}},"hosted_auth_context":{"type":"object","additionalProperties":true}}}}}}},"x-gravityads-tool-name":"gravityads.candidate.search","x-gravityads-required-scope":"gravityads.read","x-gravityads-scope-source":"hosted_entitlements"}},"/candidate-explain":{"post":{"operationId":"candidate_explain","summary":"Explain one candidate through preflight context","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"candidate_id":{"type":"string"},"operator_id":{"type":"string"}},"required":["candidate_id"]}}}},"responses":{"200":{"description":"Candidate explanation","content":{"application/json":{"schema":{"type":"object","required":["schema_version","status","candidate_id","candidate","preflight_preview","draft_created","hosted_auth_context"],"additionalProperties":true,"properties":{"schema_version":{"type":"string","const":"ads_quant.cross_platform_candidate_preflight_api.v1"},"status":{"type":"string","const":"candidate_preflight_preview_created"},"operator_id":{"type":"string"},"candidate_id":{"type":"string"},"candidate":{"type":"object","additionalProperties":true},"action_packet":{"type":"object","additionalProperties":true},"network_prior":{"type":"object","additionalProperties":true},"preflight_preview":{"type":"object","additionalProperties":true},"promotion_gate":{"type":"object","additionalProperties":true},"draft_created":{"type":"boolean","const":false},"hosted_auth_context":{"type":"object","additionalProperties":true}}}}}}},"x-gravityads-tool-name":"gravityads.candidate.explain","x-gravityads-required-scope":"gravityads.read","x-gravityads-scope-source":"hosted_entitlements"}},"/candidate-preflight":{"post":{"operationId":"candidate_preflight","summary":"Preview candidate preflight","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"candidate_id":{"type":"string"},"operator_id":{"type":"string"}},"required":["candidate_id"]}}}},"responses":{"200":{"description":"Candidate preflight","content":{"application/json":{"schema":{"type":"object","required":["schema_version","status","candidate_id","candidate","preflight_preview","draft_created","hosted_auth_context"],"additionalProperties":true,"properties":{"schema_version":{"type":"string","const":"ads_quant.cross_platform_candidate_preflight_api.v1"},"status":{"type":"string","const":"candidate_preflight_preview_created"},"operator_id":{"type":"string"},"candidate_id":{"type":"string"},"candidate":{"type":"object","additionalProperties":true},"action_packet":{"type":"object","additionalProperties":true},"network_prior":{"type":"object","additionalProperties":true},"preflight_preview":{"type":"object","additionalProperties":true},"promotion_gate":{"type":"object","additionalProperties":true},"draft_created":{"type":"boolean","const":false},"hosted_auth_context":{"type":"object","additionalProperties":true}}}}}}},"x-gravityads-tool-name":"gravityads.candidate_preflight","x-gravityads-required-scope":"gravityads.read","x-gravityads-scope-source":"hosted_entitlements"}},"/benchmark-compare":{"post":{"operationId":"benchmark_compare","summary":"Compare benchmark cohort","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"metric":{"type":"string","default":"roas"},"platform":{"type":"string","default":"all"},"cohort_type":{"type":"string","default":"platform"},"industry_key":{"type":"string","default":"unknown"},"business_type":{"type":"string","default":"unknown"}}}}}},"responses":{"200":{"description":"Benchmark comparison","content":{"application/json":{"schema":{"type":"object","required":["schema_version","status","metric","cohorts","privacy_guard","raw_customer_data_returned","raw_account_ids_returned","raw_secrets_returned","hosted_auth_context"],"additionalProperties":true,"properties":{"schema_version":{"type":"string","const":"ads_quant.network_benchmark_compare.v1"},"status":{"type":"string"},"source_status":{"type":"string"},"metric":{"type":"string"},"request":{"type":"object","additionalProperties":true},"cohorts":{"type":"array","items":{"type":"object","additionalProperties":true}},"privacy_guard":{"type":"object","additionalProperties":true},"raw_customer_data_returned":{"type":"boolean","const":false},"raw_account_ids_returned":{"type":"boolean","const":false},"raw_secrets_returned":{"type":"boolean","const":false},"hosted_auth_context":{"type":"object","additionalProperties":true}}}}}}},"x-gravityads-tool-name":"gravityads.benchmark.compare","x-gravityads-required-scope":"gravityads.read","x-gravityads-scope-source":"hosted_entitlements"}},"/landing-page-snapshot":{"post":{"operationId":"landing_page_snapshot","summary":"Fetch and summarize a public landing page","description":"Read-only public HTTP/HTTPS landing page fetch with SSRF guards. Extracts title, meta description, headings, CTA text and visible HTML text for product/advantage analysis. It does not execute browser JavaScript or access private network addresses.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","description":"公开 http/https 落地页 URL；不允许内网、localhost 或带凭据 URL。"},"operator_id":{"type":"string"},"analysis_goal":{"type":"string","description":"例如：分析产品、卖点、竞品线索、转化阻力。"},"max_bytes":{"type":"integer","default":160000,"description":"最多抓取页面字节数，服务端会强制上限。"},"max_text_chars":{"type":"integer","default":5000,"description":"返回给 LLM 的正文摘要字符上限。"},"timeout_seconds":{"type":"integer","default":12,"description":"抓取超时时间，服务端会强制上限。"}},"required":["url"]}}}},"responses":{"200":{"description":"Landing page snapshot","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}},"x-gravityads-tool-name":"gravityads.landing.page.snapshot","x-gravityads-required-scope":"gravityads.read","x-gravityads-scope-source":"hosted_entitlements"}},"/data-freshness-check":{"get":{"operationId":"data_freshness_check","summary":"Check data freshness and source readiness","responses":{"200":{"description":"Data freshness","content":{"application/json":{"schema":{"type":"object","required":["snapshot_id","platforms","hosted_auth_context"],"additionalProperties":true,"properties":{"snapshot_id":{"type":"string"},"status":{"type":"string"},"platforms":{"type":"object","additionalProperties":{"type":"object","additionalProperties":true}},"hosted_auth_context":{"type":"object","additionalProperties":true}}}}}}},"x-gravityads-tool-name":"gravityads.data_freshness","x-gravityads-required-scope":"gravityads.read","x-gravityads-scope-source":"hosted_entitlements"}},"/business-context":{"get":{"operationId":"business_context_get","summary":"Get business context coverage","responses":{"200":{"description":"Business context","content":{"application/json":{"schema":{"type":"object","required":["schema_version","status","summary","coverage_by_scope","hosted_auth_context"],"additionalProperties":true,"properties":{"schema_version":{"type":"string","const":"ads_quant.business_context_readiness.v1"},"status":{"type":"string","const":"business_context_ready"},"summary":{"type":"object","additionalProperties":true},"coverage_by_scope":{"type":"array","items":{"type":"object","additionalProperties":true}},"hosted_auth_context":{"type":"object","additionalProperties":true}}}}}}},"x-gravityads-tool-name":"gravityads.business.context.get","x-gravityads-required-scope":"gravityads.read","x-gravityads-scope-source":"hosted_entitlements"}},"/market-signal-snapshot":{"get":{"operationId":"market_signal_snapshot","summary":"Get latest market/network signal packet","responses":{"200":{"description":"Market signal snapshot","content":{"application/json":{"schema":{"type":"object","required":["schema_version","network_mode","account_platform_features","privacy_policy","hosted_auth_context"],"additionalProperties":true,"properties":{"schema_version":{"type":"string","const":"ads_quant.network_feature_packet.v1"},"network_mode":{"type":"string"},"account_platform_features":{"type":"array","items":{"type":"object","additionalProperties":true}},"privacy_policy":{"type":"object","additionalProperties":true},"hosted_auth_context":{"type":"object","additionalProperties":true}}}}}}},"x-gravityads-tool-name":"gravityads.market.signal.snapshot","x-gravityads-required-scope":"gravityads.read","x-gravityads-scope-source":"hosted_entitlements"}},"/campaign-entity-lookup":{"post":{"operationId":"campaign_entity_lookup","summary":"Look up candidate/campaign/entity ids in context","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string"},"entity_id":{"type":"string"},"operator_id":{"type":"string"},"limit":{"type":"integer","default":10}}}}}},"responses":{"200":{"description":"Entity lookup","content":{"application/json":{"schema":{"type":"object","required":["status","operator_id","query","match_count","matches","hosted_auth_context"],"additionalProperties":true,"properties":{"status":{"type":"string","const":"campaign_entity_lookup_ready"},"operator_id":{"type":"string"},"query":{"type":"string"},"match_count":{"type":"integer","minimum":0},"matches":{"type":"array","items":{"type":"object","additionalProperties":true}},"hosted_auth_context":{"type":"object","additionalProperties":true}}}}}}},"x-gravityads-tool-name":"gravityads.campaign.entity.lookup","x-gravityads-required-scope":"gravityads.read","x-gravityads-scope-source":"hosted_entitlements"}},"/creative-copy-inventory":{"post":{"operationId":"creative_copy_inventory","summary":"List active creative copy inventory for scoped ad accounts","description":"Read-only serving-warehouse lookup for ad creative copy. Use when the user asks for current/online product ad copy, creative titles, descriptions or landing URLs. It respects the current operator account scope and never writes ad platforms.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"operator_id":{"type":"string"},"customer_name":{"type":"string"},"platform":{"type":"string","description":"meta/facebook/google/bing/microsoft; optional."},"account_id":{"type":"string"},"active_only":{"type":"boolean","default":true,"description":"When true, return only latest active creatives."},"days":{"type":"integer","default":90},"limit":{"type":"integer","default":50}}}}}},"responses":{"200":{"description":"Creative copy inventory","content":{"application/json":{"schema":{"type":"object","required":["schema_version","status","operator_id","request","account_scope","creative_count","creative_copies","status_counts","hosted_auth_context","writes_platform"],"additionalProperties":true,"properties":{"schema_version":{"type":"string","const":"ads_quant.creative_copy_inventory.v1"},"status":{"type":"string"},"operator_id":{"type":"string"},"request":{"type":"object","additionalProperties":true},"account_scope":{"type":"object","additionalProperties":true},"creative_count":{"type":"integer","minimum":0},"creative_copies":{"type":"array","items":{"type":"object","additionalProperties":true}},"status_counts":{"type":"array","items":{"type":"object","additionalProperties":true}},"data_source":{"type":"object","additionalProperties":true},"hosted_auth_context":{"type":"object","additionalProperties":true},"writes_platform":{"type":"boolean","const":false}}}}}}},"x-gravityads-tool-name":"gravityads.creative.copy.inventory","x-gravityads-required-scope":"gravityads.read","x-gravityads-scope-source":"hosted_entitlements"}},"/resources/accounts/{account_key}/decision-context/latest":{"get":{"operationId":"resource_account_decision_context","summary":"Fetch account-scoped decision context resource","parameters":[{"name":"account_key","in":"path","required":true,"schema":{"type":"string"}},{"name":"operator_id","in":"query","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":25}}],"responses":{"200":{"description":"Account decision-context resource","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}},"x-gravityads-tool-name":"gravityads.resource.account.decision.context","x-gravityads-required-scope":"gravityads.read","x-gravityads-scope-source":"hosted_entitlements"}},"/resources/actions/{action_id}":{"get":{"operationId":"resource_action","summary":"Fetch one controlled action resource","parameters":[{"name":"action_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"operator_id","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Controlled action resource","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}},"x-gravityads-tool-name":"gravityads.resource.action","x-gravityads-required-scope":"gravityads.read","x-gravityads-scope-source":"hosted_entitlements"}},"/resources/etl-runs/{run_id}":{"get":{"operationId":"resource_etl_run","summary":"Fetch ETL/freshness resource","parameters":[{"name":"run_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"ETL run resource","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}},"x-gravityads-tool-name":"gravityads.resource.etl.run","x-gravityads-required-scope":"gravityads.read","x-gravityads-scope-source":"hosted_entitlements"}},"/resources/audit/{operator_id}/{date}":{"get":{"operationId":"resource_audit","summary":"Fetch audit export resource","parameters":[{"name":"operator_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"date","in":"path","required":true,"schema":{"type":"string"}},{"name":"action_id","in":"query","required":false,"schema":{"type":"string"}},{"name":"account_id","in":"query","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":100}}],"responses":{"200":{"description":"Audit export resource","content":{"application/json":{"schema":{"type":"object","required":["schema_version","status","export_scope","tenant_id","filters","entry_count","entries","control_plane_audit_log","action_ledger","export_manifest","secret_values_redacted","raw_account_ids_returned","raw_chat_ids_returned","raw_message_ids_returned","raw_tool_call_ids_returned","raw_llm_response_ids_returned","raw_user_emails_returned","raw_secrets_returned"],"additionalProperties":true,"properties":{"schema_version":{"type":"string","const":"gravityads.tenant_audit_export.v1"},"status":{"type":"string","enum":["tenant_audit_export_ready","tenant_audit_export_degraded","tenant_audit_export_unconfigured"]},"export_scope":{"type":"string","const":"tenant"},"tenant_id":{"type":"string"},"call_log_status":{"type":"string"},"filters":{"type":"object"},"entry_count":{"type":"integer","minimum":0},"entries":{"type":"array","items":{"type":"object"}},"control_plane_audit_log":{"type":"object"},"action_ledger":{"type":"object"},"resource_links":{"type":"array","items":{"type":"object"}},"export_manifest":{"type":"object"},"hosted_auth_context":{"type":"object"},"secret_values_redacted":{"type":"boolean","const":true},"raw_account_ids_returned":{"type":"boolean","const":false},"raw_chat_ids_returned":{"type":"boolean","const":false},"raw_message_ids_returned":{"type":"boolean","const":false},"raw_tool_call_ids_returned":{"type":"boolean","const":false},"raw_llm_response_ids_returned":{"type":"boolean","const":false},"raw_user_emails_returned":{"type":"boolean","const":false},"raw_secrets_returned":{"type":"boolean","const":false}}}}}}},"x-gravityads-tool-name":"gravityads.resource.audit","x-gravityads-required-scope":"gravityads.read","x-gravityads-scope-source":"hosted_entitlements"}},"/microsoft/creation-reconcile":{"post":{"operationId":"microsoft_creation_reconcile","summary":"Verify existing microsoft creation receipts","description":"Reads exact persisted IDs and fields. Never writes ads or retries an unknown request. Requires approval permission.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["action_id","request_id"],"properties":{"action_id":{"type":"string","minLength":1,"maxLength":128},"request_id":{"type":"string","minLength":1,"maxLength":128}}}}}},"responses":{"200":{"description":"Receipt reconciliation result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}},"x-gravityads-tool-name":"gravityads.microsoft_ads.creation.reconcile","x-gravityads-required-scope":"gravityads.approve","x-gravityads-scope-source":"hosted_entitlements"}},"/google/creation-reconcile":{"post":{"operationId":"google_creation_reconcile","summary":"Verify existing google creation receipts","description":"Reads exact persisted IDs and fields. Never writes ads or retries an unknown request. Requires approval permission.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["action_id","request_id"],"properties":{"action_id":{"type":"string","minLength":1,"maxLength":128},"request_id":{"type":"string","minLength":1,"maxLength":128}}}}}},"responses":{"200":{"description":"Receipt reconciliation result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}},"x-gravityads-tool-name":"gravityads.google_ads.creation.reconcile","x-gravityads-required-scope":"gravityads.approve","x-gravityads-scope-source":"hosted_entitlements"}},"/microsoft/creation-recovery-draft":{"post":{"operationId":"microsoft_creation_recovery_draft","summary":"Save a fresh Microsoft Search or non-upload Retail PMax remainder draft","description":"Reuses verified existing parents after definite rejection. Unknown outcomes and unverifiable uploaded media remain blocked. Requires draft and approve permission. Does not write ads; fresh approval and live execution remain mandatory.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["action_id"],"properties":{"action_id":{"type":"string","minLength":1,"maxLength":128}}}}}},"responses":{"200":{"description":"Recovery draft","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}},"x-gravityads-tool-name":"gravityads.microsoft_ads.creation.recovery_draft","x-gravityads-required-scope":"gravityads.draft","x-gravityads-scope-source":"hosted_entitlements"}},"/business-context/upsert":{"post":{"operationId":"business_context_upsert","summary":"Upsert operator-provided business context","description":"Writes local Ads Quant business context only. It never writes ad platforms, and it rejects raw OAuth or API credential fields.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"request_id":{"type":"string","description":"Idempotency key for this business context intake."},"operator_id":{"type":"string"},"operator":{"type":"string","default":"gravityads_operator"},"confirmation":{"type":"string","default":"record business context"},"mode":{"type":"string","enum":["merge","replace"],"default":"merge"},"refresh_local_artifacts":{"type":"boolean","default":true},"records":{"type":"array","minItems":1,"items":{"type":"object","description":"Business-context record. Typical fields include customer_id, customer_name, platform, ad_account_id, campaign_id, entity_type, entity_id, product_id, geo, business_context, target_roas, margin, locale, source, confidence, and effective_date. Raw credentials are rejected."}}},"required":["request_id","records"]}}}},"responses":{"200":{"description":"Business context upsert result","content":{"application/json":{"schema":{"type":"object","required":["schema_version","status","request_id","record_count","mode","hosted_auth_context"],"additionalProperties":true,"properties":{"schema_version":{"type":"string","const":"ads_quant.business_context_records_action.v1"},"status":{"type":"string","const":"business_context_records_upserted"},"request_id":{"type":"string"},"operator":{"type":"string"},"record_count":{"type":"integer","minimum":0},"mode":{"type":"string","enum":["merge","replace"]},"local_business_context_config_written":{"type":"boolean"},"refresh_local_artifacts":{"type":"boolean"},"refresh_results":{"type":"array","items":{"type":"object","additionalProperties":true}},"hosted_auth_context":{"type":"object","additionalProperties":true},"writes_platform":{"type":"boolean","const":false}}}}}}},"x-gravityads-tool-name":"gravityads.business_context.upsert_records","x-gravityads-required-scope":"gravityads.draft","x-gravityads-scope-source":"hosted_entitlements"}},"/controlled-draft":{"post":{"operationId":"controlled_draft","summary":"Create local controlled action draft","description":"Accepts candidate_id or action_packet. Never writes ad platforms.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"candidate_id":{"type":"string"},"action_packet":{"type":"object"},"operator_id":{"type":"string"},"requested_by":{"type":"string","default":"gravityads_operator"},"request_id":{"type":"string"},"confirmation":{"type":"string","default":"record controlled action"},"internal_override":{"type":"boolean","default":false},"audit_context":{"type":"object"}},"required":["request_id"]}}}},"responses":{"200":{"description":"Draft result","content":{"application/json":{"schema":{"type":"object","required":["status"],"additionalProperties":true,"properties":{"schema_version":{"type":"string"},"status":{"type":"string"},"action_id":{"type":"string"},"request_id":{"type":"string"},"controlled_action":{"type":"object"},"authority_flags":{"type":"object","additionalProperties":true,"properties":{"platform_write_allowed":{"type":"boolean"}}},"result":{"type":"object"}}}}}}},"x-gravityads-tool-name":"gravityads.controlled_action.draft","x-gravityads-required-scope":"gravityads.draft","x-gravityads-scope-source":"hosted_entitlements"}},"/controlled-draft/batch":{"post":{"operationId":"controlled_draft_batch","summary":"Create multiple local controlled action drafts","description":"Creates up to 25 independently auditable drafts after one shared freshness evaluation. Never approves, executes, or writes ad platforms.","requestBody":{"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"operator_id":{"type":"string"},"requested_by":{"type":"string","default":"gravityads_operator"},"confirmation":{"type":"string","default":"record controlled action"},"internal_override":{"type":"boolean","default":false},"audit_context":{"type":"object"},"items":{"type":"array","minItems":1,"maxItems":25,"items":{"type":"object","required":["request_id","action_packet"],"properties":{"request_id":{"type":"string"},"action_packet":{"type":"object"},"confirmation":{"type":"string"},"internal_override":{"type":"boolean"}}}}},"required":["items"]}}}},"responses":{"200":{"description":"Batch draft result","content":{"application/json":{"schema":{"type":"object","required":["status","item_count","results"],"properties":{"schema_version":{"type":"string"},"status":{"type":"string"},"item_count":{"type":"integer"},"results":{"type":"array","items":{"type":"object"}},"freshness_gate":{"type":"object"},"platform_write_performed":{"type":"boolean"},"approval_required_per_item":{"type":"boolean"}}}}}}},"x-gravityads-tool-name":"gravityads.controlled_action.draft","x-gravityads-required-scope":"gravityads.draft","x-gravityads-scope-source":"hosted_entitlements"}},"/creative-refresh-draft":{"post":{"operationId":"creative_refresh_draft","summary":"Create controlled creative refresh draft","description":"Creates a local creative refresh controlled-action draft. It never writes ad platforms until approve and creative_publish_controlled.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"request_id":{"type":"string"},"platform":{"type":"string"},"ad_account_id":{"type":"string"},"entity_type":{"type":"string","default":"ad"},"entity_id":{"type":"string"},"ad_id":{"type":"string"},"object_id":{"type":"string"},"campaign_id":{"type":"string"},"ad_group_id":{"type":"string"},"ad_group_resource_name":{"type":"string"},"creative_payload":{"type":"object"},"proposed_change":{"type":"object"},"action_packet":{"type":"object"},"operator_id":{"type":"string"},"requested_by":{"type":"string","default":"gravityads_operator"},"confirmation":{"type":"string","default":"record controlled action"},"internal_override":{"type":"boolean","default":false},"audit_context":{"type":"object"}},"required":["request_id"]}}}},"responses":{"200":{"description":"Creative draft result","content":{"application/json":{"schema":{"type":"object","required":["status"],"additionalProperties":true,"properties":{"schema_version":{"type":"string"},"status":{"type":"string"},"action_id":{"type":"string"},"request_id":{"type":"string"},"controlled_action":{"type":"object"},"authority_flags":{"type":"object","additionalProperties":true,"properties":{"platform_write_allowed":{"type":"boolean"}}},"result":{"type":"object"}}}}}}},"x-gravityads-tool-name":"gravityads.controlled_action.draft","x-gravityads-required-scope":"gravityads.draft","x-gravityads-scope-source":"hosted_entitlements"}},"/controlled-action/approve":{"post":{"operationId":"controlled_action_approve","summary":"Approve a local controlled action","description":"Approves a local ledger draft for controlled execution through the selected adapter.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"action_id":{"type":"string"},"request_id":{"type":"string"},"approved_by":{"type":"string","default":"gravityads_operator"},"confirmation":{"type":"string","default":"record controlled action"},"approval_note":{"type":"string"},"internal_override":{"type":"boolean","default":false},"audit_context":{"type":"object"}},"required":["action_id","request_id"]}}}},"responses":{"200":{"description":"Approval result","content":{"application/json":{"schema":{"type":"object","required":["status"],"additionalProperties":true,"properties":{"schema_version":{"type":"string"},"status":{"type":"string"},"action_id":{"type":"string"},"request_id":{"type":"string"},"controlled_action":{"type":"object"},"authority_flags":{"type":"object","additionalProperties":true,"properties":{"platform_write_allowed":{"type":"boolean"}}},"result":{"type":"object"}}}}}}},"x-gravityads-tool-name":"gravityads.controlled_action.approve","x-gravityads-required-scope":"gravityads.approve","x-gravityads-scope-source":"hosted_entitlements"}},"/controlled-action/reject":{"post":{"operationId":"controlled_action_reject","summary":"Reject a local controlled action","description":"Rejects a local ledger draft before controlled execution. It does not write ad platforms.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"action_id":{"type":"string"},"request_id":{"type":"string"},"rejected_by":{"type":"string","default":"gravityads_operator"},"confirmation":{"type":"string","default":"record controlled action"},"rejection_reason":{"type":"string"},"internal_override":{"type":"boolean","default":false},"audit_context":{"type":"object"}},"required":["action_id","request_id"]}}}},"responses":{"200":{"description":"Rejection result","content":{"application/json":{"schema":{"type":"object","required":["status"],"additionalProperties":true,"properties":{"schema_version":{"type":"string"},"status":{"type":"string"},"action_id":{"type":"string"},"request_id":{"type":"string"},"controlled_action":{"type":"object"},"authority_flags":{"type":"object","additionalProperties":true,"properties":{"platform_write_allowed":{"type":"boolean"}}},"result":{"type":"object"}}}}}}},"x-gravityads-tool-name":"gravityads.controlled_action.approve","x-gravityads-required-scope":"gravityads.approve","x-gravityads-scope-source":"hosted_entitlements"}},"/official-adapter-invocation-plan":{"post":{"operationId":"official_adapter_invocation_plan","summary":"Plan controlled action adapter handoff","description":"Builds an adapter invocation plan for an approved controlled action. Persist=false keeps planning separate from execution.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"action_id":{"type":"string"},"operator_id":{"type":"string"},"adapter":{"type":"string","enum":["auto","google_ads_api","meta_official_mcp","microsoft_ads_rest_api","noop"],"description":"Optional adapter hint. When omitted or auto, the server derives the adapter from the persisted controlled-action platform."},"execute_mode":{"type":"string","enum":["dry_run","live"],"default":"live","description":"Hosted live execution must hand off to the action worker; request-time adapter dispatch is not allowed in hosted SaaS."},"adapter_context":{"type":"object"},"persist":{"type":"boolean","default":false}},"required":["action_id"]}}}},"responses":{"200":{"description":"Invocation plan","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"schema_version":{"type":"string"},"status":{"type":"string"},"summary":{"type":"object"},"authority_flags":{"type":"object","additionalProperties":true,"properties":{"platform_write_allowed":{"type":"boolean"}}},"request":{"type":"object","additionalProperties":true,"properties":{"action_id":{"type":"string"},"adapter":{"type":"string"},"execute_mode":{"type":"string","enum":["dry_run","live"]},"persist":{"type":"boolean"}}}}}}}}},"x-gravityads-tool-name":"gravityads.official_adapter.invocation_plan","x-gravityads-required-scope":"gravityads.read","x-gravityads-scope-source":"hosted_entitlements"}},"/controlled-action/execute":{"post":{"operationId":"controlled_action_execute","summary":"Record controlled action execution attempt","description":"Records the execution attempt. In hosted SaaS, live execution must be queued for the action worker; the request thread does not write ad platforms.","x-gravityads-hosted-execution":{"phase_contract":"phase2_controlled_actions_worker_only","live_requires_worker_queue":true,"live_request_thread_writes_platform":false,"dry_run_may_queue_without_platform_write":true,"approval_policy_schema_version":"gravityads.hosted_approval_policy.v1","approval_policy_enforced_by_worker":true,"execute_scope_does_not_bypass_approval_policy":true,"plan_entitlement_does_not_bypass_approval_policy":true,"self_approval_policy_driven":true,"self_approval_allowed_by_default":true},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"action_id":{"type":"string"},"request_id":{"type":"string"},"requested_by":{"type":"string","default":"gravityads_operator"},"confirmation":{"type":"string","default":"record controlled action"},"platform":{"type":"string"},"ad_account_id":{"type":"string"},"adapter":{"type":"string","enum":["auto","google_ads_api","meta_official_mcp","microsoft_ads_rest_api","noop"],"description":"Optional adapter hint. When omitted or auto, the server derives the adapter from the persisted controlled-action platform."},"execute_mode":{"type":"string","enum":["dry_run","live"],"default":"live","description":"Hosted live execution must hand off to the action worker; request-time adapter dispatch is not allowed in hosted SaaS."},"adapter_context":{"type":"object"},"execution_note":{"type":"string"},"audit_context":{"type":"object"}},"required":["action_id","request_id"]}}}},"responses":{"200":{"description":"Execution result or worker queue handoff","content":{"application/json":{"schema":{"type":"object","required":["status"],"additionalProperties":true,"properties":{"status":{"type":"string"},"action_id":{"type":"string"},"request_id":{"type":"string"},"result":{"type":"object"},"official_adapter_invocation_plan":{"type":"object"},"hosted_action_queue":{"type":"object","required":["schema_version","enabled","queued","tenant_id","action_id","request_id","adapter","execute_mode","database_url_configured"],"additionalProperties":true,"properties":{"schema_version":{"type":"string","const":"gravityads.hosted_action_queue_handoff.v1"},"status":{"type":"string"},"enabled":{"type":"boolean"},"queued":{"type":"boolean"},"tenant_id":{"type":"string"},"action_id":{"type":"string"},"request_id":{"type":"string"},"adapter":{"type":"string"},"execute_mode":{"type":"string","enum":["dry_run","live"]},"database_url_configured":{"type":"boolean"},"queue_item_id":{"type":"string"},"queue_name":{"type":"string"},"worker_endpoint":{"type":"string"},"idempotency_key":{"type":"string"},"action_packet_hash":{"type":"string"},"queue_summary":{"type":"object"},"raw_secrets_returned":{"type":"boolean","const":false}}},"adapter_execution":{"type":"object","additionalProperties":true,"properties":{"skipped":{"type":"boolean"},"reason":{"type":"string"},"queued":{"type":"boolean"},"queue_item_id":{"type":"string"},"worker_endpoint":{"type":"string"},"platform_write_called":{"type":"boolean","const":false}}},"platform_write_boundary":{"type":"object","additionalProperties":true,"properties":{"phase_contract":{"type":"string","const":"phase2_controlled_actions_worker_only"},"execute_mode":{"type":"string"},"request_thread_platform_write_called":{"type":"boolean","const":false},"platform_write_called":{"type":"boolean","const":false},"hosted_queue_required":{"type":"boolean"},"hosted_queue_queued":{"type":"boolean"},"worker_required":{"type":"boolean"},"worker_endpoint":{"type":"string"},"queue_item_id":{"type":"string"}}},"freshness_gate":{"type":"object"}}}}}},"503":{"description":"Hosted live execution requires a durable worker queue handoff and failed closed before adapter dispatch."}},"x-gravityads-tool-name":"gravityads.controlled_action.execute","x-gravityads-required-scope":"gravityads.execute","x-gravityads-scope-source":"hosted_entitlements"}},"/creative-publish-controlled":{"post":{"operationId":"creative_publish_controlled","summary":"Publish approved creative refresh through adapter","description":"Executes an approved creative-refresh controlled action through the selected live adapter, with the same freshness gate and audit ledger as normal execute.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"action_id":{"type":"string"},"request_id":{"type":"string"},"requested_by":{"type":"string","default":"gravityads_operator"},"confirmation":{"type":"string","default":"record controlled action"},"platform":{"type":"string","description":"meta 或 google；未显式传 adapter 时用于自动选择 live adapter。"},"ad_account_id":{"type":"string"},"adapter":{"type":"string"},"execute_mode":{"type":"string","enum":["dry_run","live"],"default":"live","description":"Hosted live execution must hand off to the action worker; request-time adapter dispatch is not allowed in hosted SaaS."},"adapter_context":{"type":"object"},"execution_note":{"type":"string"},"audit_context":{"type":"object"}},"required":["action_id","request_id"]}}}},"responses":{"200":{"description":"Creative publish result","content":{"application/json":{"schema":{"type":"object","required":["status"],"additionalProperties":true,"properties":{"status":{"type":"string"},"action_id":{"type":"string"},"request_id":{"type":"string"},"result":{"type":"object"},"official_adapter_invocation_plan":{"type":"object"},"hosted_action_queue":{"type":"object","required":["schema_version","enabled","queued","tenant_id","action_id","request_id","adapter","execute_mode","database_url_configured"],"additionalProperties":true,"properties":{"schema_version":{"type":"string","const":"gravityads.hosted_action_queue_handoff.v1"},"status":{"type":"string"},"enabled":{"type":"boolean"},"queued":{"type":"boolean"},"tenant_id":{"type":"string"},"action_id":{"type":"string"},"request_id":{"type":"string"},"adapter":{"type":"string"},"execute_mode":{"type":"string","enum":["dry_run","live"]},"database_url_configured":{"type":"boolean"},"queue_item_id":{"type":"string"},"queue_name":{"type":"string"},"worker_endpoint":{"type":"string"},"idempotency_key":{"type":"string"},"action_packet_hash":{"type":"string"},"queue_summary":{"type":"object"},"raw_secrets_returned":{"type":"boolean","const":false}}},"adapter_execution":{"type":"object","additionalProperties":true,"properties":{"skipped":{"type":"boolean"},"reason":{"type":"string"},"queued":{"type":"boolean"},"queue_item_id":{"type":"string"},"worker_endpoint":{"type":"string"},"platform_write_called":{"type":"boolean","const":false}}},"platform_write_boundary":{"type":"object","additionalProperties":true,"properties":{"phase_contract":{"type":"string","const":"phase2_controlled_actions_worker_only"},"execute_mode":{"type":"string"},"request_thread_platform_write_called":{"type":"boolean","const":false},"platform_write_called":{"type":"boolean","const":false},"hosted_queue_required":{"type":"boolean"},"hosted_queue_queued":{"type":"boolean"},"worker_required":{"type":"boolean"},"worker_endpoint":{"type":"string"},"queue_item_id":{"type":"string"}}},"freshness_gate":{"type":"object"}}}}}}},"x-gravityads-tool-name":"gravityads.controlled_action.execute","x-gravityads-required-scope":"gravityads.execute","x-gravityads-scope-source":"hosted_entitlements"}},"/controlled-action/observe":{"post":{"operationId":"controlled_action_observe","summary":"Record controlled action observation","description":"Records post-action observation and optional metric snapshot in the local action ledger.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"action_id":{"type":"string"},"request_id":{"type":"string"},"observed_by":{"type":"string","default":"gravityads_operator"},"confirmation":{"type":"string","default":"record controlled action"},"observation_note":{"type":"string"},"metric_snapshot":{"type":"object"},"outcome_window":{"type":"object","description":"Post-action measurement window, for example start_at_utc/end_at_utc/window_label/lookback_days."},"baseline_metric_snapshot":{"type":"object","description":"Metric snapshot before or at the start of the outcome window."},"current_metric_snapshot":{"type":"object","description":"Metric snapshot after the outcome window observation."},"attribution":{"type":"object","description":"Redacted attribution metadata: source/model/confidence/platform_attribution_window_days/assumptions."},"evaluation":{"type":"object","description":"Human or offline evaluation metadata for feedback loops."},"audit_context":{"type":"object"}},"required":["action_id","request_id"]}}}},"responses":{"200":{"description":"Observation result","content":{"application/json":{"schema":{"type":"object","required":["status"],"additionalProperties":true,"properties":{"schema_version":{"type":"string"},"status":{"type":"string"},"action_id":{"type":"string"},"request_id":{"type":"string"},"controlled_action":{"type":"object"},"authority_flags":{"type":"object","additionalProperties":true,"properties":{"platform_write_allowed":{"type":"boolean"}}},"result":{"type":"object","additionalProperties":true,"properties":{"observation":{"type":"object","additionalProperties":true,"properties":{"metric_snapshot":{"type":"object"},"observation_contract":{"type":"object","required":["schema_version","contract_schema_version","phase_contract","contract_payload_present","raw_platform_ids_returned","raw_attribution_payload_returned","raw_customer_ids_returned"],"additionalProperties":true,"properties":{"schema_version":{"type":"string","const":"gravityads.controlled_action_observation_contract.v1"},"contract_schema_version":{"type":"string","const":"gravityads.controlled_action_observation_contract.v1"},"phase_contract":{"type":"string","const":"phase2_observe_feedback_outcome_window"},"contract_payload_present":{"type":"boolean"},"action_id_hash":{"type":"string"},"request_id_hash":{"type":"string"},"outcome_window":{"type":"object"},"metric_snapshot_present":{"type":"boolean"},"baseline_metric_snapshot_present":{"type":"boolean"},"current_metric_snapshot_present":{"type":"boolean"},"metric_delta":{"type":"object"},"attribution":{"type":"object"},"evaluation":{"type":"object"},"raw_platform_ids_returned":{"type":"boolean","const":false},"raw_attribution_payload_returned":{"type":"boolean","const":false},"raw_customer_ids_returned":{"type":"boolean","const":false}}}}}}},"observation_contract":{"type":"object","required":["schema_version","contract_schema_version","phase_contract","contract_payload_present","raw_platform_ids_returned","raw_attribution_payload_returned","raw_customer_ids_returned"],"additionalProperties":true,"properties":{"schema_version":{"type":"string","const":"gravityads.controlled_action_observation_contract.v1"},"contract_schema_version":{"type":"string","const":"gravityads.controlled_action_observation_contract.v1"},"phase_contract":{"type":"string","const":"phase2_observe_feedback_outcome_window"},"contract_payload_present":{"type":"boolean"},"action_id_hash":{"type":"string"},"request_id_hash":{"type":"string"},"outcome_window":{"type":"object"},"metric_snapshot_present":{"type":"boolean"},"baseline_metric_snapshot_present":{"type":"boolean"},"current_metric_snapshot_present":{"type":"boolean"},"metric_delta":{"type":"object"},"attribution":{"type":"object"},"evaluation":{"type":"object"},"raw_platform_ids_returned":{"type":"boolean","const":false},"raw_attribution_payload_returned":{"type":"boolean","const":false},"raw_customer_ids_returned":{"type":"boolean","const":false}}}}}}}}},"x-gravityads-tool-name":"gravityads.controlled_action.observe","x-gravityads-required-scope":"gravityads.execute","x-gravityads-scope-source":"hosted_entitlements"}},"/controlled-actions/latest":{"get":{"operationId":"controlled_actions_latest","summary":"Inspect latest controlled action ledger","parameters":[{"name":"operator_id","in":"query","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":50,"minimum":1,"maximum":500}}],"responses":{"200":{"description":"Latest ledger","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"schema_version":{"type":"string"},"status":{"type":"string"},"operator_id":{"type":"string"},"summary":{"type":"object","additionalProperties":true,"properties":{"controlled_action_count":{"type":"integer","minimum":0},"limit":{"type":"integer","minimum":1},"returned_action_count":{"type":"integer","minimum":0}}},"actions":{"type":"array","items":{"type":"object"}},"entries":{"type":"array","items":{"type":"object"}},"output_limited":{"type":"boolean"}}}}}}},"x-gravityads-tool-name":"gravityads.controlled.actions.latest","x-gravityads-required-scope":"gravityads.read","x-gravityads-scope-source":"hosted_entitlements"}},"/controlled-action/rollback-plan":{"post":{"operationId":"controlled_action_rollback_plan","summary":"Build compensating rollback plan","description":"Builds a rollback/revert plan for budget/status actions. This does not write ad platforms.","x-gravityads-rollback-boundary":{"phase_contract":"phase2_rollback_draft_never_auto_executes","request_thread_writes_platform":false,"platform_write_called":false,"draft_required_before_execute":true,"approval_required_before_execute":true,"execute_required_for_platform_write":true},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"action_id":{"type":"string"},"operator_id":{"type":"string"},"requested_by":{"type":"string","default":"gravityads_operator"}},"required":["action_id"]}}}},"responses":{"200":{"description":"Rollback plan","content":{"application/json":{"schema":{"type":"object","required":["status","action_id","supported","rollback_boundary"],"additionalProperties":true,"properties":{"status":{"type":"string","const":"rollback_plan_ready"},"action_id":{"type":"string"},"requested_by":{"type":"string"},"supported":{"type":"boolean"},"rollback_action_packet":{"type":"object"},"rollback_boundary":{"type":"object","required":["contract_schema_version","phase_contract","stage","request_thread_platform_write_called","platform_write_called","approval_required_before_execute","execute_required_for_platform_write","raw_platform_response_returned","raw_customer_ids_returned"],"additionalProperties":true,"properties":{"contract_schema_version":{"type":"string","const":"gravityads.controlled_rollback_boundary.v1"},"phase_contract":{"type":"string","const":"phase2_rollback_draft_never_auto_executes"},"stage":{"type":"string","enum":["plan","draft"]},"action_id_hash":{"type":"string"},"request_id_hash":{"type":"string"},"request_thread_platform_write_called":{"type":"boolean","const":false},"platform_write_called":{"type":"boolean","const":false},"rollback_plan_only":{"type":"boolean"},"rollback_draft_only":{"type":"boolean"},"draft_required_before_execute":{"type":"boolean"},"approval_required_before_execute":{"type":"boolean","const":true},"execute_required_for_platform_write":{"type":"boolean","const":true},"worker_required_for_hosted_live_write":{"type":"boolean"},"raw_platform_response_returned":{"type":"boolean","const":false},"raw_customer_ids_returned":{"type":"boolean","const":false}}}}}}}}},"x-gravityads-tool-name":"gravityads.controlled_action.rollback_plan","x-gravityads-required-scope":"gravityads.execute","x-gravityads-scope-source":"hosted_entitlements"}},"/controlled-action/rollback-draft":{"post":{"operationId":"controlled_action_rollback_draft","summary":"Create controlled rollback draft","description":"Creates a compensating controlled action draft from a rollback plan. Approval and execute are still separate.","x-gravityads-rollback-boundary":{"phase_contract":"phase2_rollback_draft_never_auto_executes","request_thread_writes_platform":false,"platform_write_called":false,"approval_required_before_execute":true,"execute_required_for_platform_write":true},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"action_id":{"type":"string"},"request_id":{"type":"string"},"requested_by":{"type":"string","default":"gravityads_operator"},"confirmation":{"type":"string","default":"record controlled action"},"internal_override":{"type":"boolean","default":false},"audit_context":{"type":"object"}},"required":["action_id","request_id"]}}}},"responses":{"200":{"description":"Rollback draft","content":{"application/json":{"schema":{"type":"object","required":["status"],"additionalProperties":true,"properties":{"schema_version":{"type":"string"},"status":{"type":"string"},"action_id":{"type":"string"},"request_id":{"type":"string"},"controlled_action":{"type":"object"},"authority_flags":{"type":"object","additionalProperties":true,"properties":{"platform_write_allowed":{"type":"boolean"}}},"result":{"type":"object"},"rollback_of_action_id":{"type":"string"},"rollback_boundary":{"type":"object","required":["contract_schema_version","phase_contract","stage","request_thread_platform_write_called","platform_write_called","approval_required_before_execute","execute_required_for_platform_write","raw_platform_response_returned","raw_customer_ids_returned"],"additionalProperties":true,"properties":{"contract_schema_version":{"type":"string","const":"gravityads.controlled_rollback_boundary.v1"},"phase_contract":{"type":"string","const":"phase2_rollback_draft_never_auto_executes"},"stage":{"type":"string","enum":["plan","draft"]},"action_id_hash":{"type":"string"},"request_id_hash":{"type":"string"},"request_thread_platform_write_called":{"type":"boolean","const":false},"platform_write_called":{"type":"boolean","const":false},"rollback_plan_only":{"type":"boolean"},"rollback_draft_only":{"type":"boolean"},"draft_required_before_execute":{"type":"boolean"},"approval_required_before_execute":{"type":"boolean","const":true},"execute_required_for_platform_write":{"type":"boolean","const":true},"worker_required_for_hosted_live_write":{"type":"boolean"},"raw_platform_response_returned":{"type":"boolean","const":false},"raw_customer_ids_returned":{"type":"boolean","const":false}}}}}}}}},"x-gravityads-tool-name":"gravityads.controlled_action.rollback_draft","x-gravityads-required-scope":"gravityads.execute","x-gravityads-scope-source":"hosted_entitlements"}},"/oauth-etl-metadata":{"post":{"operationId":"oauth_etl_metadata","summary":"Record metadata-only OAuth/ETL state","description":"Connector/data-plane ingestion endpoint. It records connection/account/ETL-run metadata in Ads Quant and never accepts raw tokens or writes ad platforms.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"request_id":{"type":"string"},"operator":{"type":"string","default":"gravityads_connector"},"operator_id":{"type":"string"},"confirmation":{"type":"string","default":"record oauth etl metadata"},"mode":{"type":"string","default":"merge"},"refresh_bootstrap":{"type":"boolean","default":true},"records":{"type":"array","items":{"type":"object","description":"Metadata-only OAuth connection/account/ETL run record. Raw access_token, refresh_token, developer_token, client_secret, and app_secret fields are rejected.","properties":{"tenant_id":{"type":"string"},"tenant_id_hash":{"type":"string"},"platform":{"type":"string"},"connection_id":{"type":"string"},"authorized_user_hash":{"type":"string"},"scopes":{"type":"array","items":{"type":"string"}},"oauth_status":{"type":"string"},"token_status":{"type":"string"},"refresh_status":{"type":"string"},"secret_ref_present":{"type":"boolean"},"last_successful_read_at":{"type":"string"},"accounts":{"type":"array","items":{"type":"object"}},"etl_runs":{"type":"array","items":{"type":"object"}}}}}},"required":["request_id","records"]}}}},"responses":{"200":{"description":"Metadata result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}},"x-gravityads-tool-name":"gravityads.ops.oauth_etl","x-gravityads-required-scope":"gravityads.ops","x-gravityads-scope-source":"hosted_entitlements"}},"/readonly-etl-serving-contract":{"post":{"operationId":"readonly_etl_serving_contract","summary":"Import read-only ETL serving contract","description":"Connector/data-plane ingestion endpoint. It forwards a normalized read-only ETL serving contract to Ads Quant, refreshes source readiness when requested, rejects raw credentials, and never writes ad platforms.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"request_id":{"type":"string"},"operator":{"type":"string","default":"gravityads_readonly_etl_runner"},"operator_id":{"type":"string"},"confirmation":{"type":"string","default":"record oauth etl metadata"},"mode":{"type":"string","default":"merge"},"refresh_bootstrap":{"type":"boolean","default":true},"serving_contract":{"type":"object","description":"Normalized GravityAds read-only ETL serving contract. Raw access_token, refresh_token, developer_token, client_secret, and app_secret fields are rejected."}},"required":["request_id","serving_contract"]}}}},"responses":{"200":{"description":"Serving contract import result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}},"x-gravityads-tool-name":"gravityads.ops.readonly_etl","x-gravityads-required-scope":"gravityads.ops","x-gravityads-scope-source":"hosted_entitlements"}},"/ops/adapter-health":{"get":{"operationId":"adapter_health","summary":"Check registered live adapter health","responses":{"200":{"description":"Adapter health","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}},"x-gravityads-tool-name":"gravityads.adapter.health","x-gravityads-required-scope":"gravityads.read","x-gravityads-scope-source":"hosted_entitlements"}},"/ops/adapter-architecture":{"get":{"operationId":"adapter_architecture","summary":"Explain GravityAds adapter orchestration architecture","responses":{"200":{"description":"Adapter architecture map","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}},"x-gravityads-tool-name":"gravityads.adapter.architecture","x-gravityads-required-scope":"gravityads.read","x-gravityads-scope-source":"hosted_entitlements"}},"/ops/credential-preflight":{"get":{"operationId":"credential_preflight","summary":"Check credential references without exposing secrets","responses":{"200":{"description":"Credential preflight","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}},"x-gravityads-tool-name":"gravityads.credential.preflight","x-gravityads-required-scope":"gravityads.draft","x-gravityads-scope-source":"hosted_entitlements"}},"/ops/token-scope-probe":{"get":{"operationId":"token_scope_probe","summary":"Probe platform token scopes without exposing secrets","responses":{"200":{"description":"Token scope probe","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}},"x-gravityads-tool-name":"gravityads.token.scope.probe","x-gravityads-required-scope":"gravityads.ops","x-gravityads-scope-source":"hosted_entitlements"}},"/ops/etl-status":{"get":{"operationId":"etl_status","summary":"Check ETL/source freshness status","responses":{"200":{"description":"ETL status","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}},"x-gravityads-tool-name":"gravityads.etl.status","x-gravityads-required-scope":"gravityads.read","x-gravityads-scope-source":"hosted_entitlements"}},"/ops/deployment-status":{"get":{"operationId":"deployment_status","summary":"Check local deployment shape and profile state","responses":{"200":{"description":"Deployment status","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}},"x-gravityads-tool-name":"gravityads.deployment.status","x-gravityads-required-scope":"gravityads.read","x-gravityads-scope-source":"hosted_entitlements"}},"/ops/operator-scope-resolve":{"post":{"operationId":"operator_scope_resolve","summary":"Resolve operator account scope for ops","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"operator_id":{"type":"string"},"customer_name":{"type":"string"},"platform":{"type":"string"},"account_id":{"type":"string"}}}}}},"responses":{"200":{"description":"Operator scope","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}},"x-gravityads-tool-name":"gravityads.operator.scope.resolve","x-gravityads-required-scope":"gravityads.read","x-gravityads-scope-source":"hosted_entitlements"}},"/ops/rate-limit-status":{"get":{"operationId":"rate_limit_status","summary":"Return hosted-style rate limit configuration and counters","responses":{"200":{"description":"Rate limit status","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}},"x-gravityads-tool-name":"gravityads.rate.limit.status","x-gravityads-required-scope":"gravityads.read","x-gravityads-scope-source":"hosted_entitlements"}},"/ops/hosted-control-plane-status":{"get":{"operationId":"hosted_control_plane_status","summary":"Return hosted control-plane quota, rate-limit and kill-switch state","responses":{"200":{"description":"Hosted control-plane status","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}},"x-gravityads-tool-name":"gravityads.hosted.control.plane.status","x-gravityads-required-scope":"gravityads.read","x-gravityads-scope-source":"hosted_entitlements"}},"/ops/hosted-inventory":{"get":{"operationId":"hosted_inventory","summary":"Return hosted endpoint and tool profile inventory","responses":{"200":{"description":"Hosted inventory","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}},"x-gravityads-tool-name":"gravityads.hosted.inventory","x-gravityads-required-scope":"gravityads.read","x-gravityads-scope-source":"hosted_entitlements"}},"/ops/tenant-inventory":{"get":{"operationId":"tenant_inventory","summary":"Return hosted tenant inventory for ops","responses":{"200":{"description":"Hosted tenant inventory","content":{"application/json":{"schema":{"type":"object","required":["schema_version","status","database_url_configured","tenant_count","tenants","raw_email_returned","raw_account_ids_returned","raw_secrets_returned"],"additionalProperties":true,"properties":{"schema_version":{"type":"string","const":"gravityads.tenant_inventory.v1"},"status":{"type":"string","enum":["tenant_inventory_ready","tenant_inventory_unconfigured","tenant_inventory_degraded"]},"source":{"type":"string"},"database_url_configured":{"type":"boolean"},"tenant_count":{"type":"integer","minimum":0},"limit":{"type":"integer","minimum":1},"tenants":{"type":"array","items":{"type":"object"}},"hosted_auth_context":{"type":"object"},"raw_email_returned":{"type":"boolean","const":false},"raw_account_ids_returned":{"type":"boolean","const":false},"raw_secrets_returned":{"type":"boolean","const":false}}}}}}},"x-gravityads-tool-name":"gravityads.tenant.inventory","x-gravityads-required-scope":"gravityads.read","x-gravityads-scope-source":"hosted_entitlements"}},"/ops/hosted-account-registry-status":{"get":{"operationId":"hosted_account_registry_status","summary":"Return hosted tenant/account scope registry status","responses":{"200":{"description":"Hosted account registry status","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}},"x-gravityads-tool-name":"gravityads.hosted.account.registry.status","x-gravityads-required-scope":"gravityads.read","x-gravityads-scope-source":"hosted_entitlements"}},"/ops/audit-export":{"get":{"operationId":"audit_export","summary":"Export safe call audit and action ledger entries","parameters":[{"name":"operator_id","in":"query","required":false,"schema":{"type":"string"}},{"name":"operation","in":"query","required":false,"schema":{"type":"string"}},{"name":"date","in":"query","required":false,"schema":{"type":"string"}},{"name":"action_id","in":"query","required":false,"schema":{"type":"string"}},{"name":"account_id","in":"query","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":100}}],"responses":{"200":{"description":"Audit export","content":{"application/json":{"schema":{"type":"object","required":["schema_version","status","export_scope","tenant_id","filters","entry_count","entries","control_plane_audit_log","action_ledger","export_manifest","secret_values_redacted","raw_account_ids_returned","raw_chat_ids_returned","raw_message_ids_returned","raw_tool_call_ids_returned","raw_llm_response_ids_returned","raw_user_emails_returned","raw_secrets_returned"],"additionalProperties":true,"properties":{"schema_version":{"type":"string","const":"gravityads.tenant_audit_export.v1"},"status":{"type":"string","enum":["tenant_audit_export_ready","tenant_audit_export_degraded","tenant_audit_export_unconfigured"]},"export_scope":{"type":"string","const":"tenant"},"tenant_id":{"type":"string"},"call_log_status":{"type":"string"},"filters":{"type":"object"},"entry_count":{"type":"integer","minimum":0},"entries":{"type":"array","items":{"type":"object"}},"control_plane_audit_log":{"type":"object"},"action_ledger":{"type":"object"},"resource_links":{"type":"array","items":{"type":"object"}},"export_manifest":{"type":"object"},"hosted_auth_context":{"type":"object"},"secret_values_redacted":{"type":"boolean","const":true},"raw_account_ids_returned":{"type":"boolean","const":false},"raw_chat_ids_returned":{"type":"boolean","const":false},"raw_message_ids_returned":{"type":"boolean","const":false},"raw_tool_call_ids_returned":{"type":"boolean","const":false},"raw_llm_response_ids_returned":{"type":"boolean","const":false},"raw_user_emails_returned":{"type":"boolean","const":false},"raw_secrets_returned":{"type":"boolean","const":false}}}}}}},"x-gravityads-tool-name":"gravityads.ops.audit_export","x-gravityads-required-scope":"gravityads.ops","x-gravityads-scope-source":"hosted_entitlements"}},"/ops/incident-trace":{"get":{"operationId":"incident_trace","summary":"Trace tenant incidents across audit, usage and action queue rows","parameters":[{"name":"tenant_id","in":"query","required":false,"schema":{"type":"string"}},{"name":"user_id","in":"query","required":false,"schema":{"type":"string"}},{"name":"tool_name","in":"query","required":false,"schema":{"type":"string"}},{"name":"action_id","in":"query","required":false,"schema":{"type":"string"}},{"name":"chat_id","in":"query","required":false,"schema":{"type":"string"}},{"name":"message_id","in":"query","required":false,"schema":{"type":"string"}},{"name":"tool_call_id","in":"query","required":false,"schema":{"type":"string"}},{"name":"llm_response_id","in":"query","required":false,"schema":{"type":"string"}},{"name":"date","in":"query","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":100}}],"responses":{"200":{"description":"Incident trace","content":{"application/json":{"schema":{"type":"object","required":["schema_version","status","filters","query_hashes","audit_log","tool_result_metrics","call_usage","controlled_actions","raw_user_emails_returned","raw_chat_ids_returned","raw_message_ids_returned","raw_tool_call_ids_returned","raw_llm_response_ids_returned","raw_account_ids_returned","raw_request_response_returned","raw_secrets_returned"],"additionalProperties":true,"properties":{"schema_version":{"type":"string","const":"gravityads.hosted_incident_trace.v1"},"status":{"type":"string","enum":["hosted_incident_trace_ready","hosted_incident_trace_unconfigured","hosted_incident_trace_degraded"]},"source":{"type":"string"},"database_url_configured":{"type":"boolean"},"filters":{"type":"object"},"query_hashes":{"type":"object"},"audit_log":{"type":"object"},"tool_result_metrics":{"type":"object"},"call_usage":{"type":"object"},"controlled_actions":{"type":"object"},"hosted_auth_context":{"type":"object"},"raw_user_emails_returned":{"type":"boolean","const":false},"raw_chat_ids_returned":{"type":"boolean","const":false},"raw_message_ids_returned":{"type":"boolean","const":false},"raw_tool_call_ids_returned":{"type":"boolean","const":false},"raw_llm_response_ids_returned":{"type":"boolean","const":false},"raw_account_ids_returned":{"type":"boolean","const":false},"raw_request_response_returned":{"type":"boolean","const":false},"raw_secrets_returned":{"type":"boolean","const":false}}}}}}},"x-gravityads-tool-name":"gravityads.incident.trace","x-gravityads-required-scope":"gravityads.read","x-gravityads-scope-source":"hosted_entitlements"}},"/ops/sla-ops-readiness":{"get":{"operationId":"sla_ops_readiness","summary":"Check enterprise SLA, incident, backup and support readiness","responses":{"200":{"description":"SLA ops readiness","content":{"application/json":{"schema":{"type":"object","required":["schema_version","status","ready_for_enterprise_sla","raw_secrets_returned"],"additionalProperties":true,"properties":{"schema_version":{"type":"string","const":"gravityads.hosted_sla_ops_readiness.v1"},"status":{"type":"string"},"readiness_schema_version":{"type":"string"},"readiness_status":{"type":"string"},"ready_for_enterprise_sla":{"type":"boolean"},"generated_at_utc":{"type":"string"},"checks":{"type":"array","items":{"type":"object"}},"check_count":{"type":"integer","minimum":0},"passed_check_count":{"type":"integer","minimum":0},"blockers":{"type":"array","items":{"type":"object"}},"blocker_count":{"type":"integer","minimum":0},"operator_actions":{"type":"array","items":{"type":"object"}},"operator_action_count":{"type":"integer","minimum":0},"gates":{"type":"array","items":{"type":"object"}},"gate_count":{"type":"integer","minimum":0},"passed_gate_count":{"type":"integer","minimum":0},"hosted_auth_context":{"type":"object"},"raw_secrets_returned":{"type":"boolean","const":false}}}}}}},"x-gravityads-tool-name":"gravityads.sla.ops.readiness","x-gravityads-required-scope":"gravityads.ops","x-gravityads-scope-source":"hosted_entitlements"}},"/ops/support-ticket":{"post":{"operationId":"support_ticket","summary":"Create a redacted support ticket handoff","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["subject"],"properties":{"tenant_id":{"type":"string"},"request_id":{"type":"string"},"subject":{"type":"string","minLength":1},"description":{"type":"string"},"severity":{"type":"string","enum":["low","normal","high","critical"],"default":"normal"},"category":{"type":"string","enum":["billing","data","incident","platform","security","support"],"default":"support"},"created_by":{"type":"string"},"source":{"type":"string","default":"ops"},"send":{"type":"boolean","default":false},"incident_trace":{"type":"object"}}}}}},"responses":{"200":{"description":"Redacted support ticket handoff","content":{"application/json":{"schema":{"type":"object","required":["schema_version","status","ticket_id","tenant_id_hash","request_id_hash","subject_hash","subject_length","description_hash","description_length","raw_ticket_payload_returned","raw_provider_target_returned","raw_secret_returned"],"properties":{"schema_version":{"type":"string","const":"gravityads.hosted_support_ticket.v1"},"status":{"type":"string"},"ticket_id":{"type":"string"},"created_at_utc":{"type":"string"},"tenant_id_hash":{"type":"string"},"request_id_hash":{"type":"string"},"subject_hash":{"type":"string"},"subject_length":{"type":"integer","minimum":0},"description_hash":{"type":"string"},"description_length":{"type":"integer","minimum":0},"severity":{"type":"string"},"category":{"type":"string"},"support_provider":{"type":"string"},"provider_target_hash":{"type":"string"},"support_ticket_correlation_header":{"type":"string"},"ready_for_support_ticket_handoff":{"type":"boolean"},"send_requested":{"type":"boolean"},"send_blocker":{"type":"string"},"provider_called":{"type":"boolean"},"sent":{"type":"boolean"},"provider_status_code":{"type":"integer"},"external_ticket_id_hash":{"type":"string"},"provider_response_hash":{"type":"string"},"control_plane_record":{"type":"object"},"raw_ticket_payload_returned":{"type":"boolean","const":false},"raw_provider_target_returned":{"type":"boolean","const":false},"raw_secret_returned":{"type":"boolean","const":false}}}}}}},"x-gravityads-tool-name":"gravityads.support.ticket","x-gravityads-required-scope":"gravityads.read","x-gravityads-scope-source":"hosted_entitlements"}},"/ops/support-tickets":{"get":{"operationId":"support_tickets","summary":"List tenant support ticket handoff records for ops","parameters":[{"name":"tenant_id","in":"query","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":50}},{"name":"category","in":"query","required":false,"schema":{"type":"string"}},{"name":"source","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Redacted support tickets","content":{"application/json":{"schema":{"type":"object","required":["status","tenant_id","support_ticket_count","support_tickets","raw_ticket_payload_returned","raw_provider_target_returned","raw_secrets_returned"],"properties":{"status":{"type":"string"},"tenant_id":{"type":"string"},"category_filter":{"type":"string"},"source_filter":{"type":"string"},"support_ticket_count":{"type":"integer","minimum":0},"support_tickets":{"type":"array","items":{"type":"object","required":["ticket_id","request_id_hash_prefix","subject_hash_prefix","description_hash_prefix","raw_ticket_payload_returned","raw_provider_target_returned","raw_secrets_returned"],"properties":{"ticket_id":{"type":"string"},"tenant_id":{"type":"string"},"request_id_hash_prefix":{"type":"string"},"subject_hash_prefix":{"type":"string"},"description_hash_prefix":{"type":"string"},"severity":{"type":"string"},"category":{"type":"string"},"support_provider":{"type":"string"},"provider_target_hash":{"type":"string"},"status":{"type":"string"},"provider_called":{"type":"boolean"},"sent":{"type":"boolean"},"external_ticket_id_hash":{"type":"string"},"provider_response_hash":{"type":"string"},"provider_status_code":{"type":"integer"},"created_by_user_id_hash_prefix":{"type":"string"},"source":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"raw_ticket_payload_returned":{"type":"boolean","const":false},"raw_provider_target_returned":{"type":"boolean","const":false},"raw_secrets_returned":{"type":"boolean","const":false}}}},"database_url_configured":{"type":"boolean"},"error_type":{"type":"string"},"raw_ticket_payload_returned":{"type":"boolean","const":false},"raw_provider_target_returned":{"type":"boolean","const":false},"raw_secrets_returned":{"type":"boolean","const":false}}}}}}},"x-gravityads-tool-name":"gravityads.support.tickets","x-gravityads-required-scope":"gravityads.read","x-gravityads-scope-source":"hosted_entitlements"}},"/ops/support-tickets/{ticket_id}/status":{"post":{"operationId":"ops_support_ticket_status_update","summary":"Update a redacted support ticket workflow status","description":"Updates only status and provider hash fields for an existing tenant support ticket. Raw resolution notes, subjects, provider ids and provider targets are rejected. Deletion completion requires terminal evidence from the same tenant's original linked deletion job.","parameters":[{"name":"ticket_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["tenant_id","status"],"properties":{"tenant_id":{"type":"string"},"ticket_id":{"type":"string"},"status":{"type":"string","enum":["data_deletion_cancelled","data_deletion_completed","data_deletion_in_progress","data_deletion_rejected","data_deletion_reviewing","support_ticket_closed","support_ticket_handoff_prepared","support_ticket_handoff_send_failed","support_ticket_handoff_sent","support_ticket_in_progress","support_ticket_open","support_ticket_rejected","support_ticket_resolved"]},"updated_by":{"type":"string"},"provider_called":{"type":"boolean"},"sent":{"type":"boolean"},"external_ticket_id_hash":{"type":"string"},"provider_response_hash":{"type":"string"},"provider_status_code":{"type":"integer"}},"additionalProperties":true}}}},"responses":{"200":{"description":"Redacted support ticket status update","content":{"application/json":{"schema":{"type":"object","required":["schema_version","status","updated","ticket_id","support_ticket","raw_ticket_payload_returned","raw_provider_target_returned","raw_secrets_returned"],"properties":{"schema_version":{"type":"string","const":"gravityads.support_ticket_status_update.v1"},"status":{"type":"string"},"updated":{"type":"boolean"},"tenant_id":{"type":"string"},"ticket_id":{"type":"string"},"updated_by_user_id_hash":{"type":"string"},"support_ticket":{"type":"object","required":["ticket_id","request_id_hash_prefix","subject_hash_prefix","description_hash_prefix","raw_ticket_payload_returned","raw_provider_target_returned","raw_secrets_returned"],"properties":{"ticket_id":{"type":"string"},"tenant_id":{"type":"string"},"request_id_hash_prefix":{"type":"string"},"subject_hash_prefix":{"type":"string"},"description_hash_prefix":{"type":"string"},"severity":{"type":"string"},"category":{"type":"string"},"support_provider":{"type":"string"},"provider_target_hash":{"type":"string"},"status":{"type":"string"},"provider_called":{"type":"boolean"},"sent":{"type":"boolean"},"external_ticket_id_hash":{"type":"string"},"provider_response_hash":{"type":"string"},"provider_status_code":{"type":"integer"},"created_by_user_id_hash_prefix":{"type":"string"},"source":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"raw_ticket_payload_returned":{"type":"boolean","const":false},"raw_provider_target_returned":{"type":"boolean","const":false},"raw_secrets_returned":{"type":"boolean","const":false}}},"raw_ticket_payload_returned":{"type":"boolean","const":false},"raw_provider_target_returned":{"type":"boolean","const":false},"raw_secrets_returned":{"type":"boolean","const":false}}}}}},"409":{"description":"Original deletion completion is unverified"}},"x-gravityads-tool-name":"gravityads.ops.support_ticket_status_update","x-gravityads-required-scope":"gravityads.ops","x-gravityads-scope-source":"hosted_entitlements"}},"/ops/design-partner-feedback":{"get":{"operationId":"ops_design_partner_feedback","summary":"List redacted design partner feedback records for ops","parameters":[{"name":"tenant_id","in":"query","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":50}}],"responses":{"200":{"description":"Redacted design partner feedback records","content":{"application/json":{"schema":{"type":"object","required":["schema_version","status","tenant_id","feedback_count","feedback","raw_feedback_returned","raw_contact_returned","raw_company_returned","raw_quote_returned","raw_secret_values_returned"],"properties":{"schema_version":{"type":"string","const":"gravityads.hosted_design_partner_feedback.v1"},"status":{"type":"string"},"tenant_id":{"type":"string"},"feedback_count":{"type":"integer","minimum":0},"feedback_review":{"type":"object","description":"Bounded tenant feedback review, not host task completion or automatic policy changes."},"case_study_candidate_count":{"type":"integer","minimum":0},"feedback":{"type":"array","items":{"type":"object","required":["feedback_id","tenant_id","feedback_type","stage","status","rating","public_case_study_consent","raw_feedback_returned","raw_contact_returned","raw_company_returned","raw_quote_returned","raw_secret_values_returned"],"properties":{"feedback_id":{"type":"string"},"tenant_id":{"type":"string"},"request_id_hash_prefix":{"type":"string"},"feedback_type":{"type":"string"},"stage":{"type":"string"},"status":{"type":"string"},"source":{"type":"string"},"rating":{"type":"integer"},"onboarding_score":{"type":"integer"},"candidate_quality_score":{"type":"integer"},"freshness_score":{"type":"integer"},"pricing_fit_score":{"type":"integer"},"public_case_study_consent":{"type":"boolean"},"public_logo_consent":{"type":"boolean"},"public_quote_hash_prefix":{"type":"string"},"company_name_hash_prefix":{"type":"string"},"contact_email_hash_prefix":{"type":"string"},"role_title_hash_prefix":{"type":"string"},"feedback_text_hash_prefix":{"type":"string"},"blockers_hash_prefix":{"type":"string"},"created_by_user_id_hash_prefix":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"raw_feedback_returned":{"type":"boolean","const":false},"raw_contact_returned":{"type":"boolean","const":false},"raw_company_returned":{"type":"boolean","const":false},"raw_quote_returned":{"type":"boolean","const":false},"raw_secret_values_returned":{"type":"boolean","const":false}}}},"database_url_configured":{"type":"boolean"},"error_type":{"type":"string"},"raw_feedback_returned":{"type":"boolean","const":false},"raw_contact_returned":{"type":"boolean","const":false},"raw_company_returned":{"type":"boolean","const":false},"raw_quote_returned":{"type":"boolean","const":false},"raw_secret_values_returned":{"type":"boolean","const":false}}}}}}},"x-gravityads-tool-name":"gravityads.ops.design_partner_feedback","x-gravityads-required-scope":"gravityads.ops","x-gravityads-scope-source":"hosted_entitlements"}},"/ops/auth-readiness":{"get":{"operationId":"auth_readiness","summary":"Check hosted MCP/OpenAPI auth, PRM and OIDC readiness","responses":{"200":{"description":"Auth readiness","content":{"application/json":{"schema":{"type":"object","required":["schema_version","status","ready_for_enterprise_sso","raw_secrets_returned","raw_auth_values_returned"],"additionalProperties":true,"properties":{"schema_version":{"type":"string","const":"gravityads.hosted_auth_readiness.v1"},"status":{"type":"string"},"readiness_schema_version":{"type":"string"},"readiness_status":{"type":"string"},"ready_for_enterprise_sso":{"type":"boolean"},"generated_at_utc":{"type":"string"},"checks":{"type":"array","items":{"type":"object"}},"check_count":{"type":"integer","minimum":0},"passed_check_count":{"type":"integer","minimum":0},"blockers":{"type":"array","items":{"type":"object"}},"blocker_count":{"type":"integer","minimum":0},"operator_actions":{"type":"array","items":{"type":"object"}},"operator_action_count":{"type":"integer","minimum":0},"gates":{"type":"array","items":{"type":"object"}},"gate_count":{"type":"integer","minimum":0},"passed_gate_count":{"type":"integer","minimum":0},"hosted_auth_context":{"type":"object"},"raw_secrets_returned":{"type":"boolean","const":false},"raw_auth_values_returned":{"type":"boolean","const":false}}}}}}},"x-gravityads-tool-name":"gravityads.auth.readiness","x-gravityads-required-scope":"gravityads.read","x-gravityads-scope-source":"hosted_entitlements"}},"/ops/launchd-status":{"get":{"operationId":"launchd_status","summary":"Return mini2 launchd deployment contract","responses":{"200":{"description":"Launchd status","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}},"x-gravityads-tool-name":"gravityads.launchd.status","x-gravityads-required-scope":"gravityads.read","x-gravityads-scope-source":"hosted_entitlements"}},"/ops/cloud-readiness":{"get":{"operationId":"cloud_readiness","summary":"Check internal hosted-style and cloud migration readiness","responses":{"200":{"description":"Cloud readiness","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}},"x-gravityads-tool-name":"gravityads.cloud.readiness","x-gravityads-required-scope":"gravityads.read","x-gravityads-scope-source":"hosted_entitlements"}},"/ops/commercial-setup-readiness":{"get":{"operationId":"commercial_setup_readiness","summary":"Check hosted commercial setup readiness","responses":{"200":{"description":"Commercial setup readiness","content":{"application/json":{"schema":{"type":"object","required":["schema_version","status","ready_for_commercial_launch","raw_secrets_returned"],"additionalProperties":true,"properties":{"schema_version":{"type":"string","const":"gravityads.hosted_commercial_setup_readiness.v1"},"status":{"type":"string"},"readiness_schema_version":{"type":"string"},"readiness_status":{"type":"string"},"ready_for_commercial_launch":{"type":"boolean"},"generated_at_utc":{"type":"string"},"checks":{"type":"array","items":{"type":"object"}},"check_count":{"type":"integer","minimum":0},"passed_check_count":{"type":"integer","minimum":0},"blockers":{"type":"array","items":{"type":"object"}},"blocker_count":{"type":"integer","minimum":0},"operator_actions":{"type":"array","items":{"type":"object"}},"operator_action_count":{"type":"integer","minimum":0},"gates":{"type":"array","items":{"type":"object"}},"gate_count":{"type":"integer","minimum":0},"passed_gate_count":{"type":"integer","minimum":0},"hosted_auth_context":{"type":"object"},"raw_secrets_returned":{"type":"boolean","const":false},"readiness":{"type":"object"},"warnings":{"type":"array","items":{"type":"object"}},"required_action_count":{"type":"integer","minimum":0}}}}}}},"x-gravityads-tool-name":"gravityads.commercial.setup.readiness","x-gravityads-required-scope":"gravityads.read","x-gravityads-scope-source":"hosted_entitlements"}},"/workflow/recommend":{"post":{"operationId":"workflow_recommend","summary":"Read-only optimizer workflow: recommend","requestBody":{"required":true,"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"utterance":{"default":"","maxLength":500,"title":"Utterance","type":"string"},"locale":{"default":"en","maxLength":20,"title":"Locale","type":"string"},"selected_platforms":{"items":{"enum":["google","meta","microsoft","tiktok","criteo","media_go","pinterest","linkedin","amazon"],"type":"string"},"maxItems":9,"title":"Selected Platforms","type":"array"},"current_task_id":{"default":"","pattern":"^(|T(0[1-9]|1[0-7]))$","title":"Current Task Id","type":"string"},"run_id":{"default":"","maxLength":100,"title":"Run Id","type":"string"}},"title":"RecommendRequest","type":"object"}}}},"responses":{"200":{"description":"Authorized workflow state; no platform writes","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid workflow request"},"403":{"description":"Access denied"}},"x-gravityads-tool-name":"gravityads.workflow.recommend","x-gravityads-required-scope":"gravityads.read","x-gravityads-scope-source":"hosted_entitlements"}},"/workflow/save_budget_plan":{"post":{"operationId":"workflow_save_budget_plan","summary":"Read-only optimizer workflow: save_budget_plan","requestBody":{"required":true,"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"run_id":{"maxLength":100,"minLength":1,"title":"Run Id","type":"string"},"revision":{"minimum":0,"title":"Revision","type":"integer"},"plan":{"$ref":"#/components/schemas/Local1_BudgetPlan"}},"required":["run_id","revision","plan"],"title":"BudgetPlanRequest","type":"object"}}}},"responses":{"200":{"description":"Authorized workflow state; no platform writes","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid workflow request"},"403":{"description":"Access denied"}},"x-gravityads-tool-name":"gravityads.workflow.save_budget_plan","x-gravityads-required-scope":"gravityads.read","x-gravityads-scope-source":"hosted_entitlements"}},"/workflow/save_review":{"post":{"operationId":"workflow_save_review","summary":"Read-only optimizer workflow: save_review","requestBody":{"required":true,"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"run_id":{"maxLength":100,"minLength":1,"title":"Run Id","type":"string"},"revision":{"minimum":0,"title":"Revision","type":"integer"},"plan":{"$ref":"#/components/schemas/Local2_ReviewPlan"}},"required":["run_id","revision","plan"],"title":"ReviewPlanRequest","type":"object"}}}},"responses":{"200":{"description":"Authorized workflow state; no platform writes","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid workflow request"},"403":{"description":"Access denied"}},"x-gravityads-tool-name":"gravityads.workflow.save.review","x-gravityads-required-scope":"gravityads.read","x-gravityads-scope-source":"hosted_entitlements"}},"/workflow/save_plan":{"post":{"operationId":"workflow_save_plan","summary":"Read-only optimizer workflow: save_plan","requestBody":{"required":true,"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"run_id":{"maxLength":100,"minLength":1,"title":"Run Id","type":"string"},"revision":{"minimum":0,"title":"Revision","type":"integer"},"plan":{"anyOf":[{"discriminator":{"mapping":{"experiment":"#/components/schemas/Local3_ExperimentPlan","quarterly":"#/components/schemas/Local3_QuarterlyPlan"},"propertyName":"kind"},"oneOf":[{"$ref":"#/components/schemas/Local3_QuarterlyPlan"},{"$ref":"#/components/schemas/Local3_ExperimentPlan"}]},{"$ref":"#/components/schemas/Local3_PauseSelection"},{"$ref":"#/components/schemas/Local3_BudgetAdjustment"}],"title":"Plan"}},"required":["run_id","revision","plan"],"title":"PlanningRequest","type":"object"}}}},"responses":{"200":{"description":"Authorized workflow state; no platform writes","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid workflow request"},"403":{"description":"Access denied"}},"x-gravityads-tool-name":"gravityads.workflow.save.plan","x-gravityads-required-scope":"gravityads.read","x-gravityads-scope-source":"hosted_entitlements"}},"/workflow/save_search_selection":{"post":{"operationId":"workflow_save_search_selection","summary":"Read-only optimizer workflow: save_search_selection","requestBody":{"required":true,"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"run_id":{"maxLength":100,"minLength":1,"title":"Run Id","type":"string"},"revision":{"minimum":0,"title":"Revision","type":"integer"},"selections":{"items":{"$ref":"#/components/schemas/Local4_SearchSelection"},"maxItems":100,"title":"Selections","type":"array"}},"required":["run_id","revision","selections"],"title":"SearchSelectionRequest","type":"object"}}}},"responses":{"200":{"description":"Authorized workflow state; no platform writes","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid workflow request"},"403":{"description":"Access denied"}},"x-gravityads-tool-name":"gravityads.workflow.save_search_selection","x-gravityads-required-scope":"gravityads.read","x-gravityads-scope-source":"hosted_entitlements"}},"/workflow/schedule_save":{"post":{"operationId":"workflow_schedule_save","summary":"Read-only optimizer workflow: schedule_save","requestBody":{"required":true,"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"batch_id":{"pattern":"^gwb_[a-f0-9]{64}$","title":"Batch Id","type":"string"},"frequency":{"pattern":"^(daily|weekly)$","title":"Frequency","type":"string"},"timezone":{"maxLength":100,"minLength":1,"title":"Timezone","type":"string"},"local_hour":{"default":9,"maximum":23,"minimum":0,"title":"Local Hour","type":"integer"},"weekday":{"default":0,"maximum":6,"minimum":0,"title":"Weekday","type":"integer"}},"required":["batch_id","frequency","timezone"],"title":"ScheduleSaveRequest","type":"object"}}}},"responses":{"200":{"description":"Authorized workflow state; no platform writes","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid workflow request"},"403":{"description":"Access denied"}},"x-gravityads-tool-name":"gravityads.workflow.schedule_save","x-gravityads-required-scope":"gravityads.read","x-gravityads-scope-source":"hosted_entitlements"}},"/workflow/schedule_list":{"post":{"operationId":"workflow_schedule_list","summary":"Read-only optimizer workflow: schedule_list","requestBody":{"required":true,"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"cursor":{"default":"","maxLength":100,"title":"Cursor","type":"string"}},"title":"ScopeListRequest","type":"object"}}}},"responses":{"200":{"description":"Authorized workflow state; no platform writes","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid workflow request"},"403":{"description":"Access denied"}},"x-gravityads-tool-name":"gravityads.workflow.schedule_list","x-gravityads-required-scope":"gravityads.read","x-gravityads-scope-source":"hosted_entitlements"}},"/workflow/schedule_set_enabled":{"post":{"operationId":"workflow_schedule_set_enabled","summary":"Read-only optimizer workflow: schedule_set_enabled","requestBody":{"required":true,"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"schedule_id":{"pattern":"^gwsch_[a-f0-9]{64}$","title":"Schedule Id","type":"string"},"enabled":{"title":"Enabled","type":"boolean"}},"required":["schedule_id","enabled"],"title":"ScheduleEnabledRequest","type":"object"}}}},"responses":{"200":{"description":"Authorized workflow state; no platform writes","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid workflow request"},"403":{"description":"Access denied"}},"x-gravityads-tool-name":"gravityads.workflow.schedule_set_enabled","x-gravityads-required-scope":"gravityads.read","x-gravityads-scope-source":"hosted_entitlements"}},"/workflow/scope_save":{"post":{"operationId":"workflow_scope_save","summary":"Read-only optimizer workflow: scope_save","requestBody":{"required":true,"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"scope_name":{"maxLength":80,"minLength":1,"title":"Scope Name","type":"string"},"definition":{"$ref":"#/components/schemas/Local5_ScopeDefinition"},"request_key":{"maxLength":100,"minLength":8,"pattern":"^[A-Za-z0-9_-]+$","title":"Request Key","type":"string"}},"required":["scope_name","definition","request_key"],"title":"ScopeSaveRequest","type":"object"}}}},"responses":{"200":{"description":"Authorized workflow state; no platform writes","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid workflow request"},"403":{"description":"Access denied"}},"x-gravityads-tool-name":"gravityads.workflow.scope_save","x-gravityads-required-scope":"gravityads.read","x-gravityads-scope-source":"hosted_entitlements"}},"/workflow/scope_list":{"post":{"operationId":"workflow_scope_list","summary":"Read-only optimizer workflow: scope_list","requestBody":{"required":true,"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"cursor":{"default":"","maxLength":100,"title":"Cursor","type":"string"},"scope_id":{"default":"","maxLength":100,"title":"Scope Id","type":"string"},"account_offset":{"default":0,"minimum":0,"title":"Account Offset","type":"integer"}},"title":"ScopeMembersRequest","type":"object"}}}},"responses":{"200":{"description":"Authorized workflow state; no platform writes","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid workflow request"},"403":{"description":"Access denied"}},"x-gravityads-tool-name":"gravityads.workflow.scope_list","x-gravityads-required-scope":"gravityads.read","x-gravityads-scope-source":"hosted_entitlements"}},"/workflow/scope_delete":{"post":{"operationId":"workflow_scope_delete","summary":"Read-only optimizer workflow: scope_delete","requestBody":{"required":true,"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"scope_id":{"pattern":"^gws_[0-9a-f]{64}$","title":"Scope Id","type":"string"}},"required":["scope_id"],"title":"ScopeDeleteRequest","type":"object"}}}},"responses":{"200":{"description":"Authorized workflow state; no platform writes","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid workflow request"},"403":{"description":"Access denied"}},"x-gravityads-tool-name":"gravityads.workflow.scope_delete","x-gravityads-required-scope":"gravityads.read","x-gravityads-scope-source":"hosted_entitlements"}},"/workflow/batch_background":{"post":{"operationId":"workflow_batch_background","summary":"Read-only optimizer workflow: batch_background","requestBody":{"required":true,"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"batch_id":{"maxLength":100,"minLength":1,"title":"Batch Id","type":"string"},"enabled":{"title":"Enabled","type":"boolean"}},"required":["batch_id","enabled"],"title":"BatchBackgroundRequest","type":"object"}}}},"responses":{"200":{"description":"Authorized workflow state; no platform writes","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid workflow request"},"403":{"description":"Access denied"}},"x-gravityads-tool-name":"gravityads.workflow.batch_background","x-gravityads-required-scope":"gravityads.read","x-gravityads-scope-source":"hosted_entitlements"}},"/workflow/history":{"post":{"operationId":"workflow_history","summary":"Read-only optimizer workflow: history","requestBody":{"required":true,"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"kind":{"default":"runs","pattern":"^(runs|batches)$","title":"Kind","type":"string"},"cursor":{"default":"","maxLength":500,"title":"Cursor","type":"string"}},"title":"HistoryRequest","type":"object"}}}},"responses":{"200":{"description":"Authorized workflow state; no platform writes","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid workflow request"},"403":{"description":"Access denied"}},"x-gravityads-tool-name":"gravityads.workflow.history","x-gravityads-required-scope":"gravityads.read","x-gravityads-scope-source":"hosted_entitlements"}},"/workflow/batch_start":{"post":{"operationId":"workflow_batch_start","summary":"Read-only optimizer workflow: batch_start","requestBody":{"required":true,"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"selection":{"anyOf":[{"$ref":"#/components/schemas/Local6_ScopeDefinition"},{"type":"null"}],"default":null},"report_thresholds":{"anyOf":[{"additionalProperties":{"type":"number"},"maxProperties":7,"type":"object"},{"type":"null"}],"default":null,"title":"Report Thresholds"},"report_options":{"anyOf":[{"$ref":"#/components/schemas/Local6_ReportOptions"},{"type":"null"}],"default":null},"intent":{"default":"daily_patrol","pattern":"^(daily_patrol|data_trust|weekly_review|anomaly|budget)$","title":"Intent","type":"string"},"accounts":{"items":{"additionalProperties":{"type":"string"},"type":"object"},"maxItems":1000,"minItems":1,"title":"Accounts","type":"array"},"date_start":{"title":"Date Start","type":"string"},"date_end":{"title":"Date End","type":"string"},"request_key":{"maxLength":100,"minLength":8,"title":"Request Key","type":"string"},"locale":{"default":"en","title":"Locale","type":"string"}},"required":["accounts","date_start","date_end","request_key"],"title":"BatchStartRequest","type":"object"}}}},"responses":{"200":{"description":"Authorized workflow state; no platform writes","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid workflow request"},"403":{"description":"Access denied"}},"x-gravityads-tool-name":"gravityads.workflow.batch_start","x-gravityads-required-scope":"gravityads.read","x-gravityads-scope-source":"hosted_entitlements"}},"/workflow/batch_status":{"post":{"operationId":"workflow_batch_status","summary":"Read-only optimizer workflow: batch_status","requestBody":{"required":true,"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"batch_id":{"maxLength":100,"minLength":1,"title":"Batch Id","type":"string"},"offset":{"default":0,"minimum":0,"title":"Offset","type":"integer"}},"required":["batch_id"],"title":"BatchStatusRequest","type":"object"}}}},"responses":{"200":{"description":"Authorized workflow state; no platform writes","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid workflow request"},"403":{"description":"Access denied"}},"x-gravityads-tool-name":"gravityads.workflow.batch_status","x-gravityads-required-scope":"gravityads.read","x-gravityads-scope-source":"hosted_entitlements"}},"/workflow/batch_step":{"post":{"operationId":"workflow_batch_step","summary":"Read-only optimizer workflow: batch_step","requestBody":{"required":true,"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"batch_id":{"maxLength":100,"minLength":1,"title":"Batch Id","type":"string"},"revision":{"pattern":"^[a-f0-9]{64}$","title":"Revision","type":"string"},"account_id":{"default":"","title":"Account Id","type":"string"},"platform":{"default":"","title":"Platform","type":"string"}},"required":["batch_id","revision"],"title":"BatchStepRequest","type":"object"}}}},"responses":{"200":{"description":"Authorized workflow state; no platform writes","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid workflow request"},"403":{"description":"Access denied"}},"x-gravityads-tool-name":"gravityads.workflow.batch_step","x-gravityads-required-scope":"gravityads.read","x-gravityads-scope-source":"hosted_entitlements"}},"/workflow/catalog":{"post":{"operationId":"workflow_catalog","summary":"Read-only optimizer workflow: catalog","requestBody":{"required":true,"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"query":{"default":"","maxLength":100,"title":"Query","type":"string"},"cursor":{"default":"","maxLength":100,"title":"Cursor","type":"string"},"platform":{"default":"","pattern":"^(|google|meta|microsoft|tiktok|criteo|media_go|pinterest|linkedin|amazon)$","title":"Platform","type":"string"}},"title":"CatalogRequest","type":"object"}}}},"responses":{"200":{"description":"Authorized workflow state; no platform writes","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid workflow request"},"403":{"description":"Access denied"}},"x-gravityads-tool-name":"gravityads.workflow.catalog","x-gravityads-required-scope":"gravityads.read","x-gravityads-scope-source":"hosted_entitlements"}},"/workflow/start_or_resume":{"post":{"operationId":"workflow_start_or_resume","summary":"Read-only optimizer workflow: start_or_resume","requestBody":{"required":true,"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"brief_ref":{"anyOf":[{"$ref":"#/components/schemas/Local7_BusinessReference"},{"type":"null"}],"default":null},"report_thresholds":{"anyOf":[{"additionalProperties":{"type":"number"},"maxProperties":7,"type":"object"},{"type":"null"}],"default":null,"title":"Report Thresholds"},"report_options":{"anyOf":[{"$ref":"#/components/schemas/Local7_ReportOptions"},{"type":"null"}],"default":null},"intent":{"title":"Intent","type":"string"},"platform":{"title":"Platform","type":"string"},"account_id":{"title":"Account Id","type":"string"},"date_start":{"title":"Date Start","type":"string"},"date_end":{"title":"Date End","type":"string"},"request_key":{"title":"Request Key","type":"string"},"locale":{"default":"en","title":"Locale","type":"string"}},"required":["intent","platform","account_id","date_start","date_end","request_key"],"title":"StartRequest","type":"object"}}}},"responses":{"200":{"description":"Authorized workflow state; no platform writes","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid workflow request"},"403":{"description":"Access denied"}},"x-gravityads-tool-name":"gravityads.workflow.start_or_resume","x-gravityads-required-scope":"gravityads.read","x-gravityads-scope-source":"hosted_entitlements"}},"/workflow/status":{"post":{"operationId":"workflow_status","summary":"Read-only optimizer workflow: status","requestBody":{"required":true,"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"run_id":{"maxLength":100,"minLength":1,"title":"Run Id","type":"string"},"evidence_step":{"default":"","title":"Evidence Step","type":"string"},"cursor":{"default":"","maxLength":100,"title":"Cursor","type":"string"}},"required":["run_id"],"title":"StatusRequest","type":"object"}}}},"responses":{"200":{"description":"Authorized workflow state; no platform writes","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid workflow request"},"403":{"description":"Access denied"}},"x-gravityads-tool-name":"gravityads.workflow.status","x-gravityads-required-scope":"gravityads.read","x-gravityads-scope-source":"hosted_entitlements"}},"/workflow/run_step":{"post":{"operationId":"workflow_run_step","summary":"Read-only optimizer workflow: run_step","requestBody":{"required":true,"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"run_id":{"maxLength":100,"minLength":1,"title":"Run Id","type":"string"},"revision":{"minimum":0,"title":"Revision","type":"integer"},"follow_up":{"default":false,"title":"Follow Up","type":"boolean"},"follow_up_kind":{"default":"","enum":["","creative_media","warehouse_metrics"],"title":"Follow Up Kind","type":"string"}},"required":["run_id","revision"],"title":"RunStepRequest","type":"object"}}}},"responses":{"200":{"description":"Authorized workflow state; no platform writes","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid workflow request"},"403":{"description":"Access denied"}},"x-gravityads-tool-name":"gravityads.workflow.run_step","x-gravityads-required-scope":"gravityads.read","x-gravityads-scope-source":"hosted_entitlements"}},"/workflow/feedback":{"post":{"operationId":"workflow_feedback","summary":"Read-only optimizer workflow: feedback","requestBody":{"required":true,"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"run_id":{"maxLength":100,"minLength":1,"title":"Run Id","type":"string"},"revision":{"minimum":0,"title":"Revision","type":"integer"},"rating":{"anyOf":[{"maximum":10,"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"title":"Rating"},"verdict":{"default":"","pattern":"^(|helpful|data_wrong|not_needed)$","title":"Verdict","type":"string"},"reason_code":{"anyOf":[{"pattern":"^[a-z0-9_]{0,40}$","type":"string"},{"type":"null"}],"default":null,"title":"Reason Code"}},"required":["run_id","revision"],"title":"FeedbackRequest","type":"object"}}}},"responses":{"200":{"description":"Authorized workflow state; no platform writes","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid workflow request"},"403":{"description":"Access denied"}},"x-gravityads-tool-name":"gravityads.workflow.feedback","x-gravityads-required-scope":"gravityads.read","x-gravityads-scope-source":"hosted_entitlements"}},"/workflow/save_brief":{"post":{"operationId":"workflow_save_brief","summary":"Read-only optimizer workflow: save_brief","requestBody":{"required":true,"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"run_id":{"maxLength":100,"minLength":1,"title":"Run Id","type":"string"},"revision":{"minimum":0,"title":"Revision","type":"integer"},"brief":{"$ref":"#/components/schemas/Local8_CreativeBriefInput"}},"required":["run_id","revision","brief"],"title":"BriefRequest","type":"object"}}}},"responses":{"200":{"description":"Authorized workflow state; no platform writes","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid workflow request"},"403":{"description":"Access denied"}},"x-gravityads-tool-name":"gravityads.workflow.save_brief","x-gravityads-required-scope":"gravityads.read","x-gravityads-scope-source":"hosted_entitlements"}},"/workflow/save_business":{"post":{"operationId":"workflow_save_business","summary":"Read-only optimizer workflow: save_business","requestBody":{"required":true,"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"run_id":{"maxLength":100,"minLength":1,"title":"Run Id","type":"string"},"revision":{"minimum":0,"title":"Revision","type":"integer"},"brief":{"$ref":"#/components/schemas/Local9_BusinessBrief"}},"required":["run_id","revision","brief"],"title":"BusinessRequest","type":"object"}}}},"responses":{"200":{"description":"Authorized workflow state; no platform writes","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid workflow request"},"403":{"description":"Access denied"}},"x-gravityads-tool-name":"gravityads.workflow.save_business","x-gravityads-required-scope":"gravityads.read","x-gravityads-scope-source":"hosted_entitlements"}},"/workflow/link_action":{"post":{"operationId":"workflow_link_action","summary":"Read-only optimizer workflow: link_action","requestBody":{"required":true,"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"run_id":{"maxLength":100,"minLength":1,"title":"Run Id","type":"string"},"revision":{"minimum":0,"title":"Revision","type":"integer"},"search_request_id":{"default":"","title":"Search Request Id","type":"string"},"pause_request_id":{"default":"","title":"Pause Request Id","type":"string"},"action_id":{"maxLength":100,"minLength":1,"pattern":"^[A-Za-z0-9_-]+$","title":"Action Id","type":"string"}},"required":["run_id","revision","action_id"],"title":"LinkActionRequest","type":"object"}}}},"responses":{"200":{"description":"Authorized workflow state; no platform writes","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid workflow request"},"403":{"description":"Access denied"}},"x-gravityads-tool-name":"gravityads.workflow.link_action","x-gravityads-required-scope":"gravityads.read","x-gravityads-scope-source":"hosted_entitlements"}},"/tenant/support-conversation":{"get":{"operationId":"tenant_support_conversation","parameters":[{"name":"ticket_id","in":"query","schema":{"type":"integer"}},{"name":"article_id","in":"query","schema":{"type":"integer"}},{"name":"attachment_id","in":"query","schema":{"type":"integer"}},{"name":"cursor","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Current member's provider-owned public conversation","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"request_id":{"type":"string"},"ticket_id":{"type":"integer"},"articles":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"body":{"type":"string"},"content_type":{"type":"string"},"sender":{"type":"string"},"created_at":{"type":"string"},"internal":{"type":"boolean"},"attachments":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"filename":{"type":"string"},"content_type":{"type":"string"},"size":{"type":"integer"}}}}}}},"support_tickets":{"type":"array","items":{"type":"object","properties":{"request_id":{"type":"string"},"ticket_id":{"type":["integer","null"]},"status":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"}}}},"next_cursor":{"type":["string","null"]},"retry_allowed":{"type":"boolean"},"provider_accepted":{"type":"boolean"},"email_delivered":{"type":"string"},"customer_resolved":{"type":"boolean"},"ticket_state":{"type":"string"},"attachment":{"type":"object","additionalProperties":false,"required":["filename","data","mime-type"],"properties":{"filename":{"type":"string","maxLength":128},"data":{"type":"string","maxLength":6666668},"mime-type":{"type":"string","enum":["image/png","image/jpeg","text/plain","application/pdf"]}}}}}}}}},"x-gravityads-tool-name":"gravityads.tenant.support.conversation","x-gravityads-required-scope":"gravityads.read","x-gravityads-scope-source":"hosted_entitlements"},"post":{"operationId":"tenant_support_conversation_update","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["action","request_id"],"properties":{"action":{"enum":["create","reply","reopen"],"type":"string"},"request_id":{"type":"string","maxLength":256},"ticket_id":{"type":"integer","minimum":1},"subject":{"type":"string","maxLength":200},"description":{"type":"string","maxLength":16000},"attachments":{"type":"array","maxItems":5,"items":{"type":"object","additionalProperties":false,"required":["filename","data","mime-type"],"properties":{"filename":{"type":"string","maxLength":128},"data":{"type":"string","maxLength":6666668},"mime-type":{"type":"string","enum":["image/png","image/jpeg","text/plain","application/pdf"]}}}}}}}}},"responses":{"200":{"description":"Persisted support request outcome; not an email delivery confirmation","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"request_id":{"type":"string"},"ticket_id":{"type":"integer"},"articles":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"body":{"type":"string"},"content_type":{"type":"string"},"sender":{"type":"string"},"created_at":{"type":"string"},"internal":{"type":"boolean"},"attachments":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"filename":{"type":"string"},"content_type":{"type":"string"},"size":{"type":"integer"}}}}}}},"support_tickets":{"type":"array","items":{"type":"object","properties":{"request_id":{"type":"string"},"ticket_id":{"type":["integer","null"]},"status":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"}}}},"next_cursor":{"type":["string","null"]},"retry_allowed":{"type":"boolean"},"provider_accepted":{"type":"boolean"},"email_delivered":{"type":"string"},"customer_resolved":{"type":"boolean"},"ticket_state":{"type":"string"},"attachment":{"type":"object","additionalProperties":false,"required":["filename","data","mime-type"],"properties":{"filename":{"type":"string","maxLength":128},"data":{"type":"string","maxLength":6666668},"mime-type":{"type":"string","enum":["image/png","image/jpeg","text/plain","application/pdf"]}}}}}}}}},"x-gravityads-tool-name":"gravityads.tenant.support.conversation.update","x-gravityads-required-scope":"gravityads.read","x-gravityads-scope-source":"hosted_entitlements"}},"/meta/creation-reconcile":{"post":{"operationId":"meta_creation_reconcile","summary":"meta creation reconcile","responses":{"200":{"description":"GET-only Meta verification with local receipt reconciliation; inspect reconciled, remaining_steps and error. No platform writes.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["action_id","request_id"],"properties":{"action_id":{"type":"string","minLength":1,"maxLength":128},"request_id":{"type":"string","pattern":"^[A-Za-z0-9_-]{1,128}$"}},"additionalProperties":false}}}},"x-gravityads-tool-name":"gravityads.meta.creation.reconcile","x-gravityads-required-scope":"gravityads.approve","x-gravityads-scope-source":"hosted_entitlements"}},"/meta/ad-identities":{"get":{"operationId":"meta_ad_identities","summary":"meta ad identities","responses":{"200":{"description":"Scoped identity result; inspect error and valid fields.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}},"parameters":[{"name":"account_id","in":"query","required":true,"schema":{"type":"string"}},{"name":"page_id","in":"query","required":false,"schema":{"type":"string"}},{"name":"instagram_user_id","in":"query","required":false,"schema":{"type":"string"}},{"name":"creative_id","in":"query","required":false,"schema":{"type":"string"}},{"name":"connection_id","in":"query","required":false,"schema":{"type":"string"}},{"name":"include_threads","in":"query","required":false,"schema":{"type":"boolean"}}],"x-gravityads-tool-name":"gravityads.meta.ad.identities","x-gravityads-required-scope":"gravityads.read","x-gravityads-scope-source":"hosted_entitlements"}},"/meta/ad-identity/validate":{"post":{"operationId":"meta_ad_identity_validate","summary":"meta ad identity validate","responses":{"200":{"description":"Scoped identity result; inspect error and valid fields.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["account_id","identity"],"properties":{"account_id":{"type":"string"},"connection_id":{"type":"string"},"identity":{"type":"object","required":["facebook_page_id"],"additionalProperties":false,"properties":{"facebook_page_id":{"type":"string","pattern":"^[0-9]{1,64}$"},"instagram_user_id":{"type":"string","pattern":"^[0-9]{1,64}$"},"threads_user_id":{"type":"string","pattern":"^[0-9]{1,64}$"}}}},"additionalProperties":false}}}},"x-gravityads-tool-name":"gravityads.meta.ad.identity.validate","x-gravityads-required-scope":"gravityads.read","x-gravityads-scope-source":"hosted_entitlements"}},"/meta/action-identity":{"get":{"operationId":"meta_action_identity","summary":"meta action identity","responses":{"200":{"description":"Scoped identity result; inspect error and valid fields.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}},"parameters":[{"name":"action_id","in":"query","required":true,"schema":{"type":"string"}}],"x-gravityads-tool-name":"gravityads.meta.ad.identities","x-gravityads-required-scope":"gravityads.read","x-gravityads-scope-source":"hosted_entitlements"},"post":{"operationId":"meta_action_identity_draft","summary":"meta action identity draft","responses":{"200":{"description":"Scoped identity result; inspect error and valid fields.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["action_id","identity","request_id"],"properties":{"action_id":{"type":"string"},"request_id":{"type":"string"},"identity":{"type":"object","required":["facebook_page_id"],"additionalProperties":false,"properties":{"facebook_page_id":{"type":"string","pattern":"^[0-9]{1,64}$"},"instagram_user_id":{"type":"string","pattern":"^[0-9]{1,64}$"},"threads_user_id":{"type":"string","pattern":"^[0-9]{1,64}$"}}}},"additionalProperties":false}}}},"x-gravityads-tool-name":"gravityads.meta.ad.identity.draft","x-gravityads-required-scope":"gravityads.draft","x-gravityads-scope-source":"hosted_entitlements"}}}}